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": "darragh",
    "role": "admin",
    "permissions": ["*"]
  }
}

permissions is ["*"] for admin; otherwise the explicit list your role resolves to. In open mode (zero accounts) openMode is true and the user is a synthetic local admin.

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, follows it for you, and (when auto-download is on and your role allows it) queues every missing issue:

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 }

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 or the queue's grabs needs downloads.grab.

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"}'

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.

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 ​

Users, roles & permissions — users.manage ​

Plugins — plugins.manage ​

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 (e.g. the Requests plugin's requests.create). What a plugin exposes is documented with that plugin; the rule of thumb is that anything its UI can do, a key with the right permission can do. See Plugin API for how routes are registered, and Building on the API for examples (Reader page images, OPDS, Requests).