# Web API

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`.

## Quick start

The daemon listens on `http://127.0.0.1:8787` unless `daemon.listen` says otherwise. This request calls `GET /api/status` with the `operatorToken` credential; [Authentication](#authentication) says where to get it.

```console
$ curl 'http://127.0.0.1:8787/api/status' \
    -H 'Authorization: Bearer <operatorToken>'
```

[`GET /api/status`](/docs/server/api/status/index.md#get-apistatus) describes the response.

## 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

### [Health](/docs/server/api/health/index.md)

Liveness.

| Route | Summary |
| --- | --- |
| [`GET /health`](/docs/server/api/health/index.md#get-health) | Serves `GET /health` with a static `ok` payload for liveness probes. |

### [Webhooks](/docs/server/api/webhooks/index.md)

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

| Route | Summary |
| --- | --- |
| [`POST /hooks/{token}/{name}`](/docs/server/api/webhooks/index.md#post-hookstokenname) | Stores one inbound webhook request for a plugin instance. |

### [Spec](/docs/server/api/spec/index.md)

This document.

| Route | Summary |
| --- | --- |
| [`GET /api/openapi.json`](/docs/server/api/spec/index.md#get-apiopenapijson) | Serves the OpenAPI document. |
| [`GET /api/openapi-3.0.json`](/docs/server/api/spec/index.md#get-apiopenapi-30json) | Serves the OpenAPI document restated as OpenAPI 3.0.3. |

### [Auth](/docs/server/api/auth/index.md)

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

| Route | Summary |
| --- | --- |
| [`POST /api/auth/login`](/docs/server/api/auth/index.md#post-apiauthlogin) | Validates the operator token (throttled, constant-time) and issues a hashed session cookie. |
| [`GET /api/auth/signin`](/docs/server/api/auth/index.md#get-apiauthsignin) | Public sign-in picker: operator-token availability, SSO IdPs, integration logins. |
| [`POST /api/auth/tray-handoff/prepare`](/docs/server/api/auth/index.md#post-apiauthtray-handoffprepare) | Mint a single-use tray Open Bookclerk ticket (Bearer, direct loopback only). |
| [`GET /api/auth/tray-handoff`](/docs/server/api/auth/index.md#get-apiauthtray-handoff) | Consume the pending tray ticket and set a localhost operator session cookie. |
| [`GET /api/auth/me`](/docs/server/api/auth/index.md#get-apiauthme) | Resolves the caller and returns `/me` JSON; unauthenticated callers get 401. |
| [`POST /api/auth/elevate`](/docs/server/api/auth/index.md#post-apiauthelevate) | Owner portal session + password re-auth → short-lived elevated operator cookie. |
| [`DELETE /api/auth/elevate`](/docs/server/api/auth/index.md#delete-apiauthelevate) | End elevation by revoking the elevated operator session cookie. |
| [`POST /api/auth/bootstrap`](/docs/server/api/auth/index.md#post-apiauthbootstrap) | Operator-only bootstrap of the first Owner when none exist. |
| [`PUT /api/auth/password`](/docs/server/api/auth/index.md#put-apiauthpassword) | Set password for self (portal) or target user (operator/admin); revokes sessions. |
| [`POST /api/auth/password`](/docs/server/api/auth/index.md#post-apiauthpassword) | Local password login → portal session cookie, or a TOTP challenge when enabled. |
| [`POST /api/auth/impersonate`](/docs/server/api/auth/index.md#post-apiauthimpersonate) | Operator (or elevated) session starts impersonating a User. |
| [`DELETE /api/auth/impersonate`](/docs/server/api/auth/index.md#delete-apiauthimpersonate) | Clear impersonation on the current operator session. |
| [`GET /api/auth/branch-consent`](/docs/server/api/auth/index.md#get-apiauthbranch-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`](/docs/server/api/auth/index.md#post-apiauthbranch-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`](/docs/server/api/auth/index.md#post-apiauthbranch-consentstep-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`](/docs/server/api/auth/index.md#get-apiauthclerk-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`](/docs/server/api/auth/index.md#post-apiauthclerk-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`](/docs/server/api/auth/index.md#post-apiauthlogout) | Revokes hashed operator and portal sessions and clears both cookies. |
| [`GET /api/auth/sessions`](/docs/server/api/auth/index.md#get-apiauthsessions) | List sessions for the current principal only (not every operator session). |
| [`DELETE /api/auth/sessions/{id}`](/docs/server/api/auth/index.md#delete-apiauthsessionsid) | Revoke a session by id. Operators may revoke any operator session; portal users may only revoke their own. |
| [`PATCH /api/auth/profile`](/docs/server/api/auth/index.md#patch-apiauthprofile) | Updates the caller's display name and/or email. |
| [`GET /api/auth/profile/catalog-listing`](/docs/server/api/auth/index.md#get-apiauthprofilecatalog-listing) | Reads whether the caller's books are listed to the libraries this install is a branch of. |
| [`PUT /api/auth/profile/catalog-listing`](/docs/server/api/auth/index.md#put-apiauthprofilecatalog-listing) | Sets whether the caller's books are listed to the libraries this install is a branch of. |
| [`PUT /api/auth/profile/avatar`](/docs/server/api/auth/index.md#put-apiauthprofileavatar) | Accepts a JPEG/PNG/WebP upload and stores it under `files_dir/avatars`. |
| [`DELETE /api/auth/profile/avatar`](/docs/server/api/auth/index.md#delete-apiauthprofileavatar) | Removes the caller's stored avatar, if any. |
| [`GET /api/auth/oidc/providers`](/docs/server/api/auth/index.md#get-apiauthoidcproviders) | Lists enabled IdPs for the login picker (id and display name only). |
| [`GET /api/auth/oidc/identities`](/docs/server/api/auth/index.md#get-apiauthoidcidentities) | Lists OIDC portal identities for the cookie-authenticated caller. |
| [`GET /api/auth/oidc/login`](/docs/server/api/auth/index.md#get-apiauthoidclogin) | Starts an OIDC login authorize redirect, honoring login throttle. |
| [`GET /api/auth/oidc/elevate`](/docs/server/api/auth/index.md#get-apiauthoidcelevate) | Starts an Owner re-auth elevate flow against a linked IdP (`prompt=login`). |
| [`GET /api/auth/oidc/callback`](/docs/server/api/auth/index.md#get-apiauthoidccallback) | GET callback (most IdPs); finishes the code exchange. |
| [`POST /api/auth/oidc/callback`](/docs/server/api/auth/index.md#post-apiauthoidccallback) | POST callback (Apple `form_post`); finishes the code exchange. |
| [`GET /api/auth/oidc/config`](/docs/server/api/auth/index.md#get-apiauthoidcconfig) | Operator GET: broker settings plus secret-presence flags (never plaintext). |
| [`PUT /api/auth/oidc/config`](/docs/server/api/auth/index.md#put-apiauthoidcconfig) | Operator-only PUT: writes next-generation sealed secrets, then publishes config.toml. |
| [`GET /api/auth/passkeys`](/docs/server/api/auth/index.md#get-apiauthpasskeys) | Lists this user's stored passkeys as `{ id, credential_id }` rows. |
| [`POST /api/auth/passkeys/register/begin`](/docs/server/api/auth/index.md#post-apiauthpasskeysregisterbegin) | Starts passkey registration (skips reauth only for first local-only setup). |
| [`POST /api/auth/passkeys/register/finish`](/docs/server/api/auth/index.md#post-apiauthpasskeysregisterfinish) | Completes registration, stores the passkey, and revokes elevated operator sessions. |
| [`DELETE /api/auth/passkeys/{id}`](/docs/server/api/auth/index.md#delete-apiauthpasskeysid) | Deletes one passkey after recent reauth; 404 when the id is not this user's. |
| [`POST /api/auth/passkeys/login/begin`](/docs/server/api/auth/index.md#post-apiauthpasskeysloginbegin) | Rate-limits and starts passkey login; records a failure on any error. |
| [`POST /api/auth/passkeys/login/finish`](/docs/server/api/auth/index.md#post-apiauthpasskeysloginfinish) | Verifies the assertion, updates the credential counter, and issues a portal session. |
| [`POST /api/auth/passkeys/elevate/begin`](/docs/server/api/auth/index.md#post-apiauthpasskeyselevatebegin) | Starts Owner elevation; 403 unless the signed-in user is an Owner with passkeys. |
| [`POST /api/auth/passkeys/elevate/finish`](/docs/server/api/auth/index.md#post-apiauthpasskeyselevatefinish) | Completes Owner elevation only when the assertion is user-verified. |
| [`POST /api/auth/totp/login`](/docs/server/api/auth/index.md#post-apiauthtotplogin) | Completes password+TOTP login and issues a portal session cookie. |
| [`POST /api/auth/totp/enroll/begin`](/docs/server/api/auth/index.md#post-apiauthtotpenrollbegin) | Starts TOTP enrollment: new pending secret, otpauth URL, and QR SVG. |
| [`POST /api/auth/totp/enroll/finish`](/docs/server/api/auth/index.md#post-apiauthtotpenrollfinish) | Confirms the pending secret with a valid code and sets `users.totp_enabled`. |
| [`GET /api/auth/totp`](/docs/server/api/auth/index.md#get-apiauthtotp) | GET `/api/auth/totp` — whether TOTP is confirmed for this user. |
| [`DELETE /api/auth/totp`](/docs/server/api/auth/index.md#delete-apiauthtotp) | Disables TOTP after recent reauth and deletes sealed secrets. |
| [`GET /api/auth/mfa-policy`](/docs/server/api/auth/index.md#get-apiauthmfa-policy) | Current MFA policy (`require_second_factor`). |
| [`PUT /api/auth/mfa-policy`](/docs/server/api/auth/index.md#put-apiauthmfa-policy) | Persists `daemon.auth.require_second_factor` to `config.toml`. |
| [`GET /api/auth/player-passwords`](/docs/server/api/auth/index.md#get-apiauthplayer-passwords) | Lists the caller's player passwords. |
| [`POST /api/auth/player-passwords`](/docs/server/api/auth/index.md#post-apiauthplayer-passwords) | Makes a player password for the caller and shows it once. |
| [`DELETE /api/auth/player-passwords/{id}`](/docs/server/api/auth/index.md#delete-apiauthplayer-passwordsid) | Removes one of the caller's player passwords and signs out every app it signed in. |
| [`GET /api/auth/player-consent`](/docs/server/api/auth/index.md#get-apiauthplayer-consent) | What the consent page shows. |
| [`POST /api/auth/player-consent`](/docs/server/api/auth/index.md#post-apiauthplayer-consent) | Approves or declines an app's browser sign-in. |

### [Users](/docs/server/api/users/index.md)

Library users and their claim tickets.

| Route | Summary |
| --- | --- |
| [`GET /api/users`](/docs/server/api/users/index.md#get-apiusers) | List first-party users (operator or administrator provisioner). |
| [`POST /api/users`](/docs/server/api/users/index.md#post-apiusers) | Owner/admin or operator creates a user and optional invite magic link. |
| [`DELETE /api/users/{id}`](/docs/server/api/users/index.md#delete-apiusersid) | Delete a user and their personal data (wishlist / links / sessions); keep acquired books. |
| [`PATCH /api/users/{id}`](/docs/server/api/users/index.md#patch-apiusersid) | Patch role/status/display/login/email for a first-party user (provisioner). |
| [`GET /api/users/default-scope`](/docs/server/api/users/index.md#get-apiusersdefault-scope) | Reads the library's default scope, which patrons without their own follow. |
| [`PUT /api/users/default-scope`](/docs/server/api/users/index.md#put-apiusersdefault-scope) | Replaces the library's default scope. Every patron without their own scope follows the change at once. |
| [`GET /api/users/{id}/scope`](/docs/server/api/users/index.md#get-apiusersidscope) | Reads which part of the library a patron sees. |
| [`PUT /api/users/{id}/scope`](/docs/server/api/users/index.md#put-apiusersidscope) | Gives a patron their own scope, or returns them to the library's default with `"scope": null`. |
| [`GET /api/users/default-controls`](/docs/server/api/users/index.md#get-apiusersdefault-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`](/docs/server/api/users/index.md#put-apiusersdefault-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`](/docs/server/api/users/index.md#get-apiusersidcontrols) | Reads what a patron may do: the library's default, their own overrides, and what applies. |
| [`PUT /api/users/{id}/controls`](/docs/server/api/users/index.md#put-apiusersidcontrols) | 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`](/docs/server/api/users/index.md#get-apiusersdefault-admin-controls) | Reads the library's default Administrator switches. |
| [`PATCH /api/users/default-admin-controls`](/docs/server/api/users/index.md#patch-apiusersdefault-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`](/docs/server/api/users/index.md#get-apiusersidadmin-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`](/docs/server/api/users/index.md#patch-apiusersidadmin-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`](/docs/server/api/users/index.md#post-apiusersidclaim-ticket) | Mint a fresh local claim ticket for an active first-party user. |
| [`POST /api/users/{id}/reset-password`](/docs/server/api/users/index.md#post-apiusersidreset-password) | Invalidate a user's password, revoke sessions, and mint a claim ticket for reset. |
| [`GET /api/avatars/gravatar/{hash}`](/docs/server/api/users/index.md#get-apiavatarsgravatarhash) | Serves a user's Gravatar as a 128 px JPEG through the cover service. |
| [`GET /api/users/{id}/avatar`](/docs/server/api/users/index.md#get-apiusersidavatar) | Serves a stored avatar JPEG for any authenticated household member. |

### [Library](/docs/server/api/library/index.md)

Books in the library, scans and acquires.

| Route | Summary |
| --- | --- |
| [`POST /api/library/convert`](/docs/server/api/library/index.md#post-apilibraryconvert) | Queues a convert of stored books into another copy; returns the accepted job ids. |
| [`DELETE /api/config/nodes/{node_id}`](/docs/server/api/library/index.md#delete-apiconfignodesnode_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`](/docs/server/api/library/index.md#put-apiconfignodesnode_idlabels) | `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`](/docs/server/api/library/index.md#put-apiconfignodesnode_idowner) | `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`](/docs/server/api/library/index.md#get-apiconfiglibrary-consents) | `GET /api/config/library-consents`. |
| [`POST /api/config/libraries/{library_id}/scan`](/docs/server/api/library/index.md#post-apiconfiglibrarieslibrary_idscan) | `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`](/docs/server/api/library/index.md#post-apiconfiglibrarieslibrary_idjobs) | `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`](/docs/server/api/library/index.md#post-apiconfiglibrary-consentsapprove) | `POST /api/config/library-consents/approve`. |
| [`POST /api/config/library-consents/revoke`](/docs/server/api/library/index.md#post-apiconfiglibrary-consentsrevoke) | `POST /api/config/library-consents/revoke`. |
| [`GET /api/config/join`](/docs/server/api/library/index.md#get-apiconfigjoin) | `GET /api/config/join`. |
| [`POST /api/config/join/inspect`](/docs/server/api/library/index.md#post-apiconfigjoininspect) | `POST /api/config/join/inspect`. |
| [`POST /api/config/join/start`](/docs/server/api/library/index.md#post-apiconfigjoinstart) | `POST /api/config/join/start`. |
| [`POST /api/config/join/callback`](/docs/server/api/library/index.md#post-apiconfigjoincallback) | `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`](/docs/server/api/library/index.md#post-apiconfigjoininvite) | `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`](/docs/server/api/library/index.md#post-apiconfigjoinleave) | `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`](/docs/server/api/library/index.md#get-apiconfignodes) | `GET /api/config/nodes`: every node for an operator; the caller's own nodes for a node owner. |
| [`GET /api/config/shared-branches`](/docs/server/api/library/index.md#get-apiconfigshared-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`](/docs/server/api/library/index.md#put-apiconfignodesnode_idruntime) | `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`](/docs/server/api/library/index.md#post-apilibraryscan) | Plans and enqueues a library scan; returns the accepted job ids. |
| [`POST /api/library/acquire`](/docs/server/api/library/index.md#post-apilibraryacquire) | Plans and enqueues acquire jobs; returns the accepted job ids. |
| [`PUT /api/library/listings/{id}/pin`](/docs/server/api/library/index.md#put-apilibrarylistingsidpin) | Pins a store listing to the edition it sells. |
| [`DELETE /api/library/listings/{id}/pin`](/docs/server/api/library/index.md#delete-apilibrarylistingsidpin) | Removes a listing's pin. |
| [`GET /api/library/conflicts`](/docs/server/api/library/index.md#get-apilibraryconflicts) | Pages the conflicts the resolver could not decide, for an Administrator to settle with a pin. |
| [`GET /api/library/editions/{id}/chapters/claims`](/docs/server/api/library/index.md#get-apilibraryeditionsidchaptersclaims) | Lists every source's chapter claim for an edition, with its chapters. |
| [`GET /api/library/editions/{id}/chapters`](/docs/server/api/library/index.md#get-apilibraryeditionsidchapters) | Reads the chapters an edition plays. |
| [`PUT /api/library/editions/{id}/chapters`](/docs/server/api/library/index.md#put-apilibraryeditionsidchapters) | Sets an edition's chapters by hand. |
| [`DELETE /api/library/editions/{id}/chapters`](/docs/server/api/library/index.md#delete-apilibraryeditionsidchapters) | Removes an Administrator's chapter edit, so the edition plays the best remaining claim again. |
| [`PUT /api/library/editions/{id}/chapters/pin`](/docs/server/api/library/index.md#put-apilibraryeditionsidchapterspin) | Pins one claim, so the edition plays it whatever the others say. |
| [`DELETE /api/library/editions/{id}/chapters/pin`](/docs/server/api/library/index.md#delete-apilibraryeditionsidchapterspin) | Removes the pin on an edition's chapters; the resolver chooses again. |
| [`POST /api/library/works/{id}/split`](/docs/server/api/library/index.md#post-apilibraryworksidsplit) | Splits a work an automatic merge joined wrongly. |
| [`GET /api/library/works/{id}/tags`](/docs/server/api/library/index.md#get-apilibraryworksidtags) | Reads a work's library tags. |
| [`PUT /api/library/works/{id}/tags`](/docs/server/api/library/index.md#put-apilibraryworksidtags) | Replaces the tags an Administrator set on a work. |
| [`GET /api/library/collections`](/docs/server/api/library/index.md#get-apilibrarycollections) | Reads the library's collections. |
| [`PUT /api/library/collections`](/docs/server/api/library/index.md#put-apilibrarycollections) | Replaces the library's collections. |
| [`GET /api/config/node-invites`](/docs/server/api/library/index.md#get-apiconfignode-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`](/docs/server/api/library/index.md#post-apiconfignode-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}`](/docs/server/api/library/index.md#delete-apiconfignode-invitesid) | `DELETE /api/config/node-invites/{id}`: revoke an unredeemed link. |
| [`GET /api/config/branches`](/docs/server/api/library/index.md#get-apiconfigbranches) | `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`](/docs/server/api/library/index.md#put-apiconfigbranches) | `PUT /api/config/branches`: turn "Let new branches join" on or off. |
| [`POST /api/config/branches/titles/remove`](/docs/server/api/library/index.md#post-apiconfigbranchestitlesremove) | `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`](/docs/server/api/library/index.md#put-apiconfigbranchesmembers-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`](/docs/server/api/library/index.md#get-apiconfigjoinsharing) | `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`](/docs/server/api/library/index.md#post-apiconfigjoinsharing) | `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`](/docs/server/api/library/index.md#get-apiconfigjoinwindow) | `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`](/docs/server/api/library/index.md#post-apiconfigjoinconnections) | `POST /api/config/join/connections`: "Add my connections to *library*". |
| [`POST /api/config/join/connections/disconnect`](/docs/server/api/library/index.md#post-apiconfigjoinconnectionsdisconnect) | `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`](/docs/server/api/library/index.md#post-apiconfigjoincapacity) | `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}`](/docs/server/api/library/index.md#delete-apiconfignode-credentialsnode_id) | `DELETE /api/config/node-credentials/{node_id}`: revoke an enrolled host's credential so it can no longer connect. |
| [`GET /api/library/works`](/docs/server/api/library/index.md#get-apilibraryworks) | Lists the library's works, one page at a time. |
| [`GET /api/library/works/{id}`](/docs/server/api/library/index.md#get-apilibraryworksid) | Reads one work with its editions, listings, holdings and the caller's own state. |
| [`PUT /api/library/works/{id}/state`](/docs/server/api/library/index.md#put-apilibraryworksidstate) | Changes the caller's own state for a work: finished, ratings and tags. |
| [`GET /api/library/works/facets/{facet}`](/docs/server/api/library/index.md#get-apilibraryworksfacetsfacet) | 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`](/docs/server/api/library/index.md#get-apilibraryeditionsidcover) | Serves the JPEG cover written beside an edition's acquired file on this node's local destination. |
| [`GET /api/library/editions/{id}/playback`](/docs/server/api/library/index.md#get-apilibraryeditionsidplayback) | Reads whether and what the caller may play of an edition, with their own progress and bookmarks. |
| [`GET /api/library/editions/{id}/bookmarks`](/docs/server/api/library/index.md#get-apilibraryeditionsidbookmarks) | Lists the caller's bookmarks in an edition. |
| [`POST /api/library/editions/{id}/bookmarks`](/docs/server/api/library/index.md#post-apilibraryeditionsidbookmarks) | Adds a bookmark of the caller's in an edition. |
| [`GET /api/uploads`](/docs/server/api/library/index.md#get-apiuploads) | Lists the caller's uploads, newest first. |
| [`POST /api/uploads`](/docs/server/api/library/index.md#post-apiuploads) | Starts an upload from a manifest of the files to come. |
| [`GET /api/uploads/review`](/docs/server/api/library/index.md#get-apiuploadsreview) | 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}`](/docs/server/api/library/index.md#get-apiuploadsid) | 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}`](/docs/server/api/library/index.md#delete-apiuploadsid) | Cancels an upload that has not started ingesting and drops its bytes. |
| [`PATCH /api/uploads/{id}/files/{member_no}`](/docs/server/api/library/index.md#patch-apiuploadsidfilesmember_no) | Sends bytes of one file, from the offset in the `Upload-Offset` header. |
| [`POST /api/uploads/{id}/commit`](/docs/server/api/library/index.md#post-apiuploadsidcommit) | Commits an upload whose files have all arrived: queues its ingest job. |

### [Playback](/docs/server/api/playback/index.md)

Play sessions, audio streams, listening progress and bookmarks.

| Route | Summary |
| --- | --- |
| [`POST /api/playback/sessions`](/docs/server/api/playback/index.md#post-apiplaybacksessions) | Opens a play session for the caller. |
| [`POST /api/playback/sessions/{id}/sync`](/docs/server/api/playback/index.md#post-apiplaybacksessionsidsync) | Reports where the caller is in a playing session. |
| [`POST /api/playback/sessions/{id}/close`](/docs/server/api/playback/index.md#post-apiplaybacksessionsidclose) | Sends a session's last report and ends it. |
| [`GET /api/playback/sessions/{id}/tracks/{index}`](/docs/server/api/playback/index.md#get-apiplaybacksessionsidtracksindex) | Streams one track of a play session. |
| [`GET /api/playback/progress`](/docs/server/api/playback/index.md#get-apiplaybackprogress) | Lists the caller's progress, most recently played first. |
| [`PUT /api/playback/progress/{edition_id}`](/docs/server/api/playback/index.md#put-apiplaybackprogressedition_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}`](/docs/server/api/playback/index.md#delete-apiplaybackprogressedition_id) | Forgets the caller's progress in an edition. The work's finished flag is left as it is. |
| [`PUT /api/playback/bookmarks/{id}`](/docs/server/api/playback/index.md#put-apiplaybackbookmarksid) | Changes one of the caller's bookmarks. |
| [`DELETE /api/playback/bookmarks/{id}`](/docs/server/api/playback/index.md#delete-apiplaybackbookmarksid) | Removes one of the caller's bookmarks. |

### [Discover](/docs/server/api/discover/index.md)

Recommendations, catalog search and title metadata.

| Route | Summary |
| --- | --- |
| [`POST /api/discover/sync-listening`](/docs/server/api/discover/index.md#post-apidiscoversync-listening) | Enqueues a listening-progress sync; 400 when no capable integrations are loaded. |
| [`GET /api/covers/{token}/{size}`](/docs/server/api/discover/index.md#get-apicoverstokensize) | Serves one size of a cover the API linked to. |
| [`GET /api/images/{token}`](/docs/server/api/discover/index.md#get-apiimagestoken) | Serves a signed image that is not a cover as a 128 px JPEG. |
| [`GET /api/stores/{id}/icon`](/docs/server/api/discover/index.md#get-apistoresidicon) | Serves a storefront's or integration's icon as a 128 px JPEG through the cover service. |
| [`GET /api/discover/status`](/docs/server/api/discover/index.md#get-apidiscoverstatus) | 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`](/docs/server/api/discover/index.md#post-apidiscoverrefresh) | 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`](/docs/server/api/discover/index.md#get-apidiscoverrecommendations) | Returns the caller's stored Discover shelves; never builds them on the request. |
| [`POST /api/discover/purchase-hints`](/docs/server/api/discover/index.md#post-apidiscoverpurchase-hints) | Resolves storefront price/availability for one title, forcing server-side preferred stores. |
| [`POST /api/discover/purchase-hints/batch`](/docs/server/api/discover/index.md#post-apidiscoverpurchase-hintsbatch) | Resolves up to 24 purchase-hint queries with caller-derived preferred stores. |
| [`GET /api/discover/search`](/docs/server/api/discover/index.md#get-apidiscoversearch) | Runs a multi-store catalog search with a 15s wall budget and empty-query short circuit. |
| [`POST /api/discover/title-meta`](/docs/server/api/discover/index.md#post-apidiscovertitle-meta) | Resolves Audnexus-style title metadata for one query. |
| [`POST /api/discover/title-meta/batch`](/docs/server/api/discover/index.md#post-apidiscovertitle-metabatch) | Resolves up to 24 title-metadata queries without failing the whole batch on one error. |
| [`POST /api/discover/title-reviews`](/docs/server/api/discover/index.md#post-apidiscovertitle-reviews) | Fetches Audnexus reviews for an ASIN; rejects an empty ASIN with 400. |

### [Wishlist](/docs/server/api/wishlist/index.md)

Titles users have asked for.

| Route | Summary |
| --- | --- |
| [`GET /api/wishlist`](/docs/server/api/wishlist/index.md#get-apiwishlist) | Lists open wishlist rows for the caller (portal identity or operator-owned). |
| [`POST /api/wishlist`](/docs/server/api/wishlist/index.md#post-apiwishlist) | Creates a wishlist / title-request row for the authenticated caller. |
| [`DELETE /api/wishlist/{uuid}`](/docs/server/api/wishlist/index.md#delete-apiwishlistuuid) | Cancels an open wishlist item the caller owns; others get 403. |
| [`GET /api/request-queue`](/docs/server/api/wishlist/index.md#get-apirequest-queue) | Reads the shared open-request queue from its stored ranking. |
| [`POST /api/branch-requests`](/docs/server/api/wishlist/index.md#post-apibranch-requests) | Asks a branch for a book it listed. |
| [`POST /api/download-requests`](/docs/server/api/wishlist/index.md#post-apidownload-requests) | Asks this library to download a book it holds but has no copy of. |

### [Jobs](/docs/server/api/jobs/index.md)

Queued and running control-plane jobs.

| Route | Summary |
| --- | --- |
| [`GET /api/jobs`](/docs/server/api/jobs/index.md#get-apijobs) | Returns durable scan/acquire/listen_sync jobs, newest first. |
| [`POST /api/jobs/{id}/cancel`](/docs/server/api/jobs/index.md#post-apijobsidcancel) | Cancel a pending job or request cooperative stop of a running job. |

### [Notifications](/docs/server/api/notifications/index.md)

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

| Route | Summary |
| --- | --- |
| [`GET /api/notifications/catalog`](/docs/server/api/notifications/index.md#get-apinotificationscatalog) | Lists the notification types and the notifier instances the routing screens pick from. |
| [`GET /api/notifications/channels`](/docs/server/api/notifications/index.md#get-apinotificationschannels) | Lists the library's channels. |
| [`POST /api/notifications/channels`](/docs/server/api/notifications/index.md#post-apinotificationschannels) | Makes a library channel on a notifier instance. |
| [`DELETE /api/notifications/channels/{id}`](/docs/server/api/notifications/index.md#delete-apinotificationschannelsid) | Deletes a channel with its routes and delivery-log rows. |
| [`PATCH /api/notifications/channels/{id}`](/docs/server/api/notifications/index.md#patch-apinotificationschannelsid) | Renames a channel. |
| [`POST /api/notifications/channels/{id}/resume`](/docs/server/api/notifications/index.md#post-apinotificationschannelsidresume) | Resumes a channel repeated failures paused, and clears its failure count. |
| [`POST /api/notifications/channels/{id}/test`](/docs/server/api/notifications/index.md#post-apinotificationschannelsidtest) | Sends a test notification to one channel, whatever the routes say. |
| [`GET /api/notifications/routes`](/docs/server/api/notifications/index.md#get-apinotificationsroutes) | Lists every routing rule. |
| [`PUT /api/notifications/routes/{type}`](/docs/server/api/notifications/index.md#put-apinotificationsroutestype) | Replaces the routes of one operational type. |
| [`GET /api/notifications/offers`](/docs/server/api/notifications/index.md#get-apinotificationsoffers) | Lists which notifiers patrons may pick for each patron type. |
| [`PUT /api/notifications/offers/{type}`](/docs/server/api/notifications/index.md#put-apinotificationsofferstype) | Replaces which notifiers patrons may pick for one patron type. |
| [`GET /api/notifications/deliveries`](/docs/server/api/notifications/index.md#get-apinotificationsdeliveries) | Pages the delivery log, newest first. |
| [`GET /api/me/notifications`](/docs/server/api/notifications/index.md#get-apimenotifications) | 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}`](/docs/server/api/notifications/index.md#put-apimenotificationschoicestype) | Sets what the caller gets for one patron type, replacing the defaults. |
| [`DELETE /api/me/notifications/choices/{type}`](/docs/server/api/notifications/index.md#delete-apimenotificationschoicestype) | Drops the caller's choice for one type, so the defaults apply again. |
| [`POST /api/me/notifications/destinations`](/docs/server/api/notifications/index.md#post-apimenotificationsdestinations) | Adds a personal destination for the caller. |
| [`DELETE /api/me/notifications/destinations/{id}`](/docs/server/api/notifications/index.md#delete-apimenotificationsdestinationsid) | Deletes one of the caller's destinations. |
| [`POST /api/me/notifications/destinations/{id}/resume`](/docs/server/api/notifications/index.md#post-apimenotificationsdestinationsidresume) | Resumes one of the caller's destinations that repeated failures paused, and clears its failure count. |
| [`GET /api/me/notifications/inbox`](/docs/server/api/notifications/index.md#get-apimenotificationsinbox) | Pages the caller's inbox, newest first. |
| [`POST /api/me/notifications/inbox/read`](/docs/server/api/notifications/index.md#post-apimenotificationsinboxread) | Marks one inbox entry, or all of them, read. |

### [Events](/docs/server/api/events/index.md)

Domain events and their deliveries.

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

### [Live](/docs/server/api/live/index.md)

The web interface's live-updates socket.

| Route | Summary |
| --- | --- |
| [`GET /api/live`](/docs/server/api/live/index.md#get-apilive) | `GET /api/live`. |

### [Status](/docs/server/api/status/index.md)

Library and daemon snapshot.

| Route | Summary |
| --- | --- |
| [`GET /api/status`](/docs/server/api/status/index.md#get-apistatus) | Returns library counts, listen addresses, storage backends, and whether operator auth is on. |
| [`GET /api/status/media`](/docs/server/api/status/index.md#get-apistatusmedia) | Returns the audio codecs, file types and output encodings this build's media worker handles. |
| [`GET /api/library-status`](/docs/server/api/status/index.md#get-apilibrary-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. |

### [Settings](/docs/server/api/settings/index.md)

Daemon settings and user preferences.

| Route | Summary |
| --- | --- |
| [`GET /api/settings`](/docs/server/api/settings/index.md#get-apisettings) | Returns file-backed and runtime-effective Settings plus per-plugin groups. |
| [`PATCH /api/settings`](/docs/server/api/settings/index.md#patch-apisettings) | Validates, writes, and reloads allowlisted Settings keys under `reload_lock`. |
| [`GET /api/diagnostics/reports`](/docs/server/api/settings/index.md#get-apidiagnosticsreports) | Lists the diagnostics reports this install sent, newest first, with the IDs the collector gave them. |
| [`GET /api/diagnostics/reports/{id}`](/docs/server/api/settings/index.md#get-apidiagnosticsreportsid) | 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}`](/docs/server/api/settings/index.md#delete-apidiagnosticsreportsid) | 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`](/docs/server/api/settings/index.md#post-apidatabasemigrate) | Copies library rows between database plugins and optionally switches `[database].plugin`. |
| [`GET /api/preferences`](/docs/server/api/settings/index.md#get-apipreferences) | Loads preferences for the caller with a 3s timeout, creating defaults when missing. |
| [`PATCH /api/preferences`](/docs/server/api/settings/index.md#patch-apipreferences) | Merges a preferences PATCH onto the caller’s stored row and writes it back. |

### [Plugins](/docs/server/api/plugins/index.md)

Plugin packages, instances, consent and deployment.

| Route | Summary |
| --- | --- |
| [`GET /api/config/plugin-instances`](/docs/server/api/plugins/index.md#get-apiconfigplugin-instances) | `GET /api/config/plugin-instances`. |
| [`POST /api/config/plugin-instances`](/docs/server/api/plugins/index.md#post-apiconfigplugin-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}`](/docs/server/api/plugins/index.md#delete-apiconfigplugin-instancesid) | `DELETE /api/config/plugin-instances/{id}`: removes an instance that has no deployment left. |
| [`GET /api/config/plugin-instances/{id}/config`](/docs/server/api/plugins/index.md#get-apiconfigplugin-instancesidconfig) | `GET /api/config/plugin-instances/{id}/config`. |
| [`PUT /api/config/plugin-instances/{id}/config`](/docs/server/api/plugins/index.md#put-apiconfigplugin-instancesidconfig) | `PUT /api/config/plugin-instances/{id}/config`. |
| [`GET /api/config/plugin-instances/{id}/filter`](/docs/server/api/plugins/index.md#get-apiconfigplugin-instancesidfilter) | `GET /api/config/plugin-instances/{id}/filter`: which books the storage destination takes. |
| [`PUT /api/config/plugin-instances/{id}/filter`](/docs/server/api/plugins/index.md#put-apiconfigplugin-instancesidfilter) | `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`](/docs/server/api/plugins/index.md#get-apiconfigplugin-instancesidintake) | `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`](/docs/server/api/plugins/index.md#put-apiconfigplugin-instancesidintake) | `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`](/docs/server/api/plugins/index.md#delete-apiconfigplugin-instancesidintake) | `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}`](/docs/server/api/plugins/index.md#put-apiconfigplugin-instancesiddeploymentsnode_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`](/docs/server/api/plugins/index.md#put-apiconfigplugin-instancesidplacement) | `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`](/docs/server/api/plugins/index.md#delete-apiconfigplugin-instancesidplacement) | `DELETE /api/config/plugin-instances/{id}/placement`: return the instance to hand-managed deployments; its deployments stay as they are. |
| [`GET /api/config/plugins`](/docs/server/api/plugins/index.md#get-apiconfigplugins) | `GET /api/config/plugins`: every installed plugin. |
| [`POST /api/config/plugins`](/docs/server/api/plugins/index.md#post-apiconfigplugins) | `POST /api/config/plugins`: install (and maybe activate) a version. |
| [`GET /api/config/plugins/{key}`](/docs/server/api/plugins/index.md#get-apiconfigpluginskey) | `GET /api/config/plugins/{key}`: one installed plugin with its pinned settings schema. |
| [`DELETE /api/config/plugins/{key}`](/docs/server/api/plugins/index.md#delete-apiconfigpluginskey) | `DELETE /api/config/plugins/{key}`: uninstall the plugin (active version cleared, placements dropped, every deployment `absent`). |
| [`PUT /api/config/plugins/{key}/active`](/docs/server/api/plugins/index.md#put-apiconfigpluginskeyactive) | `PUT /api/config/plugins/{key}/active`: activate, update, or roll back. |
| [`POST /api/config/plugins/{key}/versions/{version}/approve`](/docs/server/api/plugins/index.md#post-apiconfigpluginskeyversionsversionapprove) | `POST /api/config/plugins/{key}/versions/{version}/approve`: record the version's requested consent as approved for every node. |
| [`GET /api/plugins/{id}/consent`](/docs/server/api/plugins/index.md#get-apipluginsidconsent) | Loads the consent dialog for one plugin, including coverage against the stored grant. |
| [`POST /api/plugins/{id}/consent`](/docs/server/api/plugins/index.md#post-apipluginsidconsent) | Persists an approved plugin grant after validating operator overrides. |
| [`GET /api/plugins/{kind}/{id}/logo`](/docs/server/api/plugins/index.md#get-apipluginskindidlogo) | Serve an embedded `plugin.toml` `logo` file from under the plugin install root. |

### [Configuration](/docs/server/api/configuration/index.md)

Live configuration domains and reloads.

| Route | Summary |
| --- | --- |
| [`POST /api/config/reload`](/docs/server/api/configuration/index.md#post-apiconfigreload) | Reloads `config.toml` and republishes daemon runtime without a process restart. |
| [`GET /api/config/domains/core.events`](/docs/server/api/configuration/index.md#get-apiconfigdomainscoreevents) | `GET /api/config/domains/core.events`. |
| [`PUT /api/config/domains/core.events`](/docs/server/api/configuration/index.md#put-apiconfigdomainscoreevents) | `PUT /api/config/domains/core.events`. |
| [`GET /api/config/domains/core.output`](/docs/server/api/configuration/index.md#get-apiconfigdomainscoreoutput) | `GET /api/config/domains/core.output`. |
| [`PUT /api/config/domains/core.output`](/docs/server/api/configuration/index.md#put-apiconfigdomainscoreoutput) | `PUT /api/config/domains/core.output`. |
| [`GET /api/config/ingress`](/docs/server/api/configuration/index.md#get-apiconfigingress) | `GET /api/config/ingress`: the library's public address settings. |
| [`POST /api/config/ingress`](/docs/server/api/configuration/index.md#post-apiconfigingress) | `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`](/docs/server/api/configuration/index.md#get-apiconfigclerk) | `GET /api/config/clerk`. |
| [`POST /api/config/clerk/inspect`](/docs/server/api/configuration/index.md#post-apiconfigclerkinspect) | `POST /api/config/clerk/inspect`. |
| [`POST /api/config/clerk/start`](/docs/server/api/configuration/index.md#post-apiconfigclerkstart) | `POST /api/config/clerk/start`. |
| [`POST /api/config/clerk/callback`](/docs/server/api/configuration/index.md#post-apiconfigclerkcallback) | `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`](/docs/server/api/configuration/index.md#post-apiconfigclerksign-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`](/docs/server/api/configuration/index.md#post-apiconfigclerkrequest) | `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`](/docs/server/api/configuration/index.md#get-apiconfigbranch-enrollment) | `GET /api/config/branch-enrollment`: whether branch nodes may enroll. |
| [`PUT /api/config/branch-enrollment`](/docs/server/api/configuration/index.md#put-apiconfigbranch-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`](/docs/server/api/configuration/index.md#get-apiconfigmaster-key) | `GET /api/config/master-key`. |
| [`POST /api/config/master-key/recovery-copy`](/docs/server/api/configuration/index.md#post-apiconfigmaster-keyrecovery-copy) | `POST /api/config/master-key/recovery-copy`. |
| [`PUT /api/config/master-key/recovery-copy/state`](/docs/server/api/configuration/index.md#put-apiconfigmaster-keyrecovery-copystate) | `PUT /api/config/master-key/recovery-copy/state`. |

### [Accounts](/docs/server/api/accounts/index.md)

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

| Route | Summary |
| --- | --- |
| [`POST /api/portal/redeem`](/docs/server/api/accounts/index.md#post-apiportalredeem) | Redeems a claim ticket, optionally setting a first password, and sets the session cookie. |
| [`POST /api/portal/login/integration`](/docs/server/api/accounts/index.md#post-apiportalloginintegration) | Authenticates against an enabled integration and mints a portal session. |
| [`POST /api/portal/logout`](/docs/server/api/accounts/index.md#post-apiportallogout) | Revokes the portal session row and clears the session cookie. |
| [`GET /api/portal/me`](/docs/server/api/accounts/index.md#get-apiportalme) | Returns the signed-in portal identity, or 401 when the cookie is missing or expired. |
| [`GET /api/portal/sources`](/docs/server/api/accounts/index.md#get-apiportalsources) | 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`](/docs/server/api/accounts/index.md#post-apiportalsourcesidlogin) | Connects a password storefront, upserts the account, and links it to the signed-in identity. |
| [`POST /api/portal/sources/{id}/oauth/start`](/docs/server/api/accounts/index.md#post-apiportalsourcesidoauthstart) | Starts interactive OAuth for an OAuth storefront and returns the browser login URL. |
| [`POST /api/portal/libro/login`](/docs/server/api/accounts/index.md#post-apiportallibrologin) (deprecated) | Legacy `POST /libro/login` alias that forwards to the Libro password-login handler. |
| [`POST /api/portal/audible/start`](/docs/server/api/accounts/index.md#post-apiportalaudiblestart) (deprecated) | Legacy `POST /audible/start` alias that forwards to Audible OAuth start. |
| [`GET /api/portal/connections`](/docs/server/api/accounts/index.md#get-apiportalconnections) | Lists store accounts linked to the signed-in identity, including disabled sources. |
| [`POST /api/portal/sources/{source}/connections/{account_id}/revoke`](/docs/server/api/accounts/index.md#post-apiportalsourcessourceconnectionsaccount_idrevoke) | Marks a store account revoked, signs it out, deletes its stored credentials, then unlinks it. |
| [`POST /api/portal/sources/{source}/connections/{account_id}/pace`](/docs/server/api/accounts/index.md#post-apiportalsourcessourceconnectionsaccount_idpace) | Changes how fast Bookclerk downloads from one of the caller's store accounts when it starts the downloads itself, and returns the result. |

### [Clerk sign-in](/docs/server/api/clerk-sign-in/index.md)

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

| Route | Summary |
| --- | --- |
| [`POST /api/clerk/v1/token`](/docs/server/api/clerk-sign-in/index.md#post-apiclerkv1token) | `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`](/docs/server/api/clerk-sign-in/index.md#get-apiclerkv1connect) | `GET /api/clerk/v1/connect`: upgrade to the clerk socket after the transport check and the library card. |

### [Node protocol](/docs/server/api/node-protocol/index.md)

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

| Route | Summary |
| --- | --- |
| [`POST /api/node/v1/enroll`](/docs/server/api/node-protocol/index.md#post-apinodev1enroll) | `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`](/docs/server/api/node-protocol/index.md#get-apinodev1info) | `GET /api/node/v1/info`. |
| [`POST /api/node/v1/enroll/oauth`](/docs/server/api/node-protocol/index.md#post-apinodev1enrolloauth) | `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`](/docs/server/api/node-protocol/index.md#get-apinodev1connect) | `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}`](/docs/server/api/node-protocol/index.md#get-apinodev1artifactssha256) | `GET /api/node/v1/artifacts/{sha256}`. |
| [`PUT /api/node/v1/uploads/{upload_id}/files/{index}`](/docs/server/api/node-protocol/index.md#put-apinodev1uploadsupload_idfilesindex) | `PUT /api/node/v1/uploads/{upload_id}/files/{index}`. |
| [`POST /api/node/v1/uploads/{upload_id}/commit`](/docs/server/api/node-protocol/index.md#post-apinodev1uploadsupload_idcommit) | `POST /api/node/v1/uploads/{upload_id}/commit`. |

### [Library copies](/docs/server/api/library-copies/index.md)

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}`](/docs/server/api/library-copies/index.md#get-apicopiesv1copy_idfilesindex) | Streams one file of a granted copy. |

### [OIDC provider](/docs/server/api/oidc-provider/index.md)

Bookclerk as an OpenID Connect provider for other apps.

| Route | Summary |
| --- | --- |
| [`GET /.well-known/openid-configuration`](/docs/server/api/oidc-provider/index.md#get-well-knownopenid-configuration) | Serves the OIDC discovery document for registered clients. |
| [`GET /oidc/authorize`](/docs/server/api/oidc-provider/index.md#get-oidcauthorize) | Starts the authorization-code flow; unauthenticated users are sent to SPA login. |
| [`POST /oidc/authorize`](/docs/server/api/oidc-provider/index.md#post-oidcauthorize) | Completes consent: deny redirects with `access_denied`, grant issues a code. |
| [`POST /oidc/token`](/docs/server/api/oidc-provider/index.md#post-oidctoken) | 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`](/docs/server/api/oidc-provider/index.md#get-oidcuserinfo) | Returns `sub` / `name` / `preferred_username` for a valid access JWT. |
| [`POST /oidc/revoke`](/docs/server/api/oidc-provider/index.md#post-oidcrevoke) | Best-effort refresh-token revoke; always returns 200 per RFC 7009. |
| [`GET /api/auth/oidc/clients`](/docs/server/api/oidc-provider/index.md#get-apiauthoidcclients) | Owner/operator list of Bookclerk-as-IdP clients (secrets never included). |
| [`POST /api/auth/oidc/clients`](/docs/server/api/oidc-provider/index.md#post-apiauthoidcclients) | Create a client; confidential clients return the generated secret once. |
| [`PUT /api/auth/oidc/clients/{client_id}`](/docs/server/api/oidc-provider/index.md#put-apiauthoidcclientsclient_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}`](/docs/server/api/oidc-provider/index.md#delete-apiauthoidcclientsclient_id) | Delete a registered client. |
| [`POST /api/auth/oidc/clients/{client_id}/rotate-secret`](/docs/server/api/oidc-provider/index.md#post-apiauthoidcclientsclient_idrotate-secret) | Mint a new secret for a confidential client; plaintext is returned once. |

### [Player](/docs/server/api/player/index.md)

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

| Route | Summary |
| --- | --- |
| [`GET /player/status`](/docs/server/api/player/index.md#get-playerstatus) | Tells an app what the server is before it offers a sign-in. |
| [`GET /player/ping`](/docs/server/api/player/index.md#get-playerping) | Answers that the player API is up, without a card. |
| [`GET /player/healthcheck`](/docs/server/api/player/index.md#get-playerhealthcheck) | Answers `OK` in plain text, without a card, for apps that check health. |
| [`POST /player/login`](/docs/server/api/player/index.md#post-playerlogin) | Signs an app in with a username and a player password. |
| [`POST /player/auth/refresh`](/docs/server/api/player/index.md#post-playerauthrefresh) | Trades a refresh token for a new access and refresh token. |
| [`POST /player/logout`](/docs/server/api/player/index.md#post-playerlogout) | Ends the card a refresh token (or the bearer access token) belongs to. |
| [`GET /player/auth/openid`](/docs/server/api/player/index.md#get-playerauthopenid) | 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`](/docs/server/api/player/index.md#get-playerauthopenidmobile-redirect) | Sends the browser back to the app with the code (or the refusal). |
| [`GET /player/auth/openid/callback`](/docs/server/api/player/index.md#get-playerauthopenidcallback) | Trades a browser sign-in's code and PKCE verifier for a card. |
| [`GET /player/socket.io/`](/docs/server/api/player/index.md#get-playersocketio) | Opens the live socket. |
| [`GET /player/socket.io`](/docs/server/api/player/index.md#get-playersocketio-1) | Opens the live socket for a client that drops the trailing slash; the same socket as [`get_socket`]. |
| [`POST /player/api/authorize`](/docs/server/api/player/index.md#post-playerapiauthorize) | The signed-in patron, as at sign-in, without new tokens. |
| [`GET /player/api/me`](/docs/server/api/player/index.md#get-playerapime) | The signed-in patron. |
| [`GET /player/api/libraries`](/docs/server/api/player/index.md#get-playerapilibraries) | Lists the libraries the patron may open: the one library. |
| [`GET /player/api/libraries/{id}`](/docs/server/api/player/index.md#get-playerapilibrariesid) | Reads the library. |
| [`GET /player/api/libraries/{id}/items`](/docs/server/api/player/index.md#get-playerapilibrariesiditems) | Lists the library's items, one page at a time. |
| [`GET /player/api/libraries/{id}/series`](/docs/server/api/player/index.md#get-playerapilibrariesidseries) | Lists the library's series, one page at a time. |
| [`GET /player/api/libraries/{id}/authors`](/docs/server/api/player/index.md#get-playerapilibrariesidauthors) | Lists the library's authors. |
| [`GET /player/api/libraries/{id}/narrators`](/docs/server/api/player/index.md#get-playerapilibrariesidnarrators) | Lists the library's narrators. |
| [`GET /player/api/libraries/{id}/collections`](/docs/server/api/player/index.md#get-playerapilibrariesidcollections) | Lists the library's collections: none yet. |
| [`GET /player/api/libraries/{id}/playlists`](/docs/server/api/player/index.md#get-playerapilibrariesidplaylists) | Lists the patron's playlists in the library: none yet. |
| [`GET /player/api/libraries/{id}/personalized`](/docs/server/api/player/index.md#get-playerapilibrariesidpersonalized) | Reads the patron's home shelves: continue listening, recently added and listen again. |
| [`GET /player/api/libraries/{id}/search`](/docs/server/api/player/index.md#get-playerapilibrariesidsearch) | Searches the library's items, series, authors and narrators. |
| [`GET /player/api/libraries/{id}/stats`](/docs/server/api/player/index.md#get-playerapilibrariesidstats) | Adds up the library's items and their runtimes. |
| [`GET /player/api/libraries/{id}/filterdata`](/docs/server/api/player/index.md#get-playerapilibrariesidfilterdata) | Reads the library's filter values. |
| [`GET /player/api/series/{id}`](/docs/server/api/player/index.md#get-playerapiseriesid) | Reads one series with its items and the patron's progress through it. |
| [`GET /player/api/authors/{id}`](/docs/server/api/player/index.md#get-playerapiauthorsid) | Reads one author, with their items and series when asked for. |
| [`GET /player/api/items/{id}`](/docs/server/api/player/index.md#get-playerapiitemsid) | Reads one item; expanded, with its tracks and files. |
| [`POST /player/api/items/batch/get`](/docs/server/api/player/index.md#post-playerapiitemsbatchget) | Reads several items at once. |
| [`GET /player/api/items/{id}/cover`](/docs/server/api/player/index.md#get-playerapiitemsidcover) | Serves an item's cover. |
| [`POST /player/api/items/{id}/play`](/docs/server/api/player/index.md#post-playerapiitemsidplay) | Opens a play session on an item. |
| [`GET /player/api/items/{id}/file/{ino}`](/docs/server/api/player/index.md#get-playerapiitemsidfileino) | Streams one audio file of an item. |
| [`GET /player/api/items/{id}/file/{ino}/download`](/docs/server/api/player/index.md#get-playerapiitemsidfileinodownload) | Downloads one audio file of an item for offline listening. |
| [`POST /player/api/session/{id}/sync`](/docs/server/api/player/index.md#post-playerapisessionidsync) | Reports where the patron is in a playing session. |
| [`POST /player/api/session/{id}/close`](/docs/server/api/player/index.md#post-playerapisessionidclose) | Sends a session's last report, if any, and ends it. |
| [`POST /player/api/session/local`](/docs/server/api/player/index.md#post-playerapisessionlocal) | Uploads one session an app played offline. |
| [`POST /player/api/session/local-all`](/docs/server/api/player/index.md#post-playerapisessionlocal-all) | Uploads every session an app played offline. |
| [`GET /player/api/me/progress/{id}`](/docs/server/api/player/index.md#get-playerapimeprogressid) | Reads the patron's progress on an item. |
| [`DELETE /player/api/me/progress/{id}`](/docs/server/api/player/index.md#delete-playerapimeprogressid) | Clears the patron's progress on an item. |
| [`PATCH /player/api/me/progress/{id}`](/docs/server/api/player/index.md#patch-playerapimeprogressid) | Sets the patron's progress on an item: a seek, Mark finished or Start over. |
| [`PATCH /player/api/me/progress/batch/update`](/docs/server/api/player/index.md#patch-playerapimeprogressbatchupdate) | Sets the patron's progress on several items. |
| [`GET /player/api/me/items-in-progress`](/docs/server/api/player/index.md#get-playerapimeitems-in-progress) | Lists the items the patron is part way through, most recent first. |
| [`GET /player/api/me/listening-sessions`](/docs/server/api/player/index.md#get-playerapimelistening-sessions) | Lists the patron's play sessions, newest first. |
| [`GET /player/api/me/listening-stats`](/docs/server/api/player/index.md#get-playerapimelistening-stats) | Sums the patron's listening, by item and by day. |
| [`POST /player/api/me/item/{id}/bookmark`](/docs/server/api/player/index.md#post-playerapimeitemidbookmark) | Adds a bookmark to an item. |
| [`PATCH /player/api/me/item/{id}/bookmark`](/docs/server/api/player/index.md#patch-playerapimeitemidbookmark) | Renames the bookmark at a time in an item. |
| [`DELETE /player/api/me/item/{id}/bookmark/{time}`](/docs/server/api/player/index.md#delete-playerapimeitemidbookmarktime) | Removes the bookmark at a time in an item. |

### [Legacy](/docs/server/api/legacy/index.md)

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

| Route | Summary |
| --- | --- |
| [`GET /status`](/docs/server/api/legacy/index.md#get-status) (deprecated) | Deprecated alias of `GET /api/status`. |
| [`POST /scan`](/docs/server/api/legacy/index.md#post-scan) (deprecated) | Deprecated alias of `POST /api/library/scan`. |
| [`POST /acquire`](/docs/server/api/legacy/index.md#post-acquire) (deprecated) | Deprecated alias of `POST /api/library/acquire`. |
| [`GET /jobs`](/docs/server/api/legacy/index.md#get-jobs) (deprecated) | Deprecated alias of `GET /api/jobs`. |
| [`POST /jobs/{id}/cancel`](/docs/server/api/legacy/index.md#post-jobsidcancel) (deprecated) | Deprecated alias of `POST /api/jobs/{id}/cancel`. |
| [`POST /integrations/{id}/scan`](/docs/server/api/legacy/index.md#post-integrationsidscan) | Enqueues a remote integration library scan; 404 if missing, 400 if unsupported. |

## Schemas

Request and response bodies are described in [Schemas](/docs/server/api/schemas/index.md).
