Web API

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

The HTTP API of bookclerkd, the Bookclerk daemon: the web interface, the CLI and other nodes use it. Request bodies are JSON (Content-Type: application/json; send {} for defaults) unless a route says otherwise. Error responses are JSON objects with an error slug (ApiError); bare statuses get {"error", "message", "status"} (ErrorJson).

The daemon serves this reference as an OpenAPI 3.1 document, Bookclerk daemon API, at GET /api/openapi.json (API version 0.1.0). Load it into an OpenAPI viewer such as Scalar or Swagger UI, or a client generator. Tools that only read OpenAPI 3.0, such as Cloudflare API Shield's schema validation, can use the same API restated as OpenAPI 3.0.3 at GET /api/openapi-3.0.json.

Authentication

Each route lists the credentials it accepts and who may call it. The credentials are:

Name Kind Description
clerkToken header Authorization A library card (POST /api/clerk/v1/token), as Authorization: Bookclerk-Clerk <token>. Accepted only on routes any library session may use, over TLS except on loopback.
copyToken header Authorization The token of a copy grant, as Authorization: Bookclerk-Copy <token>.
nodeSignature header Authorization A node's signed request, as Authorization: Bookclerk-Node <node_id> <issued_at> <signature> with the node's identity key.
oidcAccessToken HTTP bearer An access token from this daemon's OIDC token endpoint (POST /oidc/token), as Authorization: Bearer <token>.
operatorSession cookie bookclerk_operator_session The operator's browser session, set by POST /api/auth/login.
operatorToken HTTP bearer The operator token (bookclerk daemon token), as Authorization: Bearer <token>.
playerToken HTTP bearer A player card's access token (POST /player/login), as Authorization: Bearer <token> or, in audio and cover URLs, the token query parameter. Accepted only under /player.
portalSession cookie bookclerk_portal_session A library user's browser session, set by a sign-in route. Cookie-authenticated writes must send an Origin (or Referer) matching the daemon's public origin or its host.
uploadToken header Authorization The token of an upload grant, as Authorization: Bookclerk-Upload <token>.

Routes

Liveness.

Route Summary
GET /health Serves GET /health with a static ok payload for liveness probes.

Inbound webhooks for plugins, outside operator auth: the URL token is the credential.

Route Summary
POST /hooks/{token}/{name} Stores one inbound webhook request for a plugin instance.

This document.

Route Summary
GET /api/openapi.json Serves the OpenAPI document.
GET /api/openapi-3.0.json Serves the OpenAPI document restated as OpenAPI 3.0.3.

Sign-in, sessions, passkeys, TOTP and the operator's elevation.

