Organise a library with lists

Recipes for specific tasks against the API.

Create the user's own lists, and put series on them or take them off.

A list groups entries already in the library, like "Favourites" or "Read on the train". A series can be on any number of lists, and deleting a list never removes a series from the library.

Access#↑

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

Manage lists#↑

  • List your lists: private ones included, 500 per page by default and up to 1000 with limit. Paginate with pagination.next.

    • q keeps lists whose name contains it, ignoring case and spacing.
    • visibility=public or private keeps only those.
    • sort_by is name_asc (the default), name_desc, series_count_desc, series_count_asc, created_at_desc, created_at_asc, visibility_asc (public first) or visibility_desc.
    • pagination.count counts the lists that match.
  • Create a list: { "name": "Favourites", "is_private": false }.
  • Get a list, rename it or change its privacy, or delete it.
curl -X POST "https://api.mangabaka.org/v2/my/library/lists" \
  -H "x-api-key: mb-your-token" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Favourites" }'
{
	"status": 200,
	"data": {
		"id": 10059,
		"name": "Favourites",
		"is_private": false,
		"series_count": 0,
		"created_at": "2026-11-14T12:00:00.000Z",
		"updated_at": "2026-11-14T12:00:00.000Z"
	}
}
  • Names are 1 to 255 characters, trimmed, and unique across the user's lists ignoring case: Favourites and favourites are one list.
  • Each whitespace run, tabs and newlines included, is stored as one space (an ideographic space stays ideographic). Other invisible or control characters, and stacked accents, are a 400.
  • Creating a name the user already has is a 400, whatever its is_private.
  • Renaming onto another of the user's names is a 400.
  • A private list is hidden on the user's public library.
  • series_count counts active series only.

Change or delete many lists at once#↑

Bulk change up to 100 list ids per request:

{
	"action": "set_visibility",
	"ids": [10059, 10061],
	"is_private": true
}
{
	"action": "delete",
	"ids": [10059, 10061]
}
{
	"status": 200,
	"data": { "updated": 1, "skipped": 1 }
}
  • All or nothing: an id that is not one of the user's lists, or a repeated id, is a 400 and nothing changes.
  • set_visibility skips lists that already have it and reports them in skipped. delete reports deleted.
  • Deleting keeps the series in the library.

Put a series on a list#↑

Put and take off one series at a time:

curl -X PUT "https://api.mangabaka.org/v2/my/library/74695/lists/10059" \
  -H "x-api-key: mb-your-token"

Both return every list the series is on after the change:

{
	"status": 200,
	"data": [{ "id": 10059, "name": "Favourites", "is_private": false }]
}
  • The series must already be in the library. Add it first with create a library entry.
  • Repeating either call changes nothing, so retries are safe.

Set all of an entry's lists at once#↑

Create, update and patch a library entry take lists, up to 30 list ids:

{
	"state": "reading",
	"lists": [10059, 10061]
}
  • lists replaces the lists the entry is on. [] takes it off every list. Leave lists out to keep them as they are.
  • The entry and its lists are written together. An id that is not one of the user's lists is a 400, and the entry is not changed either.

For up to 100 series in one request, send the same lists on each entry of a batch write.

Add or remove a list on many series#↑

Bulk change puts series on lists and takes them off, keeping every other list they are on:

{
	"target": { "series_ids": [74695, 1621] },
	"change": { "action": "update_lists", "add": [10059], "remove": [10061] }
}
  • All or nothing. A list that is not the user's, or a series that would end up on more than 30 lists, is a 400.
  • The summary counts how many matched series are on each list.

Targeting every series a filter matches, and the same endpoint's status and visibility changes, are in change many series at once.

Keeping a copy in sync#↑

List changes, and series going on or off a list, show up in the changes feed. The events feed has no list events.

Errors#↑

Status When
400 Invalid body, a name clash, an entry write or batch with a list id that is not one of the user's, or a series that would end up on more than 30 lists
404 A single list that is not the user's, or a series not in their library
409 A bulk change whose series or filter no longer matches what was read (library_changed)

The full set is in errors.