Skip to content

Metadata export API

New in 1.33.0. A read-only API that hands what MangaPixer knows about your series to another program on your network - built for MangaList, open to any client. It lists every folder (or archive) that has its own series link, with the linked record, the volume list, the Completion answer and when the information is looked at again, and it tells a client what changed since its last call.

It is built from what MangaPixer has already stored. Calling it never contacts a website, and it changes nothing: there is no write or trigger endpoint. It never returns a file-system path - folder and file names only.

Authentication

Every export endpoint needs one of:

  • a personal access token with the metadata:read scope, sent as Authorization: Bearer <token>. An admin creates tokens in MangaPixer Administration; a token is shown once, and it works on the export endpoints only - nowhere else in MangaPixer.
  • an admin's browser login (useful to look at the answers by hand).

Never put a token in a URL. A reader account gets 403. The export is read-only: its endpoints answer only GET (other methods get 405), and a token is refused on anything but GET / HEAD - except the one scan request below the same prefix, POST /api/v1/export/libraries/{id}/scan (1.36.0), which needs a token with the separate library:scan scope (see Request a library scan). GET /api/v1/export/ping answers { "ok": true, "serverTime": "...", "auth": "token" } - use it to test a token. See API tokens.

Endpoints

All endpoints below are GET, under /api/v1/export/, and answer JSON. Times are UTC ISO 8601 with milliseconds: 2026-10-04T12:00:00.000Z.

GET /api/v1/export/libraries

{
  "schemaVersion": 1,
  "serverTime": "2026-10-04T12:00:00.000Z",
  "libraries": [
    { "id": "lib0manga", "displayName": "Manga", "kind": "manga", "folderCount": 712, "itemCount": 698,
      "lastScanAt": "2026-10-04T03:00:00.000Z" }
  ]
}
  • kind: the library's declared type (manga, manhwa, manhua, webtoon, comic, graphic-novel, novel), or null when the library declares none (see Declared hints).
  • folderCount: folders in the library; itemCount: items the export has for it (see below); lastScanAt: the last finished scan.

GET /api/v1/export/metadata

Parameter
library Required: a library id from /libraries. One library per call.
updatedSince Optional: only items changed at or after this time (inclusive), plus the removals since then. Without it: a full sync.
cursor The nextCursor of the previous page. Repeat the other parameters unchanged.
limit Items per page, 1-500 (default 200).
include Optional blocks to return, comma-separated: volumes, completion, refresh, duplicates (1.38.0). Default: all four. include= returns none.
{
  "schemaVersion": 1,
  "serverTime": "2026-10-04T12:00:00.000Z",
  "sweeps": { "mangadexLatestUpload": "2026-10-04T09:00:00.000Z" },
  "recordFields": ["creators"],
  "library": { "id": "lib0manga", "displayName": "Manga", "kind": "manga" },
  "items": [ { "nodeId": "...", "...": "..." } ],
  "removed": [ { "nodeId": "...", "reason": "linkCleared", "at": "2026-10-04T12:00:00.000Z" } ],
  "nextCursor": null
}

A complete synthetic page - every link state, a folder and an archive, a removal, a carriedFrom, a volume list with dates, official links - is in the repository at contracts/samples/metadata-export-v1.json. It is generated by a test, so it always matches what the server sends. The full schema is in the OpenAPI document (/openapi/v1.json, contracts/openapi.json).

1.45.0: sweeps (on every page, next to serverTime, the same value on every page of one call) says how recently MangaPixer confirmed the library's new-chapter signals. sweeps.mangadexLatestUpload is the start time of the most recent MangaDex latest-upload check that completed for every MangaDex record of the library's linked series, or null when none has yet: every item's companions.mangadexLatestUpload was confirmed at least that recently. A check that stopped early (the daily budget spent, MangaDex asking to slow down, a switch turned off) still counts for the libraries whose records it had all read before it stopped; for the others it does not move. A MangaDex record that MangaDex no longer returns keeps its last value here. With Automatic matching on, MangaPixer checks every 6 hours by default (an admin can choose every 1 to 6 hours: Scheduled jobs > Series information refresh > Check for new chapters).