Route Summary
POST /api/auth/login Validates the operator token (throttled, constant-time) and issues a hashed session cookie.
GET /api/auth/signin Public sign-in picker: operator-token availability, SSO IdPs, integration logins.
POST /api/auth/tray-handoff/prepare Mint a single-use tray Open Bookclerk ticket (Bearer, direct loopback only).
GET /api/auth/tray-handoff Consume the pending tray ticket and set a localhost operator session cookie.
GET /api/auth/me Resolves the caller and returns /me JSON; unauthenticated callers get 401.
POST /api/auth/elevate Owner portal session + password re-auth → short-lived elevated operator cookie.
DELETE /api/auth/elevate End elevation by revoking the elevated operator session cookie.
POST /api/auth/bootstrap Operator-only bootstrap of the first Owner when none exist.
PUT /api/auth/password Set password for self (portal) or target user (operator/admin); revokes sessions.
POST /api/auth/password Local password login → portal session cookie, or a TOTP challenge when enabled.
POST /api/auth/impersonate Operator (or elevated) session starts impersonating a User.
DELETE /api/auth/impersonate Clear impersonation on the current operator session.
GET /api/auth/branch-consent GET /api/auth/branch-consent?<authorize params>: what the consent page shows. 400 invalid_request for a malformed request (the page then shows the problem and never redirects).
POST /api/auth/branch-consent POST /api/auth/branch-consent: approve or deny. Answers {redirect}, the URL to send the browser to: the branch's callback with a code (or error=access_denied). Approving needs an active signed-in user, host enrollment on, and a connection the transport policy allows.
POST /api/auth/branch-consent/step-up POST /api/auth/branch-consent/step-up: starts a passkey step-up for a shared branch consent (an Owner with a passkey). Answers the WebAuthn request options with a challenge_id to send back in the consent's step_up.
GET /api/auth/clerk-consent GET /api/auth/clerk-consent?<authorize params>: what the consent page shows. 400 invalid_request for a malformed request (the page then shows the problem and never redirects).
POST /api/auth/clerk-consent POST /api/auth/clerk-consent: approve or deny. Answers {redirect}, the URL to send the browser to: the clerk's callback with a code (or error=access_denied).
POST /api/auth/logout Revokes hashed operator and portal sessions and clears both cookies.
GET /api/auth/sessions List sessions for the current principal only (not every operator session).
DELETE /api/auth/sessions/{id} Revoke a session by id. Operators may revoke any operator session; portal users may only revoke their own.
PATCH /api/auth/profile Updates the caller's display name and/or email.
GET /api/auth/profile/catalog-listing Reads whether the caller's books are listed to the libraries this install is a branch of.
PUT /api/auth/profile/catalog-listing Sets whether the caller's books are listed to the libraries this install is a branch of.
PUT /api/auth/profile/avatar Accepts a JPEG/PNG/WebP upload and stores it under files_dir/avatars.
DELETE /api/auth/profile/avatar Removes the caller's stored avatar, if any.
GET /api/auth/oidc/providers Lists enabled IdPs for the login picker (id and display name only).
GET /api/auth/oidc/identities Lists OIDC portal identities for the cookie-authenticated caller.
GET /api/auth/oidc/login Starts an OIDC login authorize redirect, honoring login throttle.
GET /api/auth/oidc/elevate Starts an Owner re-auth elevate flow against a linked IdP (prompt=login).
GET /api/auth/oidc/callback GET callback (most IdPs); finishes the code exchange.
POST /api/auth/oidc/callback POST callback (Apple form_post); finishes the code exchange.
GET /api/auth/oidc/config Operator GET: broker settings plus secret-presence flags (never plaintext).
PUT /api/auth/oidc/config Operator-only PUT: writes next-generation sealed secrets, then publishes config.toml.
GET /api/auth/passkeys Lists this user's stored passkeys as { id, credential_id } rows.
POST /api/auth/passkeys/register/begin Starts passkey registration (skips reauth only for first local-only setup).
POST /api/auth/passkeys/register/finish Completes registration, stores the passkey, and revokes elevated operator sessions.
DELETE /api/auth/passkeys/{id} Deletes one passkey after recent reauth; 404 when the id is not this user's.
POST /api/auth/passkeys/login/begin Rate-limits and starts passkey login; records a failure on any error.
POST /api/auth/passkeys/login/finish Verifies the assertion, updates the credential counter, and issues a portal session.
POST /api/auth/passkeys/elevate/begin Starts Owner elevation; 403 unless the signed-in user is an Owner with passkeys.
POST /api/auth/passkeys/elevate/finish Completes Owner elevation only when the assertion is user-verified.
POST /api/auth/totp/login Completes password+TOTP login and issues a portal session cookie.
POST /api/auth/totp/enroll/begin Starts TOTP enrollment: new pending secret, otpauth URL, and QR SVG.
POST /api/auth/totp/enroll/finish Confirms the pending secret with a valid code and sets users.totp_enabled.
GET /api/auth/totp GET /api/auth/totp — whether TOTP is confirmed for this user.
DELETE /api/auth/totp Disables TOTP after recent reauth and deletes sealed secrets.
GET /api/auth/mfa-policy Current MFA policy (require_second_factor).
PUT /api/auth/mfa-policy Persists daemon.auth.require_second_factor to config.toml.
GET /api/auth/player-passwords Lists the caller's player passwords.
POST /api/auth/player-passwords Makes a player password for the caller and shows it once.
DELETE /api/auth/player-passwords/{id} Removes one of the caller's player passwords and signs out every app it signed in.
GET /api/auth/player-consent What the consent page shows.
POST /api/auth/player-consent Approves or declines an app's browser sign-in.

Library users and their claim tickets.

Route Summary
GET /api/users List first-party users (operator or administrator provisioner).
POST /api/users Owner/admin or operator creates a user and optional invite magic link.
DELETE /api/users/{id} Delete a user and their personal data (wishlist / links / sessions); keep acquired books.
PATCH /api/users/{id} Patch role/status/display/login/email for a first-party user (provisioner).
GET /api/users/default-scope Reads the library's default scope, which patrons without their own follow.
PUT /api/users/default-scope Replaces the library's default scope. Every patron without their own scope follows the change at once.
GET /api/users/{id}/scope Reads which part of the library a patron sees.
PUT /api/users/{id}/scope Gives a patron their own scope, or returns them to the library's default with "scope": null.
GET /api/users/default-controls Reads the library's default member controls, which every Member follows unless a control is set for them alone.
PUT /api/users/default-controls Replaces the library's default member controls. Every Member follows the change at once, except in the controls set for them alone; Administrators do not follow the default.
GET /api/users/{id}/controls Reads what a patron may do: the library's default, their own overrides, and what applies.
PUT /api/users/{id}/controls Sets the controls that differ for one patron; every other control follows the library's default for a Member and is allowed for an Administrator.
GET /api/users/default-admin-controls Reads the library's default Administrator switches.
PATCH /api/users/default-admin-controls Changes the named default Administrator switches; the others keep their stored value. Every Administrator follows the change at once, except in the switches set for them alone. Only an Owner or the operator may.
GET /api/users/{id}/admin-controls Reads what an Administrator may do: the library's default, their own overrides, and what applies. An Administrator may read their own.
PATCH /api/users/{id}/admin-controls Changes the named switches for one Administrator; every switch it does not name keeps what it had. Only an Owner or the operator may, and switches stored for someone who is not an Administrator apply only if their role changes to Administrator.
POST /api/users/{id}/claim-ticket Mint a fresh local claim ticket for an active first-party user.
POST /api/users/{id}/reset-password Invalidate a user's password, revoke sessions, and mint a claim ticket for reset.
GET /api/avatars/gravatar/{hash} Serves a user's Gravatar as a 128 px JPEG through the cover service.
GET /api/users/{id}/avatar Serves a stored avatar JPEG for any authenticated household member.

