Change many series at once

Recipes for specific tasks against the API.

Set one status, visibility or list change on many series in the library, or remove them: up to 100 you name, or every series a library filter matches.

To write different values per series, such as each entry's own progress, use a batch write instead.

Access#↑

Use a personal access token, or an OAuth token with library.write for writes and library.read for reads.

Pick the series#↑

Bulk change takes a target and a change. Name up to 100 series:

{
	"target": { "series_ids": [74695, 1621] },
	"change": { "action": "set_visibility", "is_private": true }
}

Or every series a library filter matches. Read the count first from the summary, which takes the same filters as list library entries without paging or sorting:

curl -G "https://api.mangabaka.org/v2/my/library/bulk/summary" \
  -d state=reading -d type=manga \
  -H "x-api-key: mb-your-token"
{
	"status": 200,
	"data": {
		"matched": 212,
		"lists": [{ "id": 10059, "series_count": 40 }]
	}
}

Then send that count back as expected_count, at most 2,500. Narrow the filter for more.

{
	"target": {
		"filter": { "state": ["reading"], "type": ["manga"] },
		"expected_count": 212
	},
	"change": { "action": "set_visibility", "is_private": true }
}

If the library changed in between, the filter now matches a different number of series and the change is a 409. Read the summary again and retry.

Show a selection like the website#↑

The summary is what the website reads to draw its bulk bar:

  • matched is the "N selected" figure, and the expected_count you send.
  • A list whose series_count equals matched holds every selected series, a smaller count holds some, and a list missing from lists holds none.
  • It takes the filters of list library entries, so reuse the listing URL without page, limit, sort_by, random_seed and schema.

For series you name by id, count from the entries you already have instead.

Change the status#↑

{
	"target": { "series_ids": [74695, 1621] },
	"change": {
		"action": "set_state",
		"state": "completed",
		"set_progress": { "chapter": true, "volume": true }
	}
}
  • An empty start date gets today on a move to Reading, and an empty finish date on a move to Completed, like a single change. Dates already set are kept.
  • set_progress is for Completed only. It sets chapter and/or volume progress to each series' total, the same as the website asks when you mark one series Completed. A series without a total, or with one over 10,000, keeps its progress.
  • With set_progress, entries already Completed are synced too: progress above the total comes down to it.

Change visibility#↑

{
	"target": { "series_ids": [74695, 1621] },
	"change": { "action": "set_visibility", "is_private": true }
}

Private entries only show in the user's own library.

Add or remove lists#↑

{
	"target": { "series_ids": [74695, 1621] },
	"change": { "action": "update_lists", "add": [10059], "remove": [10061] }
}

Every other list a series is on stays. More on lists in organise a library with lists.

Remove from the library#↑

{
	"target": { "series_ids": [74695, 1621] },
	"change": { "action": "delete" }
}
{
	"status": 200,
	"data": { "deleted": 2 }
}

The series go with their progress, rating, notes, dates and list memberships, the same as removing one. There is no undo.

delete takes series_ids only, never a filter, so it removes exactly the series you name. To empty a whole library, users clear it in their account settings.

Response#↑

For the filter target above with "add": [10059], "remove": [], where 40 of the 212 series were already on 10059:

{
	"status": 200,
	"data": { "updated": 172, "skipped": 40, "added": 172, "removed": 0 }
}
  • updated counts the entries written, skipped the ones that already matched and were left alone.
  • added and removed come back for list changes only. A delete returns only deleted.
  • All or nothing: a refused request writes nothing.

Keeping a copy in sync#↑

The changes feed returns each changed series' current entry, or a tombstone once it is removed. Status and progress changes, and removals, are also library events; visibility and lists have none.

Errors#↑

Status When
400 Invalid body, expected_count over 2,500, a filter field with over 100 distinct values, a list that is not the user's, or over 30 lists
409 A series no longer in the library, or a filter that no longer matches (library_changed)

The full set is in errors.