1.47.0: recordFields (on every page, next to sweeps) lists the optional fields of items[].record this server exports - today ["creators"]. An optional field is left out of a record that has no value for it, so the key being absent means either "this record has none" or "this MangaPixer is older than the field". Read the page: when the field's name is in recordFields, an absent key means none known; when it is not (or recordFields itself is missing - a MangaPixer before 1.47.0), the server does not export that field at all. The list is about the server, not the item, so it never changes an item's updatedAt.

Items

An item is a live folder or archive with its own link row: Confirmed, Auto, Needs review, Don't match, (new in 1.34.0) Collection about or (new in 1.37.0) Artist folder. Folders below a linked folder inherit its link in MangaPixer; the export lists only the node that carries the row, so a client applies the nearest-ancestor rule itself (a Don't match, Collection about or Artist folder row stops it).

A Collection about item (CollectionAbout) is a folder of works about a series - fan works such as doujinshi of a manga - not the series itself. Its record is that series, as a label ("Collection about Synthetic Quest"); compute nothing from it (no behind, missing, upgrade or completion), do not match the folder yourself, and do not let anything below it inherit the series. The works inside are matched on their own in MangaPixer; an archive among them that has its own link is an item of its own.

An Artist folder item (ArtistFolder, new in 1.37.0) is a folder of one artist's works. Its record is always null, and it has no companions, official links, volumes, completion or refresh. Do not match the folder yourself and do not let anything below it inherit a link; the works inside are matched on their own in MangaPixer, and each one with its own link is an item of its own. The artist is the folder's declared creator in MangaPixer (not part of the export).