Books in the library, scans and acquires.

Route Summary
POST /api/library/convert Queues a convert of stored books into another copy; returns the accepted job ids.
DELETE /api/config/nodes/{node_id} DELETE /api/config/nodes/{node_id}: remove a shared node (a shared branch, or any node sharing this database) that is no longer running from the library's node list. Only the operator (or an elevated Owner) may: it deletes the node and its rows, which is hard to undo. A running node, this node, or a branch is refused (a branch is revoked instead).
PUT /api/config/nodes/{node_id}/labels PUT /api/config/nodes/{node_id}/labels: replace a node's placement labels. The scheduler re-plans on the wakeup this publishes.
PUT /api/config/nodes/{node_id}/owner PUT /api/config/nodes/{node_id}/owner: assign or clear a node's owner. The owner may then edit that node's runtime settings without operator authority.
GET /api/config/library-consents GET /api/config/library-consents.
POST /api/config/libraries/{library_id}/scan POST /api/config/libraries/{library_id}/scan: asks the library to queue a scan for this node's owner (H-5). The owner's planner decides what that user may scan; the answer lists the queued job ids.
POST /api/config/libraries/{library_id}/jobs POST /api/config/libraries/{library_id}/jobs: the owner's view of jobs this node may see (those it would be trusted to claim).
POST /api/config/library-consents/approve POST /api/config/library-consents/approve.
POST /api/config/library-consents/revoke POST /api/config/library-consents/revoke.
GET /api/config/join GET /api/config/join.
POST /api/config/join/inspect POST /api/config/join/inspect.
POST /api/config/join/start POST /api/config/join/start.
POST /api/config/join/callback POST /api/config/join/callback: redeems the library's code with the sign-in's sealed verifier and keys. The pending sign-in is kept when the redeem fails for a reason a retry can fix (answered as 502 join_retry; the page offers Try again with the same code), and ended on success, refusal, or anything else.
POST /api/config/join/invite POST /api/config/join/invite: join with a pasted branch invite. The link is redeemed once and dropped; it is never logged or echoed. A library slower than [REDEEM_TIMEOUT] is answered 504 join_pending while the join carries on and starts its client when it lands.
POST /api/config/join/leave POST /api/config/join/leave: Leave library. The leave runs on its own task, so a request cut short (the client gone, or the API deadline) still records it once the library has been told.
GET /api/config/nodes GET /api/config/nodes: every node for an operator; the caller's own nodes for a node owner.
GET /api/config/shared-branches GET /api/config/shared-branches: the shared nodes (this one and its shared branches) for Settings → Shared branches, shaped like GET /api/config/nodes. The operator or an Owner sees every one (only the operator may remove one, with DELETE /api/config/nodes/{node_id}); another user only the ones they own, which the nodes listing already shows them. Branches are not listed.
PUT /api/config/nodes/{node_id}/runtime PUT /api/config/nodes/{node_id}/runtime: edit a node's label, budgets, or drain switch. Applies at that node's next heartbeat. A node owner may edit only the nodes it owns.
POST /api/library/scan Plans and enqueues a library scan; returns the accepted job ids.
POST /api/library/acquire Plans and enqueues acquire jobs; returns the accepted job ids.
PUT /api/library/listings/{id}/pin Pins a store listing to the edition it sells.
DELETE /api/library/listings/{id}/pin Removes a listing's pin.
GET /api/library/conflicts Pages the conflicts the resolver could not decide, for an Administrator to settle with a pin.
GET /api/library/editions/{id}/chapters/claims Lists every source's chapter claim for an edition, with its chapters.
GET /api/library/editions/{id}/chapters Reads the chapters an edition plays.
PUT /api/library/editions/{id}/chapters Sets an edition's chapters by hand.
DELETE /api/library/editions/{id}/chapters Removes an Administrator's chapter edit, so the edition plays the best remaining claim again.
PUT /api/library/editions/{id}/chapters/pin Pins one claim, so the edition plays it whatever the others say.
DELETE /api/library/editions/{id}/chapters/pin Removes the pin on an edition's chapters; the resolver chooses again.
POST /api/library/works/{id}/split Splits a work an automatic merge joined wrongly.
GET /api/library/works/{id}/tags Reads a work's library tags.
PUT /api/library/works/{id}/tags Replaces the tags an Administrator set on a work.
GET /api/library/collections Reads the library's collections.
PUT /api/library/collections Replaces the library's collections.
GET /api/config/node-invites GET /api/config/node-invites: every link for the operator or an Owner; the caller's own links for anyone else, and with ?mine=true.
POST /api/config/node-invites POST /api/config/node-invites: mint an enrollment link. Any user may mint one for themselves while branch enrollment is on; the operator or an Owner may mint for any active user.
DELETE /api/config/node-invites/{id} DELETE /api/config/node-invites/{id}: revoke an unredeemed link.
GET /api/config/branches GET /api/config/branches: this library's join settings: whether new branches may join, the transport mode, and the SPKI fingerprint a joining operator confirms in self_signed mode.
PUT /api/config/branches PUT /api/config/branches: turn "Let new branches join" on or off.
POST /api/config/branches/titles/remove POST /api/config/branches/titles/remove: removes the entries of titles from a branch that stopped sharing or left. Delivered files stay.
PUT /api/config/branches/members-books PUT /api/config/branches/members-books: turn this library's "Acquire all of this branch's members' books" on or off for one branch.
GET /api/config/join/sharing GET /api/config/join/sharing: Settings → Library for the operator or an Owner: every library this install is a branch of, with its two sharing settings ({libraries: [...]}).
POST /api/config/join/sharing POST /api/config/join/sharing: Settings → Library's sharing and work settings for one library this install is a branch of (the two book-sharing settings, the two work settings, and optionally "List my members' books"). The operator or an Owner (verified from the stored role); anyone else gets 403.
GET /api/config/join/window GET /api/config/join/window: "Books in other libraries" for the operator or an Owner: every book of each library this install is a branch of, or holds a library card for, merged by work, each edition marked when it is this install's person's ({libraries, cards, books}).
POST /api/config/join/connections POST /api/config/join/connections: "Add my connections to library".
POST /api/config/join/connections/disconnect POST /api/config/join/connections/disconnect: disconnects one of the person's store accounts here, and with everywhere in every linked library it was shared with.
POST /api/config/join/capacity POST /api/config/join/capacity: Settings → Library's job cap for one library this install is a branch of. The operator or an Owner (verified from the stored role); anyone else gets 403. The running link's share changes at once: its claims stop at the new share and its next heartbeat reports the library the new part of the machine. Jobs it already runs finish.
DELETE /api/config/node-credentials/{node_id} DELETE /api/config/node-credentials/{node_id}: revoke an enrolled host's credential so it can no longer connect.
GET /api/library/works Lists the library's works, one page at a time.
GET /api/library/works/{id} Reads one work with its editions, listings, holdings and the caller's own state.
PUT /api/library/works/{id}/state Changes the caller's own state for a work: finished, ratings and tags.
GET /api/library/works/facets/{facet} Lists the values a facet has across the library's held works, with how many works have each, for the library page's filter menus. tag lists the caller's own tags (none for an operator token).
GET /api/library/editions/{id}/cover Serves the JPEG cover written beside an edition's acquired file on this node's local destination.
GET /api/library/editions/{id}/playback Reads whether and what the caller may play of an edition, with their own progress and bookmarks.
GET /api/library/editions/{id}/bookmarks Lists the caller's bookmarks in an edition.
POST /api/library/editions/{id}/bookmarks Adds a bookmark of the caller's in an edition.
GET /api/uploads Lists the caller's uploads, newest first.
POST /api/uploads Starts an upload from a manifest of the files to come.
GET /api/uploads/review Lists uploaded books stored under a new local edition because nothing strong identified them, for an Administrator to check and, when they are a known edition, pin.
GET /api/uploads/{id} Reads one of the caller's uploads with every file: how many bytes each has received (where to resume) and, once ingested, what became of it.
DELETE /api/uploads/{id} Cancels an upload that has not started ingesting and drops its bytes.
PATCH /api/uploads/{id}/files/{member_no} Sends bytes of one file, from the offset in the Upload-Offset header.
POST /api/uploads/{id}/commit Commits an upload whose files have all arrived: queues its ingest job.

