Schemas

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

Last updated View as Markdown

The request and response bodies of the web API, in alphabetical order.

AbridgementJson

Whether an expression is abridged.

Type: one of unknown, unabridged, abridged

AccountRef

One store account, by storefront plugin key and store account id.

  • plugin_keystringrequiredProvenance-qualified plugin key of the storefront, as sent.
  • account_idstringrequiredStore account id, as sent.

AcquireRequestBody

Optional body for POST /api/library/acquire.

  • asinstring or nullAudible ASIN filter; first of uuid/asin/isbn/product_id wins.
  • uuidstring or nullLibrary title UUID filter.
  • isbnstring or nullISBN filter for non-Audible stores.
  • product_idstring or nullStore product id filter.
  • accountstring or nullRestrict acquire to this store account.
  • plugin_instance_idstring or nullWhen set, fetch through this deployed plugin instance.
  • titlesarray of stringMore title ids; each (with the single filter above) becomes its own job.
  • editionsarray of stringEditions to acquire (id of an edition in a work's detail). Each becomes one job for a title that sells it in an account the caller may acquire for (in account when that is set); the edition's titles share its files.
  • forcebooleanRe-download titles already acquired.
  • pdf_onlybooleanFetch only each title's companion PDF.

AcquireStatus

Acquire / download state for a title.

Type: one of not_acquired, queued, downloading, acquired, error

ActionResponse

Generic mutation result with success flag, message, and optional job id.

  • okbooleanrequiredTrue when the action was accepted or completed.
  • messagestringrequiredOperator-facing status text.
  • job_idstringrequiredQueued job id, or empty when the action is synchronous.
  • errorstring or nullMachine slug when admission failed (conflict, queue_full).

ActiveVersionChanged

PUT /api/config/plugins/{key}/active body: the pointer after the move.

  • plugin_keystringrequiredCanonical plugin key.
  • versionstringrequiredVersion now active.
  • revisioninteger (int64)requiredCompare-and-swap revision of the pointer after the move.

AddConnectionsBody

POST /api/config/join/connections body.

  • library_idstringrequiredThe library (parent library id) to add the connections to.
  • accountsarray of AccountRefrequiredThe person's accounts to add; 1 to 64.

AddressFieldJson

One field a patron fills in for a personal destination.

  • keystringrequiredKey in the address document.
  • labelstringrequiredLabel shown on the form.
  • requiredbooleanrequiredWhether a destination must carry it.
  • secretbooleanrequiredWhether the value is a secret: shown masked, never logged.

AdminControlOverrides

One Administrator's overrides: a value for some switches, and the library's default for the rest (an absent or null field).

  • manage_membersboolean or nullOverrides [AdminControls::manage_members].
  • set_patron_limitsboolean or nullOverrides [AdminControls::set_patron_limits].
  • library_scanboolean or nullOverrides [AdminControls::library_scan].
  • run_jobsboolean or nullOverrides [AdminControls::run_jobs].
  • fix_catalogboolean or nullOverrides [AdminControls::fix_catalog].
  • invite_branchesboolean or nullOverrides [AdminControls::invite_branches].
  • approve_requestsboolean or nullOverrides [AdminControls::approve_requests].

AdminControls

A value for each switch: the library's default, or what applies to one Administrator.

  • manage_membersbooleanMay manage Members ([AdminControl::ManageMembers]).
  • set_patron_limitsbooleanMay set patron limits ([AdminControl::SetPatronLimits]).
  • library_scanbooleanMay scan and acquire library-wide ([AdminControl::LibraryScan]).
  • run_jobsbooleanMay run the job queue ([AdminControl::RunJobs]).
  • fix_catalogbooleanMay fix the catalog ([AdminControl::FixCatalog]).
  • invite_branchesbooleanMay invite branches ([AdminControl::InviteBranches]).
  • approve_requestsbooleanMay approve interlibrary requests ([AdminControl::ApproveRequests]).

AdminSwitchChoice

What a change does to one switch of one Administrator.

Type: one of on, off, default

AfterIngest

What happens to a drop folder item once it has been ingested.

Type: one of move, delete, leave

ApiError

An error. error is a stable slug; bodies the error middleware writes also carry message and status, and some routes add fields of their own.

  • errorstringrequiredStable machine slug.
  • messagestringExplanation for people.
  • statusintegerThe HTTP status, repeated.

ApproveBody

POST /api/config/library-consents/approve body.

  • library_idstringrequiredLibrary id.
  • plugin_keystringrequiredCanonical plugin key.
  • request_digeststringrequiredThe request_digest of the request the operator reviewed, as the listing shows it (refused when the recorded request is another one).
  • deny_domainsarray of stringDomains to take out of the request. No duplicates.
  • deny_bindingsarray of stringBindings to take out of the request. No duplicates.
  • deny_own_user_agent_hostsarray of stringRequested hosts to refuse the plugin's own User-Agent on; requests to them carry Bookclerk's agent instead. No duplicates.
  • deny_networkbooleanDeny all network access.

AssertionFinish

POST /api/auth/passkeys/login/finish and elevate/finish body: the browser's assertion plus the challenge id from the matching begin.

The credential is read straight into WebAuthn's typed assertion, so the handler never decodes caller JSON itself.

  • challenge_idstringrequiredServer-issued challenge id (consumed once; 5-minute TTL).
  • credentialany JSONrequiredW3C PublicKeyCredential as the browser serializes it: a registration attestation (response.attestationObject) or an authentication assertion (response.authenticatorData, signature, userHandle), binary fields base64url-encoded.

AudioFile

An audio file of a book.

  • indexinteger (int64)requiredThe file's place in play order, from 1. At least 0.
  • inostringrequiredThe file's ino ([crate::ids::file_ino]).
  • metadataFileMetadatarequiredThe file's name, size and times.
  • addedAtinteger (int64)requiredWhen the file was stored, in epoch milliseconds.
  • updatedAtinteger (int64)requiredWhen the file was stored, in epoch milliseconds.
  • trackNumFromMetainteger (int64) or nullThe track number the file's tags state: not read. At least 0.
  • discNumFromMetainteger (int64) or nullThe disc number the file's tags state: not read. At least 0.
  • trackNumFromFilenameinteger (int64) or nullThe track number in the file name: not read. At least 0.
  • discNumFromFilenameinteger (int64) or nullThe disc number in the file name: not read. At least 0.
  • manuallyVerifiedbooleanrequiredAlways false.
  • excludebooleanrequiredAlways false.
  • errorstring or nullAlways null.
  • formatstring or nullThe container format, such as mp4 or mp3.
  • durationnumber (double)requiredThe file's length in seconds.
  • bitRateinteger (int64) or nullBits per second, if known. At least 0.
  • languagestring or nullThe file's language, if known.
  • codecstring or nullThe codec, if known.
  • timeBasestring or nullThe time base, if known.
  • channelsinteger (int64) or nullAudio channels, if known. At least 0.
  • channelLayoutstring or nullThe channel layout, if known.
  • chaptersarray of ChapterrequiredChapters embedded in the file: none are read.
  • embeddedCoverArtstring or nullAlways null.
  • metaTagsMetaTagsrequiredTags read from the file: none until the stored media probe reads them.
  • mimeTypestringrequiredThe file's media type, such as audio/mp4.

AudioTrack

A track with its place in the book.

  • indexinteger (int64)requiredThe track's place in play order, from 1. At least 0.
  • startOffsetnumber (double)requiredWhere the track starts in the book, in seconds.
  • durationnumber (double)requiredThe track's length in seconds.
  • titlestringrequiredThe track's title: its file name.
  • contentUrlstringrequiredThe path the track streams from, under the API's base address (/api/items/{id}/file/{ino}); apps add ?token=.
  • mimeTypestringrequiredThe track's media type.
  • codecstring or nullThe codec, if known.
  • metadataFileMetadata or nullThe file's name, size and times.

AuthFormData

Text an app shows on its sign-in screen.

  • authLoginCustomMessagestring or nullA note under the sign-in form: where to get a player password.
  • authOpenIDButtonTextstringrequiredThe label of the browser sign-in button.
  • authOpenIDAutoLaunchbooleanrequiredWhether apps open the browser sign-in without a tap: never.

AuthMeImpersonating

Target user shown while an operator session is impersonating.

  • user_idinteger (int64)requiredFirst-party users.id being impersonated.
  • display_namestring or nullDisplay name of the impersonated user when the row exists.

AuthMeResponse

JSON body for GET /api/auth/me.

  • authenticatedbooleanrequiredWhether the request resolved to an operator, portal, or impersonated session.
  • rolestring or nulloperator, owner, administrator, or member (legacy clients may still send portal).
  • default_viewstringrequiredConfigured post-auth landing view (discover / library / accounts / wishlist). Loaded from per-user DB preferences (not config.toml).
  • can_acquirebooleanrequiredWhether this session may acquire / scan / manage jobs. True for operator and administrator.
  • elevatedbooleanrequiredTrue when this operator session was created via Owner elevate.
  • administers_nodesbooleanrequiredWhether this session reaches the node administration routes and the library Status page: the operator, an Owner or Administrator, or a Member who owns at least one node (a branch they linked).
  • impersonatingAuthMeImpersonating or nullPresent when the operator is impersonating a User.
  • portalPortalMeInfo or nullLinked portal identity when the caller is a portal (or impersonated) user.
  • userAuthMeUser or nullFirst-party user when the session is linked to a users row.
  • second_factorAuthSecondFactor or nullPassword-login second-factor policy and this user's enrollment.
  • see_pricesbooleanrequiredWhether the caller's "See prices and store links" member control allows prices and store links. The library already drops them from its answers when it does not; the app uses this to show no store links of its own either. Always true for the operator.

AuthMeUser

First-party user snapshot attached to /me when a users row is linked.

  • idinteger (int64)requiredFirst-party users.id.
  • rolestringrequiredRole string (owner, administrator, member).
  • display_namestring or nullOptional human-readable name from the user row.
  • emailstring or nullOptional email; omitted from JSON when unset.
  • has_passwordbooleanrequiredTrue when a local password hash is stored (invite users may be false).
  • has_avatarbooleanrequiredTrue when a JPEG avatar is stored under files_dir/avatars/{id}.*.
  • avatar_sourcestringrequiredSelected picture source (auto, monogram, gravatar, upload, sso:{id}).
  • gravatar_hashstring or nullSHA-256 hex of the contact email for Gravatar, when an email is set.
  • sso_picturesarray of AuthSsoPictureIdP-supplied pictures the user can pick.

Author

An author.

  • idstringrequiredThe contributor id.
  • asinstring or nullAlways null.
  • namestringrequiredThe author's name.
  • lastFirststringrequiredThe name family name first.
  • descriptionstring or nullAlways null.
  • imagePathstring or nullAlways null: no author images.
  • libraryIdstringrequiredThe library it is listed in.
  • addedAtinteger (int64)requiredWhen the library first saw the author, in epoch milliseconds.
  • updatedAtinteger (int64)requiredWhen the record last changed, in epoch milliseconds.
  • numBooksinteger (int64)requiredItems by the author the patron can see. At least 0.
  • libraryItemsarray of LibraryItem or nullThe author's items, when asked for.
  • seriesarray of AuthorSeries or nullThe author's series with their items, when asked for.

Authors

GET /api/libraries/{id}/authors without paging.

  • authorsarray of AuthorrequiredThe authors.

AuthorSeries

A series of an author's, with the author's items in it.

  • idstringrequiredThe series id.
  • namestringrequiredThe series name.
  • itemsarray of LibraryItemrequiredThe items, in series order.

AuthSecondFactor

Host MFA policy plus whether this user has TOTP and/or passkeys.

  • requiredbooleanrequireddaemon.auth.require_second_factor.
  • totpbooleanrequiredConfirmed authenticator-app TOTP.
  • passkey_countinteger (int64)requiredNumber of registered passkeys. At least 0.
  • enrolledbooleanrequiredTrue when TOTP is enabled or at least one passkey exists.

AuthSsoPicture

HTTPS picture from a linked identity provider.

  • identity_idinteger (int64)requiredportal_identities.id.
  • providerstringrequiredIdentity-broker id (oidc:google, …).
  • picture_urlstringrequiredHTTPS URL to display.
  • picture_pathstring or nullSame-origin 128 px copy of picture_url for the web app to show, when this node can sign it.
  • last_used_atstring or nullRFC 3339 last portal-session activity for this identity, when any.

AvatarChanged

JSON body after the caller's avatar was stored or removed.

  • okbooleanrequiredAlways true on this success path.
  • has_avatarbooleanrequiredWhether an uploaded picture is stored now.
  • avatar_sourcestring or nullPresent only after an upload, always upload; absent after a removal (the stored source is then unchanged unless it was upload).

BadBookAction

How to handle acquire failures (BadBook setting).

Type: one of ask, abort, retry, ignore

BatchGetBody

POST /player/api/items/batch/get.

  • libraryItemIdsarray of stringrequiredThe items, at most 100.

BinaryBody

A request body of raw bytes (a file upload), documented as type: string, format: binary so generated clients send the bytes rather than a JSON array.

Type: binary

Bookmark

A bookmark.

  • libraryItemIdstringrequiredThe item it is in.
  • titlestringrequiredIts title.
  • timenumber (double)requiredWhere it is, in seconds.
  • createdAtinteger (int64)requiredWhen it was made, in epoch milliseconds.

BookmarkBody

POST and PATCH /player/api/me/item/{id}/bookmark.

  • timenumber (double)requiredThe place, in seconds; on PATCH, which bookmark to rename.
  • titlestring or nullThe bookmark's title.

BookmarkEditBody

PUT /api/playback/bookmarks/{id} body: what to change. A field left out keeps its stored value.

  • position_msinteger (int64) or nullThe new place, in milliseconds. At least 0.
  • titlestring or nullThe new note; an empty string clears it.

BookmarkJson

A place the caller marked in an edition.

  • idstringrequiredBookmark id.
  • edition_idstringrequiredThe edition it is in.
  • position_msinteger (int64)requiredThe marked place, in milliseconds from the edition's start. At least 0.
  • titlestringrequiredThe caller's note; may be empty.
  • created_atstringrequiredWhen it was made (RFC 3339).

BookmarksJson

GET /api/library/editions/{id}/bookmarks answer.

  • bookmarksarray of BookmarkJsonrequiredThe caller's bookmarks in the edition, in timeline order.

BookMedia

A book's media: metadata, tracks and chapters.

  • idstringrequiredThe media id: the edition id.
  • libraryItemIdstring or nullThe item id, when fetched expanded.
  • metadataBookMetadatarequiredThe book's metadata.
  • coverPathstring or nullA cover path apps only test for presence; covers are fetched from /api/items/{id}/cover.
  • tagsarray of stringrequiredTags: none.
  • numTracksinteger (int64)requiredTracks in play order. At least 0.
  • numAudioFilesinteger (int64)requiredAudio files. At least 0.
  • numChaptersinteger (int64)requiredChapters. At least 0.
  • durationnumber (double)requiredThe book's length in seconds.
  • sizeinteger (int64)requiredBytes in its audio files. At least 0.
  • audioFilesarray of AudioFile or nullThe audio files, when fetched expanded.
  • chaptersarray of Chapter or nullThe chapters, when fetched expanded.
  • tracksarray of AudioTrack or nullThe tracks with their place in the book, when fetched expanded.

BookMetadata

A book's metadata.

  • titlestringrequiredThe title.
  • titleIgnorePrefixstringrequiredThe title for sorting.
  • subtitlestring or nullThe subtitle, if any.
  • authorsarray of NamedRefrequiredThe authors.
  • authorNamestringrequiredThe authors' names joined with , .
  • authorNameLFstringrequiredThe authors' names, family name first, joined with , .
  • narratorsarray of stringrequiredThe narrators' names.
  • narratorNamestringrequiredThe narrators' names joined with , .
  • seriesarray of SeriesRefrequiredThe series the book is in.
  • seriesNamestringrequiredThe series names with the book's place (Name #2), joined.
  • genresarray of stringrequiredGenres.
  • publishedYearstring or nullThe year of publication, as a string ("2019").
  • publishedDatestring or nullThe date of publication, if known.
  • publisherstring or nullThe publisher.
  • descriptionstring or nullThe description, as the library stores it.
  • descriptionPlainstring or nullThe description with markup removed.
  • isbnstring or nullThe ISBN, if known.
  • asinstring or nullThe ASIN, if known.
  • languagestring or nullThe language.
  • explicitbooleanrequiredAlways false.
  • abridgedbooleanrequiredWhether the edition is abridged.

BootstrapRequest

Operator-only body for creating the first Owner when none exist.

  • display_namestring or nullOptional display name; falls back to login or email.
  • login_namestring or nullOptional local login name.
  • emailstring or nullOptional email.
  • passwordstring or nullOptional password; hashed before persist and never stored in plaintext.

BranchAuthorizeParams

The authorization request a consent is for (the query /oidc/authorize forwarded to /join/approve).

  • client_idstringrequiredMust be [BRANCH_CLIENT_ID].
  • redirect_uristringrequiredWhere the code goes: loopback or https.
  • response_typestringrequiredMust be code.
  • scopestring or nullMust be [BRANCH_SCOPE].
  • statestring or nullEchoed on the redirect.
  • code_challengestringrequiredPKCE S256 challenge.
  • code_challenge_methodstring or nullMust be S256.
  • branch_namestring or nullThe name the branch asks to join as.
  • shared_branch_offerstring or null1 when the joining install offers to join as a shared branch ([bookclerk_node_proto::SHARED_BRANCH_OFFER_PARAM]).

BranchAvailability

One branch a title is available through.

  • work_idstringrequiredThis library's work the branch supplies: the work_id to send POST /api/branch-requests to ask the branch for it.
  • node_idstringrequiredThe branch node id.
  • owner_namestring or nullThe branch owner's display name, for "available through Riley's branch"; absent when the owner has none.
  • storestringrequiredThe store the branch has the book from.
  • product_idstringrequiredThe store's product id of the branch's copy.

BranchConsentBody

POST /api/auth/branch-consent body.

Includes every field of BranchAuthorizeParams.

  • approvebooleanrequiredTrue to let the branch join; false to deny.
  • connectionstring or nullbranch (default) or shared_branch.
  • step_upStepUp or nullThe fresh second factor a shared branch needs.
  • bring_connectionsbooleanTrue to send the user's store connections that may travel to the branch when it joins. Ignored for a shared branch. Defaults to false.

BranchConsentPage

JSON body for GET /api/auth/branch-consent: what the consent page shows.

  • library_namestringrequiredThis library's name.
  • branch_namestringrequiredThe name the branch asks to join as.
  • redirect_originstringrequiredOrigin of the branch's redirect URI, for the page to name.
  • enrollmentbooleanrequiredWhether this library lets new branches join right now.
  • userConsentingUserrequiredThe signed-in user the branch would belong to.
  • connectionConnectionChoicerequiredThe connection types the page may offer.
  • connectionsarray of ConsentConnectionrequiredThe user's store connections here, and whether each would travel to the branch if the user chooses to bring them.

BranchEnrollment

The branch-enrollment switch.

  • enabledbooleanrequiredWhether branch nodes may enroll into this library.
  • revisioninteger (int64) or nullStored revision; null while the default (enabled) applies.

BranchesResponse

JSON body for GET /api/config/branches.

  • library_namestringrequiredThis library's name.
  • originstringrequiredThe canonical origin branches connect to.
  • transportstringrequiredThe node API transport mode (acme, proxy, self_signed, loopback).
  • enrollmentbooleanrequiredWhether new branches may join.
  • spki_fingerprintstring or nullIn self_signed mode, the fingerprint a joining operator confirms.
  • branchesarray of BranchViewrequiredEvery branch, newest first.

BranchJoined

JSON body once this install joined a library as a branch.

  • libraryLibraryLinkViewrequiredThe new link.
  • library_namestring or nullThe library's name, when the join came from a sign-in (not an invite link).
  • runningbooleanrequiredWhether the link's client is running now.
  • connectionsBroughtConnectionsView or nullWhat became of the store connections the library's user chose to bring to this branch; left out when none came.
  • replaced_cardReplacedCard or nullSet when this install held a library card for the library: the branch replaced it. Whether the card is gone here and whether the library ended its session are in [ReplacedCard]. Left out when there was none.

BranchJoinSetting

JSON body after PUT /api/config/branches.

  • enrollmentbooleanrequired"Let new branches join", as stored.

BranchMembersBooks

JSON body after PUT /api/config/branches/members-books.

  • node_idstringrequiredThe branch.
  • acquire_members_booksbooleanrequired"Acquire all of this branch's members' books", as stored.

BranchOnlyChoice

The consent page's connection block when only a branch is offered.

  • choicebooleanrequiredAlways false.
  • defaultstringrequiredAlways branch.

BranchRelationship

How a node relates to the library, as people are told: a shared branch serves the library from its database, and a branch with its own database is a remote branch when it reports a public address (it is a core branch other installs can reach) and a local branch when it does not.

Type: one of shared_branch, remote_branch, local_branch

BranchRequestBody

POST /api/branch-requests body: the work to ask a branch for, and optionally which branch.

  • work_idstringrequiredThis library's work id, as Discover and search name it.
  • node_idstring or nullThe branch to ask, from the work's available_through; absent or null asks the first branch that lists the work.

BranchRequestQueued

POST /api/branch-requests answer.

  • job_idstringrequiredThe request's job (kind branch_request), as /api/jobs lists it.
  • node_idstringrequiredThe branch the request went to.
  • already_queuedbooleanrequiredtrue when a request for this work to this branch was already waiting or being taken; job_id is that request.

BranchTitleCounts

Counts of one branch's shared titles.

  • sharedinteger (int64)requiredTitles it shares now. At least 0.
  • deliveredinteger (int64)requiredOf those, titles whose files arrived. At least 0.
  • detachedinteger (int64)requiredEditions whose files it delivered that nothing in this library holds any more (it stopped sharing, left, or withdrew them, and no store account or other branch here holds them). At least 0.

BranchTitlesRemoved

JSON body after detached branch titles were removed.

  • removedinteger (int64)requiredHow many title entries were removed. At least 0.

BranchView

One branch (branch node) of this library.

  • node_idstringrequiredThe branch's node id.
  • created_atstringrequiredRFC 3339 time the node was created.
  • owner_user_idinteger (int64) or nullThe user who owns the branch.
  • owner_namestring or nullThat user's display or login name.
  • joinedbooleanrequiredWhether its credential is still valid (it has not left or been revoked).
  • share_booksboolean or null"Share this branch's books" as it last reported it; null until its first catalog sync.
  • include_branchesboolean or null"Include books from my own branches" as it last reported it; null until its first catalog sync.
  • acquire_members_booksbooleanrequiredThis library's "Acquire all of this branch's members' books": the branch also sends the books its members acquired that it lists here, not only its owner's.
  • titlesBranchTitleCountsrequiredCounts of the titles it shared.

BrandInfo

CSS colors and logo href for a storefront or integration brand.

  • bgstringrequiredBackground color (#RRGGBB).
  • fgstringrequiredForeground / text color (#RRGGBB).
  • accentstringrequiredAccent color (#RRGGBB).
  • logostringrequiredSame-origin logo image (a 128 px copy of the brand's icon), or empty when there is none.

BroughtConnectionsView

The store connections a library sent with its person, as this install kept them.

  • offeredintegerrequiredHow many came with the join. At least 0.
  • addedintegerrequiredHow many are now connected here for the person. At least 0.
  • already_hereintegerrequiredHow many the person had already connected here (left as they are). At least 0.
  • takenintegerrequiredHow many are connected to someone else here (left as they are). At least 0.
  • failedintegerrequiredHow many could not be kept: no secret came with them, or their write failed. At least 0.
  • not_keptstring or nullWhy none were kept, when none were: not_allowed (this install's operator does not let the person connect store accounts), no_owner (no single Owner here to keep them for) or failed.

CallbackBody

POST /api/config/join/callback body.

  • codestringThe code from the library.
  • statestringThe state it came back with.
  • errorstring or nullThe library's error (access_denied), when it sent one.
  • connectionstring or nullThe connection type the library's user chose (shared_branch; a branch when left out). The code is bound to it, so a changed value only fails the redeem.

CallbackParams

Query or form_post fields from the IdP callback.

  • codestring or nullAuthorization code to exchange; required unless error is set.
  • statestring or nullCSRF state that must match the bookclerk_oidc_tx cookie.
  • errorstring or nullIdP-reported deny/error; redirects the browser to /?sso_error=denied.
  • userstring or nullApple first-login name/email JSON (form_post only).

CapacityBody

POST /api/config/join/capacity body: one library and the job cap to set for it.

  • library_idstringrequiredThe library (parent library id).
  • max_jobsinteger (int32) or nullrequiredThe most jobs to run for the library at once (0 runs none); null gives it an equal share of the machine. Required: a body without it is refused rather than read as null. At least 0; at most 16.

CatalogListing

Whether the caller's books are listed to the libraries this install is a branch of (GET / PUT /api/auth/profile/catalog-listing).

  • listedbooleanrequiredtrue (the default): the libraries this install joined can see, when they ask, that it can supply the caller's books. false keeps them out of those answers; the owner's books are always listed.

CatalogListingView

The caller's listing choice and how many libraries it applies to.

  • listedbooleanrequiredThe caller's choice; see [CatalogListing::listed].
  • librariesinteger (int32)requiredLibraries this install is currently a branch of (active links). With none, the choice has no effect yet, and the app hides it. At least 0.
  • always_listedbooleanrequiredtrue for an active Owner: an Owner's books are always listed, so listed has no effect and the app shows that instead of the toggle.

CatalogSearchHit

One autocomplete / results-page hit (possibly spanning multiple storefronts).

  • work_keystringrequiredStable map key for this work (isbn:…, asin:…, or soft title+author).
  • titlestringrequiredDisplay title as shown on the storefront or library card.
  • authorsstring or nullComma-separated author names when the storefront provides them.
  • narratorsstring or nullComma-separated narrator names when known.
  • seriesstring or nullSeries name when the title belongs to a named series.
  • series_indexstring or nullPosition within the series (e.g. 1, 1.5) when known.
  • asinstring or nullAudible / Amazon ASIN when this edition is sold on Audible.
  • isbnstring or nullCanonical ISBN-13 (or ISBN-10 normalized) when published.
  • cover_urlstring or nullHTTPS URL for cover art when the catalog exposes one.
  • cover_pathstring or nullSame-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
  • store_editionsarray of StoreEditionrequiredPer-storefront edition ids that collapsed into this work card.
  • sourcesarray of stringrequiredStorefronts that matched (deduped source ids).
  • subtitlestring or nullOptional subtitle when the catalog distinguishes it from the title.
  • descriptionstring or nullPublisher or storefront synopsis; may be truncated for embeddings.
  • publisherstring or nullPublisher imprint as reported by the catalog.
  • length_minutesinteger (int64) or nullAudiobook runtime in whole minutes when known.
  • published_atstring or nullPublication date string from the catalog (ISO or storefront format).
  • genresstring or nullGenre labels from the catalog (comma-separated when multiple).
  • languagestring or nullBCP-47 / storefront language code (en, de, …) when known.
  • is_abridgedboolean or nullWhen Some(true), the edition is marked abridged by the storefront.
  • is_explicitboolean or nullWhen Some(true), a storefront marks the edition explicit (adult) content; None when none said.
  • rating_overallnumber (double) or nullAggregate listener rating on the storefront's scale when known.
  • rating_countinteger (int64) or nullNumber of ratings backing [Self::rating_overall] when known.
  • price_centsinteger (int64) or nullCatalog list/deal price in cents when the storefront provided it.
  • purchase_hintsarray of PurchaseHintBuy / open-in-store links with optional member vs list pricing.
  • available_througharray of BranchAvailabilityBranches of this library that currently list this title, matched through a store listing the library already holds. Filled by the daemon after the search.

CatalogSearchPage

Paged catalog-search response.

  • itemsarray of CatalogSearchHitrequiredOrdered collection of child entries for this response.
  • page_sizeintegerrequiredMaximum number of items returned in this page. At least 0.
  • has_morebooleanrequiredWhen true, another page is available via [Self::next_cursor].
  • next_cursorstring or nullOpaque cursor for the next page; omit or None when exhausted.
  • sortstringrequiredSort field applied to the merged result set.
  • sort_dirstringAscending or descending order for [Self::sort].

ChannelList

The library's channels.

Chapter

A chapter of a book.

  • idinteger (int64)requiredThe chapter's place, from 0. At least 0.
  • startnumber (double)requiredWhere it starts, in seconds.
  • endnumber (double)requiredWhere it ends, in seconds.
  • titlestringrequiredIts title.

ChapterClaimJson

One source's chapter claim for an edition.

  • source_kindChapterSourceKindrequiredThe kind of source.
  • source_idstringrequiredWhich source of that kind (a PluginKey; empty for an edit or for Bookclerk's own processing).
  • qualitystringrequiredWhere a machine source ranks within its kind: strong_accurate, strong_estimated or weak for a provider, chapters, tracks or unknown for a store listing; empty otherwise.
  • digeststringrequiredSHA-256 of the claimed list, 64 lower-case hex characters.
  • chaptersarray of EditionChapter or nullThe claimed chapters; absent while the list's write is unfinished.
  • runtime_msinteger (int64) or nullLength of the timeline the list was measured on, in milliseconds. At least 0.
  • input_digeststring or nullFor a processed claim, the digest of the provider list it was aligned from.
  • playsbooleanrequiredWhether the edition plays this claim now.
  • pinned_atstring or nullWhen an Administrator pinned it (RFC 3339); absent when unpinned.
  • created_by_user_idinteger (int64) or nullThe person whose edit it is; absent for a machine source or the operator.
  • updated_atstringrequiredWhen it last changed (RFC 3339).

ChapterClaimsJson

Every chapter claim for an edition.

  • claimsarray of ChapterClaimJsonrequiredThe claims, most recently changed first.

ChapterEditBody

PUT /api/library/editions/{id}/chapters body: the edition's chapters as an Administrator sets them, in pre-order. An empty list clears them.

  • chaptersarray of ChapterEditEntryrequiredThe chapters, at most 2,000. At most 2000 items.

ChapterEditEntry

One chapter of an edit, as JSON carries it.

  • titlestringrequiredChapter title: 1 to 512 bytes, no control characters, no leading or trailing white space.
  • start_msinteger (int64)requiredStart, in milliseconds from the start of the edition's timeline; no earlier than the chapter before it. At least 0.
  • depthinteger (int32)Nesting depth, 0 for a top-level chapter; at most one more than the chapter before it, and at most 7. Left out reads as 0. At least 0.

ChapterJsonMode

Whether / which chapter JSON sidecars to write beside acquired audio.

Default is [Self::Off]. Replaces the old save_chapter_json bool + chapter_layout pair for sidecar output (Audible API fetch layout is chosen separately when chapters are needed for embedding).

Type: one of off, flat, tree, both

ChapterPinBody

PUT /api/library/editions/{id}/chapters/pin body: the claim to pin.

  • source_kindChapterSourceKindrequiredThe claim's source kind, as the claims list names it.
  • source_idstring or nullThe claim's source id (a PluginKey; empty for an edit or for Bookclerk's own processing). Left out reads as empty.

ChapterSourceKind

The kind of source a chapter claim came from (source_kind).

Type: one of person, outside_edit, processed, provider, listing, file, part_names

ChapterSpan

One chapter as a player seeks between them: where it starts and ends on the edition's timeline ([ChapterList::spans]).

  • titlestringrequiredChapter title.
  • start_msinteger (int64)requiredStart, in milliseconds from the start of the edition's timeline. At least 0.
  • end_msinteger (int64)requiredEnd, in milliseconds: the next chapter's start, or the end of the timeline for the last chapter; never before start_ms. At least 0.
  • depthinteger (int32)requiredNesting depth; 0 for a top-level chapter. A chapter at depth n + 1 is nested under the nearest earlier chapter at depth n. At least 0.

ChoiceBody

Body of PUT /api/me/notifications/choices/{type}.

  • enabledbooleanrequiredfalse keeps the type in the inbox only.
  • destination_idsarray of stringThe caller's own destinations it goes to; at most 32. Left out or empty, the type goes to no destination outside the inbox, even with enabled: true; delete the choice to return to the defaults. At most 32 items.

ClerkAuthorizeParams

The authorization request a clerk consent is for (the query /oidc/authorize forwards to the library's /clerk/approve page).

  • client_idstringrequiredMust be [CLERK_CLIENT_ID].
  • redirect_uristringrequiredWhere the code goes: loopback or https.
  • response_typestringrequiredMust be code.
  • scopestring or nullMust be [CLERK_SCOPE].
  • statestring or nullEchoed on the redirect.
  • code_challengestringrequiredPKCE S256 challenge.
  • code_challenge_methodstring or nullMust be S256.
  • clerk_namestring or nullThe name the clerk gives itself, shown on the consent page and in the user's session list.

ClerkCallbackBody

POST /api/config/clerk/callback body.

  • codestringThe code from the library.
  • statestringThe state it came back with.
  • errorstring or nullThe library's error (access_denied), when it sent one.

ClerkCards

JSON body for GET /api/config/clerk.

  • cardsarray of ClerkLinkViewrequiredThe libraries this install holds (or held) a card for, oldest sign-in first.
  • default_clerk_namestringrequiredThe name this install signs in as unless another is given.

ClerkConsentBody

POST /api/auth/clerk-consent body.

Includes every field of ClerkAuthorizeParams.

  • approvebooleanrequiredTrue to let the clerk sign in; false to deny.

ClerkConsentPage

JSON body for GET /api/auth/clerk-consent: what the consent page shows.

  • library_namestringrequiredThis library's name.
  • clerk_namestringrequiredThe name the clerk gives itself.
  • redirect_originstringrequiredOrigin of the clerk's redirect URI, for the page to name.
  • userConsentingUserrequiredThe signed-in user the clerk would sign in as.

ClerkInspectBody

POST /api/config/clerk/inspect body.

  • addressstringrequiredThe library's address (https://books.example.com, books.lan:8443).

ClerkLinkView

A library this install holds (or held) a library card for, without the card.

  • library_idstringrequiredThe library id.
  • originstringrequiredThe library's canonical origin.
  • library_namestringrequiredThe library's name at sign-in.
  • pinnedbooleanrequiredWhether the card's connection pins the library's self-signed certificate.
  • display_namestring or nullThe person's display name on the library, when it has one.
  • clerk_namestringrequiredThe name this install signed in as.
  • statestringrequiredactive, or signed_out once the library ended the card.
  • signed_in_atstringrequiredRFC 3339 sign-in time.

ClerkRequestBody

POST /api/config/clerk/request body.

  • library_idstringrequiredThe library to ask: one this install holds an active card for.
  • work_idstringrequiredThe library's own work id: 1 to 64 ASCII letters, digits and -.
  • fromClerkRequestFromrequiredWhere the copy comes from: the edition's request.from in the window books.
  • node_idstring or nullThe library's branch to ask, from the work's available_through there; absent asks the first branch that lists it. Only with from branch.

ClerkRequestFrom

Where a clerk's request asks the library to get a copy from.

Type: one of branch, library

ClerkRequestSent

JSON body for POST /api/config/clerk/request.

  • library_idstringrequiredThe library that took the request.

ClerkSignedIn

JSON body for POST /api/config/clerk/callback.

  • cardClerkLinkViewrequiredThe library this install now holds a card for.
  • left_branchLeftBranch or nullSet when the card replaced this install's branch link to the library (a sign-in started from_branch): the branch was left.

ClerkSignedOut

JSON body for POST /api/config/clerk/sign-out.

  • library_idstringrequiredThe library id.
  • library_signed_outbooleanrequiredWhether the library ended the card's session too. False when it could not be reached (or the card had already ended): the session then stays in the person's session list there until it idles out or they revoke it.

ClerkSignOutBody

POST /api/config/clerk/sign-out body.

  • library_idstringrequiredThe library id.

ClerkStartBody

POST /api/config/clerk/start body.

  • addressstringThe library's address. Left out with from_branch.
  • from_branchstring or nullThe library id of a library this install is an active branch of: the card replaces the branch. The library's address and pinned certificate come from the branch link, so address and fingerprint are left out; once the library hands over the card, the callback leaves the branch (as Leave library does) and records the card. Only the operator may, as only the operator leaves a library.
  • fingerprintstring or nullThe fingerprint the person confirmed (self-signed libraries).
  • clerk_namestring or nullThe name to sign in as (default: this machine's name).

ClerkStarted

JSON body for POST /api/config/clerk/start.

  • authorize_urlstringrequiredThe library's sign-in URL to open in the browser.
  • libraryInspectedLibraryViewrequiredWhat the library said about itself.
  • clerk_namestringrequiredThe name this install signs in as.
  • expires_in_secsinteger (int64)requiredSeconds the pending sign-in stays valid. At least 0.

ClerkTokenAnswer

POST /api/clerk/v1/token answer.

  • tokenstringrequiredThe session token, sent as Authorization: Bookclerk-Clerk <token>. Shown once; the library keeps only its hash.
  • library_idstringrequiredThe library id.
  • userClerkUserrequiredThe signed-in person on that library.
  • idle_secsinteger (int64)requiredSeconds the session stays signed in unused; each use resets it.

ClerkTokenRequest

POST /api/clerk/v1/token body: exactly these three strings, each once, and nothing else.

  • codestringrequiredThe single-use code from the redirect.
  • code_verifierstringrequiredThe PKCE verifier whose S256 challenge the authorize request sent.
  • redirect_uristringrequiredThe redirect URI the authorize request named.

ClerkUser

The person a clerk session signs in as.

  • idinteger (int64)requiredThe user's id on the library.
  • display_namestring or nullThe user's display name on the library, when set.

ConfigOptionValueInfo

One allowed value for a storefront config option.

  • idstringrequiredStored option value (for example m4b).
  • labelstringrequiredOperator-facing value label.

ConflictJson

One conflict the resolver could not decide.

  • listing_idstringrequiredThe listing whose resolution conflicted.
  • kindstringrequiredWhat conflicted: strong_identifiers (two editions share the listing's strong identifiers), work_identifiers (its work identifiers name two works), ambiguous_work (two works match its title and authors) or work_kind_mismatch (its work identifier names a work of another kind).
  • subject_idsarray of stringrequiredThe editions (strong_identifiers) or works (the other kinds) involved.
  • plugin_keystringrequiredThe listing's storefront PluginKey.
  • product_idstringrequiredThe store's product id.
  • titlestringrequiredThe listing's title as the store reported it.
  • edition_idstringrequiredThe edition the listing sells now.
  • updated_atstringrequiredWhen the conflict was last seen (RFC 3339).

ConflictPage

One page of conflicts.

  • conflictsarray of ConflictJsonrequiredThe conflicts, by listing.
  • next_cursorstring or nullPass as cursor for the next page; absent on the last page.

ConnectionChoice

What the consent page may offer: branch only, or a choice between branch and shared_branch for an Owner.

Type: BranchOnlyChoice or OwnerChoice

ConnectionInfo

One linked store account on the portal Accounts page.

  • account_idstringrequiredStore account id (unique within its source).
  • sourcestringrequiredSource plugin id that owns this account.
  • plugin_keystringrequiredProvenance-qualified PluginKey that owns the account.
  • labelstring or nullOperator-facing account label when the store provided one.
  • connection_statusstringrequiredConnection state (active, revoked, …); defaults to active if the account row is missing.
  • source_enabledbooleanrequiredWhether [sources.<id>] enabled is currently true (new connects blocked when false).
  • brandBrandInfo or nullStorefront or integration brand when a plugin or fallback palette is available.
  • pacePaceViewrequiredHow fast Bookclerk downloads from this account when it starts the downloads itself.

ConnectionsAdded

JSON body after POST /api/config/join/connections.

  • addedinteger (int64)requiredAccounts now connected in the library for the person. At least 0.
  • already_hereinteger (int64)requiredAccounts the person had already connected there. At least 0.
  • takeninteger (int64)requiredAccounts connected to someone else there; left as they are. At least 0.
  • failedinteger (int64)requiredAccounts that could not be kept there. At least 0.
  • not_sentinteger (int64)requiredAccounts not sent: not the person's, not connected, or of a storefront whose sign-ins can't be shared. At least 0.
  • not_allowedbooleanrequiredThe library's operator does not let the person connect store accounts there; nothing was kept.

ConnectionsResponse

JSON body for GET /connections.

  • connectionsarray of ConnectionInforequiredLinked store accounts the SPA may show or revoke.

ConnectionType

How a joining install connects to a library.

Type: one of branch, shared_branch

ConsentBody

Form body for POST /oidc/authorize after the user grants or denies consent.

  • client_idstringrequiredRegistered OIDC client id (must exist in the library store).
  • redirect_uristringrequiredRedirect URI; must match a URI registered for the client.
  • response_typestringrequiredOAuth response_type; only code is accepted.
  • scopestring or nullSpace-separated scopes; defaults to openid profile when omitted.
  • statestring or nullOpaque CSRF value echoed back on the redirect.
  • code_challengestringrequiredPKCE S256 challenge (base64url SHA-256 of the verifier).
  • code_challenge_methodstring or nullPKCE method; omitted is treated as plain and then rejected.
  • consentstring or nulldeny aborts with access_denied; any other value proceeds to issue a code.

ConsentChanged

JSON body after a consent was approved or revoked.

ConsentConnection

One of the consenting user's store connections, as the consent page lists it.

  • sourcestringrequiredDisplay alias of the storefront.
  • account_idstringrequiredStore account id.
  • labelstring or nullThe account's display label, when it has one.
  • travelsbooleanrequiredTrue when the connection travels: a shareable storefront's, or a single-keeper one's that no other branch keeps yet (the branch then keeps its login fresh for this library). False when another branch already keeps it, or it does not fit one join's bundle.

ConsentingUser

The user a branch consent is for.

  • idinteger (int64)requiredusers.id.
  • display_namestring or nullDisplay name, when set.

ConsentRedirect

JSON body after a branch consent was answered.

  • redirectstringrequiredWhere to send the browser: the branch's callback with a code, or with error=access_denied.

ControlOverrides

One patron's overrides: a value for some controls; the rest (an absent or null field) follow the library's default for a Member and are allowed for an Administrator.

  • link_accountsboolean or nullOverrides [MemberControls::link_accounts].
  • downloadboolean or nullOverrides [MemberControls::download].
  • edit_metadataboolean or nullOverrides [MemberControls::edit_metadata].
  • uploadboolean or nullOverrides [MemberControls::upload].
  • request_booksboolean or nullOverrides [MemberControls::request_books].
  • see_pricesboolean or nullOverrides [MemberControls::see_prices].

ConvertRequestBody

Body for POST /api/library/convert.

  • copyOutputCopyrequiredThe copy to add: a format and a quality, as output.copies lists them. original is refused: a convert makes a new encoding.
  • titlesarray of stringTitle ids (uuid, ASIN, ISBN, product id) of stored books; each becomes its own job.
  • editionsarray of stringEditions to convert (id of an edition in a work's detail); each becomes one job for the title that acquired it.
  • forcebooleanMake the copy again when the book already has it.

CopyFormat

The format of one copy of a book.

Type: one of m4b, mp3, mp3_chapters, original, opus

CopyQuality

A copy's quality: original, a bitrate (for MP3 a constant rate the encoder writes: 64k, 96k, 128k, 160k, 192k, 256k or 320k; for Opus a target: 16k, 24k, 32k, 48k, 64k, 96k or 128k), or a LAME VBR quality v0 to v9 (MP3 only); the last two may end in -mono.

Type: string

Constraints: matches ^(original|((16|24|32|48|64|96|128|160|192|256|320)k|v[0-9])(-mono)?)$

CreatePluginInstance

POST /api/config/plugin-instances body.

  • plugin_keystringrequiredCanonical plugin key; the plugin must have a pinned schema.
  • display_namestringOperator-facing name.
  • node_idstring or nullMake the instance local to this node (H-2): it deploys only there and is never placed by the scheduler.

CreateRequestBody

Wishlist / title-request create body from Discover or the portal.

  • titlestringrequiredRequired title text; empty values are rejected with 400.
  • authorsstring or nullOptional author list as a single display string.
  • asinstring or nullOptional Audible ASIN used for work-key identity.
  • isbnstring or nullOptional ISBN used for work-key identity.
  • notesstring or nullOptional operator or member note stored on the request.
  • store_editionsarray of StoreEditionKnown storefront editions to persist as title_request_sources.
  • purchase_hintsarray of PurchaseHintOptional priced storefront links snapshotted at wishlist time.
  • cover_urlstring or nullOptional cover image URL snapshotted onto the request.
  • descriptionstring or nullOptional plot/summary text persisted with the request.
  • subtitlestring or nullOptional subtitle stored on the request and source rows.
  • narratorsstring or nullOptional narrator list as a single display string.
  • seriesstring or nullOptional series name.
  • series_indexstring or nullOptional series position as a display string.
  • publisherstring or nullOptional publisher name.
  • length_minutesinteger (int64) or nullOptional runtime in minutes.
  • published_atstring or nullOptional publication date as a display string.
  • genresstring or nullOptional genre list as a single display string.
  • languagestring or nullOptional content language code.

CreateUserRequest

Provisioner body for creating a user and optional invite ticket.

  • rolestring or nullRole to assign when permitted (member when omitted).
  • display_namestring or nullOptional display name for the new user.
  • login_namestring or nullOptional local login name for the new user.
  • emailstring or nullOptional email for the new user.
  • passwordstring or nullOptional password; hashed before persist. Empty or omitted leaves the user passwordless.
  • mint_invitebooleanWhen true (default), also mint an invite/claim ticket.

DatabaseMigrateRequest

Body for copying library rows between database plugins.

  • fromstring or nullSource plugin id. Defaults to the active [database].plugin before reload.
  • tostringrequiredDestination database plugin id to copy into.
  • dry_runbooleanWhen true, count rows without writing.
  • forcebooleanWhen true, overwrite a destination that is not empty.
  • applybooleanUpdate [database].plugin in config.toml after a successful copy.

DefaultAdminControlsJson

The library's default Administrator switches as the switch routes report them.

  • controlsAdminControlsrequiredThe switches every Administrator follows unless set for them alone.

DefaultControlsJson

The library's default member controls as the control routes report them.

  • controlsMemberControlsrequiredThe controls every Member follows unless set for them alone. Administrators do not follow it.

DefaultScopeJson

The library's default scope as the scope routes report it.

  • scopePatronScoperequiredThe scope patrons without their own follow.

DefaultSwitchChanges

Changes to some of the library's default switches: a new value for each named switch; an absent switch keeps its stored value.

  • manage_membersboolean or nullNew default for [AdminControl::ManageMembers].
  • set_patron_limitsboolean or nullNew default for [AdminControl::SetPatronLimits].
  • library_scanboolean or nullNew default for [AdminControl::LibraryScan].
  • run_jobsboolean or nullNew default for [AdminControl::RunJobs].
  • fix_catalogboolean or nullNew default for [AdminControl::FixCatalog].
  • invite_branchesboolean or nullNew default for [AdminControl::InviteBranches].
  • approve_requestsboolean or nullNew default for [AdminControl::ApproveRequests].

DeliveryBacklog

Event delivery backlog across the library.

  • pendinginteger (int64)requiredDeliveries waiting for a consumer.
  • runninginteger (int64)requiredDeliveries a consumer is handling now.
  • dead_letterinteger (int64)requiredDeliveries that exhausted their retries.
  • oldest_pending_age_secsinteger (int64) or nullAge of the oldest pending delivery in seconds; null when none is pending.

DeliveryJson

One delivery-log row.

  • idstringrequiredDelivery id.
  • notification_idstringrequiredThe notification.
  • notification_typestringrequiredIts type.
  • titlestringrequiredIts title.
  • destination_idstringrequiredThe destination.
  • plugin_instance_idstringrequiredThe notifier instance.
  • statestringrequiredpending, delivered, failed or dropped.
  • attemptsinteger (int64)requiredSend attempts made.
  • provider_idstring or nullThe service's id for the delivered message.
  • reasonstring or nullThe last failure or retry reason.
  • created_atstringrequiredWhen it was made (RFC 3339).
  • updated_atstringrequiredWhen it last changed (RFC 3339).

DeliveryPage

One page of the delivery log.

  • deliveriesarray of DeliveryJsonrequiredNewest first.
  • next_cursorstring or nullPass as cursor for the next page; null on the last page, where paging stops.

DeploymentConflict

PUT /api/config/plugin-instances/{id}/deployments/{node_id} 409 body: the two conflicts a deployment write can hit.

Type: RevisionConflict or ErrorMessage

DesiredState

What a deployment row asks its node to do, and who decided it.

Operators write [DesiredState::Present] and [DesiredState::Absent] (plugins deploy|undeploy, the Settings switch). The placement scheduler writes [DesiredState::Placed] and [DesiredState::Unplaced] for an instance it owns. A node runs the instance for present and placed and retires it for absent and unplaced; the split only records whose decision the row carries, so "the operator turned this off" never reads like "the scheduler put the replica elsewhere".

Type: one of present, absent, placed, unplaced

DestinationFilter

Which books one destination takes.

  • rulesarray of FilterRuleFilter rules, at most 64. Empty means the destination takes every book. At most 64 items.

DestinationFilterResponse

GET and PUT /api/config/plugin-instances/{id}/filter body: which books a storage destination takes.

  • plugin_instance_idstringrequiredThe destination's plugin instance id.
  • revisioninteger (int64)requiredRevision of the destination's core.destination document; 0 when none was written, so the destination takes every book.
  • filterDestinationFilterrequiredThe filter; no rules take every book.

DestinationJson

A destination as administrators and its owner see it. The address is never returned: it may hold secrets.

  • idstringrequiredDestination id.
  • kindDestinationKindrequiredchannel (the library's) or personal (a patron's).
  • plugin_instance_idstringrequiredThe notifier instance that carries it.
  • labelstringrequiredName shown in pickers.
  • failure_countinteger (int64)requiredDeliveries in a row that ended failed, whether refused for good or out of attempts; a delivery, or resuming the destination, resets it to 0. It pauses at 5.
  • paused_atstring or nullWhen repeated failures paused it (RFC 3339); null while active.
  • paused_reasonstring or nullWhy it was paused.
  • created_atstringrequiredWhen it was made (RFC 3339).

DestinationKind

Whether a destination is a library channel or one patron's address.

Type: one of channel, personal

DeviceInfoBody

The device an app plays on, as it describes itself.

  • clientNamestring or nullThe app's name.
  • manufacturerstring or nullThe device's maker.
  • modelstring or nullThe device's model.
  • deviceNamestring or nullThe name the patron gave the device.

DiagnosticsReportDeleted

Body of DELETE /api/diagnostics/reports/{id}.

  • report_idstringrequiredThe report's ID.
  • deleted_at_unix_msinteger (int64)requiredWhen its stored copy was deleted, Unix milliseconds. At least 0.

DiagnosticsReportLookup

Body of GET /api/diagnostics/reports/{id}: the report as the collector holds it, and what became of it.

  • report_idstringrequiredThe report's ID.
  • received_at_unix_msinteger (int64)requiredWhen the collector received it, Unix milliseconds. At least 0.
  • deleted_at_unix_msinteger (int64) or nullWhen its stored copy was deleted, Unix milliseconds, or null. At least 0.
  • reportStoredReportView or nullThe stored report, or null once deleted.
  • issuesarray of ReportIssueViewrequiredIssues tracking it, the tracking issue first.
  • fixReportFixView or nullThe tracking issue's fix, or null.

DiagnosticsReportsResponse

Body of GET /api/diagnostics/reports.

DiagnosticsReportView

One diagnostics report this install sent.

  • report_idstringrequiredThe collector's ID for the report (a UUID). The GitHub issue filed for it mentions this ID; search the issues for it or give it to a maintainer.
  • triggerstringrequiredWhy it was sent: crash, error_burst, slow_burst, job_failed, cli_error, cli_manual, ….
  • versionstringrequiredThe Bookclerk version that sent it.
  • sent_at_unix_msinteger (int64)requiredWhen the collector accepted it, Unix milliseconds. At least 0.
  • access_codestring or nullThe code that reads the report back or deletes it, in groups of four, or null when the collector issued none. With the ID it also opens the collector's public lookup page.
  • deleted_at_unix_msinteger (int64) or nullWhen this install deleted the collector's stored copy, Unix milliseconds, or null while it is stored. At least 0.

DisconnectBody

POST /api/config/join/connections/disconnect body.

  • plugin_keystringrequiredProvenance-qualified plugin key of the storefront.
  • account_idstringrequiredStore account id.
  • everywherebooleanAlso disconnect it in every linked library it was shared with; absent means false.

Disconnected

JSON body after POST /api/config/join/connections/disconnect.

  • herebooleanrequiredThe account was the person's here and is disconnected here now.
  • librariesarray of stringrequiredLinked libraries (parent library ids) that confirmed the disconnect.
  • unreachedarray of stringrequiredLinked libraries that could not be reached or refused; the account stays connected there until the person disconnects it there.

DiscoverFeed

Full Discover page payload: ordered shelves of personalized candidates.

  • shelvesarray of DiscoverShelfrequiredOrdered horizontal shelves that make up the Discover page.
  • shelf_kindsarray of ShelfKindInfoCatalog of shelf kinds for ignore prefs (empty disabled_shelves = all on).
  • stateFeedState or nullWhether these are the caller's current shelves, set by the daemon's read of the stored feed. Absent in a stored feed and from the CLI.
  • computed_atstring or nullRFC 3339 time the shelves were ranked; absent while state is preparing.

DiscoverShelf

One horizontal Discover row (series to finish, more by author, …).

  • idstringrequiredStable identifier for this item.
  • titlestringrequiredDisplay title as shown on the storefront or library card.
  • subtitlestring or nullOptional subtitle when the catalog distinguishes it from the title.
  • itemsarray of RecommendationrequiredOrdered collection of child entries for this response.

DiscoverStatusResponse

Stored Discover state of the caller's shelves.

  • subjectstringrequiredThe caller's subject key (operator, user:<id>, portal:<id>).
  • readybooleanrequiredTrue once the caller has stored shelves to show.
  • scopestring or nullSeeds the stored feed was ranked from (own or household), when ranked.
  • feed_computed_atstring or nullRFC 3339 time the stored feed was ranked, when ranked.
  • candidates_fetched_atstring or nullRFC 3339 time the caller's last storefront fetch finished, when any.
  • updatingbooleanrequiredTrue while a fetch or ranking for the caller is waiting or running.

DiscoveryDocument

OIDC discovery document served at /.well-known/openid-configuration.

  • issuerstringrequiredIssuer origin used as iss in minted JWTs (public_origin or loopback).
  • authorization_endpointstringrequiredAbsolute URL of the authorization endpoint (/oidc/authorize).
  • token_endpointstringrequiredAbsolute URL of the token endpoint (/oidc/token).
  • userinfo_endpointstringrequiredAbsolute URL of the userinfo endpoint (/oidc/userinfo).
  • revocation_endpointstringrequiredAbsolute URL of the refresh-token revocation endpoint (/oidc/revoke).
  • response_types_supportedarray of stringrequiredSupported response_type values; this server only issues code.
  • grant_types_supportedarray of stringrequiredSupported token grants: authorization_code and refresh_token.
  • code_challenge_methods_supportedarray of stringrequiredPKCE methods; only S256 is accepted (plain is rejected).
  • scopes_supportedarray of stringrequiredScopes advertised to clients (openid, profile, and email).
  • subject_types_supportedarray of stringrequiredSubject identifier types; only public (stable user id) is used.
  • id_token_signing_alg_values_supportedarray of stringrequiredID-token signing algorithms; tokens are HS256 with a derived key.
  • token_endpoint_auth_methods_supportedarray of stringrequiredClient auth methods: public PKCE (none) or client_secret_post.

DomainEventInfo

Operator JSON for one domain_events row.

  • idstringrequiredEvent id.
  • eventTypestringrequiredEvent type (book_acquired).
  • schemaVersioninteger (int64)requiredPayload schema version.
  • dispatchStatestringrequiredpending or dispatched.
  • accountIdstringrequiredTenant / account id.
  • dedupKeystringrequiredProducer idempotency key.
  • createdAtstringrequiredRFC 3339 insert time.
  • queueNamestringrequiredQueue the row belongs to (core.events for domain events).
  • contentTypestringrequiredBody encoding (json, text, bytes).
  • sourcestringrequiredProducer plugin id; empty when the host published it.
  • deliverAfterstring or nullRFC 3339 earliest delivery time for delayed queue messages.

DomainReplayed

Body of a PUT to a configuration domain whose write committed but could not be read back as the current document: another write landed between the commit and the read-back, so only the committed revision is reported (the library also returns it when a request id is replayed).

  • namespacestringrequiredDomain namespace (core.events or core.output).
  • replayedbooleanrequiredAlways true: the write was a replay.
  • revisioninteger (int64)requiredRevision the earlier write produced.

DomainRevision

Where a configuration domain document lives and which revision it is at: the metadata every domain response carries before its settings.

  • namespacestringrequiredDomain namespace (core.events or core.output).
  • scope_typestringrequiredScope type: library for a shared document, node for one node's.
  • scope_idstringrequiredScope id: singleton for the library, else the node id.
  • schema_versioninteger (int64)requiredVersion of the document's schema, starting at 1.
  • revisioninteger (int64)requiredCompare-and-swap revision; send it back as expected_revision.
  • updated_atstringrequiredRFC 3339 time of the last write.
  • updated_bystringrequiredAudit identity of the last writer.

DownloadRequestBody

POST /api/download-requests body: the work to download.

  • work_idstringrequiredThis library's work id, as its window books and search name it.

DownloadRequestQueued

POST /api/download-requests answer.

  • job_idstringrequiredThe acquire job, as /api/jobs lists it.
  • edition_idstringrequiredThe edition being downloaded.
  • already_queuedbooleanrequiredtrue when a download of that edition was already waiting or running; job_id is that download.

EditionChapter

One chapter of a checked list.

Named EditionChapter in the OpenAPI documents, apart from the player apps' Chapter.

  • titlestringrequiredChapter title; never empty, at most 512 bytes, no control characters.
  • start_msinteger (int64)requiredStart, in milliseconds from the start of the edition's timeline. At least 0.
  • depthinteger (int32)requiredNesting depth; 0 for a top-level chapter, at most 7. A chapter at depth n + 1 is nested under the nearest earlier chapter at depth n. At least 0.

EditionChaptersJson

The chapters an edition plays.

  • edition_idstringrequiredThe edition.
  • chaptersarray of EditionChapterrequiredThe chapters in pre-order, starts never decreasing; empty when the edition has none or an Administrator cleared them.
  • source_kindChapterSourceKind or nullThe kind of source the chapters came from; absent when the edition has no chapters yet.
  • source_idstring or nullWhich source of that kind (a PluginKey; empty for an edit or for Bookclerk's own processing).
  • runtime_msinteger (int64) or nullLength of the timeline the starts were measured on, in milliseconds. At least 0.

EditionJson

One edition of a work.

  • idstringrequiredEdition id.
  • work_idstringrequiredThe work it realises: this work, or one of a show's episodes.
  • expression_idstringrequiredThe expression it carries.
  • expression_kindExpressionKindJsonrequiredHow the expression realises the work.
  • languagestring or nullThe expression's language tag, when known.
  • abridgementAbridgementJsonrequiredWhether the expression is abridged.
  • media_kindMediaKindJsonrequiredCarrier of the edition.
  • titlestringrequiredThe edition's title.
  • subtitlestring or nullThe edition's subtitle.
  • published_atstring or nullPublication date as the store gave it.
  • duration_minutesinteger (int64) or nullRunning time in minutes, for audio.
  • cover_pathstring or nullSame-origin path of the edition's cover, when it has one.
  • acquire_statusAcquireStatusrequiredThe edition's acquire state.
  • listingsarray of ListingJsonrequiredThe edition's store listings.

Elevated

JSON body after a successful Owner elevation.

  • okbooleanrequiredAlways true on this success path.
  • elevatedbooleanrequiredAlways true: the cookie the response sets is an elevated operator session.
  • expires_in_secsinteger (int64)requiredSeconds until the elevated session expires. At least 0.

ElevateRequest

JSON body for Owner password re-auth before issuing an elevated operator cookie.

  • passwordstringrequiredOwner account password (re-authentication).

EmptyPage

An empty page, for collections and playlists the library does not have yet.

  • resultsarray of objectrequiredAlways empty.
  • totalinteger (int64)requiredAlways 0. At least 0.
  • limitinteger (int64)requiredItems per page, echoed. At least 0.
  • pageinteger (int64)requiredThe page number, echoed. At least 0.

EnrollBody

POST /api/node/v1/enroll body. Keys are base64url without padding.

  • link_idstringrequiredLink id from the token.
  • secretstringrequiredLink secret from the token.
  • sign_pkstringrequiredEd25519 public signing key.
  • box_pkstringrequiredX25519 public box key.
  • software_versionstringHost's Bookclerk version.

EnrolledNodeView

JSON body after an enrollment link or branch sign-in was redeemed.

  • library_idstringrequiredThe library the node joined.
  • node_idstringrequiredThe node id minted for it.

EnrollFinish

First TOTP code that confirms the pending secret.

  • codestringrequiredSix-digit code from the authenticator app.

EnrollmentLinkView

An enrollment link as the invites routes list it; never its secret.

  • link_idstringrequiredPublic link id.
  • for_user_idinteger (int64)requiredUser the enrolled node will belong to.
  • labelstringrequiredLabel shown in listings.
  • created_bystringrequiredAudit id of whoever minted it (operator or user:<id>).
  • created_atstringrequiredRFC 3339 mint time.
  • expires_atstringrequiredRFC 3339 expiry.
  • redeemed_atstring or nullRFC 3339 redeem time, once a host used it.
  • redeemed_node_idstring or nullNode the redeem created.
  • revoked_atstring or nullRFC 3339 revoke time.
  • statestringrequiredpending, redeemed, revoked, or expired right now.

EntitlementJson

On what terms a holder has a listing.

Type: one of purchase, plus, loan, free, own

ErrorAnswer

An error answer in one of several shapes: the standard body, error alone, or error with detail; the route's examples name each.

Type: ErrorJson or ErrorMessage or ErrorDetail

ErrorDetail

JSON error body with a machine slug and a longer explanation (detail).

  • errorstringrequiredStable machine slug clients branch on.
  • detailstringrequiredWhat went wrong, for the person reading the answer.

ErrorJson

JSON error object (error, message, numeric status) for API clients.

  • errorstringrequiredMachine slug (same as [ErrorBody::code]).
  • messagestringrequiredOperator-facing explanation.
  • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.

ErrorMessage

JSON error object with a single error message, written by handlers that report a library or plugin error in their own words.

  • errorstringrequiredWhat went wrong, as the handler describes it.

EventDeliveryInfo

Operator JSON for one event_deliveries row.

  • idstringrequiredDelivery id ({event_id}:{plugin_id}).
  • eventIdstringrequiredParent event id.
  • pluginIdstringrequiredSubscriber plugin id.
  • statestringrequiredLifecycle state.
  • attemptCountinteger (int64)requiredClaim count (not incremented on resume).
  • leaseGenerationinteger (int64)requiredFence generation.
  • invocationSequenceinteger (int64)requiredResume ordinal.
  • outcomestring or nullTerminal outcome when set.
  • errorMessagestring or nullOperator-facing error.
  • runAfterstringrequiredRFC 3339 earliest claim time.
  • updatedAtstringrequiredRFC 3339 last update.
  • cancelRequestedbooleanrequiredCooperative cancel flag.
  • resourceClassstringrequiredConcurrency class (network today).
  • resumePendingbooleanrequiredNext claim should resume rather than increment attempt.
  • hasCheckpointbooleanrequiredTrue when a suspend checkpoint is stored.
  • queueNamestringrequiredQueue of the parent event.

EventQueueStatus

Outbox delivery counts for GET /api/status.

  • pendinginteger (int64)requiredPending deliveries without a suspend checkpoint.
  • runninginteger (int64)requiredCurrently claimed deliveries.
  • suspendedinteger (int64)requiredPending deliveries parked with a checkpoint.
  • dead_letterinteger (int64)requiredDead-lettered deliveries.
  • ackedinteger (int64)requiredSuccessfully acked deliveries.
  • oldest_pending_age_secsinteger (int64) or nullAge in seconds of the oldest pending delivery, when any exist.
  • retries_totalinteger (int64)requiredDurable retry outcomes (including reclaim-as-retry).
  • suspensions_totalinteger (int64)requiredDurable suspend outcomes.
  • dead_letters_totalinteger (int64)requiredDurable transitions into dead_letter.
  • dispatch_latency_ms_avginteger (int64) or nullAverage first-dispatch latency in milliseconds, when sampled.
  • handler_latency_ms_avginteger (int64) or nullAverage onEvent handler duration in milliseconds, when sampled.

EventsDomainChange

Body of PUT /api/config/domains/core.events: the settings after the change, or a replay note.

Type: EventsDomainResponse or DomainReplayed

EventsDomainResponse

Body of GET /api/config/domains/core.events and of a PUT that was applied: the revision metadata, then the [events] settings themselves.

Includes every field of DomainRevision, EventsSettingsV1.

EventsSettingsV1

Typed [events] document, schema version 1.

  • retention_daysinteger (int64)requiredDays to keep acked and rejected deliveries. At least 0.
  • dead_letter_retention_daysinteger (int64)requiredDays to keep dead-lettered deliveries. At least 0.
  • concurrencyinteger (int32)requiredLocal delivery workers and the library in-flight cap. At least 0.

ExplicitContent

Whether a patron sees books marked as explicit (adult) content.

Type: one of allow, hide

ExpressionKindJson

How an expression realises its work (expressions.kind).

Type: one of text, narration, dramatisation, graphic, original_audio

FacetValueJson

One value of a facet.

  • valuestringrequiredThe value, as value of GET /api/library/works takes it.
  • worksinteger (int64)requiredHow many held works have it. At least 0.

FacetValuesJson

A page of GET /api/library/works/facets/{facet}.

  • valuesarray of FacetValueJsonrequiredThe values, in order of their lower-cased spelling.
  • next_cursorstring or nullPass as cursor for the next page; absent on the last page.

FeedState

How current a stored Discover feed is.

Type: one of ready, refreshing, preparing

FieldJson

One labelled value.

  • namestringrequiredLabel.
  • valuestringrequiredValue.

FileMetadata

A file's name, size and times.

  • filenamestringrequiredThe file name.
  • extstringrequiredThe extension with its dot (.m4b).
  • pathstringrequiredA display path: the file name.
  • relPathstringrequiredA display path: the file name.
  • sizeinteger (int64)requiredThe file's size in bytes. At least 0.
  • mtimeMsinteger (int64)requiredWhen the file was stored, in epoch milliseconds.
  • ctimeMsinteger (int64)requiredWhen the file was stored, in epoch milliseconds.
  • birthtimeMsinteger (int64)requiredWhen the file was stored, in epoch milliseconds.

FileTimestampMode

Which timestamp to apply after acquire (CreationTime / LastWriteTime).

Type: one of now, purchased, published

FilterData

The values an app offers as filters.

  • authorsarray of NamedRefrequiredAuthors with at least one item.
  • genresarray of stringrequiredGenres.
  • tagsarray of stringrequiredTags: none are shown.
  • seriesarray of NamedRefrequiredSeries with at least one item.
  • narratorsarray of stringrequiredNarrators.
  • languagesarray of stringrequiredLanguages.
  • publishersarray of stringrequiredPublishers.
  • publishedDecadesarray of stringrequiredDecades of publication: none are offered.
  • bookCountinteger (int64)requiredItems in the library. At least 0.
  • authorCountinteger (int64)requiredAuthors in the library. At least 0.
  • seriesCountinteger (int64)requiredSeries in the library. At least 0.
  • podcastCountinteger (int64)requiredAlways 0. At least 0.
  • numberEpisodesinteger (int64)requiredAlways 0. At least 0.
  • loadedAtinteger (int64)requiredWhen the values were read, in epoch milliseconds.

FilterEffect

Whether a [FilterRule] lets matching books in or keeps them out.

Type: one of include, exclude

FilterField

The book field a [FilterRule] matches one value of.

Type: one of patron, storefront, account, media_kind, format, quality

FilterRule

One rule of a destination filter: a field, one value of it, and its effect.

  • fieldFilterFieldrequiredThe field the rule matches.
  • valuestringrequiredThe value: a user id for patron, book or podcast for media_kind, a copy format for format, a copy quality for quality, otherwise 1 to 128 bytes of text.
  • effectFilterEffectrequiredInclude or exclude.

GuestReservation

CPU and memory one guest may use at most: its grant's ceilings after the node's [plugins.jail] limits.

  • memory_bytesinteger (int64)requiredMemory ceiling in bytes.
  • cpu_millicoresinteger (int64)requiredCPU ceiling in millicores.

HealthResponse

Liveness payload for unauthenticated GET /health.

  • statusstringrequiredAlways ok when the process can serve HTTP.

HolderJson

Who holds a listing.

Type: object

HoldingJson

One holding of a listing.

  • idstringrequiredHolding id.
  • holderHolderJsonrequiredWho holds the listing.
  • entitlementEntitlementJsonrequiredOn what terms.
  • purchased_atstring or nullRFC 3339 purchase time, when the store reported one.
  • added_atstringrequiredRFC 3339 time the holding was first recorded.

ImpersonateRequest

JSON body naming the first-party user to impersonate.

  • user_idinteger (int64)requiredTarget users.id to impersonate.

ImpersonationStarted

JSON body after an operator session started impersonating a user.

  • okbooleanrequiredAlways true on this success path.
  • impersonatingAuthMeImpersonatingrequiredThe user the session now acts as.

InboxEntryJson

One inbox entry.

  • idstringrequiredNotification id.
  • notification_typestringrequiredType id.
  • severitystringrequiredinfo, warning or critical.
  • titlestringrequiredTitle.
  • textstringrequiredPlain-text body.
  • link_pathstring or nullPath inside the library it links to.
  • fieldsarray of FieldJsonrequiredLabelled values.
  • created_atstringrequiredWhen it arrived (RFC 3339).
  • read_atstring or nullWhen the patron read it (RFC 3339); null while unread.

InboxPage

One page of the inbox.

  • entriesarray of InboxEntryJsonrequiredNewest first.
  • unreadinteger (int64)requiredUnread entries in the whole inbox. At least 0.
  • next_cursorstring or nullPass as cursor for the next page; null on the last page, where paging stops.

IngressChange

POST /api/config/ingress body: each field is one change, applied in order (off or on, then exposure, then accepting a reported origin).

  • activatestring or nullMakes this the library's active ingress: a plugin instance UUID, or a plugin key for that plugin's default instance.
  • deactivatebooleanTurns ingress off; the adopted origin is kept.
  • exposureIngressExposure or nullWhat public traffic may reach.
  • accept_reported_originbooleanAdopts the origin the active instance reported. Renaming the library breaks passkeys and sign-in redirects registered under the old name.

IngressExposure

What public traffic from the ingress may reach.

Type: one of branches, library

IngressStatus

GET /api/config/ingress and the answer to POST /api/config/ingress: the library's ingress settings and what they mean now.

  • active_instancestring or nullThe plugin instance serving the library's public address, as its UUID; null when ingress is off.
  • plugin_keystring or nullThe active instance's plugin, when the instance exists.
  • exposureIngressExposurerequiredWhat public traffic may reach.
  • originstring or nullThe adopted public origin, kept while ingress is off.
  • reported_originstring or nullA different origin the active instance reported, waiting for the operator to accept it.
  • public_originstring or nullThe origin the library serves under now: integrations.public_origin when set, else the ingress origin while the instance runs.
  • operator_overridebooleanrequiredTrue when integrations.public_origin in config.toml overrides the ingress origin.
  • blockedstring or nullWhy ingress can't run now (no Owner yet, or operator auth off); null when it can.

InspectBody

POST /api/config/join/inspect body.

  • addressstringrequiredThe library's address (https://owner.example, owner.lan:8443).

InspectedLibraryResponse

JSON body for POST /api/config/join/inspect.

InspectedLibraryView

A library as POST /api/config/join/inspect saw it.

  • library_idstringrequiredThe library id.
  • library_namestringrequiredA name to show for the library.
  • originstringrequiredIts canonical origin.
  • transportstringrequiredThe node API transport mode (acme, proxy, self_signed, loopback).
  • enrollmentbooleanrequiredWhether it lets new branches join.
  • fingerprintstring or nullThe SPKI fingerprint to confirm (self-signed libraries only).
  • needs_fingerprintbooleanrequiredWhether the operator must confirm fingerprint before joining.

InstalledPluginDetail

GET /api/config/plugins/{key} body: the plugin and its pinned schema.

Includes every field of InstalledPluginSummary.

InstalledPluginsResponse

GET /api/config/plugins body.

InstalledPluginSummary

One installed plugin: its active version and every installed version, newest first.

  • plugin_keystringrequiredCanonical plugin key.
  • idstring or nullManifest id (display alias) of the active version, or of the newest one when none is active; null without versions.
  • active_versionstring or nullActive version; null when the plugin is installed but not activated.
  • revisioninteger (int64) or nullCompare-and-swap revision of the active-version pointer; null when nothing is active.
  • versionsarray of PluginVersionSummaryrequiredEvery installed version, newest first.

InstanceConfigView

Instance document as the API renders it: values and secret names only.

  • revisioninteger (int64)requiredCompare-and-swap revision.
  • settingsmap of string to SettingValuerequiredScalar settings the operator wrote.
  • secret_refsarray of InstanceSecretRefV1requiredSecret refs; ciphertext stays in encrypted_secrets.

InstanceSecretRefV1

A name in encrypted_secrets. The ciphertext is not part of the document.

  • keystringrequiredKey in the SECRETS object delivered to the guest.
  • namestringrequiredencrypted_secrets.name for this instance.

IntakeAttribution

Who holds the books a drop folder ingests.

Type: one of owner, subfolder

IntakeResponse

GET, PUT and DELETE /api/config/plugin-instances/{id}/intake body: whether a storage instance is a drop folder, and its settings.

  • plugin_instance_idstringrequiredThe storage instance's plugin instance id.
  • revisioninteger (int64)requiredRevision of the instance's core.intake document; 0 when none was written, so the instance is a destination.
  • intakeIntakeSettings or nullThe drop folder's settings; null when the instance is a destination.

IntakeSettings

The settings of one drop folder (core.intake).

Every field has a default, so {} is a valid body only when attribute_to is subfolder; owner needs a patron.

  • settle_secondsinteger (int32)requiredSeconds an item's files must stay unchanged before it is ingested, 5 to 86,400 (default 60). At least 5; at most 86400.
  • scan_interval_secondsinteger (int32)requiredSeconds between two full listings of the folder, 30 to 86,400 (default 300). A change feed starts a listing sooner. At least 30; at most 86400.
  • after_ingestAfterIngestrequiredWhat happens to an item once it is ingested (default move).
  • attribute_toIntakeAttributionrequiredWho holds the ingested books (default owner).
  • patroninteger (int64) or nullThe user id that holds every book in owner mode; required there and refused in subfolder mode. At least 1.
  • ignorearray of stringrequiredExtra file name patterns to ignore, at most 64, each 1 to 128 bytes with no /: * matches any run of characters and ? one character, compared without ASCII case. The built-in list always applies too ([BUILTIN_IGNORE_PATTERNS]). At most 64 items.
  • prune_imported_daysinteger (int32) or nullWith after_ingest = move, delete _imported day folders older than this many days, 1 to 3,650; absent keeps them. At least 1; at most 3650.

IntakeSettingsRequest

The drop folder settings as a request body may send them: every field may be left out and takes the default [IntakeSettings] names. Only the published API schema uses it; the body is read as [IntakeSettings].

  • settle_secondsinteger (int32)Seconds an item's files must stay unchanged before it is ingested, 5 to 86,400 (default 60). At least 5; at most 86400.
  • scan_interval_secondsinteger (int32)Seconds between two full listings of the folder, 30 to 86,400 (default 300). At least 30; at most 86400.
  • after_ingestAfterIngestWhat happens to an item once it is ingested (default move).
  • attribute_toIntakeAttributionWho holds the ingested books (default owner).
  • patroninteger (int64) or nullThe user id that holds every book in owner mode; required there and refused in subfolder mode. It must name an active user. At least 1.
  • ignorearray of stringExtra file name patterns to ignore, at most 64, each 1 to 128 bytes with no / (default none). At most 64 items.
  • prune_imported_daysinteger (int32) or nullWith after_ingest = move, delete _imported day folders older than this many days, 1 to 3,650; absent keeps them. At least 1; at most 3650.

IntegrationLoginBody

JSON body for POST /login/integration (provider credential login).

  • providerstringrequiredIntegration plugin id (must be enabled in config).
  • usernamestringrequiredProvider login name forwarded to authenticate_user.
  • passwordstringrequiredProvider password; never logged.

IntegrationScanRequest

Optional body for POST /integrations/{id}/scan.

  • forceboolean or nullWhen true, the integration rescans even if it considers itself current.

InviteBody

POST /api/config/join/invite body.

  • linkstringrequiredThe whole branch invite (https://<library>/enroll#bcn1...).

ItemListening

Seconds listened to one item.

  • idstringrequiredThe item id.
  • timeListeningnumber (double)requiredSeconds listened.
  • mediaMetadataBookMetadatarequiredThe item's metadata.

ItemPage

A page of items: GET /api/libraries/{id}/items and the like.

  • resultsarray of LibraryItemrequiredThe page's items.
  • totalinteger (int64)requiredItems matching the query in all. At least 0.
  • limitinteger (int64)requiredItems per page (0: no paging). At least 0.
  • pageinteger (int64)requiredThe page number, from 0. At least 0.
  • sortBystring or nullThe sort key the app sent, echoed.
  • sortDescbooleanrequiredWhether the order is reversed.
  • filterBystring or nullThe filter the app sent, echoed.
  • mediaTypestringrequiredAlways [MEDIA_TYPE_BOOK].
  • minifiedbooleanrequiredWhether items are minified.
  • collapseseriesbooleanrequiredWhether series were collapsed: never.
  • includestringrequiredThe include list the app sent, echoed.
  • offsetinteger (int64)requiredThe offset of the first result. At least 0.

JobInfo

Snapshot of one queued or running control-plane job.

  • idstringrequiredOpaque job id returned to the client when the job is accepted.
  • kindJobKindrequiredWhat the job does.
  • statusJobStaterequiredWhere the job is in its lifecycle.
  • detailstring or nullOptional operator-facing progress or error text.
  • progressstring or nullHuman-readable progress string while the job is running.
  • attempt_countinteger (int64)Number of times a worker has claimed this row.
  • max_attemptsinteger (int64)Maximum claims before a failure is terminal.
  • error_kindstring or nullStructured error kind when failed or cancelled.
  • created_atstring or nullRFC 3339 timestamp when the row was inserted.
  • finished_atstring or nullRFC 3339 timestamp when the row reached a terminal state.

JobKind

Kind of durable daemon work stored in the jobs table.

Type: one of scan, acquire, listen_sync, integration_scan, plugin_copy, plugin_scheduled, discover_candidates, discover_feed, discover_request_queue, cache_sweep, search_index_rebuild, library_index_rebuild, branch_request, ingest_batch, notify_send, invalid

JobState

Lifecycle state of a durable job row.

Type: one of pending, running, succeeded, failed, cancelled

JobStatusEntry

One job's state in [Body::JobStatuses].

  • idstringrequiredJob id.
  • kindstringrequiredJob kind (scan, acquire, ...).
  • statestringrequiredpending, running, succeeded, failed, or cancelled.
  • progressstring or nullProgress or result text.
  • error_kindstring or nullStructured error kind when it failed or was cancelled.
  • error_messagestring or nullError text when it failed or was cancelled.

JoinCompleted

JSON body once a join completed: as a branch, or as a shared branch.

Type: BranchJoined or SharedBranchJoined

JoinConflict

A 409 from a join step: the handler's error, or an origin mismatch that names the address to join with; the route's examples name each.

Type: ErrorDetail or OriginMismatch

JoinStarted

JSON body for POST /api/config/join/start.

  • authorize_urlstringrequiredThe library's sign-in URL to open in the browser.
  • libraryInspectedLibraryViewrequiredWhat the library said about itself.
  • branch_namestringrequiredThe name this install asked to join as.
  • shared_branch_offeredbooleanrequiredWhether joining as a shared branch was offered.
  • expires_in_secsinteger (int64)requiredSeconds the pending sign-in stays valid. At least 0.

JoinStatus

JSON body for GET /api/config/join.

  • freshbooleanrequiredWhether this install has no users, no libraries and no library cards yet.
  • has_ownerbooleanrequiredWhether an Owner (or legacy administrator) exists here.
  • shared_branch_eligiblebooleanrequiredWhether this install could still join a library as a shared branch.
  • shared_branch_problemstring or nullWhy it cannot join as a shared branch, when it cannot.
  • default_branch_namestringrequiredThe name a join is offered under by default (this machine's name).
  • linksarray of LibraryLinkViewrequiredEvery library this install is a branch of, with whether its client runs.

LameConfig

LAME encoder tuning (classic Lame* settings).

  • targetstringLameTarget: quality, bitrate, constant, etc. Default "quality".
  • vbr_qualityinteger (int32)LameVBRQuality (0–9, lower = better). At least 0; default 2.
  • bitrate_kbpsinteger (int32)LameBitrate in kbps when target is bitrate/constant. At least 0; default 128.
  • modestringLameMode: default, mono, stereo. Default "default".
  • downsample_monobooleanLameDownsampleMono. Default false.
  • constant_bitratebooleanLameConstantBitrate. Default false.

LeaseView

A library lease as the status page shows it.

  • namestringrequiredLease name.
  • holderstringrequiredHolder (a node id).
  • tokeninteger (int64)requiredFencing token; a new holder always gets a larger one.
  • heldbooleanrequiredTrue while the lease has not expired.
  • expires_at_msinteger (int64)requiredExpiry in Unix milliseconds.

LeaveBody

POST /api/config/join/leave body.

  • library_idstringrequiredThe library (parent library id) to leave.

LeaveStarted

JSON body once leaving a library started.

  • libraryLibraryLinkViewrequiredThe link, now left.
  • owner_notifiedbooleanrequiredWhether the library was told (otherwise it notices the missed heartbeats).

LeftBranch

The branch a card sign-in left.

  • owner_notifiedbooleanrequiredWhether the library accepted the leave notice. False when it could not be told: the branch then stays in its list until it is removed there.

Libraries

GET /api/libraries.

  • librariesarray of LibraryrequiredThe libraries the patron may open.

Library

One library an app can open.

  • idstringrequiredThe library id ([crate::ids::WHOLE_LIBRARY_ID] for the whole library).
  • namestringrequiredThe library's name.
  • foldersarray of objectrequiredFolders on disk: none are shown.
  • displayOrderinteger (int32)requiredThe library's place in the list, from 1. At least 0.
  • iconstringrequiredThe icon apps show (audiobookshelf names a book stack).
  • mediaTypestringrequiredAlways [MEDIA_TYPE_BOOK].
  • providerstringrequiredThe metadata provider apps show: none.
  • settingsLibrarySettingsrequiredDisplay settings.
  • lastScaninteger (int64) or nullAlways null.
  • lastScanVersionstring or nullAlways null.
  • createdAtinteger (int64)requiredWhen the library was made, in epoch milliseconds.
  • lastUpdateinteger (int64)requiredWhen it last changed, in epoch milliseconds.

LibraryAnswer

GET /player/api/libraries/{id} answer: the library, with its filter values when asked for (include=filterdata).

Type: LibraryWithFilterData or Library

LibraryCollection

One collection: a name and the storage key prefixes whose files belong to it.

  • namestringrequiredThe name people see and scope rules match, 1 to 64 bytes, distinct ignoring case.
  • prefixesarray of stringrequiredStorage key prefixes, 1 to 8, each a folder relative to the destination's root (no leading /); a closing / is added when missing, so kids matches kids/… but not kidsbooks/…. At most 8 items.

LibraryCollections

The library's collections: the core.collections document and the body of PUT /api/library/collections.

  • collectionsarray of LibraryCollectionrequiredThe collections, at most 32, in the order shown. At most 32 items.

LibraryConsentsResponse

JSON body for GET /api/config/library-consents.

  • librariesarray of LibraryLinkViewrequiredEvery library this install is a branch of.
  • consentsarray of RemoteConsentViewrequiredEvery plugin request from those libraries, pending or answered.

LibraryFile

A file of an item, in the expanded item's libraryFiles.

  • inostringrequiredThe file's ino ([crate::ids::file_ino]).
  • metadataFileMetadatarequiredThe file's name, size and times.
  • addedAtinteger (int64)requiredWhen the file was stored, in epoch milliseconds.
  • updatedAtinteger (int64)requiredWhen the file was stored, in epoch milliseconds.
  • fileTypestringrequiredAlways audio.

LibraryItem

An item: an edition with a stored copy.

  • idstringrequiredThe item id: the edition id.
  • inostringrequiredThe item's inode as apps expect one: the edition id again.
  • oldLibraryItemIdstring or nullAlways null.
  • libraryIdstringrequiredThe library the item is listed in.
  • folderIdstringrequiredThe folder id: the library id.
  • pathstringrequiredA display path: the title.
  • relPathstringrequiredA display path: the title.
  • isFilebooleanrequiredAlways false: an item is a folder of tracks.
  • mtimeMsinteger (int64)requiredWhen the copy last changed, in epoch milliseconds.
  • ctimeMsinteger (int64)requiredWhen the copy was stored, in epoch milliseconds.
  • birthtimeMsinteger (int64)requiredWhen the copy was stored, in epoch milliseconds.
  • addedAtinteger (int64)requiredWhen the item joined the library, in epoch milliseconds.
  • updatedAtinteger (int64)requiredWhen its record last changed, in epoch milliseconds.
  • isMissingbooleanrequiredAlways false.
  • isInvalidbooleanrequiredAlways false.
  • mediaTypestringrequiredAlways [MEDIA_TYPE_BOOK].
  • mediaBookMediarequiredThe book.
  • numFilesinteger (int64)requiredFiles in the item. At least 0.
  • sizeinteger (int64)requiredBytes in all its files. At least 0.
  • libraryFilesarray of LibraryFile or nullThe item's files, when the item is fetched expanded.
  • userMediaProgressMediaProgress or nullThe patron's progress, when the app asked for it.
  • seriesSequencestring or nullThe item's place in a series, on a series' book list.

LibraryItems

{ "libraryItems": [...] }: in-progress items and batch reads.

LibraryJobsBody

POST /api/config/libraries/{library_id}/jobs body.

  • job_idsarray of stringrequiredJob ids on the library.

LibraryJobsResponse

JSON body for POST /api/config/libraries/{library_id}/jobs.

  • jobsarray of JobStatusEntryrequiredThe owner's state of each job this install may see, in request order.

LibraryLinkView

A library this install is a branch of: ids, origin and state, never key material.

  • library_idstringrequiredThe library id.
  • owner_originstringrequiredThe library's canonical origin.
  • node_idstringrequiredThe node id the library minted for this install.
  • pinnedbooleanrequiredWhether the link pins the library's self-signed certificate.
  • statestringrequiredactive, revoked, or left.
  • enrolled_atstringrequiredRFC 3339 enrollment time.
  • share_booksbooleanrequired"Share this branch's books with the library".
  • include_branchesbooleanrequired"Include books from my own branches".
  • work_for_membersbooleanrequired"Download for other members of the library": this install takes the library's work for its other members too, not only its owner's (off by default).
  • keep_member_copiesbooleanrequired"Keep copies of other members' books": a book acquired here for another member is also written to this install's own destinations (off by default).
  • max_jobsinteger or nullThe most jobs this install runs for the library at once, as its operator set it; null gives the library an equal share of the machine. At least 0; at most 16.
  • job_shareinteger or nullHow many jobs the library may have running here now: its share of the machine after this install's own work, within max_jobs. Only the listing and sharing routes report it, and only while the link's client runs. At least 0.
  • list_members_booksbooleanrequired"List my members' books to the library": the library's catalog lookups are answered with members' books (except those who opted out) as well as the owner's.
  • keep_copiesbooleanrequired"Keep copies on this computer": the branch takes the library's copies of its person's books into its own storage. The branch takes the library's work and shows its books whether or not this is on.
  • runningboolean or nullWhether this install's client for the link is running now; only the join routes report it.

LibraryScanBody

POST /api/config/libraries/{library_id}/scan body.

  • accountstring or nullScan only this store account of the library.
  • plugin_instance_idstring or nullPin every planned job to this owner plugin instance.

LibraryScanPlanned

JSON body after the owner library queued a scan for this install.

  • library_idstringrequiredThe parent library's id.
  • createdarray of stringrequiredIds of the jobs the owner created.
  • duplicatesarray of stringrequiredIds of jobs that were already pending or running.
  • queue_fullinteger (int64)requiredPlanned jobs the owner's queue had no room for. At least 0.

LibrarySettings

A library's display settings.

  • coverAspectRatiointeger (int32)required1 for square covers, 2 for the 1.6:1 book shape: square. At least 0.
  • disableWatcherbooleanrequiredAlways true: the library is not a watched folder.
  • audiobooksOnlybooleanrequiredAlways true: audiobooks only.
  • hideSingleBookSeriesbooleanrequiredWhether one-book series are hidden from the series list: no.
  • onlyShowLaterBooksInContinueSeriesbooleanrequiredWhether continue series skips earlier books: no.
  • epubsAllowScriptedContentbooleanrequiredAlways false.
  • markAsFinishedPercentCompletenumber (double) or nullAn item counts as finished at this share listened, in percent.
  • markAsFinishedTimeRemainingnumber (double)requiredAn item counts as finished with this many seconds left.

LibraryStats

GET /api/libraries/{id}/stats.

  • totalItemsinteger (int64)requiredItems. At least 0.
  • totalAuthorsinteger (int64)requiredAuthors. At least 0.
  • totalGenresinteger (int64)requiredGenres. At least 0.
  • totalDurationnumber (double)requiredSeconds of audio in all.
  • numAudioTracksinteger (int64)requiredAudio tracks in all. At least 0.
  • totalSizeinteger (int64)requiredBytes in all: not counted. At least 0.

LibraryStatusResponse

GET /api/library-status body.

  • libraryLibrarySummaryrequiredLibrary-wide counters.
  • node_idstringrequiredId of the node that answered.
  • nodesarray of NodeViewrequiredThe nodes the caller administers.
  • capabilitiesNodeCapabilitiesrequiredWhat the caller may do with them.

LibrarySummary

Library-wide counters every node administrator may see.

  • nodesintegerrequiredNodes in the library's node list. At least 0.
  • liveintegerrequiredNodes whose last heartbeat is recent enough. At least 0.
  • drainedintegerrequiredLive nodes an operator drained. At least 0.
  • branch_nodesintegerrequiredEnrolled hosts (nodes with their own database). At least 0.
  • cpu_budget_millicoresinteger (int64)requiredCPU the scheduler may commit across live nodes, in millicores.
  • cpu_reserved_millicoresinteger (int64)requiredCPU the running guests' ceilings add up to, in millicores.
  • memory_budget_bytesinteger (int64)requiredMemory the scheduler may commit across live nodes, in bytes.
  • memory_reserved_bytesinteger (int64)requiredMemory the running guests' ceilings add up to, in bytes.
  • running_guestsinteger (int64)requiredGuests running across live nodes.
  • active_jobsinteger (int64)requiredJobs queued or running.
  • deliveriesDeliveryBacklogrequiredEvent delivery backlog.
  • leasesarray of LeaseViewrequiredEvery library lease, held or expired.
  • schemaSchemaStateViewrequiredThe database schema against this binary.

LibraryWithFilterData

GET /api/libraries/{id}?include=filterdata.

  • filterdataFilterDatarequiredThe filter values.
  • issuesinteger (int64)requiredItems with problems: none are reported. At least 0.
  • numUserPlaylistsinteger (int64)requiredThe patron's playlists in the library: none. At least 0.
  • libraryLibraryrequiredThe library.

LinkedIdentitiesResponse

JSON body for GET /api/auth/oidc/identities.

  • identitiesarray of LinkedIdentityrequiredEvery sign-in identity linked to the caller's user, the local one included.

LinkedIdentity

One sign-in identity linked to a user.

  • providerstringrequiredIdentity-broker id (local, oidc:google, …).
  • external_user_idstringrequiredProvider-stable subject.
  • labelstring or nullOperator-facing label, when the provider supplied one.

ListeningStats

GET /api/me/listening-stats.

  • totalTimenumber (double)requiredSeconds listened in all.
  • itemsmap of string to ItemListeningrequiredSeconds listened per item, by item id.
  • daysmap of string to number (double)requiredSeconds listened per day, by YYYY-MM-DD.
  • dayOfWeekmap of string to number (double)requiredSeconds listened per weekday, by English weekday name.
  • todaynumber (double)requiredSeconds listened today.
  • recentSessionsarray of PlaybackSessionrequiredThe most recent sessions.

ListingJson

One store listing of an edition.

  • idstringrequiredListing id.
  • plugin_keystringrequiredThe storefront plugin that lists it.
  • marketplacestringrequiredStore marketplace; empty when the store has one.
  • product_idstringrequiredThe store's product id.
  • urlstring or nullThe product page, when known.
  • holdingsarray of HoldingJsonrequiredThe listing's holdings.

LocalSessionBody

POST /player/api/session/local: a stretch of listening the app made offline.

  • idstringrequiredThe app's own id for the session.
  • libraryItemIdstringrequiredThe item.
  • currentTimenumber (double)requiredThe position, in seconds.
  • timeListeningnumber (double) or nullSeconds listened in the session.
  • durationnumber (double) or nullThe runtime the app measured, in seconds.
  • updatedAtinteger (int64) or nullWhen the app last updated the session, in epoch milliseconds.

LocalSessionsBody

POST /player/api/session/local-all: several offline sessions.

  • sessionsarray of LocalSessionBodyrequiredThe sessions; each is answered on its own.

LoginBegin

Login-name or email used to start a discoverable-less passkey login.

  • loginstringrequiredLogin name or email looked up before issuing an authentication challenge.

LoginBody

POST /player/login: a sign-in with a player password.

  • usernamestringrequiredThe patron's sign-in name or email address.
  • passwordstringrequiredA player password from Account settings; the account password is never accepted.

LoginRequest

JSON body for POST /api/auth/login (operator token).

  • tokenstringrequiredOperator token from the client; compared in constant time and never persisted.

LoginResponse

JSON body after a successful operator token login.

  • okbooleanrequiredAlways true on this success path.
  • rolestringrequiredIssued role (operator for token login).
  • default_viewstringrequiredPost-login SPA landing view from operator preferences (discover on lookup failure).

LoginThrottled

JSON body of a 429 after too many failed sign-in attempts from one client.

  • errorstringrequiredAlways too_many_requests.
  • messagestringrequiredCaller-facing explanation naming the wait.
  • statusinteger (int32)requiredAlways 429 (duplicates the response status for clients). At least 0.
  • retry_after_secsinteger (int64)requiredSeconds until this client may try again; the same value as Retry-After. At least 0.

LoginVerify

TOTP code plus the challenge id from password login.

  • challenge_idstringrequiredServer-issued challenge id (5-minute TTL, single use).
  • codestringrequiredSix-digit authenticator code.

ManifestFile

One file of a POST /api/uploads manifest, as sent.

  • pathstringrequiredRelative path, folders kept (Book/01 Chapter.mp3); \ reads as /. Refused when absolute, when it climbs out with .., or when it is too long or too deep.
  • sizeinteger (int64)requiredSize in bytes. At least 0.
  • sha256string or nullLower-case hex SHA-256 of the file, checked before it is stored.

MasterKeyStatus

GET /api/config/master-key and the PUT answer.

  • storeMasterKeyStorerequiredWhere the key lives.
  • recovery_copyRecoveryCopyAnswerrequiredWhat the operator recorded about a recovery copy of this key. A record for an earlier key (since restored or replaced) reads as unrecorded.
  • recorded_atstring or nullWhen that was recorded (RFC 3339, UTC); absent when unrecorded.
  • needs_recovery_copybooleanrequiredWhether the web app should remind the operator to save a copy: the key is in the OS keychain or sealed with systemd-creds (so backups of the files directory don't include it) and no copy was recorded as saved.

MasterKeyStore

Where this install keeps its key.

Type: one of file, password_file, keychain, systemd_creds

MediaCapabilitiesJson

The codecs, containers and encodings this build's media worker handles.

  • decodesarray of stringrequiredAudio codecs the worker decodes (aac, alac, flac, mp3, opus, vorbis, and eac3 in builds with the FFmpeg decoders).
  • readsarray of stringrequiredMedia types of files the worker opens, compared without case or parameters. Builds with the FFmpeg decoders add WMA, raw AC-3 and E-AC-3, and AMR types.
  • encodesarray of OutputEncodingJsonrequiredEncodings the worker writes.

MediaKindJson

Carrier of an edition (editions.media_kind).

Type: one of audio, ebook, print

MediaProgress

The patron's progress on one item.

  • idstringrequiredThe progress id: the item id (one record per patron and item).
  • userIdstringrequiredThe patron's id.
  • libraryItemIdstringrequiredThe item id.
  • episodeIdstring or nullAlways null.
  • mediaItemIdstringrequiredThe media id: the item id.
  • mediaItemTypestringrequiredAlways book.
  • durationnumber (double)requiredThe book's length in seconds, as last reported.
  • progressnumber (double)requiredThe share listened, from 0 to 1.
  • currentTimenumber (double)requiredWhere the patron is, in seconds.
  • isFinishedbooleanrequiredWhether the patron finished it.
  • hideFromContinueListeningbooleanrequiredWhether it is hidden from continue listening.
  • ebookLocationstring or nullAlways null.
  • ebookProgressnumber (double) or nullAlways null.
  • lastUpdateinteger (int64)requiredWhen the progress last changed, in epoch milliseconds.
  • startedAtinteger (int64)requiredWhen the patron started, in epoch milliseconds.
  • finishedAtinteger (int64) or nullWhen the patron finished, in epoch milliseconds.

MemberControls

A value for each control: the library's default, or what applies to one user.

  • link_accountsbooleanMay connect store accounts ([MemberControl::LinkAccounts]).
  • downloadbooleanMay take copies of the library's files ([MemberControl::Download]).
  • edit_metadatabooleanMay change metadata ([MemberControl::EditMetadata]).
  • uploadbooleanMay upload books ([MemberControl::Upload]); off unless set.
  • request_booksbooleanMay ask branches for books ([MemberControl::RequestBooks]).
  • see_pricesbooleanMay see prices and store links ([MemberControl::SeePrices]).

MembersBooksBody

PUT /api/config/branches/members-books body: a branch, and whether this library acquires all of its members' books.

  • node_idstringrequiredThe branch's node id, as Settings → Branches lists it.
  • acquirebooleanrequired"Acquire all of this branch's members' books".

MeResponse

JSON body for GET /me.

  • providerstringrequiredIdentity provider id (local or an integration plugin id).
  • external_user_idstringrequiredProvider-scoped user id stored on the portal identity row.
  • labelstring or nullOptional display label from the identity row.

MetaTags

The tags read from an audio file, as apps read them: always empty until the stored media probe reads tags, so it serializes as {}.

Type: object

MfaPolicy

The host-wide second-factor policy.

  • require_second_factorbooleanrequiredWhether every password sign-in must be followed by a passkey or authenticator code.

MfaPolicyPut

PUT body for the host-wide second-factor policy.

  • require_second_factorbooleanrequiredWhen true, password login requires TOTP or the user must use a passkey.

MissingFileAction

What happens to a stored copy whose file disappears from its destination outside Bookclerk (noticed by the destination's change feed or listing).

Type: one of mark_missing, restore

MultiDestinationMode

Behavior when some output destinations already have a title and others do not.

Type: one of sync_missing, refetch_missing, refetch_all

NamedRef

An id and a name.

  • idstringrequiredThe entity's id.
  • namestringrequiredIts display name.

NamingProfile

Preset path-template profile.

Select via output.naming_profile. Individual folder_template / file_template / chapter_file_template values override the profile when set.

Type: one of audiobookshelf, classic

Narrator

A narrator with how many items they read.

  • idstringrequiredThe name in URL-safe base64, as apps filter by it.
  • namestringrequiredThe narrator's name.
  • numBooksinteger (int64)requiredItems they read that the patron can see. At least 0.

Narrators

GET /api/libraries/{id}/narrators.

  • narratorsarray of NarratorrequiredThe narrators.

NewBookmarkBody

POST /api/library/editions/{id}/bookmarks body.

  • position_msinteger (int64)requiredThe place to mark, in milliseconds (at most sixty days). At least 0.
  • titlestringA note for it, at most 200 bytes, no control characters; empty when left out.

NewChannelBody

Body of POST /api/notifications/channels.

  • plugin_instance_idstringrequiredA notifier instance that sends to channels; its own settings say where (a webhook URL, a service key).
  • labelstringrequiredName shown in the routing matrix, 1 to 128 bytes on one line.

NewPersonalBody

Body of POST /api/me/notifications/destinations.

  • plugin_instance_idstringrequiredA notifier instance that sends to patrons.
  • addressmap of string to stringrequiredThe address, as the notifier's address_fields describe it: a flat object of strings. A key written twice is refused (422) rather than one value kept.
  • labelstring or nullName shown in pickers; the notifier's own label for the address, or the notifier's name, when absent.

NewPlayerPasswordBody

POST /api/auth/player-passwords body.

  • labelstringrequiredA name for it, such as the app or device (1 to 64 bytes once trimmed).

NewPlayerPasswordJson

POST /api/auth/player-passwords answer.

  • passwordPlayerPasswordJsonrequiredThe stored password.
  • secretstringrequiredThe password itself, shown this once: the library keeps only its digest.

NodeCapabilities

What the caller may do on the nodes it sees.

  • scopeNodeScoperequiredall for the operator, owned for a node owner.
  • can_edit_runtimebooleanrequiredTrue: every caller may edit the runtime settings of the nodes it sees.
  • can_edit_labelsbooleanrequiredTrue for the operator, who may replace placement labels.
  • can_assign_ownerbooleanrequiredTrue for the operator, who may assign or clear a node's owner.

NodeCredentialRevoked

JSON body after a host's credential was revoked.

  • credentialNodeCredentialViewrequiredThe credential, with revoked_at set (revoking twice keeps the first time).

NodeCredentialView

A host's node credential as the credentials routes show it; never its keys.

  • node_idstringrequiredBranch node.
  • link_idstringrequiredLink that enrolled it.
  • enrolled_atstringrequiredRFC 3339 enrollment time.
  • revoked_atstring or nullRFC 3339 revoke time.
  • last_connected_atstring or nullRFC 3339 time of the last authenticated connection.

NodeInviteCreated

JSON body after an enrollment link was minted.

  • linkEnrollmentLinkViewrequiredThe link's record.
  • urlstringrequiredThe full enrollment URL with the secret, shown once.

NodeInviteRevoked

JSON body after an enrollment link was revoked.

NodeInvitesResponse

JSON body for GET /api/config/node-invites.

NodeKind

How a node joined the library.

Type: one of shared, branch

NodeOwnerChanged

PUT /api/config/nodes/{node_id}/owner body: the owner after the change.

  • node_idstringrequiredNode id.
  • owner_user_idinteger (int64) or nullUser id of the owner; null when cleared.

NodeOwnerSummary

The user who owns a node, as the nodes listing shows them.

  • user_idinteger (int64)requiredThe owner's user id.
  • display_namestring or nullDisplay name, or the login name when none is set; null when the user has neither.
  • roleUserRolerequiredThe owner's role.

NodeRefusal

A 403 from a node API route: the transport policy's refusal, the standard body, or the handler's own error; the route's examples name each.

Type: TransportRefused or ErrorJson or ErrorMessage or ErrorDetail

NodeRuntimeChanged

PUT /api/config/nodes/{node_id}/runtime body: the document after the write.

  • node_idstringrequiredNode id, trimmed.
  • revisioninteger (int64)requiredCompare-and-swap revision of the runtime document after the write.
  • runtimeNodeRuntimeSettingsV1requiredThe runtime document now stored.

NodeRuntimeSettingsV1

Typed node-scoped runtime document, schema version 1.

Desired state for one node, editable from any node in the library: an operator label, and the budget the scheduler may commit on this node. Budgets are shares of the capacity the node detects at heartbeat (CPU cores and memory, the tighter of the machine and its cgroup).

  • labelstringrequiredOperator label shown for this node. Empty is allowed.
  • cpu_budget_percentinteger (int32)Share of detected CPU cores the scheduler may commit to plugin guests on this node (1..=100). At least 1; at most 100.
  • memory_budget_percentinteger (int32)Share of detected memory the scheduler may commit (1..=100). At least 1; at most 100.
  • schedulablebooleanFalse drains the node: the scheduler places nothing new here and moves its replicas elsewhere. Hand-managed deployments still run.
  • cache_budget_bytesinteger (int64) or nullDisk space, in bytes, this node's image caches may use together, overriding the library's core.cache budget (16 MiB to 1 TiB). Absent means the library budget applies. At least 16777216; at most 1099511627776.

NodeScope

Which nodes a listing shows the caller.

Type: one of all, owned

NodesResponse

GET /api/config/nodes body.

  • node_idstringrequiredId of the node that answered.
  • nodesarray of NodeViewrequiredThe nodes the caller administers.
  • capabilitiesNodeCapabilitiesrequiredWhat the caller may do with them.

NodeStatus

A node's latest heartbeat with budget, accounting, and availability.

  • node_idstringrequiredReporting node.
  • incarnationstringrequiredDaemon process incarnation.
  • started_atstringrequiredRFC 3339 daemon start.
  • heartbeat_atstringrequiredRFC 3339 heartbeat time.
  • heartbeat_msinteger (int64)requiredHeartbeat time in Unix milliseconds.
  • interval_msinteger (int64)requiredPromised interval in milliseconds.
  • cpu_millicoresinteger (int64)requiredDetected CPU capacity in millicores.
  • memory_bytesinteger (int64) or nullDetected memory in bytes.
  • cpu_budget_millicoresinteger (int64)requiredCPU the scheduler may commit, in millicores.
  • memory_budget_bytesinteger (int64) or nullMemory the scheduler may commit, in bytes.
  • schedulablebooleanrequiredFalse when an operator drained the node.
  • cpu_used_millicoresinteger (int64) or nullMeasured CPU in use, in millicores.
  • memory_available_bytesinteger (int64) or nullMeasured memory available, in bytes.
  • files_dir_free_bytesinteger (int64) or nullFree bytes on the files directory's filesystem.
  • reservedGuestReservationrequiredCeilings of the guests running here.
  • running_guestsinteger (int64)requiredGuests running here.
  • availability_ppminteger (int64)requiredRecent online fraction in parts per million.
  • online_since_msinteger (int64)requiredUnix milliseconds the current online stretch began.
  • cache_bytesinteger (int64) or nullBytes the node's image caches hold; None from a node that keeps none.
  • cache_budget_bytesinteger (int64) or nullBytes the node's image caches may hold.
  • cache_swept_msinteger (int64) or nullWhen the node's last cache sweep finished, in Unix milliseconds.
  • public_originstring or nullThe address other installs reach this branch at, as it last reported it; null for a local branch and for a shared node. A branch with one is a remote branch of this library.

NodeView

One node with its latest heartbeat, budget and owner.

  • node_idstringrequiredNode id.
  • library_idstringrequiredLibrary the node belongs to.
  • created_atstringrequiredRFC 3339 time the node first enrolled.
  • heartbeat_atstringrequiredRFC 3339 time of the last heartbeat the node row recorded.
  • software_versionstringrequiredBookclerk version the node runs.
  • schema_statestringrequiredDatabase schema the node last applied.
  • compatiblebooleanrequiredTrue when the node's own binary accepted the schema it reported; not a comparison with this daemon's schema.
  • targetstringrequiredBookclerk target the node runs on.
  • labelsarray of stringrequiredOperator-set placement labels.
  • implicit_labelsarray of stringrequiredLabels the scheduler adds for the node (its id and target).
  • livebooleanrequiredTrue while the last heartbeat is recent enough.
  • runtimeNodeRuntimeSettingsV1requiredThe node's runtime document, or the defaults when it never wrote one.
  • statusNodeStatus or nullThe latest heartbeat; null before the first one.
  • this_nodebooleanrequiredTrue for the node that answered the request.
  • kindNodeKindrequiredshared for a node sharing this library's database, branch for an enrolled branch.
  • relationshipBranchRelationshiprequiredHow the node relates to this library: shared_branch (shares its database), remote_branch (a branch reporting a public address in its heartbeat, status.public_origin) or local_branch (a branch with none).
  • owner_user_idinteger (int64) or nullUser id of the node's owner; null when unassigned.
  • share_booksboolean or nullA branch's sharing setting, as it last reported it; null for a shared node.
  • include_branchesboolean or nullA branch's include-branches setting, as it last reported it; null for a shared node.
  • ownerNodeOwnerSummary or nullThe owner, when the node has one and the user still exists.

NotificationCatalog

Everything the routing screens pick from.

  • typesarray of NotificationTypeJsonrequiredHost types first, then plugin types by id.
  • notifiersarray of NotifierJsonrequiredNotifier instances installed on this server.

NotificationTypeJson

One notification type a routing rule or a patron choice can name.

  • idstringrequiredQualified id: a host type (test) or <plugin id>:<type>.
  • audiencestringrequiredWho it is for: operational (routed to channels) or patron (offered to patrons).
  • severitystringrequiredDefault severity: info, warning or critical.
  • titlestringrequiredTitle shown in the routing matrix and on each notification.
  • sourcestringrequiredThe plugin that raises it; empty for a host type.

NotifierJson

One notifier instance.

  • plugin_instance_idstringrequiredPlugin instance id.
  • plugin_keystringrequiredCanonical plugin key.
  • namestringrequiredName shown in pickers.
  • channelbooleanrequiredWhether administrators can make library channels on it.
  • personalbooleanrequiredWhether patrons can add their own address on it.
  • address_fieldsarray of AddressFieldJsonrequiredWhat a patron enters for a personal destination.

OAuthEnrollAnswer

POST /api/node/v1/enroll/oauth answer.

  • library_idstringrequiredThe library id.
  • node_idstringrequiredThe node id recorded for the joining install.
  • connectionConnectionTypeThe connection type recorded (branch when left out).
  • bootstrapstring or nullFor a shared branch: the [crate::SharedBranchBootstrap] sealed to the node's box key ([crate::seal_shared_branch_bootstrap]), as base64url without padding.
  • accountsstring or nullFor a branch whose user chose "Bring my store connections to this branch": the user's own store accounts as a [crate::AccountBundle] sealed to the node's box key ([crate::seal_account_bundle]), as base64url without padding. Left out when the user did not choose it or had none to bring.

OAuthEnrollRequest

POST /api/node/v1/enroll/oauth body. Keys are base64url without padding.

  • codestringrequiredThe authorization code from the callback.
  • code_verifierstringrequiredThe PKCE verifier.
  • redirect_uristringrequiredThe redirect URI the authorization was requested with.
  • sign_pkstringrequiredEd25519 public signing key.
  • box_pkstringrequiredX25519 public box key.
  • branch_namestringThe name this branch joins as (the node's label).
  • software_versionstringThe joining install's Bookclerk version.
  • connectionConnectionTypeThe connection type the code was approved for. It must match the one bound to the code at consent; left out for a branch.

OAuthStartUrl

JSON body of an OAuth start: the browser login URL to open.

  • urlstringrequiredThe store's login page, bound to this sign-in.

OfferJson

One notifier offered to patrons for a type.

  • plugin_instance_idstringrequiredA notifier instance that sends to personal destinations.
  • default_onbooleanrequiredWhether a patron who chose nothing gets the type there.

OffersBody

Body of PUT /api/notifications/offers/{type}.

  • offersarray of OfferJsonrequiredThe type's offers, replacing the old ones; at most 32. Empty keeps the type in patrons' inboxes only. At most 32 items.

OfferTable

Every patron offer, by type.

  • offersmap of string to array of OfferJsonrequiredType id to its offers.

OidcClientsResponse

JSON body for GET /api/auth/oidc/clients.

  • clientsarray of OidcClientViewrequiredEvery registered client, without secrets.

OidcClientView

A Bookclerk-as-IdP client as operators see it; the secret appears only when freshly minted.

  • client_idstringrequiredPublic client id used at the authorize and token endpoints.
  • namestring or nullOperator-facing display name.
  • redirect_urisarray of stringrequiredAllowed OAuth redirect URIs.
  • confidentialbooleanrequiredWhether the client authenticates with a secret (otherwise it is a public PKCE client).
  • issue_refresh_tokenbooleanrequiredWhether token responses include a refresh token.
  • allowed_scopesarray of stringrequiredScopes the client may be granted.
  • has_secretbooleanrequiredSame as confidential: a secret hash is stored.
  • enabledbooleanrequiredWhether the authorize and token endpoints accept this client.
  • plugin_idstring or nullPlugin that provides this client, or null for an operator-created one.
  • client_secretstring or nullThe new secret, shown once after create, rotate-secret, or a PUT that makes a public client confidential; never stored in clear.

OidcClientWrite

Body for creating or updating a Bookclerk-as-IdP client.

  • client_idstring or nullPublic client_id (create only; path wins on update).
  • namestring or nullOperator-facing display name.
  • redirect_urisarray of stringAllowed OAuth redirect URIs.
  • confidentialbooleanWhen true, mint a client secret (confidential). When false, public PKCE.
  • issue_refresh_tokenbooleanWhen true, token responses include a refresh token.
  • allowed_scopesarray of stringScopes this client may request (openid, profile, email).
  • enabledbooleanWhen true, authorize and token endpoints accept this client.

OidcConfigPut

Operator PUT body that replaces the broker table (secrets omitted or replaced).

  • enabledbooleanrequiredWhether the broker should accept authorize starts after this write.
  • allowed_email_domainsarray of stringReplacement broker-wide email domain allowlist.
  • providersarray of OidcProviderPutFull replacement list of IdPs (omitted secrets keep the previous generation).
  • public_originstring or nullintegrations.public_origin. Omit to leave unchanged; empty string clears.

OidcConfigResponse

Operator-facing OIDC broker snapshot; secret material is never included.

  • enabledbooleanrequiredWhether the broker accepts new authorize starts.
  • allowed_email_domainsarray of stringrequiredBroker-wide email domain allowlist applied before per-provider rules.
  • public_originstring or nullConfigured integrations.public_origin (issuer / callback / invite base).
  • issuer_urlstringrequiredEffective issuer origin (public_origin, else this request, else localhost).
  • detected_originstringrequiredOrigin detected from this request (loopback IPs rewritten to localhost).
  • discovery_urlstringrequiredAbsolute OpenID discovery URL (/.well-known/openid-configuration).
  • authorization_endpointstringrequiredAbsolute authorization endpoint (/oidc/authorize) for Bookclerk-as-IdP.
  • token_endpointstringrequiredAbsolute token endpoint (/oidc/token) for Bookclerk-as-IdP.
  • userinfo_endpointstringrequiredAbsolute userinfo endpoint (/oidc/userinfo) for Bookclerk-as-IdP.
  • revocation_endpointstringrequiredAbsolute revocation endpoint (/oidc/revoke) for Bookclerk-as-IdP.
  • callback_urlstringrequiredAbsolute /api/auth/oidc/callback derived from the effective issuer origin.
  • providersarray of OidcProviderViewrequiredConfigured IdPs with presence flags instead of secret material.

OidcProviderPut

One IdP in a PUT: omit secret fields to keep, empty string to clear.

  • idstringrequiredStable provider id; also the logical name of the sealed client-secret row.
  • namestringOperator-facing display name stored in config.toml.
  • presetstring or nullBuilt-in social preset; empty or omitted means a generic OpenID issuer.
  • issuerstring or nullOpenID issuer URL required when preset is unset.
  • client_idstringrequiredOAuth client id registered at the IdP.
  • client_secretstring or nullOmit to keep; empty string to clear; non-empty to store.
  • scopesarray of stringOAuth scopes; empty is replaced with the provider default set.
  • provisionstringJIT, mapped-role, allowlist, or invite-only policy for first login.
  • default_rolestringFallback portal role when no mapped claim matches.
  • role_claimstringClaim name used for role mapping (defaults to groups).
  • role_mapmap of string to stringClaim value to portal role mapping applied at provision time.
  • link_by_emailbooleanWhen true, verified email may attach this IdP to an existing user.
  • allowed_email_domainsarray of stringPer-provider email domain allowlist.
  • allowed_emailsarray of stringExact emails permitted under allowlist provision.
  • allowed_subjectsarray of stringExact IdP subject ids permitted under allowlist provision.
  • apple_team_idstring or nullApple Developer team id for client-secret JWT minting.
  • apple_key_idstring or nullApple Sign In key id paired with the sealed private key.
  • apple_private_keystring or nullOmit to keep; empty string to clear; non-empty to store.

OidcProvidersResponse

JSON body for GET /api/auth/oidc/providers.

  • enabledbooleanrequiredWhether the OIDC broker is switched on at all.
  • providersarray of SigninOidcProviderrequiredProviders enabled in configuration, in configuration order (empty while the broker is off).

OidcProviderView

One IdP as shown to an operator (no client secret or Apple PEM).

  • idstringrequiredStable provider id used in authorize URLs and sealed-row names.
  • namestringrequiredOperator-facing display name.
  • presetstring or nullBuilt-in social preset (google, github, apple, discord) when not a generic issuer.
  • issuerstring or nullOpenID issuer URL for discovery when no social preset applies.
  • client_idstringrequiredOAuth client id registered at the IdP.
  • scopesarray of stringrequiredOAuth scopes requested at authorize.
  • provisionstringrequiredHow a first login becomes a portal user (JIT, mapped role, allowlist, invite-only).
  • default_rolestringrequiredPortal role used when no mapped claim matches (member by default).
  • role_claimstringrequiredClaim name read from id_token/userinfo for role mapping (groups by default).
  • role_mapmap of string to stringrequiredIdP group/role claim values mapped onto Bookclerk portal roles.
  • link_by_emailbooleanrequiredWhen true, a verified email may attach this IdP to an existing user.
  • allowed_email_domainsarray of stringrequiredPer-provider email domain allowlist (in addition to the broker-wide list).
  • allowed_emailsarray of stringrequiredExact emails permitted under allowlist provision.
  • allowed_subjectsarray of stringrequiredExact IdP subject ids permitted under allowlist provision.
  • apple_team_idstring or nullApple Developer team id used to mint the client-secret JWT.
  • apple_key_idstring or nullApple Sign In key id paired with the sealed private key.
  • has_client_secretbooleanrequiredWhether a client secret exists in env, TOML, or the sealed store (value never returned).
  • has_apple_private_keybooleanrequiredWhether an Apple PEM exists in env, TOML, or the sealed store (PEM never returned).
  • secret_sourcestringrequiredWhere the client secret was found: env, config, store, or none.

OkResponse

Acknowledgement body ({"ok": true}) for actions with nothing else to report.

  • okbooleanrequiredAlways true: a failure answers with an error status instead.

OpenApiDocument

An OpenAPI document as this daemon serves it: the openapi version string, info about the daemon, every route under paths and the schemas under components.

Type: object

OpenApiV30Unavailable

Body of the 500 from GET /api/openapi-3.0.json when the 3.1 document could not be restated as 3.0.3.

  • errorstringrequiredAlways openapi_v30_unavailable.
  • messagestringrequiredWhat to do: the daemon log names the form that could not be restated.

OpenSessionBody

POST /api/playback/sessions body.

  • edition_idstringrequiredThe edition to play (1 to 128 bytes).
  • playerPlayerKindParamWhat kind of player asks; web when left out.
  • player_namestringThe player's own name, shown in listening history. Control characters are dropped and at most 64 bytes are kept.

OperatorSessionView

An operator session as listed by GET /api/auth/sessions.

  • idinteger (int64)requiredSession id, for DELETE /api/auth/sessions/{id}.
  • created_atstringrequiredRFC 3339 time the session was created.
  • last_used_atstring or nullRFC 3339 time of the last authenticated use, when any.
  • expires_atstringrequiredRFC 3339 expiry.
  • elevatedbooleanrequiredWhether an Owner elevated into this session (rather than the operator token).
  • impersonating_user_idinteger (int64) or nullUser the session is impersonating, when it is. Never set on the session making the request: while that session impersonates, the list shows the target's portal sessions instead.
  • is_currentbooleanrequiredWhether this is the session making the request.
  • client_labelstring or nullBest-effort OS or client label from the User-Agent.
  • device_typestring or nullBest-effort device class (desktop, mobile, tablet, api).
  • user_agentstring or nullRaw User-Agent captured when the session was created.

OriginMismatch

409 origin_mismatch: the library's canonical address is not the one the join was started with. An [crate::http_error::ErrorDetail] that also carries the address to use.

  • errorstringrequiredAlways origin_mismatch.
  • detailstringrequiredWhy, naming the address to join with instead.
  • originstringrequiredThe library's canonical origin, to join with instead.

OutputCopy

One copy of every acquired book: a format at a quality.

OutputDomainChange

Body of PUT /api/config/domains/core.output: the settings after the change, or a replay note.

Type: OutputDomainResponse or DomainReplayed

OutputDomainResponse

Body of GET /api/config/domains/core.output and of a PUT that was applied: the revision metadata and the [output] document.

Includes every field of DomainRevision.

  • documentOutputSettingsV1requiredThe settings at that revision (schema version 1).

OutputEncodingJson

One encoding the media worker writes.

  • namestringrequiredThe output format id that selects it (m4b, mp3 or opus).
  • advancedbooleanrequiredTrue when settings offer it only under their advanced options, because fewer players open it than M4B and MP3.

OutputFormat

Post-download output formatting. Default is enriched M4B (tags + chapters). split_mp3_by_size parses but is not implemented yet: the acquire pipeline rejects a job that selects it before downloading.

Type: one of enriched_m4b, single_mp3, split_mp3_by_chapter, split_mp3_by_size, opus, none

OutputSettingsV1

Typed core.output document, schema version 1.

Field meanings match [OutputConfig]. Unknown fields are rejected, inside the nested lame and replacement_characters objects too, so a document written by a newer binary under the same schema version fails closed instead of being silently truncated on the next write.

  • formatOutputFormatrequiredPost-acquire packaging format.
  • copiesarray of OutputCopyFurther copies of every acquired book beside the main output, at most 8; empty keeps one copy. Each needs a quality that suits its format, and none may repeat another or the main output's copy. At most 8 items.
  • widevinebooleanrequiredPrefer Widevine/CENC.
  • xhe_aacbooleanrequiredPrefer xHE-AAC on the Widevine path when offered.
  • widevine_cdmstring or nullOptional .wvd path; relative paths resolve under each host's files dir.
  • widevine_cdm_providerstring or nullRemote L3 CDM provider endpoint URL (None = the built-in AudibleCdm provider, empty/off disables provisioning).
  • naming_profileNamingProfilerequiredNamed path-template preset.
  • folder_templatestring or nullFolder-path template override.
  • file_templatestring or nullFile-stem template override.
  • chapter_file_templatestring or nullPer-chapter file-stem template override.
  • chapter_title_templatestring or nullEmbedded chapter-title template.
  • download_coverbooleanrequiredSave cover JPEG alongside audio.
  • download_pdfbooleanrequiredDownload companion PDF when available.
  • create_cuebooleanrequiredWrite a .cue sidecar.
  • keep_codec_in_m4bbooleanKeep Opus, FLAC, ALAC, E-AC-3 and AC-4 audio unchanged inside an M4B instead of encoding it to AAC (advanced; off by default).
  • fixup_metadatabooleanrequiredEmbed tags, cover, and chapters natively.
  • chapter_jsonChapterJsonModerequiredChapter JSON sidecars.
  • save_metadata_jsonbooleanrequiredPersist raw catalog API JSON.
  • cover_sizestringrequiredCover image size (500, 1215, another pixel size, or native).
  • chapter_layoutstringrequiredPreferred chapter API layout (tree, flat, or both).
  • overwrite_existingbooleanrequiredRe-acquire when media already exists at the destination.
  • multi_destinationMultiDestinationModerequiredPolicy when only some enabled destinations have a title.
  • missing_filesMissingFileActionWhat happens to a stored copy whose file disappears from its destination outside Bookclerk. Absent in documents written before the setting existed, which read as the default.
  • bad_book_actionBadBookActionrequiredOperator action when a title fails to acquire.
  • split_mp3_max_mbinteger (int32)requiredMax MP3 part size in MiB for split_mp3_by_size. At least 0.
  • minimum_file_duration_minutesinteger (int32)requiredDrop chapter splits shorter than this many minutes. At least 0.
  • combine_nested_chapter_titlesbooleanrequiredFlatten nested chapter titles.
  • merge_opening_and_end_creditsbooleanrequiredMerge opening/end credit chapters into neighbours.
  • strip_unabridgedbooleanrequiredStrip an "Unabridged" suffix from titles used in naming.
  • strip_audible_brand_audiobooleanrequiredTrim Audible brand intro/outro audio.
  • download_clips_bookmarksbooleanrequiredDownload Audible clips/bookmarks sidecars.
  • retain_aax_filebooleanrequiredKeep the encrypted download.
  • download_speed_limit_kbpsinteger (int32)requiredFetch speed cap in KB/s (0 = unlimited). At least 0.
  • lameLameConfigrequiredLAME encoder knobs.
  • max_sample_rateinteger (int32) or nullOptional output sample-rate ceiling in Hz. At least 0.
  • creation_timeFileTimestampModerequiredFile creation timestamp policy.
  • last_write_timeFileTimestampModerequiredFile last-write timestamp policy.
  • path_sanitizationPathSanitizationModerequiredSanitization profile used when no explicit rules are set.
  • replacement_charactersarray of ReplacementRulerequiredExplicit find/replace rules for path segments.
  • max_filename_lengthinteger (int32)requiredMax length per path segment (0 disables truncation). At least 0.

OverrideSwitchChanges

Changes to some of one Administrator's overrides: on or off for them alone, or default to follow the library's default again; an absent switch keeps what it had.

OwnerBootstrapped

JSON body after the first Owner was created.

  • okbooleanrequiredAlways true on this success path.
  • user_idinteger (int64)requiredusers.id of the new Owner.
  • claim_ticketstringrequiredSingle-use claim ticket that signs the Owner in once (valid for seven days).
  • invite_urlstringrequiredInvite link carrying the ticket, for the browser.
  • login_namestring or nullLogin name the Owner signs in with, when one was given.
  • has_passwordbooleanrequiredWhether a password was set, so password sign-in works right away.

OwnerChoice

The consent page's connection block for an Owner, who may pick shared branch.

  • choicebooleanrequiredAlways true.
  • defaultstringrequiredAlways branch.
  • shared_branch_availablebooleanrequiredWhether shared branch may be chosen right now.
  • shared_branch_reasonstring or nullWhy shared branch is shown disabled, when it is.
  • step_uparray of stringrequiredThe second factors the Owner can step up with (totp, passkey).

OwnerInfo

GET /api/node/v1/info answer.

  • library_idstringrequiredThe library id.
  • library_namestringrequiredA name to show for the library.
  • originstringrequiredThe library's canonical origin: the one the node handshake signs and the authorize endpoint lives under.
  • transportstringrequiredThe node API transport mode (acme, proxy, self_signed, loopback).
  • enrollmentbooleanrequiredWhether the library lets new branches join (core.branch_enrollment).
  • spki_fingerprintstring or nullIn self_signed mode: base64url SHA-256 of the certificate's SubjectPublicKeyInfo, which the joining operator confirms against the owner's Settings → Branches page.
  • software_versionstringThe library's Bookclerk version.
  • ancestryarray of stringThe library's ancestry: its own library id first, then the library id of every library above it up to the root. A joining library refuses a parent whose ancestry names its own library id, so a tree of libraries never becomes a cycle.

PaceModeSchema

The mode of a [PaceRequestBody], for the API reference.

Type: one of default, custom, unlimited

PaceRequestBody

Request body of the pace route, for the API reference (the route reads the raw bytes with bookclerk_library::pacing::parse_pace_request).

  • modePaceModeSchema or nulldefault, custom or unlimited. Leave it out to only end the cool-down (then clear_cooldown must be true) and keep the stored pace.
  • downloads_per_dayinteger (int32) or nullCustom downloads per rolling 24 hours; custom only. At least 1; at most 10000.
  • min_gap_secondsinteger (int32) or nullCustom seconds between downloads; custom only. At least 0; at most 86400.
  • clear_cooldownboolean or nullAlso end a cool-down the store asked for.

PaceView

How fast Bookclerk downloads from one store account when it starts the downloads itself, for the Accounts page.

  • modestringrequireddefault (the store's pace), custom or unlimited.
  • downloads_per_dayinteger (int32) or nullDownloads allowed in any rolling 24 hours now in force; null for no daily budget. At least 0.
  • min_gap_secondsinteger (int64)requiredSeconds between two downloads now in force. At least 0.
  • store_downloads_per_dayinteger (int32) or nullThe store's declared daily budget; null when it declares none or its plugin is not deployed here. At least 0.
  • store_min_gap_secondsinteger (int64) or nullThe store's declared gap in seconds; null when its plugin is not deployed here. At least 0.
  • custom_downloads_per_dayinteger (int32) or nullCustom daily budget the operator set, when mode is custom. At least 0.
  • custom_min_gap_secondsinteger (int32) or nullCustom gap the operator set, when mode is custom. At least 0.
  • downloads_last_dayintegerrequiredDownloads from this account in the last 24 hours, by hand or not. At least 0.
  • cooldown_untilstring or nullEnd of the cool-down the store asked for (RFC 3339), when one is running.
  • next_automatic_atstring or nullWhen the next automatic download may start (RFC 3339); null when one may start now.

PasskeyCreationOptions

WebAuthn creation options for navigator.credentials.create(), plus the challenge id for the finish step.

  • challenge_idstringrequiredServer-issued challenge id to send back with the attestation; consumed once, five-minute lifetime.
  • publicKeyany JSONrequiredW3C PublicKeyCredentialCreationOptions (relying party, user, challenge, algorithms, excluded credentials), binary fields base64url-encoded.

PasskeyReauthBody

Optional current password for step-up before register or delete.

  • current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.

PasskeyRequestOptions

WebAuthn request options for navigator.credentials.get(), plus the challenge id for the finish step.

  • challenge_idstringrequiredServer-issued challenge id to send back with the assertion; consumed once, five-minute lifetime.
  • publicKeyany JSONrequiredW3C PublicKeyCredentialRequestOptions (challenge, relying party id, allowed credentials), binary fields base64url-encoded.
  • mediationstring or nullCredential mediation the daemon asks the browser for; absent unless conditional mediation was requested.

PasskeysResponse

JSON body for GET /api/auth/passkeys.

  • passkeysarray of PasskeySummaryrequiredThe caller's passkeys, oldest first.

PasskeySummary

One stored passkey.

  • idinteger (int64)requiredRow id, for DELETE /api/auth/passkeys/{id}.
  • credential_idstringrequiredBase64url credential id the authenticator reports.
  • namestringrequiredLabel chosen at registration (Passkey when none was given).

PasswordLoginBody

JSON body for password-store connect (email + password).

  • emailstringrequiredStore account email / username.
  • passwordstringrequiredStore account password; never logged.

PasswordLoginOutcome

JSON body of a successful POST /api/auth/password.

Type: PortalSessionIssued or TotpChallenge

PasswordLoginRequest

JSON body for local password login (login name or email plus password).

  • loginstringrequiredLogin name or email.
  • passwordstringrequiredPassword verified against the stored hash; mismatch fails closed and counts toward lockout.

PasswordSet

JSON body after a password was set.

  • okbooleanrequiredAlways true on this success path.
  • revoked_sessionsinteger (int64)requiredPortal sessions of that user revoked by the change (the caller signs in again). At least 0.

PatchDefaultAdminControls

PATCH /api/users/default-admin-controls body.

  • changesDefaultSwitchChangesrequiredThe default switches to change and their new values. Switches it does not name keep their stored value, so two Owners editing different switches do not undo each other.

PatchPreferencesBody

Partial preferences update; omitted fields keep their stored values.

  • default_viewstring or nullReplacement landing view when set.
  • disabled_shelvesarray of string or nullReplacement hidden-shelf list when set.
  • discover_sortstring or nullReplacement Discover sort key when set.
  • discover_sort_dirstring or nullReplacement Discover sort direction when set.
  • discover_languagestring or nullPresent + value sets language; present + null clears to browser default; omitted leaves unchanged.
  • discover_excluded_sourcesarray of string or nullReplacement excluded-store list when set.
  • themestring or nullReplacement appearance preference when set (system, light, dark).

PatchProfileRequest

JSON body for PATCH /api/auth/profile.

  • display_namestring or nullReplacement display name; empty or whitespace clears the field.
  • emailstring or nullReplacement email; empty or whitespace clears the field.
  • avatar_sourcestring or nullPicture choice (auto, monogram, gravatar, upload, or sso:{id}).

PatchSettingsRequest

Body for PATCH /api/settings.

  • settingsarray of SettingsUpdaterequiredKey/value pairs to validate, persist, and reload.
  • expected_output_revisioninteger (int64) or nullcore.output document revision the client read (output_revision in GET /api/settings). When set and stale, an output.* update is rejected with 409.

PatchUserAdminControls

PATCH /api/users/{id}/admin-controls body.

  • changesOverrideSwitchChangesrequiredThe switches to change for this Administrator: on or off sets the switch for them alone, default follows the library's default again. Switches it does not name keep what they had, so two Owners editing different switches do not undo each other.

PatchUserRequest

Partial profile, role, or status patch for a first-party user.

  • rolestring or nullReplacement role (owner / administrator / member) when present.
  • statusstring or nullReplacement status (active / disabled) when present.
  • display_namestring or nullReplacement display name when present.
  • login_namestring or nullReplacement local login name when present.
  • emailstring or nullReplacement email when present.

PathSanitizationMode

How to sanitize storage path segments when [crate::OutputConfig::replacement_characters] is empty (explicit rules always win).

Type: one of auto, windows, posix, s3, none

PatronOfferJson

One notifier a patron may pick for a type.

  • plugin_instance_idstringrequiredThe notifier instance.
  • namestringrequiredIts name.
  • default_onbooleanrequiredWhether the type goes there when the patron chose nothing.

PatronScope

Which part of the library a patron sees.

  • rulesarray of ScopeRuleVisibility rules, at most 16 and 1,024 bytes as JSON. Empty means every book is visible. At most 16 items.
  • explicitExplicitContentWhether books marked explicit are visible; left out means allow.

PatronSettings

A patron's notification settings.

  • typesarray of PatronTypeJsonrequiredPatron types administrators offer a notifier for.
  • destinationsarray of DestinationJsonrequiredThe patron's own destinations.
  • notifiersarray of NotifierJsonrequiredNotifiers the patron can add a destination on.

PatronTypeJson

One patron type and what the patron chose for it.

  • idstringrequiredType id.
  • titlestringrequiredTitle.
  • offersarray of PatronOfferJsonrequiredNotifiers offered for it.
  • chosenbooleanrequiredWhether the patron made a choice; without one the defaults apply.
  • enabledbooleanrequiredThe patron's preference, not a delivery result: false keeps the type in the inbox only. true when nothing is chosen, in which case the offers' defaults pick where it goes.
  • destination_idsarray of stringrequiredThe destinations the patron saved for it, when chosen. These are saved choices, not live targets: routing skips one whose notifier is no longer offered for the type, so check offers before showing one as eligible or sending the list back.

Permissions

What a patron may do, as apps read it.

  • downloadbooleanrequiredWhether the patron may download items to the device.
  • updatebooleanrequiredAlways false: apps edit nothing.
  • deletebooleanrequiredAlways false.
  • uploadbooleanrequiredAlways false.
  • createEreaderbooleanrequiredAlways false.
  • accessAllLibrariesbooleanrequiredAlways true: the libraries listed are the ones the patron sees.
  • accessAllTagsbooleanrequiredAlways true.
  • accessExplicitContentbooleanrequiredAlways true: scope, not an explicit flag, decides visibility.
  • selectedTagsNotAccessiblebooleanrequiredAlways false.

PinBody

Body of PUT /api/library/listings/{id}/pin.

  • edition_idstringrequiredThe edition the listing sells.

Ping

GET /ping: { "success": true }.

  • successbooleanrequiredAlways true.

PinJson

A listing's pin.

  • listing_idstringrequiredThe listing.
  • edition_idstringrequiredThe edition it is pinned to, and now sells.
  • moved_fromstring or nullThe edition it sold before, when the pin moved it; absent when it already sold the pinned edition.

PinnedSchemaSummary

The settings schema pinned for a plugin, as the API renders it.

  • manifest_idstringrequiredManifest id (display alias) at pin time.
  • schema_sha256stringrequiredFingerprint of the normalized schema.
  • package_versionstringrequiredSemver package version that produced the pinned schema.
  • recorded_atstringrequiredRFC 3339 time of the last pin.
  • recorded_by_nodestringrequiredNode that recorded the last pin.
  • settingsarray of SettingSpecrequiredDeclared settings.

PlacementView

Scheduler placement of one instance: the operator's intent and the last pass's result.

  • replicasinteger or allrequiredA replica count (0 stops every replica) or "all".
  • constraintsarray of stringrequiredLabel constraints every chosen node must satisfy.
  • revisioninteger (int64)requiredCompare-and-swap revision of the intent.
  • placedinteger (int32)requiredReplicas the last scheduler pass placed. At least 0.
  • detailstringrequiredWhy fewer than requested are placed; empty when satisfied.
  • scheduled_atstringrequiredRFC 3339 time the scheduler last changed the status.
  • updated_atstringrequiredRFC 3339 time of the last intent write.

PlanConflict

POST /api/library/scan and POST /api/library/acquire 409 body: the two conflicts a plan can hit.

Type: ScanPlanResponse or ActionResponse

PlaybackManifestJson

GET /api/library/editions/{id}/playback answer.

  • edition_idstringrequiredThe edition.
  • work_idstring or nullIts work.
  • titlestringrequiredThe edition's display title.
  • playablebooleanrequiredTrue when this node holds a copy the caller may play. False when the library has not acquired the edition, no destination of this node holds it, or the caller may not take it.
  • duration_msinteger (int64) or nullRuntime in milliseconds: the last player's report when the caller has one, else the catalog's, to the minute; null when neither is known. At least 0.
  • tracksarray of TrackJsonrequiredThe tracks in play order; empty when not playable. A session's answer adds the stream paths.
  • progressProgressJson or nullThe caller's progress; null before they first play it.
  • bookmarksarray of BookmarkJsonrequiredThe caller's bookmarks, in timeline order.
  • chaptersarray of ChapterSpanrequiredThe chapters the edition plays, in pre-order, each ending where the next starts and the last at duration_ms; empty when it has none.

PlaybackSession

A playback session, as POST /api/items/{id}/play answers.

  • idstringrequiredThe session id; apps send it back to sync and close.
  • userIdstringrequiredThe patron's id.
  • libraryIdstringrequiredThe library id.
  • libraryItemIdstringrequiredThe item id.
  • bookIdstringrequiredThe media id: the item id.
  • episodeIdstring or nullAlways null.
  • mediaTypestringrequiredAlways [MEDIA_TYPE_BOOK].
  • mediaMetadataBookMetadatarequiredThe book's metadata.
  • chaptersarray of ChapterrequiredThe book's chapters.
  • displayTitlestringrequiredThe title apps show.
  • displayAuthorstringrequiredThe author apps show.
  • coverPathstring or nullA cover path apps test for presence.
  • durationnumber (double)requiredThe book's length in seconds.
  • playMethodinteger (int32)requiredHow the app plays: 0, direct play of the stored files. At least 0.
  • mediaPlayerstringrequiredThe player the app reported.
  • deviceInfoSessionDevicerequiredThe device the session was opened from.
  • serverVersionstringrequired[crate::COMPATIBLE_SERVER_VERSION].
  • datestringrequiredThe day the session started, YYYY-MM-DD in UTC.
  • dayOfWeekstringrequiredThe weekday the session started, in English.
  • timeListeningnumber (double)requiredSeconds listened in this session.
  • startTimenumber (double)requiredWhere the session started, in seconds.
  • currentTimenumber (double)requiredWhere the patron is, in seconds.
  • startedAtinteger (int64)requiredWhen the session started, in epoch milliseconds.
  • updatedAtinteger (int64)requiredWhen it last synced, in epoch milliseconds.
  • audioTracksarray of AudioTrackrequiredThe tracks to play, in order.
  • libraryItemLibraryItem or nullThe item, expanded.

PlaybackSyncBody

POST /api/playback/sessions/{id}/sync and .../close body: where the listener is.

  • position_msinteger (int64)requiredPosition on the edition's timeline, in milliseconds from its start (at most sixty days). At least 0.
  • listened_msinteger (int64)requiredMilliseconds listened since this session's last report, as the player counted them; left out reads as 0. At least 0.
  • duration_msinteger (int64) or nullThe edition's whole runtime in milliseconds, when the player knows it; left out or null keeps the stored one. At least 0.

PlayBody

POST /player/api/items/{id}/play: what an app asks for when it starts playing. Tracks always play directly, whatever it asks.

  • deviceInfoDeviceInfoBody or nullThe device, named in the patron's session list.
  • forceDirectPlayboolean or nullWhether the app asks for direct play; tracks always play directly.
  • forceTranscodeboolean or nullWhether the app asks for transcoding; it gets direct tracks too.
  • mediaPlayerstring or nullThe app's player, shown in the session list.

PlayerConsentBody

POST /api/auth/player-consent body.

Includes every field of PlayerConsentParams.

  • approvebooleanrequiredTrue to let the app sign in; false to decline.

PlayerConsentPage

GET /api/auth/player-consent answer: what the consent page shows.

  • app_namestringrequiredThe app asking, as the page names it.
  • display_namestring or nullThe signed-in patron's display name.

PlayerConsentParams

The consent page's parameters, as the app passed them on.

  • redirect_uristringrequiredThe return address from /player/auth/openid: the library's mobile-redirect path with the app's address as app.
  • code_challengestringrequiredThe PKCE S256 challenge.
  • statestring or nullThe app's state.

PlayerConsentRedirect

POST /api/auth/player-consent answer.

  • redirectstringrequiredWhere to send the browser: the library's own way back to the app, with a code or the refusal.

PlayerKindParam

The kind of first-party player that opens a session. Outside player apps open theirs through the player API.

Type: one of web, desktop

PlayerLoginResponse

The answer to a sign-in, a token refresh, POST /api/authorize and the browser sign-in's callback.

  • userUserrequiredThe signed-in patron, with the card's tokens.
  • userDefaultLibraryIdstringrequiredThe library an app opens first: the whole library.
  • serverSettingsServerSettingsrequiredSettings apps read at sign-in.
  • ereaderDevicesarray of objectrequiredE-reader devices: always empty, the API serves no ebooks.
  • SourcestringrequiredHow the server was installed; apps only display it.

PlayerPasswordJson

A player password as Account settings lists it.

  • idstringrequiredIts id, for removing it.
  • labelstringrequiredThe name the patron gave it.
  • created_atstringrequiredWhen it was made (RFC 3339).
  • last_used_atstring or nullWhen it last signed an app in (RFC 3339), if ever.

PlayerPasswordsJson

GET /api/auth/player-passwords answer.

  • passwordsarray of PlayerPasswordJsonrequiredThe patron's player passwords, newest first.

PluginArtifactSummary

One downloadable artifact of an installed version, as the API renders it.

  • targetstringrequiredBookclerk target (linux-x64-gnu, …; any for workerd packages).
  • urlstringrequiredWhere nodes fetch the archive: https:, file:, or blob:sha256:<hex>.
  • archive_sha256stringrequiredLowercase hex SHA-256 of the archive bytes.
  • payload_root_sha256stringrequiredPayload-root digest of the extracted plugin tree.

PluginConsentApproveRequest

Body for POST /api/plugins/{id}/consent.

  • approvebooleanrequiredMust be true; a false value is rejected with 400.
  • grantPluginGrantOverride or nullOptional operator overrides applied on top of the manifest request.
  • setting_destinationsarray of PluginSettingDestinationApprovalSetting destinations to approve, from the response's setting_destinations. An approved destination stays approved while a setting still names it; one left out stays pending, and one no setting names any more is withdrawn.

PluginConsentBrand

Optional branding shown on the plugin consent dialog.

  • namestringrequiredDisplay name from the portal brand or plugin manifest.
  • bgstring or nullBackground CSS color from the portal brand, when known.
  • fgstring or nullForeground CSS color from the portal brand, when known.
  • accentstring or nullAccent CSS color from the portal brand, when known.
  • logostring or nullSame-origin logo: the host-served embed path, or a 128 px copy of the remote logo the plugin names.

PluginConsentLimits

Host-capped resource defaults shown on the consent dialog.

  • cpu_msinteger (int32)requiredRequested workerd CPU budget in milliseconds. At least 0.
  • subrequestsinteger (int32)requiredRequested workerd subrequest budget. At least 0.
  • max_cpu_msinteger (int32)requiredHost hard cap for workerd CPU milliseconds. At least 0.
  • max_subrequestsinteger (int32)requiredHost hard cap for workerd subrequests. At least 0.
  • disk_mibinteger (int32)requiredDefault plugin state disk budget in mebibytes. At least 0.
  • max_disk_mibinteger (int32)requiredHost hard cap for plugin state disk in mebibytes. At least 0.
  • memory_mibinteger (int32)requiredDefault jail memory in mebibytes. At least 0.
  • max_memory_mibinteger (int32)requiredHost hard cap for jail memory in mebibytes. At least 0.
  • cpu_coresnumber (double)requiredManifest / default jail CPU in cores (2 d.p.).
  • max_cpu_coresnumber (double)requiredHost max jail CPU in cores (2 d.p.).
  • jail_cpu_coresnumber (double) or nullOptional [plugins.jail] ceiling in cores.
  • extra_processesinteger (int32)requiredDefault extra process/thread budget (native consent). At least 0.
  • max_extra_processesinteger (int32)requiredHost hard cap for extra process budget. At least 0.
  • known_bindingsarray of stringrequiredSuggested / default host bindings operators may grant.

PluginConsentPending

The difference between a plugin's request and its stored grant.

  • linesarray of stringrequiredOperator-facing lines naming every capability awaiting consent, the same lines bookclerk plugins info and bookclerk plugins approve print; empty when the stored grant covers the request.
  • domainsarray of stringrequiredFetch host patterns the request adds (* is any public host).
  • tcparray of TcpGrantViewrequiredTCP host:ports the request adds, narrowed to the new ports.
  • addressCidrsarray of stringrequiredCIDRs the request adds.
  • allowUndeclaredPublicRedirectsbooleanrequiredWhether the request newly asks to follow undeclared public redirects.

PluginConsentResponse

Consent dialog payload for one plugin.

  • plugin_idstringrequiredPlugin id whose grant is being reviewed.
  • plugin_keystringrequiredCanonical PluginKey for this install (empty when unknown).
  • provenancestringrequiredHost-evaluated provenance label.
  • runtimestringrequiredGuest runtime (native or workerd) — drives which controls are enforceable.
  • requestPluginGrantViewrequiredManifest-derived grant the plugin is asking for.
  • coveredbooleanrequiredTrue when an existing on-disk grant already satisfies the request.
  • summaryarray of stringrequiredOperator-facing bullet list of requested capabilities.
  • existingPluginGrantView or nullPreviously approved grant, when one is stored.
  • pendingPluginConsentPending or nullWhat the request asks for beyond the stored grant (a plugin upgrade that widened its capabilities); absent when no grant is stored. The plugin keeps running under the stored grant until these are approved.
  • brandPluginConsentBrand or nullOptional portal or manifest branding for the dialog.
  • limitsPluginConsentLimitsrequiredHost-capped resource defaults (workerd budgets + shared disk). Always set.
  • host_user_agentstringrequiredThe User-Agent this host sends for the plugin's requests, except to the request's ownUserAgentHosts.
  • setting_destinationsarray of PluginSettingDestinationViewrequiredThe destination each network setting (network = "fetch" or "tcp") names on each instance, and whether it is approved. Empty when the plugin declares no network setting. A pending row is not reachable until it is approved; covered is false while one is.

PluginDeploymentChanged

PUT /api/config/plugin-instances/{id}/deployments/{node_id} body: the deployment row after the write.

  • deployment_idstringrequiredDeployment row id.
  • plugin_instance_idstringrequiredInstance the row belongs to.
  • node_idstringrequiredNode the row targets.
  • desiredDesiredStaterequiredDesired state now stored.
  • revisioninteger (int64)requiredCompare-and-swap revision after the write.

PluginDeploymentView

This node's view of one deployment row, with its latest observation.

  • deployment_idstringrequiredDeployment row id.
  • node_idstringrequiredNode the row targets.
  • desiredDesiredStaterequiredWhat the row asks the node to do: present / absent from an operator, placed / unplaced from the scheduler.
  • revisioninteger (int64)requiredCompare-and-swap revision of the desired row.
  • statusstring or nullLatest observation status from that node, when it reported one.
  • detailstring or nullObservation detail (error text, redacted).
  • applied_config_revisioninteger (int64) or nullDocument revision the running guest applied.
  • observed_atstring or nullRFC 3339 time of the observation.

PluginGrantOverride

Operator-supplied grant fields that replace matching request values.

  • networkModestring or nullOverride egress mode (deny or outbound) when set.
  • domainsarray of string or nullOverride approved hostnames when set.
  • tcparray of TcpGrantView or nullOverride raw TCP grants when set.
  • addressCidrsarray of string or nullOverride address-space CIDRs when set.
  • allowUndeclaredPublicRedirectsboolean or nullOverride undeclared-public-redirect permission when set.
  • ownUserAgentHostsarray of string or nullOverride the hosts that keep the plugin's own User-Agent when set. Each entry must be one the request lists; leaving one out sends the host's agent there instead.
  • bindingsarray of string or nullOverride approved bindings when set. Entries are host binding names (config, secrets, plugin_kv, work_fs, oauth) and the manifest tokens the consent request lists (database:<NAME>, queue:<BINDING>, queue_consumer:<queue>, cron:<schedule>). A manifest token must match one in the request exactly; leaving one out narrows the grant.
  • compatibilityFlagsarray of string or nullOverride compatibility flags when set.
  • cpuMsinteger (int32) or nullOverride workerd CPU milliseconds when set. At least 0.
  • subrequestsinteger (int32) or nullOverride workerd subrequest budget when set. At least 0.
  • diskMibinteger (int32) or nullOverride disk budget in mebibytes when set. At least 0.
  • memoryMibinteger (int32) or nullOverride jail memory in mebibytes when set. At least 0.
  • cpuCoresnumber (double) or nullJail CPU in cores (2 d.p.); converted to Spec percent server-side.
  • extraProcessesinteger (int32) or nullExtra process/thread budget (native); ignored for workerd. At least 0.

PluginGrantView

Operator-facing grant JSON: CPU as cores (not Spec percent).

  • pluginKeystringrequiredCanonical provenance-qualified PluginKey.
  • pluginIdstringrequiredPlugin id this grant applies to.
  • entrypointsarray of stringrequiredExported entrypoints the operator approved (storefront, cli, …).
  • producersarray of stringrequiredEvent types the operator approved the plugin to publish.
  • consumersarray of objectrequiredApproved event-consumer subscriptions.
  • jobsarray of stringrequiredApproved job trigger types.
  • networkModestringrequiredApproved egress mode (deny or outbound).
  • domainsarray of stringrequiredHostnames the operator approved for egress.
  • manifestDomainsarray of stringrequiredDestinations requested by the current manifest.
  • operatorAddedDomainsarray of stringrequiredOperator-added destinations beyond the manifest.
  • operatorDeniedDomainsarray of stringrequiredOperator-denied destinations still listed by the manifest.
  • tcparray of TcpGrantViewrequiredEffective raw TCP grants.
  • operatorAddedTcparray of TcpGrantViewrequiredOperator-added TCP grants.
  • operatorDeniedTcparray of TcpGrantViewrequiredOperator-denied TCP grants still listed by the manifest.
  • addressCidrsarray of stringrequiredEffective address-space CIDRs.
  • operatorAddedCidrsarray of stringrequiredOperator-added CIDRs.
  • operatorDeniedCidrsarray of stringrequiredOperator-denied CIDRs still listed by the manifest.
  • allowUndeclaredPublicRedirectsbooleanrequiredUndeclared public redirect permission.
  • ownUserAgentHostsarray of string or nullHosts (exact or *. wildcard) that receive the plugin's own User-Agent; every other request carries the host's agent. Absent on a grant approved before this permission existed, which keeps the hosts the plugin's manifest declares.
  • ownUserAgentReasonstring or nullThe plugin's reason for [Self::own_user_agent_hosts], from plugin.toml.
  • grantRevisionstringrequiredSHA-256 of persisted operator consent (no host overlays).
  • authorityRevisionstringrequiredSHA-256 of the canonical effective authority.
  • bindingsarray of stringrequiredHost bindings the operator approved.
  • compatibilityFlagsarray of stringrequiredExtra compatibility flags stored on the grant.
  • approvedAtstringrequiredRFC 3339 timestamp when the grant was last approved.
  • cpuMsinteger (int32) or nullOptional workerd CPU budget in milliseconds. At least 0.
  • subrequestsinteger (int32) or nullOptional workerd subrequest budget. At least 0.
  • diskMibinteger (int32) or nullOptional plugin state disk budget in mebibytes. At least 0.
  • memoryMibinteger (int32) or nullOptional jail memory in mebibytes. At least 0.
  • cpuCoresnumber (double) or nullJail CPU in cores (2 d.p.); absent for workerd.
  • extraProcessesinteger (int32) or nullExtra process/thread budget beyond launcher overhead; native only. At least 0.

PluginInstalled

POST /api/config/plugins body: what the install did.

  • createdbooleanrequiredTrue when the version row was written now; false when the same version with the same artifacts was installed already.
  • plugin_instance_idstringrequiredId of the plugin's default instance.
  • versionPluginVersionSummaryrequiredThe installed version.

PluginInstanceConfigChanged

PUT /api/config/plugin-instances/{id}/config body: the document after the write.

  • plugin_instance_idstringrequiredInstance id.
  • revisioninteger (int64)requiredRevision after the write; unchanged when the same write was replayed.
  • settingsmap of string to SettingValuerequiredScalar settings now stored.
  • secret_refsarray of InstanceSecretRefV1requiredSecret refs now stored, the newly sealed secrets included.

PluginInstanceConfigResponse

GET /api/config/plugin-instances/{id}/config body: the stored document and the configuration the guest receives.

  • plugin_instance_idstringrequiredInstance id.
  • plugin_keystringrequiredCanonical plugin key.
  • revisioninteger (int64)requiredCompare-and-swap revision of the document.
  • settingsmap of string to SettingValuerequiredScalar settings the operator wrote.
  • secret_refsarray of InstanceSecretRefV1requiredSecret refs; ciphertext stays in encrypted_secrets.
  • effectivemap of string to any JSONrequiredSettings as the guest sees them: schema defaults overlaid with the stored values. Empty when the plugin has no pinned schema.
  • schemaarray of SettingSpecrequiredDeclared settings from the pinned schema; empty when there is none.

PluginInstanceCreated

POST /api/config/plugin-instances body: the instance that was created.

  • plugin_instance_idstringrequiredId of the new instance.
  • plugin_keystringrequiredCanonical plugin key the instance belongs to.
  • display_namestringrequiredOperator-facing name, trimmed.
  • owner_node_idstring or nullNode the instance is local to; null for a library-wide instance.

PluginInstanceDeleted

DELETE /api/config/plugin-instances/{id} body.

  • plugin_instance_idstringrequiredId of the instance that was removed.
  • deletedbooleanrequiredAlways true: removing an instance that is already gone answers the same way.

PluginInstancesResponse

GET /api/config/plugin-instances body: every instance as this node sees it.

  • node_idstringrequiredId of the node that answered; its deployments carry its own observations.
  • instancesarray of PluginInstanceViewrequiredEvery plugin instance in the library.

PluginInstanceView

One plugin instance with its schema, document, and deployments.

  • plugin_instance_idstringrequiredInstance id.
  • plugin_keystringrequiredCanonical plugin key.
  • aliasstringrequiredManifest id recorded with the pinned schema (display alias).
  • display_namestringrequiredOperator-facing name; empty for the default instance.
  • is_defaultbooleanrequiredTrue when a bare plugin key or alias routes to this instance.
  • created_atstringrequiredRFC 3339 creation time.
  • schemaarray of SettingSpecrequiredDeclared settings from the pinned schema.
  • configInstanceConfigView or nullCurrent document, when the instance has one.
  • deploymentsarray of PluginDeploymentViewrequiredDeployment rows across nodes.
  • placementPlacementView or nullScheduler placement; absent when the instance is hand-managed.
  • storage_syncStorageSyncView or nullHow outside changes at this destination are followed; absent until a storage instance's first sync pass.

PluginPlacementChanged

PUT /api/config/plugin-instances/{id}/placement body: the placement after the write.

  • plugin_instance_idstringrequiredInstance the scheduler now places.
  • placementPlacementViewrequiredThe stored intent and the last scheduler pass's result.

PluginPlacementDeleted

DELETE /api/config/plugin-instances/{id}/placement body.

  • plugin_instance_idstringrequiredInstance that is hand-managed again.
  • deletedbooleanrequiredTrue when a placement existed and was removed; false when the instance was hand-managed already.

PluginSettingChoice

One selectable value for a Settings dropdown.

  • valuestringrequiredStored config value; empty string means use the plugin default.
  • labelstringrequiredOperator-facing choice caption.

PluginSettingColumn

One column of a table setting in the Settings UI.

  • keystringrequiredRecord field the column fills in each row.
  • labelstringrequiredColumn heading.
  • value_typestringrequiredUI widget hint (boolean, string, or number).
  • choicesarray of PluginSettingChoice or nullDropdown values of an enum column; omitted otherwise.
  • defaultstring or nullString form of the value a new row starts with; omitted when there is no default.
  • requiredbooleanTrue when every row must have a value in this column.

PluginSettingDestinationApproval

A setting destination the operator approves.

  • settingstringrequiredThe setting key.
  • destinationstringrequiredThe destination exactly as the consent response shows it.

PluginSettingDestinationView

One network setting's destination on one plugin instance.

  • instanceIdstring or nullThe instance whose settings name it; absent when the plugin has no instance yet and the row shows the setting's default.
  • settingstringrequiredThe setting key, the source the grant is stored under.
  • labelstringrequiredThe setting's label (its key when it has none).
  • networkstringrequiredfetch (HTTP requests) or tcp (a raw socket).
  • destinationstring or nullThe destination: scheme://host:port for a fetch, host:port for TCP (IPv6 in brackets); absent when the setting is unset or invalid.
  • scopestring or nullWhat kind of host it is: name (may resolve to a local-network address, for this name only), publicAddress, localAddress (this one local-network address) or restricted (loopback, link-local or a name such as localhost, which also needs an address grant).
  • tlsboolean or nullTrue for an https fetch, whose certificate is verified; false for plain HTTP and raw TCP, which trust the network's DNS answer.
  • statestringrequiredapproved, pending (awaiting consent), unset or invalid.
  • errorstring or nullWhy the value names no destination, when state is invalid.

PluginSettingOption

One editable setting shown in the Settings UI.

  • keystringrequiredDotted config.toml key for this option.
  • labelstringrequiredOperator-facing field caption.
  • valuestringrequiredCurrent string form of the setting.
  • value_typestringrequiredUI widget hint (boolean, string, number, secret, or table).
  • choicesarray of PluginSettingChoice or nullOptional dropdown values; omitted for free-form fields.
  • secretbooleanTrue for a secret setting: value is never the stored value.
  • secret_setboolean or nullFor a secret setting, whether the instance document names a sealed value.
  • columnsarray of PluginSettingColumn or nullColumns of a table setting, in display order; omitted for other kinds. value is then the rows as JSON text.

PluginSettingsGroup

Settings UI group for one discovered or loaded plugin.

  • idstringrequiredPlugin id (audible, sqlite, and similar).
  • familystringrequiredHandler family wire label (source, integration, output, database).
  • plugin_keystring or nullProvenance-qualified PluginKey when this row came from a discovered install.
  • provenancestring or nullHost-evaluated provenance (platform_bundled, verified_staged, installed, …).
  • logostring or nullSame-origin logo for Settings list rows: the plugin's embedded logo, or a 128 px copy of the remote logo its manifest names.
  • settingsarray of PluginSettingOptionrequiredEditable options for this plugin, including .enabled.
  • plugin_instance_idstring or nullPlugin instance this group edits; absent for a bootstrap database adapter.
  • display_namestring or nullOperator-facing instance name, when the operator set one.
  • is_defaultbooleanTrue when a bare plugin key or alias routes to this instance.
  • config_revisioninteger (int64) or nullInstance document revision for compare-and-swap writes.
  • deploymentPluginDeploymentView or nullThis node's deployment of the instance, when one exists.
  • placementPlacementView or nullScheduler placement; absent when the instance is hand-managed (the Enabled switch applies only then).
  • storage_syncStorageSyncView or nullHow outside changes at this destination are followed; absent for other plugins and before a destination's first sync pass.
  • present_onarray of stringNodes whose deployment of the instance is present.

PluginUninstalled

DELETE /api/config/plugins/{key} body.

  • plugin_keystringrequiredCanonical plugin key.
  • uninstalledbooleanrequiredTrue when an active-version pointer existed and was cleared.
  • deployments_undeployedintegerrequiredDeployment rows switched to absent across the plugin's instances. At least 0.

PluginVersionApproved

POST /api/config/plugins/{key}/versions/{version}/approve body.

  • plugin_keystringrequiredCanonical plugin key.
  • versionstringrequiredSemver version whose grant was approved.
  • approvedbooleanrequiredAlways true: a version that cannot be approved is an error instead.
  • grantobjectrequiredThe grant document, as the consent store keeps it: approved entrypoints, event producers and consumers, jobs, the network mode with the effective, manifest, operator-added and operator-denied domains, TCP targets and CIDRs, host bindings, compatibility flags, resource budgets and the approval time.

PluginVersionSummary

One installed version of a plugin, as the API renders it.

  • plugin_keystringrequiredCanonical plugin key.
  • idstringrequiredManifest id (display alias).
  • versionstringrequiredSemver package version.
  • activebooleanrequiredTrue when this is the plugin's active version.
  • approvedbooleanrequiredTrue once an operator approved the version's consent request.
  • publisher_verifiedbooleanrequiredTrue when the publisher was verified at install time.
  • coordinatestringrequiredPackage coordinate the version was resolved from; empty for a local archive.
  • installed_atstringrequiredRFC 3339 install time.
  • installed_bystringrequiredAudit identity of the installer.
  • host_payload_root_sha256string or nullPayload-root digest of the artifact this host would run; null when no artifact fits the host's target.
  • artifactsarray of PluginArtifactSummaryrequiredPer-target artifacts.

PortalErrorBody

JSON body of every portal error response.

  • errorstringrequiredOperator-facing error text (no structured code).

PortalMeInfo

Portal identity fields exposed on /me for SSO / local-portal callers.

  • identity_idinteger (int64)requiredportal_identities.id for this session.
  • providerstringrequiredIdentity-broker id (local, OIDC provider name, …).
  • external_user_idstringrequiredProvider-stable subject / external user id.
  • labelstring or nullOptional operator-facing label for the identity.

PortalOk

JSON body of a portal route that has nothing to report beyond success.

  • okbooleanrequiredAlways true.

PortalSessionIssued

JSON body after a portal session was minted for a first-party user.

  • okbooleanrequiredAlways true on this success path.
  • rolestringrequiredThe user's role (owner, administrator, or member).

PortalSessionKind

Where a user's session token is presented.

A token works only in its own place: a browser token only as the session cookie, a library card only as Authorization: Bookclerk-Clerk, and a player card's tokens only on the /player API.

Type: one of browser, clerk, player

PortalSessionView

A portal (user) session as listed by GET /api/auth/sessions.

  • idinteger (int64)requiredSession id, for DELETE /api/auth/sessions/{id}.
  • created_atstringrequiredRFC 3339 time the session was created.
  • expires_atstringrequiredRFC 3339 expiry.
  • last_used_atstring or nullRFC 3339 time of the last authenticated use, when any.
  • is_currentbooleanrequiredWhether this is the session making the request.
  • client_labelstring or nullBest-effort OS or client label from the User-Agent.
  • device_typestring or nullBest-effort device class (desktop, mobile, tablet, api).
  • user_agentstring or nullRaw User-Agent captured when the session was created.
  • channelPortalSessionKindrequiredHow the session is used: browser for a browser session, clerk for a library card, whose client_label is the name the clerk gave itself, player for a player app's card (/player), whose client_label is the player password's label or the app's name.

PostNodeInvite

POST /api/config/node-invites body.

  • user_idinteger (int64) or nullUser who will own the node. Defaults to the caller; the operator must name one.
  • ttl_secsinteger (int64) or nullLink lifetime in seconds (default 24 h, 5 min to 7 days). At least 0.
  • labelstringLabel shown in listings.

PostPluginInstall

POST /api/config/plugins body: exactly one of coordinate or package (a directory name under plugin-packages/).

  • coordinatestring or nullRegistry coordinate (cargo:…@v, registry:…#name@v).
  • packagestring or nullOperator-placed package directory under plugin-packages/.
  • activatebooleanMake the new version active even when another is.
  • approvebooleanRecord the requested consent as approved.
  • allow_unverified_publisherbooleanAccept a publisher without independent authenticity.

PreferencesResponse

Normalized Discover/library preferences for the authenticated subject.

  • default_viewstringrequiredLanding view id (library, discover, …) after normalization.
  • disabled_shelvesarray of stringrequiredLowercased Discover shelf ids the user has hidden.
  • discover_sortstringrequiredDiscover sort key (relevance, popularity, …).
  • discover_sort_dirstringrequiredDiscover sort direction (asc or desc).
  • discover_languagestring or nullnull = use browser language on the client.
  • discover_excluded_sourcesarray of stringrequiredLowercased store ids hidden from Discover results.
  • themestringrequiredAppearance preference (system, light, or dark).

ProfileChanged

JSON body after PATCH /api/auth/profile.

  • okbooleanrequiredAlways true on this success path.
  • userAuthMeUserrequiredThe profile after the change, as GET /api/auth/me reports it.

ProgressBatchEntry

One entry of PATCH /player/api/me/progress/batch/update.

  • libraryItemIdstringrequiredThe item.
  • currentTimenumber (double) or nullThe position, in seconds.
  • durationnumber (double) or nullThe runtime, in seconds.
  • isFinishedboolean or nullWhether the book is finished.

ProgressBody

PATCH /player/api/me/progress/{id}: a change to the patron's progress.

  • currentTimenumber (double) or nullThe position, in seconds.
  • progressnumber (double) or nullThe share of duration listened, 0 to 1, read when currentTime is absent.
  • durationnumber (double) or nullThe runtime, in seconds.
  • isFinishedboolean or nullWhether the book is finished.
  • hideFromContinueListeningboolean or nullTrue to take the item off Continue listening.

ProgressEditBody

PUT /api/playback/progress/{edition_id} body: what to set. A field left out keeps its stored value.

  • position_msinteger (int64) or nullPosition in milliseconds (at most sixty days). At least 0.
  • duration_msinteger (int64) or nullThe edition's runtime in milliseconds, when the page knows it. At least 0.
  • is_finishedboolean or nullTrue marks the edition and its work finished; false clears the edition's flag (the work's stays, and is changed with the work's own state). Left out, the position decides.

ProgressJson

One person's progress in one edition.

  • edition_idstringrequiredThe edition.
  • work_idstring or nullThe edition's work, when known: what a Continue listening shelf reads the title and cover from.
  • position_msinteger (int64)requiredPosition on the edition's timeline, in milliseconds. At least 0.
  • duration_msinteger (int64) or nullThe edition's runtime in milliseconds as the last player reported it; null until one has. At least 0.
  • is_finishedbooleanrequiredTrue once the caller reached the end of this edition.
  • started_atstringrequiredWhen the caller first played it (RFC 3339).
  • finished_atstring or nullWhen the caller last reached the end (RFC 3339).
  • updated_atstringrequiredWhen the progress last changed (RFC 3339).

ProgressPage

GET /api/playback/progress answer.

  • itemsarray of ProgressJsonrequiredThe caller's progress rows, most recently played first. Editions their patron scope no longer shows are left out, so a page can be shorter than limit with more to come.
  • next_cursorstring or nullCursor of the next page; absent on the last.

PurchaseHint

A purchase / catalog availability hint (optionally priced at view time).

  • sourcestringrequiredCanonical storefront / plugin id (audible, libro, chirp, …).
  • product_idstringrequiredStorefront-native product id (ASIN, ISBN, UUID, …).
  • titlestring or nullDisplay title as shown on the storefront or library card.
  • urlstring or nullAbsolute HTTPS URL.
  • price_centsinteger (int64) or nullPrimary / best known sell price in minor units (prefer member when dual). 0 = free.
  • currencystring or nullISO 4217 currency code for price fields (USD, EUR, …).
  • price_labelstring or nullDisplay string from the store ($2.99, FREE, …).
  • list_price_centsinteger (int64) or nullNon-member / list price in integer cents when known.
  • list_price_labelstring or nullHuman-readable list price from the storefront.
  • member_price_centsinteger (int64) or nullMember / credit price in integer cents when known.
  • member_price_labelstring or nullHuman-readable member price from the storefront.

PurchaseHintsBatchBody

Body for batched purchase-hint lookups (max 24 queries).

PurchaseHintsBatchResponse

Parallel purchase-hint results aligned with the request queries.

PurchaseHintsQuery

Inputs for view-time catalog + pricing lookup.

  • titlestringrequiredDisplay title as shown on the storefront or library card.
  • authorsstring or nullComma-separated author names when the storefront provides them.
  • asinstring or nullAudible / Amazon ASIN when this edition is sold on Audible.
  • isbnstring or nullCanonical ISBN-13 (or ISBN-10 normalized) when published.
  • candidate_sourcestring or nullStorefront id of the edition that produced this card.
  • candidate_product_idstring or nullStorefront product id of the edition that produced this card.
  • store_editionsarray of StoreEditionKnown storefront editions already on the recommendation card.
  • regionstring or nullMarketplace / region code (us, uk, …) for catalog lookups.
  • preferred_sourcesarray of stringStorefronts the caller has linked accounts for. Treated as member pricing when picking best; other stores are compared at list / non-member price. Every catalog match is still returned in hints.

PurchaseHintsResponse

Priced catalog matches for one title, sorted best-first.

  • hintsarray of PurchaseHintrequiredResolved purchase hints for this query.
  • bestPurchaseHint or nullLowest-priced hint (or first catalog hit when no prices resolved).
  • incompletebooleanTrue when the batch deadline cut this lookup short (the hints are the query's trusted seeds alone), or when the hints could not be checked against the card's recording in time: a client should not keep the answer and asks again later. Omitted (false) for a finished lookup.

PutActiveVersion

PUT /api/config/plugins/{key}/active body.

  • versionstringrequiredInstalled version to activate.

PutBranchEnrollment

PUT /api/config/branch-enrollment body.

  • enabledbooleanrequiredWhether branch nodes may enroll into this library.

PutBranches

PUT /api/config/branches body.

  • enrollmentbooleanrequired"Let new branches join" (core.branch_enrollment.enabled).

PutEventsDomainRequest

JSON body for PUT /api/config/domains/core.events.

  • expected_revisioninteger (int64)requiredRevision the caller read. A mismatch is a conflict.
  • retention_daysinteger (int64)requiredReplacement [events] document. At least 0.
  • dead_letter_retention_daysinteger (int64)requiredReplacement dead-letter retention. At least 0.
  • concurrencyinteger (int32)requiredReplacement concurrency cap. At least 0.

PutNodeLabels

PUT /api/config/nodes/{node_id}/labels body.

  • labelsarray of stringrequiredThe node's complete operator label set.

PutNodeOwner

PUT /api/config/nodes/{node_id}/owner body.

  • user_idinteger (int64) or nullUser who owns the node, or null to clear.

PutNodeRuntime

PUT /api/config/nodes/{node_id}/runtime body: any subset of the node's runtime document.

  • labelstring or nullOperator label.
  • cpu_budget_percentinteger (int32) or nullShare of detected CPU the scheduler may commit (1..=100). At least 0.
  • memory_budget_percentinteger (int32) or nullShare of detected memory the scheduler may commit (1..=100). At least 0.
  • schedulableboolean or nullFalse drains the node.
  • cache_budget_bytesinteger (int64) or nullThis node's image cache budget in bytes (16 MiB to 1 TiB), overriding the library's cache.budget_bytes. null removes the override; leaving the field out keeps it as it is. At least 0.

PutOutputDomainRequest

JSON body for PUT /api/config/domains/core.output.

  • expected_revisioninteger (int64)requiredRevision the caller read. A mismatch is a conflict.
  • documentOutputSettingsV1requiredComplete replacement document (schema version 1).

PutPluginDeployment

PUT /api/config/plugin-instances/{id}/deployments/{node_id} body.

  • desiredDesiredStaterequiredWhat the node should do: present or absent (the scheduler's placed / unplaced are accepted too).
  • expected_revisioninteger (int64) or nullRevision the caller last observed; required when the row exists and the caller wants compare-and-swap. Omitted means "replace whatever is current".

PutPluginInstanceConfig

PUT /api/config/plugin-instances/{id}/config body.

  • expected_revisioninteger (int64)requiredRevision the caller last observed.
  • settingsmap of string to SettingValueScalar settings. Secret values are not accepted here.
  • secret_refsarray of objectSecret refs to keep. Omitted refs are dropped from the document; the ciphertext stays sealed until the secret is overwritten.
  • secretsmap of string to stringSecret values to seal, keyed by the declared secret setting. Each is sealed into encrypted_secrets and referenced from the document; the plaintext is never stored in the document or echoed back.

PutPluginPlacement

PUT /api/config/plugin-instances/{id}/placement body.

  • replicasinteger or allrequiredA replica count (0 stops every replica) or "all".
  • constraintsarray of stringLabel constraints (name, name=value, !name).
  • expected_revisioninteger (int64) or nullCurrent revision to replace; omit (or 0) to create.

PutUserControls

PUT /api/users/{id}/controls body.

  • overridesControlOverridesrequiredThe controls set for this patron alone; an absent or null control follows the library's default for a Member and is allowed for an Administrator, so {} clears every override.

PutUserScope

PUT /api/users/{id}/scope body.

  • scopePatronScope or nullThe patron's own scope, or null to return them to the library's default.

QueueDetail

Operator JSON for GET /api/queues/{name}.

Includes every field of QueueInfo.

  • messagesarray of DomainEventInforequiredRecent messages on the queue, newest first.
  • deliveriesarray of EventDeliveryInforequiredRecent deliveries on the queue, newest first.

QueueInfo

Operator JSON for one queue on GET /api/queues.

  • namestringrequiredQueue name.
  • corebooleanrequiredTrue for the domain-event bus (core.events).
  • pendinginteger (int64)requiredDeliveries waiting to be claimed (including suspended rows).
  • runninginteger (int64)requiredDeliveries currently claimed by a worker.
  • ackedinteger (int64)requiredDeliveries acked.
  • deadLetterinteger (int64)requiredDeliveries parked for operator review.
  • consumersarray of stringrequiredLive catalog consumers (plugin keys or instance ids) of this queue.

QueueWisher

Compact wisher shown on the global queue (avatar + label).

  • user_idinteger (int64) or nullFirst-party users.id when the portal identity is linked.
  • identity_idinteger (int64) or nullPortal identity that created the wish (dedupe for unlinked identities).
  • display_namestring or nullDisplay name, identity label, or "Operator".
  • login_namestring or nullLocal login name when the first-party user has one.
  • operatorbooleanTrue when the wish came from the operator token (no portal user).
  • has_avatarbooleanTrue when an uploaded avatar file exists (filled by the daemon).
  • avatar_sourcestring or nullExplicit picture choice when the user has set one.
  • gravatar_hashstring or nullSHA-256 hex of the contact email for Gravatar.
  • picture_urlstring or nullHTTPS picture from the wishing identity, when any.
  • picture_pathstring or nullSame-origin 128 px copy of picture_url for the web app to show (filled by the daemon; never stored).

RankedQueueEntry

Global wishlist queue entry ranked by overall/operator recommend taste + heavy wish-count weight (shared order; not per-viewer personalized).

  • work_keystringrequiredStable map key for this work (isbn:…, asin:…, or soft title+author).
  • work_idstringrequiredThe work every wish of this entry is for. Wishes for one work are one entry even when their work_keys differ, so a client matches its own wishes on this id first and on work_key otherwise.
  • titlestringrequiredDisplay title as shown on the storefront or library card.
  • authorsstring or nullComma-separated author names when the storefront provides them.
  • asinstring or nullAudible / Amazon ASIN when this edition is sold on Audible.
  • isbnstring or nullCanonical ISBN-13 (or ISBN-10 normalized) when published.
  • cover_urlstring or nullHTTPS URL for cover art when the catalog exposes one.
  • cover_pathstring or nullSame-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
  • wish_countinteger (int64)requiredNumber of distinct users who wishlisted this title.
  • wishersarray of QueueWisherDistinct people who have this title on an open wishlist.
  • sample_uuidsarray of stringrequiredSample Bookclerk user UUIDs who requested this title (privacy-capped).
  • first_requested_atstring (date-time)requiredUTC timestamp of the earliest wishlist request for this work.
  • last_requested_atstring (date-time)requiredUTC timestamp of the latest wishlist request for this work.
  • scorenumber (double)requiredFinal rank score (taste_score + wish_count * [WISH_COUNT_WEIGHT]).
  • taste_scorenumber (double)requiredLocal taste / embedding component before the wish-count boost.
  • reasonsarray of stringrequiredShort human-readable explanations for why this item was ranked here.

ReadBody

Body of POST /api/me/notifications/inbox/read.

  • notification_idstring or nullOne notification to mark read; absent or null marks the whole inbox read.

ReadMarked

How many entries a read marked.

  • markedinteger (int64)requiredEntries that were unread and are now read. At least 0.

ReceivedJson

Where a file's bytes stand after a PATCH.

  • memberNointeger (int32)requiredThe file's number. At least 0.
  • receivedinteger (int64)requiredBytes received; send the next PATCH from here. At least 0.
  • completebooleanrequiredTrue once every byte has arrived.

Recommendation

One ranked recommendation (typically an unowned storefront title).

  • work_idstring or nullLibrary works.id of the work the card's edition belongs to, when the library's data model places it (a wish, or a store listing from the shared listing pool). Cards for one work are one card.
  • titlestringrequiredDisplay title as shown on the storefront or library card.
  • authorsstring or nullComma-separated author names when the storefront provides them.
  • narratorsstring or nullComma-separated narrator names when known.
  • seriesstring or nullSeries name when the title belongs to a named series.
  • series_indexstring or nullPosition within the series (e.g. 1, 1.5) when known.
  • asinstring or nullAudible / Amazon ASIN when this edition is sold on Audible.
  • isbnstring or nullCanonical ISBN-13 (or ISBN-10 normalized) when published.
  • scorenumber (double)requiredRanking score (higher is better); units are algorithm-specific.
  • reasonsarray of stringrequiredShort human-readable explanations for why this item was ranked here.
  • purchase_hintsarray of PurchaseHintrequiredBuy / open-in-store links with optional member vs list pricing.
  • from_requestbooleanrequiredTrue when sourced from an open title request rather than storefront discovery.
  • request_uuidstring or nullWishlist / title-request UUID when this card came from a request.
  • candidate_sourcestring or nullStorefront that proposed this title (audible, libro, …).
  • candidate_product_idstring or nullStorefront product id of the edition that produced this card.
  • store_editionsarray of StoreEditionAll known storefront editions (for multi-store purchase links).
  • seed_categoriesstring or nullCategories/subjects copied from the taste seed that produced this hit.
  • categoriesarray of stringStable shelf-kind tags for prefs (finish_series, author, chirp_deals, …). Dynamic shelf titles stay in build_discover_feed; membership uses these.
  • work_keystringStable bibliographic key for wishlist / merge (isbn: / asin: / soft:…).
  • cover_urlstring or nullCover art URL when known from a storefront catalog hit or wishlist row.
  • cover_pathstring or nullSame-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
  • subtitlestring or nullOptional bibliographic extras from storefront catalog / Audnexus.
  • descriptionstring or nullPublisher or storefront synopsis; may be truncated for embeddings.
  • publisherstring or nullPublisher imprint as reported by the catalog.
  • length_minutesinteger (int64) or nullAudiobook runtime in whole minutes when known.
  • published_atstring or nullPublication date string from the catalog (ISO or storefront format).
  • genresstring or nullCandidate genres (not taste-seed seed_categories).
  • languagestring or nullBCP-47 / storefront language code (en, de, …) when known.
  • is_explicitboolean or nullWhen Some(true), a storefront marks the edition explicit (adult) content; None when none said (a wishlist entry says nothing).
  • wishersarray of QueueWisherDistinct people who have this title on an open wishlist.
  • wish_countinteger (int64)Number of distinct users who wishlisted this title (may exceed wishers.len()).
  • seed_titlestring or nullTitle of the book or wish the storefront was asked about to find this card, when it came from such an expansion.
  • starter_genrestring or nullStarter genre this card was browsed from while the taste was thin.
  • available_througharray of BranchAvailabilityBranches of this library that currently list this title (they answered a catalog lookup for its work). Filled when the feed is read, never stored with it.

RecoveryCopyAnswer

What the operator recorded about a recovery copy of the key in use.

Type: one of unrecorded, saved, skipped

RecoveryCopyChoiceBody

What the operator did about a recovery copy.

Type: one of saved, skipped

RecoveryCopyRequest

POST /api/config/master-key/recovery-copy body.

  • passwordstringrequiredThe password the copy is wrapped with: at least 12 characters. Keep it apart from the copy; without it the copy can't be restored.

RecoveryCopyStateRequest

PUT /api/config/master-key/recovery-copy/state body.

RedeemBody

JSON body for POST /redeem (claim ticket plus retry nonce).

  • ticketstringrequiredRaw claim-ticket token to redeem into a portal session.
  • noncestringrequiredBrowser-generated one-time nonce persisted across HTTP retries.
  • passwordstring or nullRequired when the linked local user has no password (invite / reset).

RegistrationFinish

POST /api/auth/passkeys/register/finish body: the browser's attestation plus the challenge id from register/begin.

The credential is read straight into WebAuthn's typed attestation, so the handler never decodes caller JSON itself.

  • challenge_idstringrequiredServer-issued challenge id (consumed once; 5-minute TTL).
  • credentialany JSONrequiredW3C PublicKeyCredential as the browser serializes it: a registration attestation (response.attestationObject) or an authentication assertion (response.authenticatorData, signature, userHandle), binary fields base64url-encoded.
  • namestring or nullLabel stored with the credential (Passkey when empty).

RemoteConsentView

An owner library's request to run a plugin on this install, and what the operator answered.

  • library_idstringrequiredThe parent library's id.
  • plugin_keystringrequiredCanonical plugin key.
  • requested_versionstringrequiredVersion the owner deploys here now.
  • requested_grantany JSONrequiredA plugin grant document (the plugin host's PluginGrant): the plugin key, the entrypoints, network mode and domains, and the bindings it may use; null when nothing was approved.
  • requested_artifactRequestedArtifactrequiredThe archive the owner deploys to this install.
  • request_digeststringrequiredDigest of the request as a whole; an approval names it so a changed request is not approved by mistake.
  • approved_versionstring or nullVersion this install's operator approved, when any.
  • grantany JSONrequiredA plugin grant document (the plugin host's PluginGrant): the plugin key, the entrypoints, network mode and domains, and the bindings it may use; null when nothing was approved.
  • approved_atstring or nullRFC 3339 approval time.
  • approved_bystring or nullWho approved (operator, or platform for an automatic approval).
  • revoked_atstring or nullRFC 3339 time the operator revoked the approval.
  • updated_atstringrequiredRFC 3339 time of the last write.
  • statestringrequiredHow this host stands on the request: consented, awaiting_host_consent (no approval, or a revoked one), awaiting_host_reapproval (the owner changed the request or the archive since the approval), or invalid_grant (a grant that does not parse).
  • pendingarray of stringrequiredWhat the owner's current request asks for beyond the request the operator approved, as the operator-facing lines the CLI prints; empty when nothing was approved yet or the request stays within the approval.

RemoveBranchTitles

POST /api/config/branches/titles/remove body.

  • node_idstring or nullOnly this branch's entries; every branch's when absent.

RenameBody

Body of PATCH /api/notifications/channels/{id}.

  • labelstringrequiredThe new name, 1 to 128 bytes on one line.

ReplacedCard

The library card a branch join replaced.

  • card_removedbooleanrequiredWhether the card was dropped here. False when it could not be read or dropped: it is then still listed under Library cards, and the person signs it out there. The branch join stands either way.
  • library_signed_outbooleanrequiredWhether the library ended the card's session too. False when it could not be reached, or the card was not dropped here.

ReplacementRule

Character replacement rule (ReplacementCharacters in classic Settings.json).

  • findstringrequiredSubstring to search for in each path segment / tag value.
  • replacestringrequiredReplacement text (may be empty to strip find).

ReportEventField

One field recorded with an event.

  • namestringrequiredThe field's name.
  • valuestringrequiredIts value, redacted before the report was sent.

ReportEventLevel

Severity of one event in a report.

Type: one of ERROR, WARN, INFO, DEBUG, TRACE

ReportEventView

One logged event in a stored report.

  • ts_unix_msinteger (int64)requiredWhen it happened, Unix milliseconds, or 0 when the report had none. At least 0.
  • levelReportEventLevelrequiredIts severity.
  • targetstringrequiredWhere it was logged (the tracing target).
  • messagestringrequiredThe message, redacted before the report was sent.
  • fieldsarray of ReportEventFieldrequiredFields recorded with it.

ReportFixView

The fix recorded for the report's tracking issue.

  • pr_numberinteger (int64) or nullThe pull request that fixed it, when known. At least 0.
  • pr_urlstring or nullThat pull request's page (https://), when known.
  • fixed_instring or nullThe first release with the fix, when one has shipped.

ReportIssueState

Whether an issue is open.

Type: one of open, closed

ReportIssueView

A GitHub issue tracking the report.

  • numberinteger (int64)requiredThe issue number. At least 0.
  • titlestringrequiredIts title.
  • stateReportIssueStaterequiredWhether it is open.
  • urlstringrequiredIts page (always https://).

RequestedArtifact

The archive an owner library deploys to this install.

  • urlstringrequiredWhere the owner fetches it from.
  • archive_sha256stringrequiredSHA-256 of the archive.
  • payload_root_sha256stringrequiredPayload-root digest of the tree it unpacks to.

RequestStatus

Wishlist row status (open while wishlisted; cancelled after un-wishlist).

Type: one of open, cancelled

ReviewItemJson

One stored book to review.

  • upload_idstringrequiredThe upload.
  • member_nointeger (int32)requiredThe file's number in it. At least 0.
  • pathstringrequiredThe file's path in the upload.
  • edition_idstring or nullThe local edition it was stored under.
  • user_idinteger (int64)requiredThe patron who uploaded it.

ReviewPage

One page of books to review.

  • itemsarray of ReviewItemJsonrequiredThe books, oldest upload first.
  • next_cursorstring or nullPass as cursor for the next page; absent when this page is empty.

RevisionConflict

Body of a 409 Conflict from a compare-and-swap write whose expected_revision lost to a newer revision.

  • errorstringrequiredAlways revision_conflict.
  • current_revisioninteger (int64)requiredThe revision to read and retry against.

RevokeBody

POST /api/config/library-consents/revoke body.

  • library_idstringrequiredLibrary id.
  • plugin_keystringrequiredCanonical plugin key.

RevokeForm

Form body for POST /oidc/revoke (RFC 7009-style refresh-token revoke).

  • tokenstringrequiredToken to revoke; treated as a refresh token (hashed before lookup).
  • token_type_hintstring or nullOptional hint ignored; this server only stores refresh tokens.

RouteJson

One route: a channel, or the built-in "In app" target, and the least severity it takes.

  • destination_idstringrequiredThe channel's id, or in-app for the built-in target that puts the notification in every active Owner's and Administrator's inbox (the bell in the web app, and browser or desktop notifications where they turned them on). in-app runs no plugin and is listed first.
  • min_severitystringrequiredinfo, warning or critical: notifications less urgent than this skip the channel.

RoutesBody

Body of PUT /api/notifications/routes/{type}.

  • routesarray of RouteJsonrequiredThe type's routes, replacing the old ones; at most 32. Empty sends the type nowhere. At most 32 items.

RouteTable

Every routing rule, by type.

  • routesmap of string to array of RouteJsonrequiredType id to its routes.

RuleEffect

Whether a [ScopeRule] lets matching books in or keeps them out.

Type: one of include, exclude

ScanPlanResponse

Result of a planned scan or acquire: [ActionResponse] plus every job id.

  • okbooleanrequiredTrue when at least one job was accepted.
  • messagestringrequiredOperator-facing status text.
  • job_idstringrequiredFirst accepted (or, when none was, already queued) job id.
  • job_idsarray of stringrequiredEvery accepted or already-queued job id, in plan order.
  • errorstring or nullMachine slug when nothing was accepted (conflict, queue_full, nothing_to_scan, nothing_to_acquire).

ScanRequest

Optional body for POST /api/library/scan.

  • accountstring or nullWhen set, scan this account even if scan_enabled is false.
  • plugin_instance_idstring or nullWhen set, scan only this deployed plugin instance.

SchemaStateView

Whether the database carries exactly the schema this binary applies.

The object example is the successful read; a failed read has state null, compatible false and the error text.

  • statestring or nullThe schema state (uninitialized, unreleased@base<n>+<checksum> or frozen@<n>+<checksum>); null when it could not be read.
  • compatiblebooleanrequiredTrue when this binary can run against that schema.
  • errorstring or nullWhy the state could not be read; omitted when it was.

ScopeField

The book field a [ScopeRule] matches one value of.

Type: one of genre, series, author, narrator, tag, collection

ScopeRule

One rule of a scope: a field, one value of it, and its effect.

  • fieldScopeFieldrequiredThe field the rule matches.
  • valuestringrequiredThe value, compared without case and surrounding space (1 to 256 bytes).
  • effectRuleEffectrequiredInclude or exclude.

SearchBook

An item that matched a search.

SearchResults

GET /api/libraries/{id}/search.

  • bookarray of SearchBookrequiredMatching items.
  • podcastarray of objectrequiredAlways empty.
  • narratorsarray of NarratorrequiredMatching narrators.
  • tagsarray of objectrequiredAlways empty.
  • genresarray of objectrequiredAlways empty.
  • seriesarray of SearchSeriesrequiredMatching series.
  • authorsarray of AuthorrequiredMatching authors.

SearchSeries

A series that matched a search.

Series

A series.

  • idstringrequiredThe series id.
  • namestringrequiredIts name.
  • nameIgnorePrefixstringrequiredThe name for sorting.
  • descriptionstring or nullIts description: none.
  • addedAtinteger (int64)requiredWhen the library first saw it, in epoch milliseconds.
  • updatedAtinteger (int64)requiredWhen it last changed, in epoch milliseconds.
  • libraryIdstringrequiredThe library it is listed in.
  • booksarray of LibraryItem or nullIts items in series order, on lists.
  • progressSeriesProgress or nullThe patron's progress through it, when asked for.

SeriesPage

A page of series.

  • resultsarray of SeriesrequiredThe page's series.
  • totalinteger (int64)requiredSeries in all. At least 0.
  • limitinteger (int64)requiredSeries per page. At least 0.
  • pageinteger (int64)requiredThe page number, from 0. At least 0.
  • sortBystring or nullThe sort key, echoed.
  • sortDescbooleanrequiredWhether the order is reversed.
  • filterBystring or nullThe filter, echoed.
  • minifiedbooleanrequiredWhether items are minified.
  • includestringrequiredThe include list, echoed.

SeriesProgress

The patron's progress through a series.

  • libraryItemIdsarray of stringrequiredThe series' items, by id.
  • libraryItemIdsFinishedarray of stringrequiredThose the patron finished.
  • isFinishedbooleanrequiredWhether the patron finished every one.

SeriesRef

A series an item belongs to, with the item's place in it.

  • idstringrequiredThe series id.
  • namestringrequiredThe series name.
  • sequencestring or nullThe item's place in the series as the library writes it (1, 2.5), if known.

ServerSettings

The server settings apps read.

  • idstringrequiredAlways server-settings.
  • versionstringrequired[crate::COMPATIBLE_SERVER_VERSION]: apps turn features on by it.
  • buildNumberinteger (int32)requiredAlways 1. At least 0.
  • languagestringrequiredThe interface language.
  • dateFormatstringrequiredHow apps format dates.
  • timeFormatstringrequiredHow apps format times.
  • sortingIgnorePrefixbooleanrequiredWhether sorting skips leading articles: no.
  • sortingPrefixesarray of stringrequiredThe articles sorting would skip.
  • chromecastEnabledbooleanrequiredWhether apps offer casting: no.
  • homeBookshelfViewinteger (int32)requiredThe home shelf style (1: standard). At least 0.
  • bookshelfViewinteger (int32)requiredThe library shelf style (1: standard). At least 0.
  • authActiveAuthMethodsarray of stringrequired[AUTH_METHODS].
  • authOpenIDButtonTextstringrequiredThe browser sign-in button's label.
  • authOpenIDAutoLaunchbooleanrequiredNever true.
  • authLoginCustomMessagestring or nullThe sign-in screen's note.
  • timeZonestringrequiredThe host's time zone name, or UTC.

SessionDevice

The device a playback session was opened from.

  • deviceIdstringrequiredThe device's id: the card's session id.
  • deviceNamestring or nullThe device name the app reported, if any.
  • clientNamestring or nullThe app's name, if reported.

SessionJson

POST /api/playback/sessions answer.

  • session_idstringrequiredThe session's id, for its sync, close and track routes.
  • edition_idstringrequiredThe edition being played.
  • work_idstring or nullIts work.
  • position_msinteger (int64)requiredWhere to start, in milliseconds: the caller's stored position, or 0 for a first listen or an edition they had finished. At least 0.
  • duration_msinteger (int64) or nullRuntime in milliseconds when known (see the manifest). At least 0.
  • tracksarray of TrackJsonrequiredThe tracks in play order, each with the path to stream it from.
  • idle_secsinteger (int64)requiredSeconds without a report after which the session stops streaming and the player opens a new one.

SessionPage

GET /api/me/listening-sessions.

  • totalinteger (int64)requiredSessions in all. At least 0.
  • numPagesinteger (int64)requiredPages in all. At least 0.
  • pageinteger (int64)requiredThe page number, from 0. At least 0.
  • itemsPerPageinteger (int64)requiredSessions per page. At least 0.
  • sessionsarray of PlaybackSessionrequiredThe page's sessions, newest first.

SessionsResponse

JSON body for GET /api/auth/sessions.

  • sessionsarray of SessionViewrequiredThe caller's sessions, newest first; empty for a Bearer-only caller, who has no session rows.

SessionView

One session in the caller's list, told apart by kind: an operator session or a portal (user) session.

Type: OperatorSessionView and object or PortalSessionView and object

SetPasswordRequest

JSON body for setting a password (self or provisioner target).

  • passwordstringrequiredNew password; hashed before persist. Empty is rejected.
  • current_passwordstring or nullRequired when the caller already has a password (not first-time invite setup).
  • user_idinteger (int64) or nullTarget users.id when a provisioner sets another user's password.

SettingCell

One cell of a table setting row: the scalar kinds only.

Type: boolean or SettingNumber or string

SettingKind

Value type of a declared plugin setting.

Type: one of string, bool, integer, enum, secret, table

SettingNumber

A finite JSON number; an integer for integer settings.

Type: number

SettingSpec

One setting a plugin declares in its plugin.toml [[settings]]: its key, value type, default and help text.

  • keystringrequiredSetting key ([a-z][a-z0-9_]*, at most 64 bytes).
  • labelstring or nullOperator-facing label; omitted when the key is shown.
  • typeSettingKindrequiredValue type: string, bool, integer, enum, secret or table.
  • valuesarray of SettingValueSpec or nullAllowed values of an enum setting; omitted for other kinds.
  • defaultany JSONDefault applied when the instance document has no value; omitted when there is none. A string, boolean or integer, or for a table an array of row objects, as the setting's type says.
  • requiredboolean or nullTrue when the instance cannot run without a value; omitted when false.
  • descriptionstring or nullHelp text shown beside the setting; omitted when there is none.
  • columnsarray of SettingSpec or nullColumns of a table setting, in display order: each a scalar entry naming one field of every row. Omitted for other kinds.

SettingsResponse

Settings page payload: file values, effective runtime, and plugin groups.

  • settingsmap of string to stringrequiredValues as written in config.toml (and env overlays), plus output.* from the core.output database document.
  • effectivemap of string to stringrequiredRuntime-effective values after the last successful reload (auth, plugins).
  • pluginsarray of PluginSettingsGrouprequiredPer-plugin setting groups rendered by the Settings UI.
  • host_cpu_cores_maxnumber (double)requiredHost max jail CPU in cores (2 d.p.; equals logical CPU count).
  • jail_cpu_coresnumber (double) or nullOptional global per-jail CPU ceiling in cores (from [plugins.jail]).
  • output_revisioninteger (int64) or nullRevision of the core.output document the output.* values in settings were read from; send it back as expected_output_revision. effective["output.revision"] is the revision this host has applied, which lags the document until the host's next wakeup.

SettingsUpdate

One config.toml key/value pair from a settings PATCH.

  • keystringrequiredDotted config key; rejected unless it passes the settings allowlist.
  • valuestringrequiredRaw string value, normalized before it is written.

SettingValue

One setting value: a scalar, or the rows of a table setting.

Type: boolean or SettingNumber or string or array of map of string to SettingCell

SettingValueSpec

One allowed value of an enum setting: the stored id and its label.

  • idstringrequiredStored value.
  • labelstring or nullOperator-facing label; omitted when the id is shown.

SharedBranchesResponse

GET /api/config/shared-branches body.

  • node_idstringrequiredId of the node that answered.
  • nodesarray of NodeViewrequiredThis node and the shared branches the caller may see.

SharedBranchJoined

JSON body once this install joined a library as a shared branch.

  • connectionstringrequiredAlways shared_branch.
  • library_idstringrequiredThe library id.
  • node_idstringrequiredThe node id the library minted for this install.
  • library_namestringrequiredThe library's name.
  • databasestringrequiredThe database plugin this install now runs (postgres or d1).
  • master_key_wrappedbooleanrequiredWhether the shared master key was wrapped with this install's password.
  • restartingbooleanrequiredAlways true: the daemon restarts as a shared node right after answering.

SharedNodeRemoved

DELETE /api/config/nodes/{node_id} body.

  • node_idstringrequiredId of the node that was removed, trimmed.
  • removedbooleanrequiredAlways true: a refused removal is an error status instead.

SharingBody

POST /api/config/join/sharing body: one library and the settings to change for it.

  • library_idstringrequiredThe library (parent library id).
  • share_booksbooleanrequired"Share this branch's books with library".
  • include_branchesbooleanrequired"Include books from my own branches".
  • list_members_booksboolean or null"List my members' books to library"; absent or null keeps the stored setting.
  • work_for_membersboolean or null"Download for other members of library": take the library's work for its other members too, not only this install owner's. Absent or null keeps the stored setting.
  • keep_member_copiesboolean or null"Keep copies of other members' books": also write a book acquired here for another member to this install's own destinations. Absent or null keeps the stored setting.
  • keep_copiesboolean or null"Keep copies on this computer": take the library's copies of this install's person's books into its own storage. Absent or null keeps the stored setting.

SharingChanged

JSON body after POST /api/config/join/sharing.

SharingSettings

JSON body for GET /api/config/join/sharing.

  • librariesarray of LibraryLinkViewrequiredEvery library this install is a branch of, with its sharing and work settings.

Shelf

A personalized shelf on the home screen.

  • idstringrequiredThe shelf id, such as continue-listening.
  • labelstringrequiredThe shelf's English label.
  • labelStringKeystringrequiredThe key apps translate the label by.
  • typestringrequiredWhat the shelf holds: book, series or authors.
  • entitiesShelfEntitiesrequiredThe shelf's entries.
  • totalinteger (int64)requiredEntries in all. At least 0.

ShelfEntities

A shelf's entries.

Type: array of LibraryItem or array of Series or array of Author

ShelfKindInfo

A shelf kind the operator can ignore (all offered by default).

  • idstringrequiredStable kind id (finish_series, author, genre, from_store, …).
  • labelstringrequiredOperator-visible label for this account or item.

SigninIntegration

One integration that signs people in with its own credentials.

  • idstringrequiredIntegration id, used in /api/integrations/{id}/login.
  • namestringrequiredButton label.

SigninMethods

JSON body for GET /api/auth/signin: the ways this library lets people sign in.

  • operator_tokenbooleanrequiredWhether the operator token may be entered in the SPA (only before an Owner exists).
  • oidcarray of SigninOidcProviderrequiredEnabled OIDC identity providers, in configuration order.
  • integrationsarray of SigninIntegrationrequiredIntegrations that accept their own credentials at sign-in.
  • require_second_factorbooleanrequiredWhether daemon.auth.require_second_factor is on, so clients can explain the enrollment step.

SigninOidcProvider

One OIDC identity provider offered on the sign-in page.

  • idstringrequiredProvider id from [auth.oidc.providers], used in /api/auth/oidc/{id}/start.
  • namestringrequiredButton label.
  • presetstring or nullKnown social preset the client may style (google, github, …), when the provider matches one.

SourceConfigOptionInfo

One storefront config option (key, label, allowed values).

  • keystringrequiredConfig table key (for example container).
  • labelstringrequiredOperator-facing option name.
  • valuesarray of ConfigOptionValueInforequiredAllowed values the SPA may offer for this option.

SourceConnected

JSON body of a connected store account.

  • okbooleanrequiredAlways true.
  • account_idstringrequiredThe store's id for the account.
  • sourcestringrequiredThe source's id, as listed by GET /api/portal/sources.
  • plugin_keystringrequiredThe plugin that owns the account.

SourceInfo

One enabled storefront as shown on the portal Accounts page.

  • idstringrequiredSource plugin id (audible, libro, …).
  • namestringrequiredOperator-facing storefront name.
  • authstringrequiredPortal auth mode (password or oauth).
  • config_optionsarray of SourceConfigOptionInfoStore-specific knobs the SPA can present (omitted when empty).
  • brandBrandInforequiredStorefront colors and logo href for the Accounts UI.

SourcesResponse

JSON body for GET /sources.

  • sourcesarray of SourceInforequiredEnabled storefronts the SPA may offer for connect / login.

SplitJson

The result of a split.

  • work_idstringrequiredThe new work the expressions moved to.
  • split_fromstringrequiredThe work that was split.

StartBody

POST /api/config/join/start body.

  • addressstringThe library's address. Left out with from_card.
  • from_cardstring or nullThe library id of a library this install holds an active library card for: the branch replaces the card. The library's address and pinned certificate come from the card, so address and fingerprint are left out, and the branch name defaults to the card's name. Not with shared_branch.
  • fingerprintstring or nullThe fingerprint the operator confirmed (self-signed libraries).
  • branch_namestring or nullThe name to join as (default: this machine's name).
  • shared_branchbooleanOffer to join as a shared branch (a shared node that shares the library's database): only an empty install may, and its data is replaced.

Status

GET /status: what an app asks before it signs in.

  • appstringrequiredAlways [STATUS_APP].
  • serverVersionstringrequiredThe server release whose API this one answers like ([crate::COMPATIBLE_SERVER_VERSION]).
  • isInitbooleanrequiredAlways true: the library is set up before an app can sign in.
  • languagestringrequiredThe interface language apps show server text in.
  • authMethodsarray of stringrequired[AUTH_METHODS].
  • authFormDataAuthFormDatarequiredWhat the sign-in screen shows.

StatusResponse

Library and daemon snapshot for GET /api/status.

  • accountsintegerrequiredCount of configured store accounts. At least 0.
  • booksintegerrequiredHeld works in the library (the works page index). At least 0.
  • acquiredinteger (int64)requiredHeld works whose furthest acquire state is acquired.
  • pendinginteger (int64)requiredHeld works still needing acquire (not_acquired).
  • errorinteger (int64)requiredHeld works stuck in error after a failed acquire.
  • in_progressinteger (int64)requiredHeld works currently queued or downloading.
  • listenstringrequiredComma-joined daemon.listen addresses from live config.
  • storage_backendstringrequiredComma-joined enabled destination plugin ids, or none.
  • auth_enabledbooleanrequiredWhether the live auth middleware requires operator credentials.
  • eventsEventQueueStatusrequiredDurable domain-event delivery-queue counters.

StepUp

A fresh second factor for a shared branch consent. Debug prints no code.

Type: object

StorageFeedState

The state of a destination's change feed, as the API reports it.

Type: one of off, healthy, gap, failing

StorageSyncView

How a destination notices changes made outside Bookclerk: its change feed's state and its listings (storage destinations ADR, decision 5).

  • feed_stateStorageFeedStaterequiredThe change feed's state: off (no feed; listings alone), healthy, gap (the feed may have missed changes; a listing runs at once) or failing (reading the feed failed; listings cover it).
  • feed_errorstring or nullThe last feed failure.
  • feed_checked_atstring or nullRFC 3339 time the feed was last read.
  • listed_atstring or nullRFC 3339 time the last listing finished.
  • next_listing_atstring or nullRFC 3339 time the next scheduled listing is due.
  • listing_in_progressbooleanrequiredTrue while a listing is in progress (it continues on the next pass).
  • listing_errorstring or nullWhy the last listing failed or its removals were held back.
  • objectsinteger (int64)requiredFiles the destination held after the last listing or feed page. At least 0.

StoredReportView

The stored report as the collector keeps it.

  • versionstringrequiredThe Bookclerk version that sent it.
  • triggerstringrequiredWhy it was sent.
  • osstringrequiredThe sender's operating system.
  • archstringrequiredThe sender's CPU architecture.
  • distrostringrequiredThe sender's Linux distribution, or empty.
  • eventsarray of ReportEventViewrequiredIts events, oldest first.

StoreEdition

One storefront edition of a work (for multi-store purchase links).

  • sourcestringrequiredCanonical storefront / plugin id (audible, libro, chirp, …).
  • product_idstringrequiredStorefront-native product id (ASIN, ISBN, UUID, …).

SyncBody

POST /player/api/session/{id}/sync and .../close: where the patron is.

  • currentTimenumber (double) or nullThe position, in seconds.
  • timeListenednumber (double) or nullSeconds listened since the last sync.
  • durationnumber (double) or nullThe runtime the app measured, in seconds.

SyncJson

POST /api/playback/sessions/{id}/sync and .../close answer.

  • progressProgressJsonrequiredThe caller's progress after the report.
  • finished_nowbooleanrequiredTrue when this report is the one that reached the edition's end: the edition and its work are now finished for the caller.

SyncResult

One entry's outcome in a batch sync.

  • idstringrequiredThe session or item id the entry named.
  • successbooleanrequiredWhether it was applied.
  • errorstring or nullWhy not, when it was not.

SyncResults

POST /api/session/local-all.

  • resultsarray of SyncResultrequiredOne outcome per entry, in the order sent.

TcpGrantView

Operator-facing TCP grant (host + ports).

  • hoststringrequiredHostname or *. wildcard.
  • portsarray of integer (int32)requiredDestination ports.

TestSent

The answer to a test send.

  • notification_idstringrequiredThe stored test notification.
  • delivery_idstringrequiredIts delivery; follow it in the delivery log.

TitleMeta

Bibliographic fields suitable for an Audible-style detail panel.

  • asinstring or nullAudible / Amazon ASIN when this edition is sold on Audible.
  • titlestring or nullDisplay title as shown on the storefront or library card.
  • subtitlestring or nullOptional subtitle when the catalog distinguishes it from the title.
  • authorsstring or nullComma-separated author names when the storefront provides them.
  • narratorsstring or nullComma-separated narrator names when known.
  • seriesstring or nullSeries name when the title belongs to a named series.
  • series_indexstring or nullPosition within the series (e.g. 1, 1.5) when known.
  • isbnstring or nullCanonical ISBN-13 (or ISBN-10 normalized) when published.
  • cover_urlstring or nullHTTPS URL for cover art when the catalog exposes one.
  • cover_pathstring or nullSame-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
  • descriptionstring or nullPublisher or storefront synopsis; may be truncated for embeddings.
  • publisherstring or nullPublisher imprint as reported by the catalog.
  • length_minutesinteger (int64) or nullAudiobook runtime in whole minutes when known.
  • published_atstring or nullPublication date string from the catalog (ISO or storefront format).
  • categoriesstring or nullGenre / subject tags as a single delimited string when known.
  • languagestring or nullBCP-47 / storefront language code (en, de, …) when known.
  • is_abridgedboolean or nullSome(true) abridged / Some(false) unabridged when the storefront said so.
  • rating_overallnumber (double) or nullAudible community overall rating (0–5).
  • rating_performancenumber (double) or nullNarration / performance sub-score when the storefront splits ratings.
  • rating_storynumber (double) or nullStory / content sub-score when the storefront splits ratings.
  • rating_countinteger (int64) or nullCount of star ratings (Audible num_ratings).
  • review_countinteger (int64) or nullCount of written reviews (Audible num_reviews).
  • reviewsarray of TitleReviewDeprecated: reviews load via /api/discover/title-reviews. Kept empty for older clients; prefer the paginated reviews endpoint.

TitleMetaBatchBody

Body for batched title-metadata lookups (max 24 queries).

  • queriesarray of TitleMetaQueryPer-title metadata queries in this batch.

TitleMetaBatchResponse

Title-metadata results aligned with the request; failed items are null.

  • resultsarray of TitleMeta or nullrequiredOne optional metadata payload per query; enrichment errors become None.
  • incompletearray of booleanrequiredPer query, in order: true when its null is a failure or a query that ran past the batch deadline, not an answer, so the client should not keep it and may ask again later.

TitleMetaQuery

Query for public title metadata (Audnexus / Audible catalog).

  • titlestringDisplay title as shown on the storefront or library card.
  • authorsstring or nullComma-separated author names when the storefront provides them.
  • asinstring or nullAudible / Amazon ASIN when this edition is sold on Audible.
  • isbnstring or nullCanonical ISBN-13 (or ISBN-10 normalized) when published.
  • narratorsstring or nullComma-separated narrator names when known.
  • length_minutesinteger (int64) or nullAudiobook runtime in whole minutes when known.
  • regionstringMarketplace / region code (us, uk, …) for catalog lookups.
  • store_editionsarray of StoreEditionStore editions that listed this title (the search hit's or card's store_editions), at most 16. A sparse record is filled from each of these stores that declared detailByProductId, by the product id it gave the title, before the stores that declared detailByIsbn are asked by ISBN.

TitleRequestRecord

Personal wishlist row (also contributes to the shared global queue while open).

  • idinteger (int64)requiredSurrogate primary key assigned by the database.
  • uuidstringrequiredStable UUID for this row (API / foreign-key identity).
  • identity_idinteger (int64) or nullForeign key to portal_identities.id.
  • titlestringrequiredDisplay title: the title of the wish's work.
  • authorsstring or nullComma-separated authors: the work's author credits in billing order.
  • asinstring or nullAmazon ASIN from the wish's storefront sources, when one carries it.
  • isbnstring or nullISBN-10/13 from the wish's storefront sources, when one carries it.
  • notesstring or nullFree-form operator or requester notes.
  • statusRequestStatusrequiredLifecycle status for the row (user, request, …).
  • work_keystringBibliographic card key (isbn:… / asin:… / soft:…) clients use to match a wish to a catalog card. Derived from the work's title and authors and the sources' identifiers on every read, never stored.
  • work_idstringrequiredThe work the wish is for; wishes for one work are one queue entry.
  • edition_idstring or nullThe edition the wish named, when the library knows it.
  • resolved_edition_idstring or nullEdition (editions.id) the library holds once the wishlist item is fulfilled.
  • cover_urlstring or nullHTTPS URL for cover art when known.
  • cover_pathstring or nullSame-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
  • sourcesarray of TitleRequestSourceRecordPer-storefront snapshots (empty for legacy rows).
  • descriptionstring or nullBlurb / synopsis text (may contain HTML).
  • subtitlestring or nullOptional subtitle from bibliographic metadata.
  • narratorsstring or nullComma-separated or JSON narrator list when present.
  • seriesstring or nullSeries name when the title belongs to a series.
  • series_indexstring or nullPosition within the series (storefront string form).
  • publisherstring or nullPublisher name from metadata enrichment or the storefront.
  • length_minutesinteger (int64) or nullRuntime in whole minutes when the storefront reports it.
  • published_atstring or nullPublication date string from the storefront or enrichment.
  • genresstring or nullMerged genre / category list for display.
  • languagestring or nullBCP-47 or storefront language code when known.
  • store_editionsarray of WishlistStoreEditionDistinct storefront editions contributing to this wishlist item.
  • purchase_hintsarray of WishlistPurchaseHintPurchase URLs and prices observed per storefront.
  • created_atstring (date-time)requiredRFC 3339 timestamp when the row was inserted.
  • updated_atstring (date-time)requiredRFC 3339 timestamp when the row was last modified.

TitleRequestSourceRecord

Per-storefront catalog/pricing snapshot attached to a wishlist row.

  • idinteger (int64)requiredSurrogate primary key assigned by the database.
  • title_request_idinteger (int64)requiredForeign key to title_requests.id.
  • sourcestringrequiredContent-source plugin id (audible, libro, …).
  • product_idstringrequiredStorefront product id (ASIN, ISBN, UUID, …).
  • titlestring or nullDisplay title of the work or edition.
  • subtitlestring or nullOptional subtitle from bibliographic metadata.
  • authorsstring or nullComma-separated or JSON author list from the storefront.
  • narratorsstring or nullComma-separated or JSON narrator list when present.
  • seriesstring or nullSeries name when the title belongs to a series.
  • series_indexstring or nullPosition within the series (storefront string form).
  • asinstring or nullAmazon ASIN when known; otherwise null.
  • isbnstring or nullISBN-10/13 when known; otherwise null.
  • descriptionstring or nullBlurb / synopsis text (may contain HTML).
  • publisherstring or nullPublisher name from metadata enrichment or the storefront.
  • length_minutesinteger (int64) or nullRuntime in whole minutes when the storefront reports it.
  • published_atstring or nullPublication date string from the storefront or enrichment.
  • categoriesstring or nullStorefront category / genre path list (serialized).
  • languagestring or nullBCP-47 or storefront language code when known.
  • cover_urlstring or nullHTTPS URL for cover art when known.
  • urlstring or nullStorefront product or purchase URL when known.
  • price_centsinteger (int64) or nullObserved price in minor currency units, when known.
  • currencystring or nullISO 4217 currency code for price fields.
  • price_labelstring or nullStorefront-formatted price string for display.
  • list_price_centsinteger (int64) or nullList/MSRP price in minor units, when known.
  • list_price_labelstring or nullStorefront-formatted list price for display.
  • member_price_centsinteger (int64) or nullMember/subscriber price in minor units, when known.
  • member_price_labelstring or nullStorefront-formatted member price for display.
  • observed_atstring (date-time) or nullRFC 3339 time when this storefront snapshot was observed.
  • created_atstring (date-time)requiredRFC 3339 timestamp when the row was inserted.
  • updated_atstring (date-time)requiredRFC 3339 timestamp when the row was last modified.

TitleReview

One Audible customer review for the title detail panel.

  • idstring or nullStable identifier for this item.
  • titlestring or nullDisplay title as shown on the storefront or library card.
  • bodystringrequiredFull review text from the storefront.
  • author_namestring or nullDisplay name of the review author on the storefront.
  • overall_ratinginteger (int64) or nullOverall star rating for this review when present.
  • performance_ratinginteger (int64) or nullNarration sub-rating for this review when present.
  • story_ratinginteger (int64) or nullStory sub-rating for this review when present.
  • submitted_atstring or nullWhen the review was submitted (storefront timestamp string).

TitleReviewsPage

One page of title reviews for infinite scroll.

  • asinstringrequiredAudible / Amazon ASIN when this edition is sold on Audible.
  • pageinteger (int32)required1-based page index for this reviews / list request. At least 0.
  • page_sizeinteger (int32)requiredMaximum number of items returned in this page. At least 0.
  • has_morebooleanrequiredWhen true, another page is available by incrementing [Self::page].
  • sort_bystringrequiredRemote sort key for reviews (MostHelpful or MostRecent, as applied).
  • reviewsarray of TitleReviewrequiredReview rows on this page.

TitleReviewsQuery

Query for a page of Audible customer reviews.

  • asinstringrequiredAudible / Amazon ASIN when this edition is sold on Audible.
  • regionstringMarketplace / region code (us, uk, …) for catalog lookups.
  • pageinteger (int32)1-based page index. At least 0.
  • page_sizeinteger (int32)Page size (clamped server-side to 1..=20). At least 0.
  • sort_bystringMostHelpful (default) or MostRecent.

TokenError

A token-endpoint refusal as RFC 6749 §5.2 writes it: JSON with an error code and a human-readable error_description, sent with Cache-Control: no-store.

  • errorTokenErrorCoderequiredWhat went wrong, as a client library branches on it.
  • error_descriptionstring or nullA sentence for the person debugging the client; never a secret or a token.

TokenErrorCode

The error code of a token-endpoint refusal (RFC 6749 §5.2), which also fixes its status.

Type: one of invalid_request, invalid_client, invalid_grant, unsupported_grant_type, server_error

TokenForm

application/x-www-form-urlencoded body for POST /oidc/token.

  • grant_typestringrequiredGrant: authorization_code or refresh_token; anything else is 400.
  • codestring or nullAuthorization code from the redirect (authorization_code grant).
  • redirect_uristring or nullMust match the URI bound to the consumed authorization code.
  • client_idstring or nullClient id; required for code exchange, optional (but checked) on refresh.
  • client_secretstring or nullClient secret for confidential clients (client_secret_post).
  • code_verifierstring or nullPKCE verifier; SHA-256 must match the stored challenge.
  • refresh_tokenstring or nullRefresh token to rotate (refresh_token grant).

TokenResponse

Successful token-endpoint JSON (access, optional refresh, and ID tokens).

  • access_tokenstringrequiredHS256 JWT access token bound to the User (token_use=access).
  • token_typestringrequiredAlways Bearer for this server.
  • expires_ininteger (int64)requiredAccess-token lifetime in seconds (same as [ACCESS_TTL_SECS]).
  • refresh_tokenstring or nullOpaque refresh token when the client is allowed to receive one.
  • id_tokenstringrequiredHS256 ID token; profile/email claims follow the granted scope.
  • scopestringrequiredSpace-separated scopes granted to this token pair.

TotpChallenge

Password accepted, but an authenticator-app code is needed before a session is issued.

  • okbooleanrequiredAlways true: the password step succeeded.
  • mfaTotpChallengeDetailsrequiredThe second step the client must complete.

TotpChallengeDetails

The pending second-factor step after a password login.

  • methodstringrequiredAlways totp: finish with POST /api/auth/totp/login.
  • challenge_idstringrequiredChallenge to send with the code; expires after five minutes.

TotpEnrollment

JSON body after TOTP enrollment began: what the authenticator app needs.

  • secretstringrequiredPending base32 secret, for typing into an app by hand.
  • otpauth_urlstringrequiredotpauth:// URL the QR code encodes.
  • qr_svgstringrequiredThe QR code as an SVG document, ready to inline.

TotpReauthBody

Optional current password for enroll/disable step-up.

  • current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.

TotpStatus

JSON body for GET /api/auth/totp.

  • enabledbooleanrequiredWhether an authenticator app is confirmed for the caller.

TrackJson

One audio file of an edition, as a player sees it.

  • indexintegerrequiredThe track's place in play order, from 0. At least 0.
  • pathstring or nullPath to stream it from, on this origin; only in a session's answer.
  • content_typestringrequiredMedia type the stream states, such as audio/mp4.
  • bitrate_kbpsinteger (int32) or nullAverage bitrate in kilobits per second, once probed. At least 0.
  • losslessbooleanrequiredTrue for a lossless encoding.

TransportRefused

JSON body of a 403 from the node API's transport policy: the connection is plain HTTP off loopback, or arrived through a proxy the policy does not trust, and reason names the check that refused it.

  • errorstringrequiredAlways transport_insecure.
  • reasonstringrequiredThe transport check that refused the connection (plain_http, unknown_peer, untrusted_forwarding, proxy_proto_missing, proxy_proto_ambiguous, proxy_proto_not_https, public_origin_not_https, listener_mode_mismatch, node_api_misconfigured).

TrayHandoffPrepareResponse

JSON returned to the tray after a successful prepare.

  • codestringrequiredSingle-use loopback handoff code for GET /api/auth/tray-handoff?code=.
  • expires_in_secsinteger (int64)requiredSeconds until this ticket expires (matches the in-process deadline). At least 0.

UploadAnswer

Answer of the upload endpoint (every status carries one).

  • statusstringrequiredStable outcome: received, partial (a part that is not the file's last was taken), committed, lost, refused, misdirected, unauthorized, unavailable.
  • reasonstring or nullWhy, for refused, and resume for an unavailable part that does not continue the open file at [Self::offset].
  • offsetinteger (int64) or nullFor partial, and an unavailable part with reason resume: the offset of the next byte of the file the owner needs. At least 0.
  • job_completedbooleanFor committed: the job is finished.

UploadCommitRequest

Body of POST <UPLOADS_PATH><upload_id>/commit.

  • finishbooleanComplete the job with this commit (the job's closing upload).
  • detailstring or nullOutcome text recorded as the job's progress when finish is set.

UploadJson

One upload.

  • idstringrequiredThe upload id (32 hex digits).
  • statestringrequiredopen (taking bytes), committed (queued), running, done, failed or cancelled.
  • sourcestringrequiredupload, or intake for a batch a drop folder made.
  • fileCountinteger (int64)requiredFiles the manifest named. At least 0.
  • declaredBytesinteger (int64)requiredBytes the manifest declared. At least 0.
  • jobIdstring or nullThe ingest job, once committed.
  • detailstring or nullWhy the upload failed.
  • createdAtstringrequiredWhen it was created (RFC 3339).
  • updatedAtstringrequiredIts last activity (RFC 3339).
  • finishedAtstring or nullWhen it finished (RFC 3339).
  • filesarray of UploadMemberJson or nullIts files; left out of lists.

UploadList

The caller's uploads, newest first.

  • uploadsarray of UploadJsonrequiredAt most 50 uploads, without their files.

UploadManifest

POST /api/uploads body: the files of one batch.

  • filesarray of ManifestFilerequiredEvery file of the batch, in the order their numbers follow.

UploadMemberJson

One file of an upload.

  • memberNointeger (int32)requiredIts number in the upload; manifest files are numbered from 0 in order, an archive's entries after every earlier file. At least 0.
  • parentNointeger (int32) or nullThe archive it was expanded from. At least 0.
  • pathstringrequiredIts path in the upload (for a refused archive entry, its cleaned name).
  • sizeinteger (int64)requiredIts size in bytes. At least 0.
  • receivedinteger (int64)requiredBytes received so far; resume a PATCH here. At least 0.
  • outcomestringrequiredWhat became of it: pending, expanded (an archive), matched, needs_review, duplicate, refused or failed.
  • reasonstring or nullWhy it was refused or failed, as a stable code.
  • editionIdstring or nullThe edition it was stored under.

User

A patron as apps see them.

  • idstringrequiredThe patron's portal identity id, as a string.
  • usernamestringrequiredThe name the patron signs in with.
  • emailstring or nullThe patron's email address, if the library has one.
  • typestringrequiredAlways user: no app is given administrator powers.
  • tokenstringrequiredThe access token, for apps that read it from here (older apps send this one as their bearer). Empty where the answer is not a sign-in.
  • accessTokenstring or nullThe card's access token, on sign-in and refresh answers only.
  • refreshTokenstring or nullThe card's refresh token, on sign-in and refresh answers only.
  • isOldTokenbooleanrequiredAlways false: tokens are never the old non-expiring kind.
  • mediaProgressarray of MediaProgressrequiredProgress on every item the patron has started.
  • seriesHideFromContinueListeningarray of stringrequiredSeries hidden from continue listening: none.
  • bookmarksarray of BookmarkrequiredEvery bookmark the patron has made.
  • isActivebooleanrequiredAlways true: a disabled patron cannot sign in.
  • isLockedbooleanrequiredAlways false.
  • lastSeeninteger (int64) or nullWhen the patron was last seen, in epoch milliseconds.
  • createdAtinteger (int64)requiredWhen the patron joined, in epoch milliseconds.
  • permissionsPermissionsrequiredWhat the patron may do.
  • librariesAccessiblearray of stringrequiredLibraries the patron may open, by id.
  • itemTagsSelectedarray of stringrequiredTags that limit what the patron sees: none (scope is applied by the host, not by tags).
  • hasOpenIDLinkbooleanrequiredWhether the patron signed in through the browser at least once.

UserAdminControlsJson

An Administrator's switches as the switch routes report them.

  • user_idinteger (int64)requiredThe user (users.id).
  • defaultsAdminControlsrequiredThe library's default for every Administrator.
  • overridesAdminControlOverridesrequiredThe switches set for this Administrator alone; the others follow the default.
  • effectiveAdminControlsrequiredWhat applies to the user now: everything for an Owner, nothing for a disabled user or a Member, and the default with the overrides applied for an Administrator.
  • appliesbooleanrequiredWhether the switches limit the user's role: true only for an Administrator.

UserChangeConflict

Body of a 409 Conflict from a user change that would leave the library without an owner or administrator.

  • errorstringrequiredWhy the change was refused: last_owner or last_administrator.

UserChangeInvalid

Body of a 400 Bad Request from a user change with an invalid email.

  • errorstringrequiredMachine slug for the rejected value.
  • messagestringrequiredA sentence to show the person who made the request.

UserChangeResponse

Body of a user change that succeeded: the user as stored afterwards.

  • okbooleanrequiredAlways true; the status code says the change was applied.
  • userUserSummaryrequiredThe user after the change.

UserClaimTicketResponse

Body of POST /api/users/{id}/claim-ticket.

  • okbooleanrequiredAlways true; the status code says the ticket was minted.
  • claim_ticketstringrequiredOpaque single-use claim ticket for the user.
  • invite_urlstringrequiredInvite link that redeems the claim ticket.

UserControlsJson

A patron's member controls as the control routes report them.

  • user_idinteger (int64)requiredThe user (users.id).
  • defaultsMemberControlsrequiredThe library's default, which Members follow.
  • overridesControlOverridesrequiredThe controls set for this patron alone; the others follow the default for a Member and are allowed for an Administrator.
  • effectiveMemberControlsrequiredWhat applies to the user now: nothing for a disabled user, everything for an Owner, the overrides alone for an Administrator, and the default with the overrides applied for a Member.
  • appliesbooleanrequiredWhether controls can limit the user's role: false for an Owner, who may always do everything.
  • follows_defaultbooleanrequiredWhether the user follows the library's default: true for a Member, false for an Administrator, whom only controls set for them alone limit (and only an Owner or the operator sets those).

UserCreatedResponse

Body of POST /api/users: the new user and, when one was asked for, the invite that lets them claim it.

  • okbooleanrequiredAlways true; the status code says the user was created.
  • userUserSummaryrequiredThe user as created.
  • claim_ticketstring or nullOpaque single-use claim ticket, when mint_invite was true.
  • invite_urlstring or nullInvite link that redeems the claim ticket, when one was minted.

UserDeletedResponse

Body of DELETE /api/users/{id}.

  • okbooleanrequiredAlways true; the status code says the user was deleted.

UserIdentitySummary

An external sign-in identity linked to a user.

  • providerstringrequiredIdentity-broker id (oidc:google, oidc:github, …).
  • external_user_idstringrequiredThe user's id at the provider.
  • labelstring or nullOperator-facing label for the identity, when one was set.

UserinfoResponse

Standard OIDC claims for GET /oidc/userinfo, limited to the token's scopes.

  • substringrequiredSubject: the Bookclerk users.id as a string.
  • namestring or nullDisplay name (profile scope), when the user has one.
  • preferred_usernamestring or nullLogin name (profile scope), when the user has one.
  • emailstring or nullEmail (email scope), when the user has one.
  • email_verifiedboolean or nullAlways true when email is present: Bookclerk trusts the address the Owner recorded.

UserIntegrationHint

Storefront / integration connection summary for admin user lists.

  • sourcestringrequiredContent-source or integration plugin id (audible, libro, …).
  • account_idstringrequiredStore or operator account id this row belongs to.
  • labelstring or nullOptional operator-facing account label.

UserListeningHint

Recent unfinished listening hint for admin user lists.

  • titlestring or nullTitle of the work being listened to, when the library knows it.
  • providerstringrequiredIntegration / storefront provider id.
  • last_listened_atstring (date-time)requiredRFC 3339 time of the last playback update.

UserListEntry

One user in the list GET /api/users returns: the summary plus presence, avatar and connection details for administration.

Includes every field of UserSummary.

  • onlinebooleanrequiredWhether the user has a portal session that has not expired.
  • last_active_atstring or nullRFC 3339 time of the most recent activity on an unexpired portal session, when the user is online.
  • last_seen_atstring or nullRFC 3339 time of the last authenticated portal activity; kept after the session ends.
  • has_avatarbooleanrequiredWhether an uploaded avatar is stored for the user.
  • avatar_sourcestringrequiredWhich avatar the user shows: auto, upload, gravatar, or an identity's picture.
  • gravatar_hashstring or nullSHA-256 digest of the user's email for Gravatar, when they have one.
  • sso_picturesarray of UserSsoPictureSummaryrequiredPictures the user's identity providers supplied.
  • listeningUserListeningHint or nullThe most recent unfinished listen within the last 30 minutes, if any.
  • integrationsarray of UserIntegrationHintrequiredStorefront and integration accounts linked to the user.
  • controlsMemberControlsrequiredWhat the user may do here (the member controls that apply to them; see GET /api/users/{id}/controls for the default and overrides).
  • identitiesarray of UserIdentitySummaryrequiredExternal sign-in identities linked to the user.

UserListResponse

Body of GET /api/users.

UserPasswordResetResponse

Body of POST /api/users/{id}/reset-password.

  • okbooleanrequiredAlways true; the status code says the password was cleared.
  • claim_ticketstringrequiredOpaque single-use claim ticket that lets the user set a new password.
  • revoked_sessionsinteger (int64)requiredHow many of the user's portal sessions were signed out. At least 0.

UserRole

First-party user role (owner | administrator | member).

Type: one of owner, administrator, member

UserScopeJson

A patron's scope as the scope routes report it.

  • user_idinteger (int64)requiredThe user (users.id).
  • scopePatronScoperequiredThe scope that applies to them: their own, or the library's default.
  • ownbooleanrequiredTrue when an Administrator gave them this scope; false when they follow the library's default.
  • appliesbooleanrequiredWhether the scope applies to the user's role: false for an Owner or Administrator, who always see the whole library.

UserSsoPictureSummary

A profile picture an identity provider supplied for a user.

  • identity_idinteger (int64)requiredThe linked identity the picture came from.
  • providerstringrequiredIdentity-broker id (oidc:google, oidc:github, …).
  • picture_urlstringrequiredHTTPS URL of the picture at the provider or its CDN.
  • picture_pathstring or nullSame-origin 128 px copy of picture_url for the web app to show, when this node can sign it.
  • last_used_atstring or nullRFC 3339 time the identity last signed in, when it has.

UserStatus

First-party user status.

Type: one of active, disabled

UserSummary

A first-party user as the Users routes return one: profile, role and status, never the password hash.

  • idinteger (int64)requiredSurrogate primary key assigned by the database.
  • roleUserRolerequiredFirst-party role.
  • statusUserStatusrequiredWhether the account may sign in.
  • display_namestring or nullHuman-readable name shown in the UI, when set.
  • login_namestring or nullLocal username for password login, when set.
  • emailstring or nullContact email, when set.
  • has_passwordbooleanrequiredWhether a local password is stored for the user.

WindowBooks

JSON body for GET /api/config/join/window.

  • librariesarray of LibraryLinkViewrequiredThe libraries this install is an active branch of.
  • cardsarray of ClerkLinkViewrequiredThe libraries this install holds an active library card for.
  • booksarray of WindowEntryViewrequiredTheir books, every one they list for a member, one entry per work, by title; each edition says whether it is this install's person's.

WindowEditionView

One edition in [WindowBooks], and the library that holds it.

  • library_idstringrequiredThe library (parent library id) that holds it.
  • owner_originstringrequiredThe library's origin.
  • storestringrequiredThe store's plain id.
  • marketplacestringrequiredLower-cased store marketplace; empty when the store has none.
  • product_idstringrequiredThe store's product id.
  • formatsarray of stringrequiredFormats that library has (audio, pdf); empty when unknown.
  • titlestringrequiredThe edition's title.
  • subtitlestring or nullSubtitle, when known.
  • authorsstring or nullAuthors as one display string, when known.
  • narratorsstring or nullNarrators as one display string, when known.
  • seriesstring or nullSeries name, when known.
  • series_indexstring or nullPosition in the series, when known.
  • length_minutesinteger (int64) or nullLength in minutes, when known.
  • yoursbooleanrequiredTrue when this install's person holds it there through a store account of their own; false for a book only other people there hold.
  • requestWindowRequestView or nullHow to ask the library for a copy of this edition (POST /api/config/clerk/request): set when this install holds a card for the library and the library holds no copy, while one of its branches lists it (from is branch) or one of its own store accounts holds it (from is library). Absent otherwise.

WindowEntryView

One work in [WindowBooks]: every edition its libraries hold for the person.

  • keystringrequiredA key that stays the same while the entry's editions do.
  • work_idstring or nullThe work of this install's own library the entry was placed on, by identifier; absent when none was.
  • editionsarray of WindowEditionViewrequiredThe editions, in library then store order; the first names the entry.

WindowRequestView

How a clerk asks a library for a copy of one edition in [WindowBooks].

  • work_idstringrequiredThe library's own work id to ask for.
  • fromClerkRequestFromrequiredWhere the copy would come from.

WishlistPurchaseHint

Snapshotted purchase link/price for a wishlist title.

  • sourcestringrequiredContent-source plugin id (audible, libro, …).
  • product_idstringrequiredStorefront product id (ASIN, ISBN, UUID, …).
  • titlestring or nullDisplay title of the work or edition.
  • urlstring or nullStorefront product or purchase URL when known.
  • price_centsinteger (int64) or nullObserved price in minor currency units, when known.
  • currencystring or nullISO 4217 currency code for price fields.
  • price_labelstring or nullStorefront-formatted price string for display.
  • list_price_centsinteger (int64) or nullList/MSRP price in minor units, when known.
  • list_price_labelstring or nullStorefront-formatted list price for display.
  • member_price_centsinteger (int64) or nullMember/subscriber price in minor units, when known.
  • member_price_labelstring or nullStorefront-formatted member price for display.

WishlistStoreEdition

Storefront edition key for wishlist / queue payloads.

  • sourcestringrequiredContent-source plugin id (audible, libro, …).
  • product_idstringrequiredStorefront product id (ASIN, ISBN, UUID, …).

WorkDetailJson

GET /api/library/works/{id} answer.

  • idstringrequiredWork id.
  • kindWorkKindJsonrequiredBook or podcast.
  • titlestringrequiredDisplay title.
  • descriptionstring or nullBlurb or synopsis (may contain HTML).
  • authorsarray of stringrequiredAuthors (hosts for a podcast), in billing order.
  • seriesstring or nullFirst series the work belongs to.
  • series_positionstring or nullPosition in series.
  • editionsarray of EditionJsonrequiredEditions; a show's episodes' editions included.
  • stateWorkStateJson or nullThe caller's own state; absent for the operator or when the caller recorded nothing.
  • can_edit_statebooleanrequiredWhether the caller can keep their own state for the work (PUT /api/library/works/{id}/state): false when the session has no library user, such as the operator token.

WorkKindJson

Book or podcast (works.kind).

Type: one of book, podcast

WorksPage

A page of GET /api/library/works.

  • worksarray of WorkSummaryJsonrequiredThe works, in the requested order.
  • next_cursorstring or nullPass as cursor for the next page; absent on the last page.

WorkSplitBody

POST /api/library/works/{id}/split body: the expressions to move.

  • expression_idsarray of stringrequiredThe expressions to move to the new work (1 to 12 distinct ids, each at most 64 bytes), from the work detail's editions (expression_id).

WorkStateEdit

PUT /api/library/works/{id}/state body: the fields of the caller's own state to change. A field left out keeps its stored value; null clears a rating or the tags.

  • is_finishedboolean or nullWhether the caller finished the work.
  • rating_overallnumber (double) or nullOverall rating, 0 to 5; null clears it.
  • rating_performancenumber (double) or nullNarration rating, 0 to 5; null clears it.
  • rating_storynumber (double) or nullStory rating, 0 to 5; null clears it.
  • tagsstring or nullTags separated by whitespace (at most 32, each at most 64 bytes, 1024 bytes in all); null or an empty string clears them.

WorkStateJson

The caller's own state for a work.

  • is_finishedbooleanrequiredWhether the caller finished the work.
  • rating_overallnumber (double) or nullOverall rating, 0 to 5.
  • rating_performancenumber (double) or nullNarration rating, 0 to 5.
  • rating_storynumber (double) or nullStory rating, 0 to 5.
  • tagsstring or nullThe caller's tags, as one serialized string.

WorkSummaryJson

One work in a page of GET /api/library/works.

  • idstringrequiredWork id.
  • kindWorkKindJsonrequiredBook or podcast.
  • titlestringrequiredDisplay title.
  • authorsstring or nullAuthors (hosts for a podcast), joined for display.
  • seriesstring or nullFirst series the work belongs to.
  • series_positionstring or nullPosition in series, as the store gave it.
  • cover_edition_idstring or nullThe edition whose cover the list shows.
  • cover_pathstring or nullSame-origin path of that cover, when it has one.
  • media_kindsarray of MediaKindJsonrequiredCarriers of the work's editions.
  • acquire_statusAcquireStatusrequiredThe furthest acquire state any edition reached.
  • edition_countinteger (int64)requiredHow many editions the work has. At least 0.
  • holding_countinteger (int64)requiredHow many holdings the work's listings have. At least 0.
  • added_atstringrequiredRFC 3339 time of the newest holding.
  • length_minutesinteger (int64) or nullRuntime in minutes of the longest held edition, when known. At least 0.
  • purchased_atstring or nullRFC 3339 time of the newest purchase a store reported.

WorkTag

One library tag on a work.

  • valuestringrequiredThe tag as written.
  • sourceWorkTagSourcerequiredWhere it came from.

WorkTagsBody

PUT /api/library/works/{id}/tags body: the tags an Administrator sets.

  • tagsarray of stringrequiredThe tags, replacing the ones set in Bookclerk (sidecar tags stay). Blanks and repeats, ignoring case, are dropped; at most 32 tags of at most 256 bytes each. At most 32 items.

WorkTagsJson

A work's library tags.

  • work_idstringrequiredThe work.
  • tagsarray of WorkTagrequiredEvery tag, by key, with where it came from.

WorkTagSource

Where a library tag came from (work_tags.source).

Type: one of admin, sidecar

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