API reference ​

The complete HTTP endpoint list. For the why — API keys, how access is clamped to your role, CORS, client tips — read Building on the API first; this page is the map of what's there.

Everything lives under /api. It is the same API the web UI runs on, so any screen in the app is a live example of these endpoints in action.

Conventions ​

• Base URL — your install, e.g. http://backissue.local:8787. All paths below are relative to it.
• Auth — send X-Api-Key: bi_… or Authorization: Bearer bi_… on every request (the browser UI uses a session cookie instead; both resolve to a user). See Building on the API.
• Request bodies — JSON, with Content-Type: application/json. Query strings are used for filters on GET endpoints.
• Responses — JSON. Lists return a JSON array; single resources return an object.
• Errors — { "error": "…" } with a meaningful status: 400 (bad input), 401 (missing/invalid key), 403 (your role lacks the permission), 404 (not found or hidden from your role), 502 (an upstream like ComicVine or an indexer failed).

How permissions are assigned ​

Every call resolves to one required permission. Most follow a default rule, and the tables below only call out the endpoint's effective permission:

• GET (reading) needs library.view.
• Writes (POST/PATCH/DELETE) need library.manage.
• Download actions — searching sources, queueing grabs, retrying, cancelling — need downloads.grab.
• Admin areas (settings, users, plugins, jobs, logs) need their specific permission.
• /api/auth/* is self-service: any signed-in user can call it for their own account.

A request acts as its user: it can do exactly what the account's role allows. The core permissions:

Account & auth ​

Self-service — any signed-in user, for their own account. A few are public (no key needed) because the sign-in screen calls them.

GET /api/auth/me →

{
  "openMode": false,
  "registration": false,
  "user": {
    "id": 3,
    "username": "you",
    "role": "admin",
    "permissions": ["*"]
  }
}

permissions is ["*"] for admin; otherwise the explicit list your role resolves to. hideMature reports the account's own preference.

POST /api/auth/hide-mature narrows what this account sees, on top of what its role allows. It cannot widen anything: an account whose role lacks library.restricted never sees flagged series regardless. Note that this preference filters the web app and this API, but not the OPDS catalog — see OPDS. Open-mode installs have no real account to store it against and get 403 sign in with a real account first.

openMode is true only in the window before the first account exists — a brand-new install that hasn't been through first-run setup yet. The API then reports a synthetic local admin so the setup wizard can do its work. First-run setup makes you create an admin, so a configured server always has accounts and openMode is false from then on. See Users & access.

Collection & series ​

Your tracked series and their issues. Reads need library.view; changes need library.manage. Series flagged restricted return 404 to roles without library.restricted.

POST /api/collection/add-cv — adds the volume (monitoring all issues), follows it for you, and (when download-on-add is on and your role allows it) queues every missing issue. With Only the issues that were asked for on and cvIssueIds given, the series arrives with monitoring off and just those issues picked (reason is stored with the picks):

curl -X POST http://backissue.local:8787/api/collection/add-cv \
  -H "X-Api-Key: bi_…" -H "Content-Type: application/json" \
  -d '{"comicvineId": 18166}'
# → { "seriesId": 42, "cvId": 18166, "queued": 12 }

GET /api/collection/counts returns a flat map — all, incomplete, followed, monitored, unmonitored, ongoing, ended, problems, unmatched and manga — so a client can label its filter chips without fetching each filtered list. It always answers, falling back to a slower synchronous count if the cached one isn't ready.

POST /api/collection/{id}/assign-file is the escape hatch for a file the matcher reads wrongly. path must be a file already attributed to that series, and cvIssueId must belong to that series' volume, or you get 400 with that file is not in this series or that issue is not in this volume. The assignment is remembered against the file path, so rescans, re-matches and metadata refreshes keep it. Re-pointing the series at a different ComicVine volume drops it.

Libraries ​

Libraries are the named root folders your series live in, each with a type that decides how its files are read. Reading the list needs library.view; changing one needs library.manage.

Three things are worth knowing before you automate against this:

• Updates are POST, not PUT or PATCH. There is no PUT route.
• Deleting a library never touches files or series. Its series are simply unassigned and fall back to the default library.
• types is not a fixed list. It always holds comic and manga, and gains whatever library types your installed plugins register — which is how Books and Audiobooks appear. Read it rather than hard-coding.

A library marked restricted is hidden from roles without library.restricted, the same way a restricted series is.

ComicVine lookup ​

Search and read ComicVine data on demand (the source of truth for comic metadata). Upstream failures surface as 502.

Files, folders & import ​

Attribute files on disk to series, and reorganize the library. Import and library-wide tools are gated tighter than ordinary edits.

Downloads, search & queue ​

Finding and grabbing issues. Anything that touches a source, the queue or the history needs downloads.grab — including reading them. The queue and the history both name the source that fetched each issue, so a read-only account cannot see or steer what the household is grabbing.

POST /api/search takes a series/issue and returns ranked results from every enabled source; feed one back to /api/search/grab:

curl -X POST http://backissue.local:8787/api/search \
  -H "X-Api-Key: bi_…" -H "Content-Type: application/json" \
  -d '{"seriesId": 42, "cvIssueId": 987654, "query": "Saga 1"}'

The blocklist is what stops a broken Usenet release being grabbed again and again. Each row carries id, source, reason, created_at, the human release title, and the issue it was for (issue_id, issue_number, series_id, series_title). Removing a row makes that release eligible for automatic grabbing again; a manual search was never filtered by it. Rows for restricted series are hidden from roles that cannot see them. The endpoint is read-only apart from removal — nothing adds to the blocklist through the API. See how downloads work.

Library statistics ​

GET /api/stats (library.view) is one call for everything the Stats page shows. It takes no parameters and is cached for a minute. The payload has five parts:

Restricted series are filtered out of completion.topGaps and activity.recent for roles that cannot see them. The aggregate numbers are not filtered, so totals can exceed what such a role can browse.

Releases ​

The weekly new-comics list.

Reading lists ​

Personal curation — each user manages their own; no files are touched, so library.view is enough for every verb. Two exceptions: sharing a list needs lists.share, and wanting a whole list needs library.manage because it can add series.

Notifications ​

Live updates (SSE) ​

Instead of polling, subscribe once and re-fetch only the domain that changed. Each event names a domain (status, queue, jobs, releases, notifications, …) mirroring the matching GET endpoint:

const es = new EventSource('/api/events'); // key via cookie/session in a browser
es.addEventListener('queue', () => refetch('/api/queue'));
es.addEventListener('status', () => refetch('/api/status'));

Settings & connections — settings.manage ​

POST /api/metadata/test does more than probe: on a server that has never registered, it provisions the instance key and then proves it with a live search, so a success means the whole path works. It answers 200 either way — read ok. registered tells you whether a key exists at all, which separates "never registered" from "registered but the service is unreachable".

Users, roles & permissions — users.manage ​

Plugins — plugins.manage ​

Download sites install separately from plugins but at the same bar, because both change what the app runs. Each catalog entry carries id, name, description, what it carries, what it requires, its version, and whether it is installed with an updateAvailable. Installing or removing one sets restartRequired, so follow with POST /api/restart when you are ready. Reading the list of enabled sources is a different, unprivileged call: GET /api/sources.

Jobs, schedules, tools & logs ​

Health ​

Plugin routes ​

Plugins register their own endpoints under the same /api tree, gated by the same permissions, so an API key reaches them too. Each declares an access tier — viewer → library.view, trusted → library.manage, admin → plugins.manage — or its own registered permission, like the Requests plugin's requests.create. Omit the declaration and a GET defaults to viewer, everything else to trusted. Core rules win over a plugin's own declaration, which is why any plugin path ending in /test is admin-only.

These endpoints exist only while their plugin is installed and enabled. Check GET /api/plugins, or just handle 404. See Plugin API for how routes are registered.

Reader ​

Reading, progress and page images. Everything needs reader.read unless noted.

Page images are cached hard and revalidate with an ETag, so a client that sends If-None-Match gets 304 and pays nothing. Ask for a width and the server transcodes to WebP when your Accept header allows it. An issue with no file, or one your role cannot see, answers 404 either way — the two are deliberately indistinguishable.

Requests ​

Filing a request has three outcomes worth handling separately. A duplicate of an open request comes back as a vote rather than an error. With auto-approve on it comes back already approved, and the response says what was queued. And a volume you already own is refused with 409 and the series id, so a client can link straight to it. Server policy can also refuse a request outright with 403, for collected editions or non-Western publishers, if the admin has restricted those.

Approved downloads run under the approver's permissions, not the requester's.

Books ​

ebooks.use unless noted. {id} is the issue id.

The file and cover routes accept HTTP Basic as well as a key, because OPDS download managers need a challenge before they will send credentials. A book held remotely rather than on disk is fetched on first open, so the first request can be slow and concurrent opens share one download. A source that has lost the file answers 404 with unavailable: true, and the entry is marked so; a transient failure answers 502 and leaves it retryable.

Audiobooks ​

audiobooks.use unless noted.

Streaming is built for real players: Range is passed through to the source, Accept-Ranges is always set, and a strong validator is synthesised when the upstream does not provide one, so a dropped connection resumes instead of starting over.

Shelves ​

Faceted browsing for large book and audiobook libraries. library.view unless noted.

A size of zero on the status route means the index has never been built, and every other route will come back empty until it is.

Gamify ​

All library.view, and all scoped to the calling account.

When the feature is switched off, or the Reader plugin that records reading is missing, /me answers 200 with ready: false and a reason rather than an error. Handle that before reading any other field.

OPDS ​

The OPDS catalog is a protocol surface rather than a JSON API, and it is documented in full on its own page, including every feed path in both protocol versions, page streaming, and how progress syncs back. See OPDS catalog.