Play sessions, audio streams, listening progress and bookmarks.

Route Summary
POST /api/playback/sessions Opens a play session for the caller.
POST /api/playback/sessions/{id}/sync Reports where the caller is in a playing session.
POST /api/playback/sessions/{id}/close Sends a session's last report and ends it.
GET /api/playback/sessions/{id}/tracks/{index} Streams one track of a play session.
GET /api/playback/progress Lists the caller's progress, most recently played first.
PUT /api/playback/progress/{edition_id} Sets the caller's progress in an edition outright: Mark finished, Start over, or a place chosen with no session open.
DELETE /api/playback/progress/{edition_id} Forgets the caller's progress in an edition. The work's finished flag is left as it is.
PUT /api/playback/bookmarks/{id} Changes one of the caller's bookmarks.
DELETE /api/playback/bookmarks/{id} Removes one of the caller's bookmarks.

Recommendations, catalog search and title metadata.

Route Summary
POST /api/discover/sync-listening Enqueues a listening-progress sync; 400 when no capable integrations are loaded.
GET /api/covers/{token}/{size} Serves one size of a cover the API linked to.
GET /api/images/{token} Serves a signed image that is not a cover as a 128 px JPEG.
GET /api/stores/{id}/icon Serves a storefront's or integration's icon as a 128 px JPEG through the cover service.
GET /api/discover/status Reports whether the caller's Discover shelves are stored yet, so provisioning can wait for a new visitor's shelves before sending them in.
POST /api/discover/refresh Queues a storefront fetch and ranking for the caller's shelves now, as the Discover page's Refresh button asks. Unchanged store calls answer from the day's cache, so a refresh is cheap; a fetch already waiting absorbs the request.
GET /api/discover/recommendations Returns the caller's stored Discover shelves; never builds them on the request.
POST /api/discover/purchase-hints Resolves storefront price/availability for one title, forcing server-side preferred stores.
POST /api/discover/purchase-hints/batch Resolves up to 24 purchase-hint queries with caller-derived preferred stores.
GET /api/discover/search Runs a multi-store catalog search with a 15s wall budget and empty-query short circuit.
POST /api/discover/title-meta Resolves Audnexus-style title metadata for one query.
POST /api/discover/title-meta/batch Resolves up to 24 title-metadata queries without failing the whole batch on one error.
POST /api/discover/title-reviews Fetches Audnexus reviews for an ASIN; rejects an empty ASIN with 400.