Field
nodeId The node's id. A renamed or moved folder becomes a new node with a new id; an archive keeps its id when it moves, also to another library.
nodeKind folder or archive (an archive that is its own work, such as a one-shot).
carriedFrom The old nodeId when MangaPixer's folder carry-over moved this link from a renamed or moved folder, or (1.37.0) an admin chose Use old for a series-link move conflict; re-key your row instead of removing and adding it. Shown for at least the removal window. Otherwise null.
trail The on-disk names from below the library root down to the node itself (["Shonen", "Series"]; an archive's trail ends with its file name). Names only, never a path.
updatedAt When the export last saw this item change.
link state (Confirmed, Auto, NeedsReview, DontMatch, CollectionAbout, ArtistFolder), method (search, reference, comicInfo, auto, or null), score (0-1 or null), updatedAt.
record The linked record, or null - always null for Needs review, Don't match and Artist folder. For CollectionAbout it is the series the folder is about (a label only). provider is mangaupdates (or gcd for comics; 1.42.0: or mangadex for a series MangaUpdates does not list - then externalId is the MangaDex id, type, statusText, licensedEn and translationComplete are null, englishPublishers is empty, latestChapter is the highest chapter released in the preferred language (the same as companions.mangadexReleased.latestChapter), totalChapters is set only for a finished series, and companions.mangadex is the same id - the record is its own MangaDex companion; ignore providers you do not know). After Switch to MangaUpdates the same item carries the MangaUpdates record instead. Unit numbers such as latestChapter are exact strings ("12.5"). englishPublishers lists the English publishers with their volume / chapter totals and status.
companions mangadex: the MangaDex record id, or null; anilist: { id, chapters, volumes }, or null; mangadexReleased (1.42.0, left out when unknown): what MangaDex lists as released in the instance's preferred language - { language, latestChapter, chapters, fetchedAt }, where language is the language the list was read for (en unless an admin chose another preferred language), latestChapter the highest chapter listed as an exact string (or null), chapters how many whole chapters are listed (parts such as 4.1 and 4.2 count once) and fetchedAt when the list was last read. latestChapter and chapters also count chapters MangaDex took down (unavailable there). 1.43.0: readable (left out until the list is next read after the update) says what of that list can actually be read on MangaDex - { latestWholeChapter, chapters }, where latestWholeChapter is the highest whole chapter readable as an exact string (a readable 18.5 or 18.1 gives "18"), or null when nothing listed is readable, and chapters how many whole chapters are readable. It comes from the stored volume list, never from an extra request during the export. 1.45.0: mangadexLatestUpload (left out when MangaPixer never read it) is MangaDex's latest uploaded chapter of the mangadex record, in any language - { chapterId, fetchedAt }, where chapterId is the chapter's MangaDex id (a UUID), or null when MangaDex lists no chapter, and fetchedAt is when MangaPixer first read that chapterId (the change as MangaPixer saw it), not the last check. The block - and so the item for updatedSince - changes only when chapterId changes; how recently every value was confirmed is the page's sweeps.mangadexLatestUpload. All null or left out for CollectionAbout.
officialLinks Official sources from the linked MangaDex record: { kind, label, url, source: "mangadex" }, kind being publisher or store. [] until MangaPixer next reads that record (they fill in on each series' refresh schedule).
volumes The per-volume list (below), or null when none is stored.
completion The Completion answer (below), or null - only folders with a Confirmed or Auto link have one, and (1.39.0) not a folder whose completion tracking is off.
refresh lastFetchedAt, intervalDays, nextDueAt: when MangaPixer read the record and looks at it again; null without a record and for CollectionAbout (its record is not refreshed automatically). officialLinks is [] and volumes / completion are null for CollectionAbout too.
tracking (1.39.0) "off" when an admin turned Track completion off for the folder (see below); the key is left out otherwise.
duplicates (1.38.0) Chapter or volume numbers that more than one file states - the same duplicates the Missing report lists - each with its files: { kind, number, files: [{ nodeId, name, folder }] }. Open a file in the reader at /reader/{nodeId}. kind is Volume or Chapter; number is exact ("12.5"); folder is the unit subfolder (Volumes, Season 2) or null in the series folder itself (a number is a duplicate only within one folder). Only folders with a Confirmed or Auto link have it, and the key is left out when there are none. At most 50 numbers, 20 files each. 1.44.0: a chapter file the volume contents scan found inside a volume file is listed too, with inVolume (the volume's number) and files: [the chapter file, the volume file] - the chapter file is a copy of part of the volume, so a client may offer to remove it; inVolume is left out on the other entries.

Creators

New in 1.47.0. record.creators lists the people the linked record credits, so a client can search by creator without asking MangaUpdates itself:

"creators": [
  { "name": "Synthetic Writer", "role": "Author, Artist", "muAuthorId": 20000001, "otherNames": ["Shinsetsu Sakka", "S. Writer"] },
  { "name": "Sample Illustrator", "role": "Artist", "muAuthorId": 20000002, "otherNames": [] }
]
Field
name The name as the record credits it.
role Author, Artist or Author, Artist: one entry per person, not per credit - a person credited for both roles appears once. MangaUpdates' other credits (editors, translators, ...) are left out.
muAuthorId The MangaUpdates author number (a number), or null for a credit that has none (records read from MangaDex or the Grand Comics Database).
otherNames The person's other names (pen names, other spellings and scripts; at most 50): the main name of their MangaUpdates author page when it is not the name above, then the other names, as MangaPixer stored them. [] when none are stored.
  • Left out when empty. A record with no creators has no creators key at all - never null, never [] - so such an item keeps its exact form and does not come again from updatedSince because of this field. Use the page's recordFields (above) to tell "none known" from an older MangaPixer.
  • Order. The people are in the order the record first credits them (a person's place is their first credit, whatever the role), so the list is the same on every call.
  • otherNames needs an admin. MangaPixer reads a person's other names from the author pages MangaUpdates holds, and only when an admin presses Look up the rest under Artists' other names (never automatic). Until then, and for a person without an author number, otherNames is []; the names appear on the next rebuild after the admin's run.
  • What moves an item. An item changes (and so comes again from updatedSince) only when its creators list changes - a credit added or removed, or a person's other names changed by an Artists' other names run. Other items do not move.
  • After the upgrade to 1.47.0. Every item whose record has creators gains the list once, so those items come again in the first incremental call; items without creators are unchanged.
  • A Collection about item's record is the series the folder is about, so its creators are that series' creators (a label, like the rest of that record).

Volumes

"volumes": { "source": "merged", "fetchedAt": "...", "items": [
  { "volume": "1", "title": null, "chapters": { "from": "1", "to": "8" }, "englishDate": "2025-03-04",
    "englishDateKind": "released", "isbn": "9780000000011", "sources": ["mangadex", "wikipedia"] } ] }

The same list MangaPixer's own Volumes view uses: MangaDex's volume list, completed from Wikipedia where MangaDex lacks volumes or chapters, with Wikipedia's English release dates and ISBNs. source is mangadex, wikipedia or merged. Numbers are exact strings. chapters is null when the volume's chapters are not known. englishDate may be partial (2025-07, 2025); englishDateKind is released when the whole date is not after today, else announced.

Estimated volumes (1.42.0). When the Volumes view of a linked folder shows an estimated volume (~ Volume 7: a volume the list does not map, its chapters placed by MangaDex's average chapters per volume), that volume is added to the folder's items with "chaptersEstimated": true and "sources": ["estimate"]. Its chapters are the first and last chapter file of this folder the estimate places in that volume - for a held volume file, the chapter files it most likely contains - so a client can offer "replace these chapters with the volume" for a person to confirm; never act on it automatically. A volume the list maps never gets an estimated row, and the key chaptersEstimated is left out on every other row. When there is no list at all but estimated volumes exist, source is estimate.

Volumes read from the files (1.44.0). When the volume contents scan found chapter files inside a volume file of the folder, that volume's row lists them in filesInside: [{ "nodeId", "name", "number" }] (open one at /reader/{nodeId}), and its sources has scan. When the chapters found fill the volume (its range is known), chapters is the first and last chapter found, sources is ["scan"] and chaptersEstimated is left out; otherwise the row keeps the estimate's range and chaptersEstimated: true, with scan added to sources. A row of the volume list is never changed. filesInside is left out when the scan found nothing, so an item without scanned volumes keeps its exact form. When there is no list at all, source is scan.

Completion

{ "answer", "reason", "upgradeAvailable", "upgradeVolumes", "computedAt", "basedOnScanAt" } - the answer of the Completion tab, computed from MangaPixer's own scan of the folder:

answer Meaning
HaveItAll Finished - the original run ended and the folder holds the whole edition it collects.
FinishedMissing Finished - but something released (or part of the finished edition) is not in the folder.
UpToDate Everything released so far in the preferred language is here; more is still to come.
MissingSome Still running, and something released in the preferred language is not here.
CantTell No comparison possible; reason says why.

reason is one of None, Running, OnHiatus, StatusUnknown, WaitingForLanguage, LanguageEditionDropped, NoNumbers, NumberingRestarts, NothingKnownReleased, NoVolumeTotal, OneShot. upgradeVolumes: volumes released officially that the folder holds only as chapters (the first 50); upgradeAvailable is true when there is at least one. computedAt and basedOnScanAt are the time and the library scan of the export rebuild that last changed this item - a later rebuild that finds the same answer does not move them (the response's serverTime says when it was checked again).

New in 1.39.0: two more keys, each left out unless an admin declared it on the folder itself (This folder's edition):

  • volumeTotalOverride (number): the folder holds another edition than the regular one (an omnibus or master edition) with this many volumes. The answer counts that edition's volumes 1..N (as volume files), not the regular edition's volume list - so do not count the folder's volumes as missing against record.originVolumes, englishPublishers or volumes (those stay the regular edition's). Chapter numbers are unaffected.
  • edition (string): the edition label - regular, omnibus, master or deluxe. Ignore a value you do not know.

Completion tracking off

New in 1.39.0. An item with "tracking": "off" is a folder an admin keeps linked but does not want completion answers for (a sampler, a reading copy). Its link, record, companions, official links, volumes, refresh and duplicates stay as usual; completion is null. Compute no behind, missing, upgrade or complete answer for it yourself either. An item without the key is tracked.

Keeping in sync

  1. Full sync: call without updatedSince and follow nextCursor until it is null. Keep the FIRST page's serverTime.
  2. Incremental sync: call with updatedSince = the serverTime you kept, follow nextCursor, keep the new first page's serverTime. updatedSince is inclusive and the same item may come twice - treat items as upserts. Use MangaPixer's serverTime, never your own clock.
  3. Removals come on the first page of an incremental call (removed, empty on later pages and in a full sync):
  4. nodeGone: the folder or archive is gone (deleted, or renamed - a rename that carry-over could follow shows as carriedFrom instead);
  5. linkCleared: the node is still there but no longer has its own link (it may inherit one again);
  6. movedToOtherLibrary: the node (or the folder its link was carried to) is now in another library - look for it there.

A node is never both an item and a removal in one answer. 4. 409 { "error": "fullSyncRequired" }: updatedSince lies before the window MangaPixer keeps removals for (at least 30 days, and at least the trash retention). Do a full sync. The first call after the export was introduced, or after a client was off for longer than the window, ends here.

  1. New chapters (1.45.0): an item whose companions.mangadexLatestUpload.chapterId changed comes again in the next incremental call; an item whose value was only confirmed does not. To decide whether MangaPixer's value is fresh enough to skip asking MangaDex yourself, compare the page's sweeps.mangadexLatestUpload with your own interval - not the item's fetchedAt, which only moves with a new chapter.

MangaPixer rebuilds a library's export at most once every 5 minutes (configurable, Export:MinRebuildMinutes); calls in between are served from the last rebuild. Only the first page of a call can start a rebuild. A rebuild between two pages only moves changed items to the end, so following the cursor still returns every item.

Errors

Errors are { "error": "<code>" }.

Status error
400 libraryRequired, invalidUpdatedSince, invalidCursor, invalidInclude Fix the request.
401 No credentials; a token that is wrong, revoked or expired, or whose admin is no longer an active admin. The WWW-Authenticate header says Bearer error="invalid_token" when a token was refused.
403 Signed in with a browser login that is not an admin's (a reader account).
404 libraryNotFound The library id is unknown (it may have been removed: call /libraries).
409 fullSyncRequired See above.
429 rate_limited, too_many_attempts Wait for the Retry-After header's seconds. rate_limited: this token made more requests a minute than the server allows (600 by default). too_many_attempts: too many wrong tokens came from your address; every token request from it is refused for a few minutes.

Versioning

schemaVersion is 1. New fields may appear in any MangaPixer release without changing it - ignore fields you do not know. A field is never removed or renamed, and a value never changes meaning, without raising schemaVersion; a client should refuse a higher version than it knows.

1.47.0: record.creators and the page's recordFields were added without changing schemaVersion (they are new fields). Later optional record fields follow the same rule: the field is left out when empty, and its name is added to recordFields.

New link.state values may also appear without a new schemaVersion. Treat a state you do not know as "not a series": the folder or archive is not matched by your own matcher, no numbers (behind, missing, complete) are computed from its record, and it stops inheritance like DontMatch - items below it without their own link are not part of a series either. Never fail a sync on an unknown state; store the item and show the state as it is.