Titles users have asked for.

Route Summary
GET /api/wishlist Lists open wishlist rows for the caller (portal identity or operator-owned).
POST /api/wishlist Creates a wishlist / title-request row for the authenticated caller.
DELETE /api/wishlist/{uuid} Cancels an open wishlist item the caller owns; others get 403.
GET /api/request-queue Reads the shared open-request queue from its stored ranking.
POST /api/branch-requests Asks a branch for a book it listed.
POST /api/download-requests Asks this library to download a book it holds but has no copy of.

Queued and running control-plane jobs.

Route Summary
GET /api/jobs Returns durable scan/acquire/listen_sync jobs, newest first.
POST /api/jobs/{id}/cancel Cancel a pending job or request cooperative stop of a running job.

Channels, routing rules, patron offers, the delivery log, and each user's own notification settings and inbox.

Route Summary
GET /api/notifications/catalog Lists the notification types and the notifier instances the routing screens pick from.
GET /api/notifications/channels Lists the library's channels.
POST /api/notifications/channels Makes a library channel on a notifier instance.
DELETE /api/notifications/channels/{id} Deletes a channel with its routes and delivery-log rows.
PATCH /api/notifications/channels/{id} Renames a channel.
POST /api/notifications/channels/{id}/resume Resumes a channel repeated failures paused, and clears its failure count.
POST /api/notifications/channels/{id}/test Sends a test notification to one channel, whatever the routes say.
GET /api/notifications/routes Lists every routing rule.
PUT /api/notifications/routes/{type} Replaces the routes of one operational type.
GET /api/notifications/offers Lists which notifiers patrons may pick for each patron type.
PUT /api/notifications/offers/{type} Replaces which notifiers patrons may pick for one patron type.
GET /api/notifications/deliveries Pages the delivery log, newest first.
GET /api/me/notifications Reads the caller's notification settings: the types they can receive beyond the inbox, what they chose, and their destinations.
PUT /api/me/notifications/choices/{type} Sets what the caller gets for one patron type, replacing the defaults.
DELETE /api/me/notifications/choices/{type} Drops the caller's choice for one type, so the defaults apply again.
POST /api/me/notifications/destinations Adds a personal destination for the caller.
DELETE /api/me/notifications/destinations/{id} Deletes one of the caller's destinations.
POST /api/me/notifications/destinations/{id}/resume Resumes one of the caller's destinations that repeated failures paused, and clears its failure count.
GET /api/me/notifications/inbox Pages the caller's inbox, newest first.
POST /api/me/notifications/inbox/read Marks one inbox entry, or all of them, read.

Domain events and their deliveries.

Route Summary
GET /api/events Returns recent domain-event outbox rows, newest first.
GET /api/events/deliveries Returns event deliveries, optionally filtered by state.
GET /api/queues Returns every queue the outbox or the live catalog knows about, with delivery counters and the consumers subscribed to it.
GET /api/queues/{name} Returns one queue's counters, consumers, recent messages, and deliveries.
POST /api/events/deliveries/{id}/retry Re-queue a dead-lettered delivery.
POST /api/events/deliveries/{id}/acknowledge Acknowledge a dead-lettered delivery (no further retry).
POST /api/events/deliveries/{id}/cancel Cancel a pending delivery or request cooperative stop of a running one.
POST /api/events/deliveries/{id}/resume Resume a suspended delivery (wake now, next claim uses resume_pending).

The web interface's live-updates socket.

Route Summary
GET /api/live GET /api/live.

Library and daemon snapshot.

Route Summary
GET /api/status Returns library counts, listen addresses, storage backends, and whether operator auth is on.
GET /api/status/media Returns the audio codecs, file types and output encodings this build's media worker handles.
GET /api/library-status GET /api/library-status: library-wide health every node administrator may see (node counts, committed capacity, active jobs, delivery backlog), plus detail for the nodes the caller may see.

Daemon settings and user preferences.

Route Summary
GET /api/settings Returns file-backed and runtime-effective Settings plus per-plugin groups.
PATCH /api/settings Validates, writes, and reloads allowlisted Settings keys under reload_lock.
GET /api/diagnostics/reports Lists the diagnostics reports this install sent, newest first, with the IDs the collector gave them.
GET /api/diagnostics/reports/{id} Reads a sent report back from the collector with its access code: the stored report (redacted, as sent), the GitHub issues tracking it and the fix, if one is recorded.
DELETE /api/diagnostics/reports/{id} Deletes the collector's stored copy of a sent report. The collector keeps its one-line index entry and issue links, so the report still counts; the install's history notes the deletion.
POST /api/database/migrate Copies library rows between database plugins and optionally switches [database].plugin.
GET /api/preferences Loads preferences for the caller with a 3s timeout, creating defaults when missing.
PATCH /api/preferences Merges a preferences PATCH onto the caller’s stored row and writes it back.

Plugin packages, instances, consent and deployment.

Route Summary
GET /api/config/plugin-instances GET /api/config/plugin-instances.
POST /api/config/plugin-instances POST /api/config/plugin-instances: a second (non-default) instance of a plugin, with an empty document so schema defaults apply. With node_id, the instance is local to that node.
DELETE /api/config/plugin-instances/{id} DELETE /api/config/plugin-instances/{id}: removes an instance that has no deployment left.
GET /api/config/plugin-instances/{id}/config GET /api/config/plugin-instances/{id}/config.
PUT /api/config/plugin-instances/{id}/config PUT /api/config/plugin-instances/{id}/config.
GET /api/config/plugin-instances/{id}/filter GET /api/config/plugin-instances/{id}/filter: which books the storage destination takes.
PUT /api/config/plugin-instances/{id}/filter PUT /api/config/plugin-instances/{id}/filter: replaces which books the storage destination takes. Acquires that start afterwards use it; files already stored stay where they are.
GET /api/config/plugin-instances/{id}/intake GET /api/config/plugin-instances/{id}/intake: whether the storage instance is a drop folder, and its settings.
PUT /api/config/plugin-instances/{id}/intake PUT /api/config/plugin-instances/{id}/intake: makes the storage instance a drop folder with these settings, or changes a drop folder's settings. Turning a destination into a drop folder is refused while the instance is deployed on any node.
DELETE /api/config/plugin-instances/{id}/intake DELETE /api/config/plugin-instances/{id}/intake: makes a drop folder a destination again. Refused while the instance is deployed on any node.
PUT /api/config/plugin-instances/{id}/deployments/{node_id} PUT /api/config/plugin-instances/{id}/deployments/{node_id}: the Deployed switch. Creates the row when the node has none.
PUT /api/config/plugin-instances/{id}/placement PUT /api/config/plugin-instances/{id}/placement: hand the instance's deployments to the scheduler with a replica count and constraints.
DELETE /api/config/plugin-instances/{id}/placement DELETE /api/config/plugin-instances/{id}/placement: return the instance to hand-managed deployments; its deployments stay as they are.
GET /api/config/plugins GET /api/config/plugins: every installed plugin.
POST /api/config/plugins POST /api/config/plugins: install (and maybe activate) a version.
GET /api/config/plugins/{key} GET /api/config/plugins/{key}: one installed plugin with its pinned settings schema.
DELETE /api/config/plugins/{key} DELETE /api/config/plugins/{key}: uninstall the plugin (active version cleared, placements dropped, every deployment absent).
PUT /api/config/plugins/{key}/active PUT /api/config/plugins/{key}/active: activate, update, or roll back.
POST /api/config/plugins/{key}/versions/{version}/approve POST /api/config/plugins/{key}/versions/{version}/approve: record the version's requested consent as approved for every node.
GET /api/plugins/{id}/consent Loads the consent dialog for one plugin, including coverage against the stored grant.
POST /api/plugins/{id}/consent Persists an approved plugin grant after validating operator overrides.
GET /api/plugins/{kind}/{id}/logo Serve an embedded plugin.toml logo file from under the plugin install root.

Live configuration domains and reloads.

Route Summary
POST /api/config/reload Reloads config.toml and republishes daemon runtime without a process restart.
GET /api/config/domains/core.events GET /api/config/domains/core.events.
PUT /api/config/domains/core.events PUT /api/config/domains/core.events.
GET /api/config/domains/core.output GET /api/config/domains/core.output.
PUT /api/config/domains/core.output PUT /api/config/domains/core.output.
GET /api/config/ingress GET /api/config/ingress: the library's public address settings.
POST /api/config/ingress POST /api/config/ingress: turns ingress on or off, sets what it exposes, or accepts a reported origin. The deployment reconciler then starts or stops the instance.
GET /api/config/clerk GET /api/config/clerk.
POST /api/config/clerk/inspect POST /api/config/clerk/inspect.
POST /api/config/clerk/start POST /api/config/clerk/start.
POST /api/config/clerk/callback POST /api/config/clerk/callback: redeems the library's code with the sign-in's verifier, seals the card and starts reading the person's books. The pending sign-in is ended whatever the outcome; a failed one is started again.
POST /api/config/clerk/sign-out POST /api/config/clerk/sign-out: ends a library card at the library when it can be reached, then drops the card, the books read with it, and the library from the list here whatever the library answered.
POST /api/config/clerk/request POST /api/config/clerk/request: asks a library this install holds a card for, with the card, to get a copy of a book: from one of its branches (from branch) or by downloading it on one of its own store accounts (from library).
GET /api/config/branch-enrollment GET /api/config/branch-enrollment: whether branch nodes may enroll.
PUT /api/config/branch-enrollment PUT /api/config/branch-enrollment: turn branch enrollment on or off. The operator may always; a user only while the stored role is an active Owner.
GET /api/config/master-key GET /api/config/master-key.
POST /api/config/master-key/recovery-copy POST /api/config/master-key/recovery-copy.
PUT /api/config/master-key/recovery-copy/state PUT /api/config/master-key/recovery-copy/state.

Store accounts a library user connects (the Accounts page).

Route Summary
POST /api/portal/redeem Redeems a claim ticket, optionally setting a first password, and sets the session cookie.
POST /api/portal/login/integration Authenticates against an enabled integration and mints a portal session.
POST /api/portal/logout Revokes the portal session row and clears the session cookie.
GET /api/portal/me Returns the signed-in portal identity, or 401 when the cookie is missing or expired.
GET /api/portal/sources Lists the deployed content sources (one per plugin, through its default instance) with portal auth mode, config options, and brand colors.
POST /api/portal/sources/{id}/login Connects a password storefront, upserts the account, and links it to the signed-in identity.
POST /api/portal/sources/{id}/oauth/start Starts interactive OAuth for an OAuth storefront and returns the browser login URL.
POST /api/portal/libro/login (deprecated) Legacy POST /libro/login alias that forwards to the Libro password-login handler.
POST /api/portal/audible/start (deprecated) Legacy POST /audible/start alias that forwards to Audible OAuth start.
GET /api/portal/connections Lists store accounts linked to the signed-in identity, including disabled sources.
POST /api/portal/sources/{source}/connections/{account_id}/revoke Marks a store account revoked, signs it out, deletes its stored credentials, then unlinks it.
POST /api/portal/sources/{source}/connections/{account_id}/pace Changes how fast Bookclerk downloads from one of the caller's store accounts when it starts the downloads itself, and returns the result.

A clerk's sign-in as a person: redeem an approved code for a session token.

Route Summary
POST /api/clerk/v1/token POST /api/clerk/v1/token: redeem an approved clerk sign-in for a session token. The code is spent by any attempt, matching or not.
GET /api/clerk/v1/connect GET /api/clerk/v1/connect: upgrade to the clerk socket after the transport check and the library card.

Node-to-node enrollment, socket, artifacts and uploads; each route checks its own credential.

Route Summary
POST /api/node/v1/enroll POST /api/node/v1/enroll: redeem an enrollment link. Answers {library_id, node_id}; 403 transport_insecure when the connection fails the transport policy, 403 enrollment_refused for any link that does not redeem.
GET /api/node/v1/info GET /api/node/v1/info.
POST /api/node/v1/enroll/oauth POST /api/node/v1/enroll/oauth: redeem an approved branch sign-in. Answers {library_id, node_id} for a branch, plus connection and the sealed bootstrap for a shared branch; 403 transport_insecure for a refused connection, 403 enrollment_refused for a code that does not redeem (unknown, used, expired, another client's, a wrong verifier or redirect URI, enrollment off, or the user no longer active).
GET /api/node/v1/connect GET /api/node/v1/connect: upgrade to the branch-node socket after the transport check. 403 transport_insecure for a refused connection, 400 subprotocol_required without [SUBPROTOCOL].
GET /api/node/v1/artifacts/{sha256} GET /api/node/v1/artifacts/{sha256}.
PUT /api/node/v1/uploads/{upload_id}/files/{index} PUT /api/node/v1/uploads/{upload_id}/files/{index}.
POST /api/node/v1/uploads/{upload_id}/commit POST /api/node/v1/uploads/{upload_id}/commit.

Downloads of an edition's files the library already holds, by a branch or clerk it granted the copy to; the grant's token is the credential.

Route Summary
GET /api/copies/v1/{copy_id}/files/{index} Streams one file of a granted copy.

Bookclerk as an OpenID Connect provider for other apps.

Route Summary
GET /.well-known/openid-configuration Serves the OIDC discovery document for registered clients.
GET /oidc/authorize Starts the authorization-code flow; unauthenticated users are sent to SPA login.
POST /oidc/authorize Completes consent: deny redirects with access_denied, grant issues a code.
POST /oidc/token Dispatches token grants. Every refusal is an RFC 6749 §5.2 JSON body ([TokenError]), never the branded error page, so a client library can tell invalid_grant from invalid_client.
GET /oidc/userinfo Returns sub / name / preferred_username for a valid access JWT.
POST /oidc/revoke Best-effort refresh-token revoke; always returns 200 per RFC 7009.
GET /api/auth/oidc/clients Owner/operator list of Bookclerk-as-IdP clients (secrets never included).
POST /api/auth/oidc/clients Create a client; confidential clients return the generated secret once.
PUT /api/auth/oidc/clients/{client_id} Update redirects, name, scopes, and public/confidential mode; switching a public client to confidential mints its secret, shown once.
DELETE /api/auth/oidc/clients/{client_id} Delete a registered client.
POST /api/auth/oidc/clients/{client_id}/rotate-secret Mint a new secret for a confidential client; plaintext is returned once.

The player API for audiobook apps written for an Audiobookshelf server (docs/server/player-apps.md).

Route Summary
GET /player/status Tells an app what the server is before it offers a sign-in.
GET /player/ping Answers that the player API is up, without a card.
GET /player/healthcheck Answers OK in plain text, without a card, for apps that check health.
POST /player/login Signs an app in with a username and a player password.
POST /player/auth/refresh Trades a refresh token for a new access and refresh token.
POST /player/logout Ends the card a refresh token (or the bearer access token) belongs to.
GET /player/auth/openid Starts the browser sign-in: answers a 302 to the library's consent page, which the app opens in a browser.
GET /player/auth/openid/mobile-redirect Sends the browser back to the app with the code (or the refusal).
GET /player/auth/openid/callback Trades a browser sign-in's code and PKCE verifier for a card.
GET /player/socket.io/ Opens the live socket.
GET /player/socket.io Opens the live socket for a client that drops the trailing slash; the same socket as [get_socket].
POST /player/api/authorize The signed-in patron, as at sign-in, without new tokens.
GET /player/api/me The signed-in patron.
GET /player/api/libraries Lists the libraries the patron may open: the one library.
GET /player/api/libraries/{id} Reads the library.
GET /player/api/libraries/{id}/items Lists the library's items, one page at a time.
GET /player/api/libraries/{id}/series Lists the library's series, one page at a time.
GET /player/api/libraries/{id}/authors Lists the library's authors.
GET /player/api/libraries/{id}/narrators Lists the library's narrators.
GET /player/api/libraries/{id}/collections Lists the library's collections: none yet.
GET /player/api/libraries/{id}/playlists Lists the patron's playlists in the library: none yet.
GET /player/api/libraries/{id}/personalized Reads the patron's home shelves: continue listening, recently added and listen again.
GET /player/api/libraries/{id}/search Searches the library's items, series, authors and narrators.
GET /player/api/libraries/{id}/stats Adds up the library's items and their runtimes.
GET /player/api/libraries/{id}/filterdata Reads the library's filter values.
GET /player/api/series/{id} Reads one series with its items and the patron's progress through it.
GET /player/api/authors/{id} Reads one author, with their items and series when asked for.
GET /player/api/items/{id} Reads one item; expanded, with its tracks and files.
POST /player/api/items/batch/get Reads several items at once.
GET /player/api/items/{id}/cover Serves an item's cover.
POST /player/api/items/{id}/play Opens a play session on an item.
GET /player/api/items/{id}/file/{ino} Streams one audio file of an item.
GET /player/api/items/{id}/file/{ino}/download Downloads one audio file of an item for offline listening.
POST /player/api/session/{id}/sync Reports where the patron is in a playing session.
POST /player/api/session/{id}/close Sends a session's last report, if any, and ends it.
POST /player/api/session/local Uploads one session an app played offline.
POST /player/api/session/local-all Uploads every session an app played offline.
GET /player/api/me/progress/{id} Reads the patron's progress on an item.
DELETE /player/api/me/progress/{id} Clears the patron's progress on an item.
PATCH /player/api/me/progress/{id} Sets the patron's progress on an item: a seek, Mark finished or Start over.
PATCH /player/api/me/progress/batch/update Sets the patron's progress on several items.
GET /player/api/me/items-in-progress Lists the items the patron is part way through, most recent first.
GET /player/api/me/listening-sessions Lists the patron's play sessions, newest first.
GET /player/api/me/listening-stats Sums the patron's listening, by item and by day.
POST /player/api/me/item/{id}/bookmark Adds a bookmark to an item.
PATCH /player/api/me/item/{id}/bookmark Renames the bookmark at a time in an item.
DELETE /player/api/me/item/{id}/bookmark/{time} Removes the bookmark at a time in an item.

Old unprefixed paths; use the /api/… route named in each.

Route Summary
GET /status (deprecated) Deprecated alias of GET /api/status.
POST /scan (deprecated) Deprecated alias of POST /api/library/scan.
POST /acquire (deprecated) Deprecated alias of POST /api/library/acquire.
GET /jobs (deprecated) Deprecated alias of GET /api/jobs.
POST /jobs/{id}/cancel (deprecated) Deprecated alias of POST /api/jobs/{id}/cancel.
POST /integrations/{id}/scan Enqueues a remote integration library scan; 404 if missing, 400 if unsupported.

Schemas

Request and response bodies are described in Schemas.

Generated from crates/bookclerkd/openapi.json at main · View as Markdown