Schemas
The request and response bodies of the web API, in alphabetical order.
Whether an expression is abridged.
Type: one of unknown, unabridged, abridged
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.
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 (idof 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 (inaccountwhen that is set); the edition's titles share its files.forcebooleanRe-download titles already acquired.pdf_onlybooleanFetch only each title's companion PDF.
Acquire / download state for a title.
Type: one of not_acquired, queued, downloading, acquired, error
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).
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.
POST /api/config/join/connections body.
library_idstringrequiredThe library (parent library id) to add the connections to.accountsarray ofAccountRefrequiredThe person's accounts to add; 1 to 64.
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.
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].
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]).
What a change does to one switch of one Administrator.
Type: one of on, off, default
What happens to a drop folder item once it has been ingested.
Type: one of move, delete, leave
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.
POST /api/config/library-consents/approve body.
library_idstringrequiredLibrary id.plugin_keystringrequiredCanonical plugin key.request_digeststringrequiredTherequest_digestof 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.
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.
An audio file of a book.
indexinteger (int64)requiredThe file's place in play order, from 1. At least 0.inostringrequiredThe file'sino([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 asmp4ormp3.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 ofChapterrequiredChapters 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 asaudio/mp4.
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.metadataFileMetadataor nullThe file's name, size and times.
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.
Target user shown while an operator session is impersonating.
user_idinteger (int64)requiredFirst-partyusers.idbeing impersonated.display_namestring or nullDisplay name of the impersonated user when the row exists.
JSON body for GET /api/auth/me.
authenticatedbooleanrequiredWhether the request resolved to an operator, portal, or impersonated session.rolestring or nulloperator,owner,administrator, ormember(legacy clients may still sendportal).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).impersonatingAuthMeImpersonatingor nullPresent when the operator is impersonating a User.portalPortalMeInfoor nullLinked portal identity when the caller is a portal (or impersonated) user.userAuthMeUseror nullFirst-party user when the session is linked to ausersrow.second_factorAuthSecondFactoror 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.
First-party user snapshot attached to /me when a users row is linked.
idinteger (int64)requiredFirst-partyusers.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 underfiles_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 ofAuthSsoPictureIdP-supplied pictures the user can pick.
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 ofLibraryItemor nullThe author's items, when asked for.seriesarray ofAuthorSeriesor nullThe author's series with their items, when asked for.
GET /api/libraries/{id}/authors without paging.
authorsarray ofAuthorrequiredThe authors.
A series of an author's, with the author's items in it.
idstringrequiredThe series id.namestringrequiredThe series name.itemsarray ofLibraryItemrequiredThe items, in series order.
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.
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 ofpicture_urlfor 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.
JSON body after the caller's avatar was stored or removed.
okbooleanrequiredAlwaystrueon this success path.has_avatarbooleanrequiredWhether an uploaded picture is stored now.avatar_sourcestring or nullPresent only after an upload, alwaysupload; absent after a removal (the stored source is then unchanged unless it wasupload).
How to handle acquire failures (BadBook setting).
Type: one of ask, abort, retry, ignore
POST /player/api/items/batch/get.
libraryItemIdsarray of stringrequiredThe items, at most 100.
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
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.
POST and PATCH /player/api/me/item/{id}/bookmark.
timenumber (double)requiredThe place, in seconds; onPATCH, which bookmark to rename.titlestring or nullThe bookmark's title.
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.
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).
GET /api/library/editions/{id}/bookmarks answer.
bookmarksarray ofBookmarkJsonrequiredThe caller's bookmarks in the edition, in timeline order.
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 ofAudioFileor nullThe audio files, when fetched expanded.chaptersarray ofChapteror nullThe chapters, when fetched expanded.tracksarray ofAudioTrackor nullThe tracks with their place in the book, when fetched expanded.
A book's metadata.
titlestringrequiredThe title.titleIgnorePrefixstringrequiredThe title for sorting.subtitlestring or nullThe subtitle, if any.authorsarray ofNamedRefrequiredThe 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 ofSeriesRefrequiredThe 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.
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.
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 becode.scopestring or nullMust be [BRANCH_SCOPE].statestring or nullEchoed on the redirect.code_challengestringrequiredPKCE S256 challenge.code_challenge_methodstring or nullMust beS256.branch_namestring or nullThe name the branch asks to join as.shared_branch_offerstring or null1when the joining install offers to join as a shared branch ([bookclerk_node_proto::SHARED_BRANCH_OFFER_PARAM]).
One branch a title is available through.
work_idstringrequiredThis library's work the branch supplies: thework_idto sendPOST /api/branch-requeststo 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.
POST /api/auth/branch-consent body.
Includes every field of BranchAuthorizeParams.
approvebooleanrequiredTrue to let the branch join; false to deny.connectionstring or nullbranch(default) orshared_branch.step_upStepUpor 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.
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 ofConsentConnectionrequiredThe user's store connections here, and whether each would travel to the branch if the user chooses to bring them.
The branch-enrollment switch.
enabledbooleanrequiredWhether branch nodes may enroll into this library.revisioninteger (int64) or nullStored revision;nullwhile the default (enabled) applies.
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 nullInself_signedmode, the fingerprint a joining operator confirms.branchesarray ofBranchViewrequiredEvery branch, newest first.
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.connectionsBroughtConnectionsViewor nullWhat became of the store connections the library's user chose to bring to this branch; left out when none came.replaced_cardReplacedCardor 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.
JSON body after PUT /api/config/branches.
enrollmentbooleanrequired"Let new branches join", as stored.
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.
The consent page's connection block when only a branch is offered.
choicebooleanrequiredAlwaysfalse.defaultstringrequiredAlwaysbranch.
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
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'savailable_through; absent ornullasks the first branch that lists the work.
POST /api/branch-requests answer.
job_idstringrequiredThe request's job (kindbranch_request), as/api/jobslists it.node_idstringrequiredThe branch the request went to.already_queuedbooleanrequiredtruewhen a request for this work to this branch was already waiting or being taken;job_idis that request.
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.
JSON body after detached branch titles were removed.
removedinteger (int64)requiredHow many title entries were removed. At least 0.
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;nulluntil its first catalog sync.include_branchesboolean or null"Include books from my own branches" as it last reported it;nulluntil 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.
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.
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) orfailed.
POST /api/config/join/callback body.
codestringThe code from the library.statestringThestateit came back with.errorstring or nullThe library'serror(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.
Query or form_post fields from the IdP callback.
codestring or nullAuthorization code to exchange; required unlesserroris set.statestring or nullCSRFstatethat must match thebookclerk_oidc_txcookie.errorstring or nullIdP-reported deny/error; redirects the browser to/?sso_error=denied.userstring or nullApple first-login name/email JSON (form_post only).
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);nullgives it an equal share of the machine. Required: a body without it is refused rather than read asnull. At least 0; at most 16.
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.falsekeeps them out of those answers; the owner's books are always listed.
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_listedbooleanrequiredtruefor an active Owner: an Owner's books are always listed, solistedhas no effect and the app shows that instead of the toggle.
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 whencover_urlis anhttpsURL. Append/128(thumbnail),/360(card) or/full, so a client can show covers without loadingcover_urlfrom another site.store_editionsarray ofStoreEditionrequiredPer-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 nullWhenSome(true), the edition is marked abridged by the storefront.is_explicitboolean or nullWhenSome(true), a storefront marks the edition explicit (adult) content;Nonewhen 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 ofPurchaseHintBuy / open-in-store links with optional member vs list pricing.available_througharray ofBranchAvailabilityBranches of this library that currently list this title, matched through a store listing the library already holds. Filled by the daemon after the search.
Paged catalog-search response.
itemsarray ofCatalogSearchHitrequiredOrdered 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 orNonewhen exhausted.sortstringrequiredSort field applied to the merged result set.sort_dirstringAscending or descending order for [Self::sort].
The library's channels.
channelsarray ofDestinationJsonrequiredOldest first.
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.
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_estimatedorweakfor a provider,chapters,tracksorunknownfor a store listing; empty otherwise.digeststringrequiredSHA-256 of the claimed list, 64 lower-case hex characters.chaptersarray ofEditionChapteror 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).
Every chapter claim for an edition.
claimsarray ofChapterClaimJsonrequiredThe claims, most recently changed first.
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 ofChapterEditEntryrequiredThe chapters, at most 2,000. At most 2000 items.
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.
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
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.
The kind of source a chapter claim came from (source_kind).
Type: one of person, outside_edit, processed, provider, listing, file, part_names
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 beforestart_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.
Body of PUT /api/me/notifications/choices/{type}.
enabledbooleanrequiredfalsekeeps 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 withenabled: true; delete the choice to return to the defaults. At most 32 items.
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 becode.scopestring or nullMust be [CLERK_SCOPE].statestring or nullEchoed on the redirect.code_challengestringrequiredPKCE S256 challenge.code_challenge_methodstring or nullMust beS256.clerk_namestring or nullThe name the clerk gives itself, shown on the consent page and in the user's session list.
POST /api/config/clerk/callback body.
codestringThe code from the library.statestringThestateit came back with.errorstring or nullThe library'serror(access_denied), when it sent one.
JSON body for GET /api/config/clerk.
cardsarray ofClerkLinkViewrequiredThe 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.
POST /api/auth/clerk-consent body.
Includes every field of ClerkAuthorizeParams.
approvebooleanrequiredTrue to let the clerk sign in; false to deny.
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.
POST /api/config/clerk/inspect body.
addressstringrequiredThe library's address (https://books.example.com,books.lan:8443).
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, orsigned_outonce the library ended the card.signed_in_atstringrequiredRFC 3339 sign-in time.
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'srequest.fromin the window books.node_idstring or nullThe library's branch to ask, from the work'savailable_throughthere; absent asks the first branch that lists it. Only withfrombranch.
Where a clerk's request asks the library to get a copy from.
Type: one of branch, library
JSON body for POST /api/config/clerk/request.
library_idstringrequiredThe library that took the request.
JSON body for POST /api/config/clerk/callback.
cardClerkLinkViewrequiredThe library this install now holds a card for.left_branchLeftBranchor nullSet when the card replaced this install's branch link to the library (a sign-in startedfrom_branch): the branch was left.
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.
POST /api/config/clerk/sign-out body.
library_idstringrequiredThe library id.
POST /api/config/clerk/start body.
addressstringThe library's address. Left out withfrom_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, soaddressandfingerprintare 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).
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.
POST /api/clerk/v1/token answer.
tokenstringrequiredThe session token, sent asAuthorization: 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.
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.
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.
One allowed value for a storefront config option.
idstringrequiredStored option value (for examplem4b).labelstringrequiredOperator-facing value label.
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) orwork_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).
One page of conflicts.
conflictsarray ofConflictJsonrequiredThe conflicts, by listing.next_cursorstring or nullPass ascursorfor the next page; absent on the last page.
What the consent page may offer: branch only, or a choice between branch and shared_branch for an Owner.
Type: BranchOnlyChoice or OwnerChoice
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 toactiveif the account row is missing.source_enabledbooleanrequiredWhether[sources.<id>] enabledis currently true (new connects blocked when false).brandBrandInfoor 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.
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.
JSON body for GET /connections.
connectionsarray ofConnectionInforequiredLinked store accounts the SPA may show or revoke.
How a joining install connects to a library.
Type: one of branch, shared_branch
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_typestringrequiredOAuthresponse_type; onlycodeis accepted.scopestring or nullSpace-separated scopes; defaults toopenid profilewhen 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 asplainand then rejected.consentstring or nulldenyaborts withaccess_denied; any other value proceeds to issue a code.
JSON body after a consent was approved or revoked.
consentRemoteConsentViewrequiredThe consent as stored now.
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.
The user a branch consent is for.
idinteger (int64)requiredusers.id.display_namestring or nullDisplay name, when set.
JSON body after a branch consent was answered.
redirectstringrequiredWhere to send the browser: the branch's callback with a code, or witherror=access_denied.
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].
Body for POST /api/library/convert.
copyOutputCopyrequiredThe copy to add: a format and a quality, asoutput.copieslists them.originalis 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 (idof 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.
The format of one copy of a book.
Type: one of m4b, mp3, mp3_chapters, original, opus
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)?)$
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.
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 ofStoreEditionKnown storefront editions to persist astitle_request_sources.purchase_hintsarray ofPurchaseHintOptional 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.
Provisioner body for creating a user and optional invite ticket.
rolestring or nullRole to assign when permitted (memberwhen 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.
Body for copying library rows between database plugins.
fromstring or nullSource plugin id. Defaults to the active[database].pluginbefore 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].pluginin config.toml after a successful copy.
The library's default Administrator switches as the switch routes report them.
controlsAdminControlsrequiredThe switches every Administrator follows unless set for them alone.
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.
The library's default scope as the scope routes report it.
scopePatronScoperequiredThe scope patrons without their own follow.
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].
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;nullwhen none is pending.
One delivery-log row.
idstringrequiredDelivery id.notification_idstringrequiredThe notification.notification_typestringrequiredIts type.titlestringrequiredIts title.destination_idstringrequiredThe destination.plugin_instance_idstringrequiredThe notifier instance.statestringrequiredpending,delivered,failedordropped.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).
One page of the delivery log.
deliveriesarray ofDeliveryJsonrequiredNewest first.next_cursorstring or nullPass ascursorfor the next page;nullon the last page, where paging stops.
PUT /api/config/plugin-instances/{id}/deployments/{node_id} 409 body: the two conflicts a deployment write can hit.
Type: RevisionConflict or ErrorMessage
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
Which books one destination takes.
rulesarray ofFilterRuleFilter rules, at most 64. Empty means the destination takes every book. At most 64 items.
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'score.destinationdocument;0when none was written, so the destination takes every book.filterDestinationFilterrequiredThe filter; no rules take every book.
A destination as administrators and its owner see it. The address is never returned: it may hold secrets.
idstringrequiredDestination id.kindDestinationKindrequiredchannel(the library's) orpersonal(a patron's).plugin_instance_idstringrequiredThe notifier instance that carries it.labelstringrequiredName shown in pickers.failure_countinteger (int64)requiredDeliveries in a row that endedfailed, 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);nullwhile active.paused_reasonstring or nullWhy it was paused.created_atstringrequiredWhen it was made (RFC 3339).
Whether a destination is a library channel or one patron's address.
Type: one of channel, personal
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.
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.
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.reportStoredReportViewor nullThe stored report, or null once deleted.issuesarray ofReportIssueViewrequiredIssues tracking it, the tracking issue first.fixReportFixViewor nullThe tracking issue's fix, or null.
Body of GET /api/diagnostics/reports.
reportsarray ofDiagnosticsReportViewrequiredSent reports, newest first (the last 200 are kept).
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.
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 meansfalse.
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.
Full Discover page payload: ordered shelves of personalized candidates.
shelvesarray ofDiscoverShelfrequiredOrdered horizontal shelves that make up the Discover page.shelf_kindsarray ofShelfKindInfoCatalog of shelf kinds for ignore prefs (emptydisabled_shelves= all on).stateFeedStateor 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 whilestateispreparing.
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 ofRecommendationrequiredOrdered collection of child entries for this response.
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 (ownorhousehold), 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.
OIDC discovery document served at /.well-known/openid-configuration.
issuerstringrequiredIssuer origin used asissin minted JWTs (public_originor 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 stringrequiredSupportedresponse_typevalues; this server only issuescode.grant_types_supportedarray of stringrequiredSupported token grants:authorization_codeandrefresh_token.code_challenge_methods_supportedarray of stringrequiredPKCE methods; only S256 is accepted (plainis rejected).scopes_supportedarray of stringrequiredScopes advertised to clients (openid,profile, andemail).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) orclient_secret_post.
Operator JSON for one domain_events row.
idstringrequiredEvent id.eventTypestringrequiredEvent type (book_acquired).schemaVersioninteger (int64)requiredPayload schema version.dispatchStatestringrequiredpendingordispatched.accountIdstringrequiredTenant / account id.dedupKeystringrequiredProducer idempotency key.createdAtstringrequiredRFC 3339 insert time.queueNamestringrequiredQueue the row belongs to (core.eventsfor 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.
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.eventsorcore.output).replayedbooleanrequiredAlwaystrue: the write was a replay.revisioninteger (int64)requiredRevision the earlier write produced.
Where a configuration domain document lives and which revision it is at: the metadata every domain response carries before its settings.
namespacestringrequiredDomain namespace (core.eventsorcore.output).scope_typestringrequiredScope type:libraryfor a shared document,nodefor one node's.scope_idstringrequiredScope id:singletonfor 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 asexpected_revision.updated_atstringrequiredRFC 3339 time of the last write.updated_bystringrequiredAudit identity of the last writer.
POST /api/download-requests body: the work to download.
work_idstringrequiredThis library's work id, as its window books and search name it.
POST /api/download-requests answer.
job_idstringrequiredThe acquire job, as/api/jobslists it.edition_idstringrequiredThe edition being downloaded.already_queuedbooleanrequiredtruewhen a download of that edition was already waiting or running;job_idis that download.
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.
The chapters an edition plays.
edition_idstringrequiredThe edition.chaptersarray ofEditionChapterrequiredThe chapters in pre-order, starts never decreasing; empty when the edition has none or an Administrator cleared them.source_kindChapterSourceKindor 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.
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 ofListingJsonrequiredThe edition's store listings.
JSON body after a successful Owner elevation.
okbooleanrequiredAlwaystrueon this success path.elevatedbooleanrequiredAlwaystrue: the cookie the response sets is an elevated operator session.expires_in_secsinteger (int64)requiredSeconds until the elevated session expires. At least 0.
JSON body for Owner password re-auth before issuing an elevated operator cookie.
passwordstringrequiredOwner account password (re-authentication).
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.
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.
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.
First TOTP code that confirms the pending secret.
codestringrequiredSix-digit code from the authenticator app.
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 (operatororuser:<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, orexpiredright now.
On what terms a holder has a listing.
Type: one of purchase, plus, loan, free, own
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
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.
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.
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.
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 (networktoday).resumePendingbooleanrequiredNext claim should resume rather than increment attempt.hasCheckpointbooleanrequiredTrue when a suspend checkpoint is stored.queueNamestringrequiredQueue of the parent event.
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 intodead_letter.dispatch_latency_ms_avginteger (int64) or nullAverage first-dispatch latency in milliseconds, when sampled.handler_latency_ms_avginteger (int64) or nullAverageonEventhandler duration in milliseconds, when sampled.
Body of PUT /api/config/domains/core.events: the settings after the
change, or a replay note.
Type: EventsDomainResponse or DomainReplayed
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.
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.
Whether a patron sees books marked as explicit (adult) content.
Type: one of allow, hide
How an expression realises its work (expressions.kind).
Type: one of text, narration, dramatisation, graphic, original_audio
One value of a facet.
valuestringrequiredThe value, asvalueofGET /api/library/workstakes it.worksinteger (int64)requiredHow many held works have it. At least 0.
A page of GET /api/library/works/facets/{facet}.
valuesarray ofFacetValueJsonrequiredThe values, in order of their lower-cased spelling.next_cursorstring or nullPass ascursorfor the next page; absent on the last page.
How current a stored Discover feed is.
Type: one of ready, refreshing, preparing
One labelled value.
namestringrequiredLabel.valuestringrequiredValue.
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.
Which timestamp to apply after acquire (CreationTime / LastWriteTime).
Type: one of now, purchased, published
The values an app offers as filters.
authorsarray ofNamedRefrequiredAuthors with at least one item.genresarray of stringrequiredGenres.tagsarray of stringrequiredTags: none are shown.seriesarray ofNamedRefrequiredSeries 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.
Whether a [FilterRule] lets matching books in or keeps them out.
Type: one of include, exclude
The book field a [FilterRule] matches one value of.
Type: one of patron, storefront, account, media_kind, format, quality
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 forpatron,bookorpodcastformedia_kind, a copy format forformat, a copy quality forquality, otherwise 1 to 128 bytes of text.effectFilterEffectrequiredInclude or exclude.
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.
Liveness payload for unauthenticated GET /health.
statusstringrequiredAlwaysokwhen the process can serve HTTP.
Who holds a listing.
Type: object
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.
JSON body naming the first-party user to impersonate.
user_idinteger (int64)requiredTargetusers.idto impersonate.
JSON body after an operator session started impersonating a user.
okbooleanrequiredAlwaystrueon this success path.impersonatingAuthMeImpersonatingrequiredThe user the session now acts as.
One inbox entry.
idstringrequiredNotification id.notification_typestringrequiredType id.severitystringrequiredinfo,warningorcritical.titlestringrequiredTitle.textstringrequiredPlain-text body.link_pathstring or nullPath inside the library it links to.fieldsarray ofFieldJsonrequiredLabelled values.created_atstringrequiredWhen it arrived (RFC 3339).read_atstring or nullWhen the patron read it (RFC 3339);nullwhile unread.
One page of the inbox.
entriesarray ofInboxEntryJsonrequiredNewest first.unreadinteger (int64)requiredUnread entries in the whole inbox. At least 0.next_cursorstring or nullPass ascursorfor the next page;nullon the last page, where paging stops.
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.exposureIngressExposureor 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.
What public traffic from the ingress may reach.
Type: one of branches, library
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;nullwhen 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_originwhen set, else the ingress origin while the instance runs.operator_overridebooleanrequiredTrue whenintegrations.public_origininconfig.tomloverrides the ingress origin.blockedstring or nullWhy ingress can't run now (no Owner yet, or operator auth off);nullwhen it can.
POST /api/config/join/inspect body.
addressstringrequiredThe library's address (https://owner.example,owner.lan:8443).
JSON body for POST /api/config/join/inspect.
libraryInspectedLibraryViewrequiredWhat the library said about itself.
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 confirmfingerprintbefore joining.
GET /api/config/plugins/{key} body: the plugin and its pinned schema.
Includes every field of InstalledPluginSummary.
schemaPinnedSchemaSummaryor nullThe pinned settings schema;nulluntil a node pins one.
GET /api/config/plugins body.
pluginsarray ofInstalledPluginSummaryrequiredEvery plugin with at least one installed version, by key.
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;nullwithout versions.active_versionstring or nullActive version;nullwhen the plugin is installed but not activated.revisioninteger (int64) or nullCompare-and-swap revision of the active-version pointer;nullwhen nothing is active.versionsarray ofPluginVersionSummaryrequiredEvery installed version, newest first.
Instance document as the API renders it: values and secret names only.
revisioninteger (int64)requiredCompare-and-swap revision.settingsmap of string toSettingValuerequiredScalar settings the operator wrote.secret_refsarray ofInstanceSecretRefV1requiredSecret refs; ciphertext stays inencrypted_secrets.
A name in encrypted_secrets. The ciphertext is not part of the document.
keystringrequiredKey in theSECRETSobject delivered to the guest.namestringrequiredencrypted_secrets.namefor this instance.
Who holds the books a drop folder ingests.
Type: one of owner, subfolder
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'score.intakedocument;0when none was written, so the instance is a destination.intakeIntakeSettingsor nullThe drop folder's settings;nullwhen the instance is a destination.
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 (defaultmove).attribute_toIntakeAttributionrequiredWho holds the ingested books (defaultowner).patroninteger (int64) or nullThe user id that holds every book inownermode; required there and refused insubfoldermode. 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 nullWithafter_ingest = move, delete_importedday folders older than this many days, 1 to 3,650; absent keeps them. At least 1; at most 3650.
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 (defaultmove).attribute_toIntakeAttributionWho holds the ingested books (defaultowner).patroninteger (int64) or nullThe user id that holds every book inownermode; required there and refused insubfoldermode. 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 nullWithafter_ingest = move, delete_importedday folders older than this many days, 1 to 3,650; absent keeps them. At least 1; at most 3650.
JSON body for POST /login/integration (provider credential login).
providerstringrequiredIntegration plugin id (must be enabled in config).usernamestringrequiredProvider login name forwarded toauthenticate_user.passwordstringrequiredProvider password; never logged.
Optional body for POST /integrations/{id}/scan.
forceboolean or nullWhen true, the integration rescans even if it considers itself current.
POST /api/config/join/invite body.
linkstringrequiredThe whole branch invite (https://<library>/enroll#bcn1...).
Seconds listened to one item.
idstringrequiredThe item id.timeListeningnumber (double)requiredSeconds listened.mediaMetadataBookMetadatarequiredThe item's metadata.
A page of items: GET /api/libraries/{id}/items and the like.
resultsarray ofLibraryItemrequiredThe 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.
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.
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
Lifecycle state of a durable job row.
Type: one of pending, running, succeeded, failed, cancelled
One job's state in [Body::JobStatuses].
idstringrequiredJob id.kindstringrequiredJob kind (scan,acquire, ...).statestringrequiredpending,running,succeeded,failed, orcancelled.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.
JSON body once a join completed: as a branch, or as a shared branch.
Type: BranchJoined or SharedBranchJoined
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
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.
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 ofLibraryLinkViewrequiredEvery library this install is a branch of, with whether its client runs.
LAME encoder tuning (classic Lame* settings).
targetstringLameTarget:quality,bitrate,constant, etc. Default"quality".vbr_qualityinteger (int32)LameVBRQuality(0–9, lower = better). At least 0; default2.bitrate_kbpsinteger (int32)LameBitratein kbps when target is bitrate/constant. At least 0; default128.modestringLameMode:default,mono,stereo. Default"default".downsample_monobooleanLameDownsampleMono. Defaultfalse.constant_bitratebooleanLameConstantBitrate. Defaultfalse.
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.
POST /api/config/join/leave body.
library_idstringrequiredThe library (parent library id) to leave.
JSON body once leaving a library started.
libraryLibraryLinkViewrequiredThe link, nowleft.owner_notifiedbooleanrequiredWhether the library was told (otherwise it notices the missed heartbeats).
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.
GET /api/libraries.
librariesarray ofLibraryrequiredThe libraries the patron may open.
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 (audiobookshelfnames 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.
GET /player/api/libraries/{id} answer: the library, with its filter
values when asked for (include=filterdata).
Type: LibraryWithFilterData or Library
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, sokidsmatcheskids/…but notkidsbooks/…. At most 8 items.
The library's collections: the core.collections document and the
body of PUT /api/library/collections.
collectionsarray ofLibraryCollectionrequiredThe collections, at most 32, in the order shown. At most 32 items.
JSON body for GET /api/config/library-consents.
librariesarray ofLibraryLinkViewrequiredEvery library this install is a branch of.consentsarray ofRemoteConsentViewrequiredEvery plugin request from those libraries, pending or answered.
A file of an item, in the expanded item's libraryFiles.
inostringrequiredThe file'sino([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.fileTypestringrequiredAlwaysaudio.
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 ofLibraryFileor nullThe item's files, when the item is fetched expanded.userMediaProgressMediaProgressor 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": [...] }: in-progress items and batch reads.
libraryItemsarray ofLibraryItemrequiredThe items.
POST /api/config/libraries/{library_id}/jobs body.
job_idsarray of stringrequiredJob ids on the library.
JSON body for POST /api/config/libraries/{library_id}/jobs.
jobsarray ofJobStatusEntryrequiredThe owner's state of each job this install may see, in request order.
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, orleft.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;nullgives 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, withinmax_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.
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.
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.
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.
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.
GET /api/library-status body.
libraryLibrarySummaryrequiredLibrary-wide counters.node_idstringrequiredId of the node that answered.nodesarray ofNodeViewrequiredThe nodes the caller administers.capabilitiesNodeCapabilitiesrequiredWhat the caller may do with them.
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 ofLeaseViewrequiredEvery library lease, held or expired.schemaSchemaStateViewrequiredThe database schema against this binary.
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.
JSON body for GET /api/auth/oidc/identities.
identitiesarray ofLinkedIdentityrequiredEvery sign-in identity linked to the caller's user, the local one included.
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.
GET /api/me/listening-stats.
totalTimenumber (double)requiredSeconds listened in all.itemsmap of string toItemListeningrequiredSeconds listened per item, by item id.daysmap of string to number (double)requiredSeconds listened per day, byYYYY-MM-DD.dayOfWeekmap of string to number (double)requiredSeconds listened per weekday, by English weekday name.todaynumber (double)requiredSeconds listened today.recentSessionsarray ofPlaybackSessionrequiredThe most recent sessions.
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 ofHoldingJsonrequiredThe listing's holdings.
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.
POST /player/api/session/local-all: several offline sessions.
sessionsarray ofLocalSessionBodyrequiredThe sessions; each is answered on its own.
Login-name or email used to start a discoverable-less passkey login.
loginstringrequiredLogin name or email looked up before issuing an authentication challenge.
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.
JSON body for POST /api/auth/login (operator token).
tokenstringrequiredOperator token from the client; compared in constant time and never persisted.
JSON body after a successful operator token login.
okbooleanrequiredAlwaystrueon this success path.rolestringrequiredIssued role (operatorfor token login).default_viewstringrequiredPost-login SPA landing view from operator preferences (discoveron lookup failure).
JSON body of a 429 after too many failed sign-in attempts from one client.
errorstringrequiredAlwaystoo_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 asRetry-After. At least 0.
TOTP code plus the challenge id from password login.
challenge_idstringrequiredServer-issued challenge id (5-minute TTL, single use).codestringrequiredSix-digit authenticator code.
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.
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 asunrecorded.recorded_atstring or nullWhen that was recorded (RFC 3339, UTC); absent whenunrecorded.needs_recovery_copybooleanrequiredWhether the web app should remind the operator to save a copy: the key is in the OS keychain or sealed withsystemd-creds(so backups of the files directory don't include it) and no copy was recorded as saved.
Where this install keeps its key.
Type: one of file, password_file, keychain, systemd_creds
The codecs, containers and encodings this build's media worker handles.
decodesarray of stringrequiredAudio codecs the worker decodes (aac,alac,flac,mp3,opus,vorbis, andeac3in 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 ofOutputEncodingJsonrequiredEncodings the worker writes.
Carrier of an edition (editions.media_kind).
Type: one of audio, ebook, print
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.mediaItemTypestringrequiredAlwaysbook.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.
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]).
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".
JSON body for GET /me.
providerstringrequiredIdentity provider id (localor 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.
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
The host-wide second-factor policy.
require_second_factorbooleanrequiredWhether every password sign-in must be followed by a passkey or authenticator code.
PUT body for the host-wide second-factor policy.
require_second_factorbooleanrequiredWhen true, password login requires TOTP or the user must use a passkey.
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
Behavior when some output destinations already have a title and others do not.
Type: one of sync_missing, refetch_missing, refetch_all
An id and a name.
idstringrequiredThe entity's id.namestringrequiredIts display name.
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
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.
GET /api/libraries/{id}/narrators.
narratorsarray ofNarratorrequiredThe narrators.
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.
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.
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'saddress_fieldsdescribe 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.
POST /api/auth/player-passwords body.
labelstringrequiredA name for it, such as the app or device (1 to 64 bytes once trimmed).
POST /api/auth/player-passwords answer.
passwordPlayerPasswordJsonrequiredThe stored password.secretstringrequiredThe password itself, shown this once: the library keeps only its digest.
What the caller may do on the nodes it sees.
scopeNodeScoperequiredallfor the operator,ownedfor 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.
JSON body after a host's credential was revoked.
credentialNodeCredentialViewrequiredThe credential, withrevoked_atset (revoking twice keeps the first time).
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.
JSON body after an enrollment link was minted.
linkEnrollmentLinkViewrequiredThe link's record.urlstringrequiredThe full enrollment URL with the secret, shown once.
JSON body after an enrollment link was revoked.
linkEnrollmentLinkViewrequiredThe link, withrevoked_atset.
JSON body for GET /api/config/node-invites.
linksarray ofEnrollmentLinkViewrequiredThe links the caller may see, newest first.
How a node joined the library.
Type: one of shared, branch
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;nullwhen cleared.
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;nullwhen the user has neither.roleUserRolerequiredThe owner's role.
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
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.
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'score.cachebudget (16 MiB to 1 TiB). Absent means the library budget applies. At least 16777216; at most 1099511627776.
Which nodes a listing shows the caller.
Type: one of all, owned
GET /api/config/nodes body.
node_idstringrequiredId of the node that answered.nodesarray ofNodeViewrequiredThe nodes the caller administers.capabilitiesNodeCapabilitiesrequiredWhat the caller may do with them.
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;Nonefrom 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;nullfor a local branch and for a shared node. A branch with one is a remote branch of this library.
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.statusNodeStatusor nullThe latest heartbeat;nullbefore the first one.this_nodebooleanrequiredTrue for the node that answered the request.kindNodeKindrequiredsharedfor a node sharing this library's database,branchfor 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) orlocal_branch(a branch with none).owner_user_idinteger (int64) or nullUser id of the node's owner;nullwhen unassigned.share_booksboolean or nullA branch's sharing setting, as it last reported it;nullfor a shared node.include_branchesboolean or nullA branch's include-branches setting, as it last reported it;nullfor a shared node.ownerNodeOwnerSummaryor nullThe owner, when the node has one and the user still exists.
Everything the routing screens pick from.
typesarray ofNotificationTypeJsonrequiredHost types first, then plugin types by id.notifiersarray ofNotifierJsonrequiredNotifier instances installed on this server.
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) orpatron(offered to patrons).severitystringrequiredDefault severity:info,warningorcritical.titlestringrequiredTitle shown in the routing matrix and on each notification.sourcestringrequiredThe plugin that raises it; empty for a host type.
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 ofAddressFieldJsonrequiredWhat a patron enters for a personal destination.
POST /api/node/v1/enroll/oauth answer.
library_idstringrequiredThe library id.node_idstringrequiredThe node id recorded for the joining install.connectionConnectionTypeThe connection type recorded (branchwhen 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.
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.
JSON body of an OAuth start: the browser login URL to open.
urlstringrequiredThe store's login page, bound to this sign-in.
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.
Body of PUT /api/notifications/offers/{type}.
offersarray ofOfferJsonrequiredThe type's offers, replacing the old ones; at most 32. Empty keeps the type in patrons' inboxes only. At most 32 items.
Every patron offer, by type.
offersmap of string to array ofOfferJsonrequiredType id to its offers.
JSON body for GET /api/auth/oidc/clients.
clientsarray ofOidcClientViewrequiredEvery registered client, without secrets.
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 asconfidential: a secret hash is stored.enabledbooleanrequiredWhether the authorize and token endpoints accept this client.plugin_idstring or nullPlugin that provides this client, ornullfor 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.
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.
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 ofOidcProviderPutFull replacement list of IdPs (omitted secrets keep the previous generation).public_originstring or nullintegrations.public_origin. Omit to leave unchanged; empty string clears.
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 nullConfiguredintegrations.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 tolocalhost).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/callbackderived from the effective issuer origin.providersarray ofOidcProviderViewrequiredConfigured IdPs with presence flags instead of secret material.
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 whenpresetis 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 togroups).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.
JSON body for GET /api/auth/oidc/providers.
enabledbooleanrequiredWhether the OIDC broker is switched on at all.providersarray ofSigninOidcProviderrequiredProviders enabled in configuration, in configuration order (empty while the broker is off).
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 (memberby default).role_claimstringrequiredClaim name read from id_token/userinfo for role mapping (groupsby 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, ornone.
Acknowledgement body ({"ok": true}) for actions with nothing else to report.
okbooleanrequiredAlwaystrue: a failure answers with an error status instead.
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
Body of the 500 from GET /api/openapi-3.0.json when the 3.1
document could not be restated as 3.0.3.
errorstringrequiredAlwaysopenapi_v30_unavailable.messagestringrequiredWhat to do: the daemon log names the form that could not be restated.
POST /api/playback/sessions body.
edition_idstringrequiredThe edition to play (1 to 128 bytes).playerPlayerKindParamWhat kind of player asks;webwhen left out.player_namestringThe player's own name, shown in listening history. Control characters are dropped and at most 64 bytes are kept.
An operator session as listed by GET /api/auth/sessions.
idinteger (int64)requiredSession id, forDELETE /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.
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.
errorstringrequiredAlwaysorigin_mismatch.detailstringrequiredWhy, naming the address to join with instead.originstringrequiredThe library's canonical origin, to join with instead.
One copy of every acquired book: a format at a quality.
formatCopyFormatrequiredThe copy's format.qualityCopyQualityrequiredThe copy's quality.
Body of PUT /api/config/domains/core.output: the settings after the
change, or a replay note.
Type: OutputDomainResponse or DomainReplayed
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).
One encoding the media worker writes.
namestringrequiredThe output format id that selects it (m4b,mp3oropus).advancedbooleanrequiredTrue when settings offer it only under their advanced options, because fewer players open it than M4B and MP3.
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
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 ofOutputCopyFurther 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.wvdpath; 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/offdisables 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.cuesidecar.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, ornative).chapter_layoutstringrequiredPreferred chapter API layout (tree,flat, orboth).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 forsplit_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 ofReplacementRulerequiredExplicit find/replace rules for path segments.max_filename_lengthinteger (int32)requiredMax length per path segment (0disables truncation). At least 0.
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.
manage_membersAdminSwitchChoiceor nullChange to [AdminControl::ManageMembers].set_patron_limitsAdminSwitchChoiceor nullChange to [AdminControl::SetPatronLimits].library_scanAdminSwitchChoiceor nullChange to [AdminControl::LibraryScan].run_jobsAdminSwitchChoiceor nullChange to [AdminControl::RunJobs].fix_catalogAdminSwitchChoiceor nullChange to [AdminControl::FixCatalog].invite_branchesAdminSwitchChoiceor nullChange to [AdminControl::InviteBranches].approve_requestsAdminSwitchChoiceor nullChange to [AdminControl::ApproveRequests].
JSON body after the first Owner was created.
okbooleanrequiredAlwaystrueon this success path.user_idinteger (int64)requiredusers.idof 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.
The consent page's connection block for an Owner, who may pick shared branch.
choicebooleanrequiredAlwaystrue.defaultstringrequiredAlwaysbranch.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).
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 nullInself_signedmode: 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.
The mode of a [PaceRequestBody], for the API reference.
Type: one of default, custom, unlimited
Request body of the pace route, for the API reference (the route reads
the raw bytes with bookclerk_library::pacing::parse_pace_request).
modePaceModeSchemaor nulldefault,customorunlimited. Leave it out to only end the cool-down (thenclear_cooldownmust betrue) and keep the stored pace.downloads_per_dayinteger (int32) or nullCustom downloads per rolling 24 hours;customonly. At least 1; at most 10000.min_gap_secondsinteger (int32) or nullCustom seconds between downloads;customonly. At least 0; at most 86400.clear_cooldownboolean or nullAlso end a cool-down the store asked for.
How fast Bookclerk downloads from one store account when it starts the downloads itself, for the Accounts page.
modestringrequireddefault(the store's pace),customorunlimited.downloads_per_dayinteger (int32) or nullDownloads allowed in any rolling 24 hours now in force;nullfor 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;nullwhen 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;nullwhen its plugin is not deployed here. At least 0.custom_downloads_per_dayinteger (int32) or nullCustom daily budget the operator set, whenmodeiscustom. At least 0.custom_min_gap_secondsinteger (int32) or nullCustom gap the operator set, whenmodeiscustom. 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);nullwhen one may start now.
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.
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.
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.
JSON body for GET /api/auth/passkeys.
passkeysarray ofPasskeySummaryrequiredThe caller's passkeys, oldest first.
One stored passkey.
idinteger (int64)requiredRow id, forDELETE /api/auth/passkeys/{id}.credential_idstringrequiredBase64url credential id the authenticator reports.namestringrequiredLabel chosen at registration (Passkeywhen none was given).
JSON body for password-store connect (email + password).
emailstringrequiredStore account email / username.passwordstringrequiredStore account password; never logged.
JSON body of a successful POST /api/auth/password.
Type: PortalSessionIssued or TotpChallenge
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.
JSON body after a password was set.
okbooleanrequiredAlwaystrueon this success path.revoked_sessionsinteger (int64)requiredPortal sessions of that user revoked by the change (the caller signs in again). At least 0.
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.
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 +nullclears 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).
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, orsso:{id}).
Body for PATCH /api/settings.
settingsarray ofSettingsUpdaterequiredKey/value pairs to validate, persist, and reload.expected_output_revisioninteger (int64) or nullcore.outputdocument revision the client read (output_revisioninGET /api/settings). When set and stale, anoutput.*update is rejected with 409.
PATCH /api/users/{id}/admin-controls body.
changesOverrideSwitchChangesrequiredThe switches to change for this Administrator:onoroffsets the switch for them alone,defaultfollows 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.
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.
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
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.
Which part of the library a patron sees.
rulesarray ofScopeRuleVisibility 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 meansallow.
A patron's notification settings.
typesarray ofPatronTypeJsonrequiredPatron types administrators offer a notifier for.destinationsarray ofDestinationJsonrequiredThe patron's own destinations.notifiersarray ofNotifierJsonrequiredNotifiers the patron can add a destination on.
One patron type and what the patron chose for it.
idstringrequiredType id.titlestringrequiredTitle.offersarray ofPatronOfferJsonrequiredNotifiers offered for it.chosenbooleanrequiredWhether the patron made a choice; without one the defaults apply.enabledbooleanrequiredThe patron's preference, not a delivery result:falsekeeps the type in the inbox only.truewhen 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 checkoffersbefore showing one as eligible or sending the list back.
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.
Body of PUT /api/library/listings/{id}/pin.
edition_idstringrequiredThe edition the listing sells.
GET /ping: { "success": true }.
successbooleanrequiredAlways true.
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.
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 ofSettingSpecrequiredDeclared settings.
Scheduler placement of one instance: the operator's intent and the last pass's result.
replicasinteger orallrequiredA 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.
POST /api/library/scan and POST /api/library/acquire 409 body: the two conflicts a plan can hit.
Type: ScanPlanResponse or ActionResponse
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 ofTrackJsonrequiredThe tracks in play order; empty when not playable. A session's answer adds the stream paths.progressProgressJsonor nullThe caller's progress; null before they first play it.bookmarksarray ofBookmarkJsonrequiredThe caller's bookmarks, in timeline order.chaptersarray ofChapterSpanrequiredThe chapters the edition plays, in pre-order, each ending where the next starts and the last atduration_ms; empty when it has none.
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 ofChapterrequiredThe 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-DDin 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 ofAudioTrackrequiredThe tracks to play, in order.libraryItemLibraryItemor nullThe item, expanded.
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 ornullkeeps the stored one. At least 0.
POST /player/api/items/{id}/play: what an app asks for when it starts
playing. Tracks always play directly, whatever it asks.
deviceInfoDeviceInfoBodyor 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.
POST /api/auth/player-consent body.
Includes every field of PlayerConsentParams.
approvebooleanrequiredTrue to let the app sign in; false to decline.
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.
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 asapp.code_challengestringrequiredThe PKCE S256 challenge.statestring or nullThe app's state.
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.
The kind of first-party player that opens a session. Outside player apps open theirs through the player API.
Type: one of web, desktop
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.
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.
GET /api/auth/player-passwords answer.
passwordsarray ofPlayerPasswordJsonrequiredThe patron's player passwords, newest first.
One downloadable artifact of an installed version, as the API renders it.
targetstringrequiredBookclerk target (linux-x64-gnu, …;anyfor workerd packages).urlstringrequiredWhere nodes fetch the archive:https:,file:, orblob:sha256:<hex>.archive_sha256stringrequiredLowercase hex SHA-256 of the archive bytes.payload_root_sha256stringrequiredPayload-root digest of the extracted plugin tree.
Body for POST /api/plugins/{id}/consent.
approvebooleanrequiredMust be true; a false value is rejected with 400.grantPluginGrantOverrideor nullOptional operator overrides applied on top of the manifest request.setting_destinationsarray ofPluginSettingDestinationApprovalSetting destinations to approve, from the response'ssetting_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.
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.
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.
The difference between a plugin's request and its stored grant.
linesarray of stringrequiredOperator-facing lines naming every capability awaiting consent, the same linesbookclerk plugins infoandbookclerk plugins approveprint; empty when the stored grant covers the request.domainsarray of stringrequiredFetch host patterns the request adds (*is any public host).tcparray ofTcpGrantViewrequiredTCPhost:portsthe request adds, narrowed to the new ports.addressCidrsarray of stringrequiredCIDRs the request adds.allowUndeclaredPublicRedirectsbooleanrequiredWhether the request newly asks to follow undeclared public redirects.
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 (nativeorworkerd) — 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.existingPluginGrantViewor nullPreviously approved grant, when one is stored.pendingPluginConsentPendingor 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.brandPluginConsentBrandor nullOptional portal or manifest branding for the dialog.limitsPluginConsentLimitsrequiredHost-capped resource defaults (workerd budgets + shared disk). Always set.host_user_agentstringrequiredTheUser-Agentthis host sends for the plugin's requests, except to the request'sownUserAgentHosts.setting_destinationsarray ofPluginSettingDestinationViewrequiredThe 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. Apendingrow is not reachable until it is approved;coveredis false while one is.
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.
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/absentfrom an operator,placed/unplacedfrom 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.
Operator-supplied grant fields that replace matching request values.
networkModestring or nullOverride egress mode (denyoroutbound) when set.domainsarray of string or nullOverride approved hostnames when set.tcparray ofTcpGrantViewor 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 ownUser-Agentwhen 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.
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 (denyoroutbound).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 ofTcpGrantViewrequiredEffective raw TCP grants.operatorAddedTcparray ofTcpGrantViewrequiredOperator-added TCP grants.operatorDeniedTcparray ofTcpGrantViewrequiredOperator-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 ownUser-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], fromplugin.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.
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.
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 toSettingValuerequiredScalar settings now stored.secret_refsarray ofInstanceSecretRefV1requiredSecret refs now stored, the newly sealed secrets included.
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 toSettingValuerequiredScalar settings the operator wrote.secret_refsarray ofInstanceSecretRefV1requiredSecret refs; ciphertext stays inencrypted_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 ofSettingSpecrequiredDeclared settings from the pinned schema; empty when there is none.
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;nullfor a library-wide instance.
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.
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 ofPluginInstanceViewrequiredEvery plugin instance in the library.
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 ofSettingSpecrequiredDeclared settings from the pinned schema.configInstanceConfigViewor nullCurrent document, when the instance has one.deploymentsarray ofPluginDeploymentViewrequiredDeployment rows across nodes.placementPlacementViewor nullScheduler placement; absent when the instance is hand-managed.storage_syncStorageSyncViewor nullHow outside changes at this destination are followed; absent until a storage instance's first sync pass.
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.
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.
One selectable value for a Settings dropdown.
valuestringrequiredStored config value; empty string means use the plugin default.labelstringrequiredOperator-facing choice caption.
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, ornumber).choicesarray ofPluginSettingChoiceor nullDropdown values of anenumcolumn; 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.
A setting destination the operator approves.
settingstringrequiredThe setting key.destinationstringrequiredThe destination exactly as the consent response shows it.
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) ortcp(a raw socket).destinationstring or nullThe destination:scheme://host:portfor a fetch,host:portfor 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) orrestricted(loopback, link-local or a name such aslocalhost, which also needs an address grant).tlsboolean or nullTrue for anhttpsfetch, whose certificate is verified; false for plain HTTP and raw TCP, which trust the network's DNS answer.statestringrequiredapproved,pending(awaiting consent),unsetorinvalid.errorstring or nullWhy the value names no destination, whenstateisinvalid.
One editable setting shown in the Settings UI.
keystringrequiredDottedconfig.tomlkey for this option.labelstringrequiredOperator-facing field caption.valuestringrequiredCurrent string form of the setting.value_typestringrequiredUI widget hint (boolean,string,number,secret, ortable).choicesarray ofPluginSettingChoiceor nullOptional dropdown values; omitted for free-form fields.secretbooleanTrue for asecretsetting:valueis never the stored value.secret_setboolean or nullFor a secret setting, whether the instance document names a sealed value.columnsarray ofPluginSettingColumnor nullColumns of atablesetting, in display order; omitted for other kinds.valueis then the rows as JSON text.
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 ofPluginSettingOptionrequiredEditable 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.deploymentPluginDeploymentViewor nullThis node's deployment of the instance, when one exists.placementPlacementViewor nullScheduler placement; absent when the instance is hand-managed (the Enabled switch applies only then).storage_syncStorageSyncViewor 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 ispresent.
DELETE /api/config/plugins/{key} body.
plugin_keystringrequiredCanonical plugin key.uninstalledbooleanrequiredTrue when an active-version pointer existed and was cleared.deployments_undeployedintegerrequiredDeployment rows switched toabsentacross the plugin's instances. At least 0.
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.
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;nullwhen no artifact fits the host's target.artifactsarray ofPluginArtifactSummaryrequiredPer-target artifacts.
JSON body of every portal error response.
errorstringrequiredOperator-facing error text (no structured code).
Portal identity fields exposed on /me for SSO / local-portal callers.
identity_idinteger (int64)requiredportal_identities.idfor 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.
JSON body of a portal route that has nothing to report beyond success.
okbooleanrequiredAlwaystrue.
JSON body after a portal session was minted for a first-party user.
okbooleanrequiredAlwaystrueon this success path.rolestringrequiredThe user's role (owner,administrator, ormember).
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
A portal (user) session as listed by GET /api/auth/sessions.
idinteger (int64)requiredSession id, forDELETE /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:browserfor a browser session,clerkfor a library card, whoseclient_labelis the name the clerk gave itself,playerfor a player app's card (/player), whoseclient_labelis the player password's label or the app's name.
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.
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 underplugin-packages/.activatebooleanMake the new version active even when another is.approvebooleanRecord the requested consent as approved.allow_unverified_publisherbooleanAccept a publisher without independent authenticity.
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 (ascordesc).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, ordark).
JSON body after PATCH /api/auth/profile.
okbooleanrequiredAlwaystrueon this success path.userAuthMeUserrequiredThe profile after the change, asGET /api/auth/mereports it.
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.
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 ofdurationlistened, 0 to 1, read whencurrentTimeis 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.
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.
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).
GET /api/playback/progress answer.
itemsarray ofProgressJsonrequiredThe caller's progress rows, most recently played first. Editions their patron scope no longer shows are left out, so a page can be shorter thanlimitwith more to come.next_cursorstring or nullCursor of the next page; absent on the last.
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.
Body for batched purchase-hint lookups (max 24 queries).
queriesarray ofPurchaseHintsQueryPer-title purchase-hint queries in this batch.
Parallel purchase-hint results aligned with the request queries.
resultsarray ofPurchaseHintsResponserequiredOne purchase-hint response per query, in request order.
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 ofStoreEditionKnown 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 pickingbest; other stores are compared at list / non-member price. Every catalog match is still returned inhints.
Priced catalog matches for one title, sorted best-first.
hintsarray ofPurchaseHintrequiredResolved purchase hints for this query.bestPurchaseHintor 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.
PUT /api/config/plugins/{key}/active body.
versionstringrequiredInstalled version to activate.
PUT /api/config/branch-enrollment body.
enabledbooleanrequiredWhether branch nodes may enroll into this library.
PUT /api/config/branches body.
enrollmentbooleanrequired"Let new branches join" (core.branch_enrollment.enabled).
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.
PUT /api/config/nodes/{node_id}/labels body.
labelsarray of stringrequiredThe node's complete operator label set.
PUT /api/config/nodes/{node_id}/owner body.
user_idinteger (int64) or nullUser who owns the node, ornullto clear.
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'scache.budget_bytes.nullremoves the override; leaving the field out keeps it as it is. At least 0.
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).
PUT /api/config/plugin-instances/{id}/deployments/{node_id} body.
desiredDesiredStaterequiredWhat the node should do:presentorabsent(the scheduler'splaced/unplacedare 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".
PUT /api/config/plugin-instances/{id}/config body.
expected_revisioninteger (int64)requiredRevision the caller last observed.settingsmap of string toSettingValueScalar 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 declaredsecretsetting. Each is sealed intoencrypted_secretsand referenced from the document; the plaintext is never stored in the document or echoed back.
PUT /api/config/plugin-instances/{id}/placement body.
replicasinteger orallrequiredA 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.
PUT /api/users/{id}/controls body.
overridesControlOverridesrequiredThe controls set for this patron alone; an absent ornullcontrol follows the library's default for a Member and is allowed for an Administrator, so{}clears every override.
PUT /api/users/{id}/scope body.
scopePatronScopeor nullThe patron's own scope, ornullto return them to the library's default.
Operator JSON for GET /api/queues/{name}.
Includes every field of QueueInfo.
messagesarray ofDomainEventInforequiredRecent messages on the queue, newest first.deliveriesarray ofEventDeliveryInforequiredRecent deliveries on the queue, newest first.
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.
Compact wisher shown on the global queue (avatar + label).
user_idinteger (int64) or nullFirst-partyusers.idwhen 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 ofpicture_urlfor the web app to show (filled by the daemon; never stored).
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 theirwork_keys differ, so a client matches its own wishes on this id first and onwork_keyotherwise.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 whencover_urlis anhttpsURL. Append/128(thumbnail),/360(card) or/full, so a client can show covers without loadingcover_urlfrom another site.wish_countinteger (int64)requiredNumber of distinct users who wishlisted this title.wishersarray ofQueueWisherDistinct 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.
Body of POST /api/me/notifications/inbox/read.
notification_idstring or nullOne notification to mark read; absent ornullmarks the whole inbox read.
How many entries a read marked.
markedinteger (int64)requiredEntries that were unread and are now read. At least 0.
Where a file's bytes stand after a PATCH.
memberNointeger (int32)requiredThe file's number. At least 0.receivedinteger (int64)requiredBytes received; send the nextPATCHfrom here. At least 0.completebooleanrequiredTrue once every byte has arrived.
One ranked recommendation (typically an unowned storefront title).
work_idstring or nullLibraryworks.idof 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 ofPurchaseHintrequiredBuy / 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 ofStoreEditionAll 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 inbuild_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 whencover_urlis anhttpsURL. Append/128(thumbnail),/360(card) or/full, so a client can show covers without loadingcover_urlfrom 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-seedseed_categories).languagestring or nullBCP-47 / storefront language code (en,de, …) when known.is_explicitboolean or nullWhenSome(true), a storefront marks the edition explicit (adult) content;Nonewhen none said (a wishlist entry says nothing).wishersarray ofQueueWisherDistinct people who have this title on an open wishlist.wish_countinteger (int64)Number of distinct users who wishlisted this title (may exceedwishers.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 ofBranchAvailabilityBranches 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.
What the operator recorded about a recovery copy of the key in use.
Type: one of unrecorded, saved, skipped
What the operator did about a recovery copy.
Type: one of saved, skipped
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.
PUT /api/config/master-key/recovery-copy/state body.
stateRecoveryCopyChoiceBodyrequiredWhat the operator did.
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).
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 (Passkeywhen empty).
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'sPluginGrant): the plugin key, the entrypoints, network mode and domains, and the bindings it may use;nullwhen 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'sPluginGrant): the plugin key, the entrypoints, network mode and domains, and the bindings it may use;nullwhen nothing was approved.approved_atstring or nullRFC 3339 approval time.approved_bystring or nullWho approved (operator, orplatformfor 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), orinvalid_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.
POST /api/config/branches/titles/remove body.
node_idstring or nullOnly this branch's entries; every branch's when absent.
Body of PATCH /api/notifications/channels/{id}.
labelstringrequiredThe new name, 1 to 128 bytes on one line.
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.
Character replacement rule (ReplacementCharacters in classic Settings.json).
findstringrequiredSubstring to search for in each path segment / tag value.replacestringrequiredReplacement text (may be empty to stripfind).
One field recorded with an event.
namestringrequiredThe field's name.valuestringrequiredIts value, redacted before the report was sent.
Severity of one event in a report.
Type: one of ERROR, WARN, INFO, DEBUG, TRACE
One logged event in a stored report.
ts_unix_msinteger (int64)requiredWhen it happened, Unix milliseconds, or0when 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 ofReportEventFieldrequiredFields recorded with it.
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.
Whether an issue is open.
Type: one of open, closed
A GitHub issue tracking the report.
numberinteger (int64)requiredThe issue number. At least 0.titlestringrequiredIts title.stateReportIssueStaterequiredWhether it is open.urlstringrequiredIts page (alwayshttps://).
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.
Wishlist row status (open while wishlisted; cancelled after un-wishlist).
Type: one of open, cancelled
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.
One page of books to review.
itemsarray ofReviewItemJsonrequiredThe books, oldest upload first.next_cursorstring or nullPass ascursorfor the next page; absent when this page is empty.
Body of a 409 Conflict from a compare-and-swap write whose
expected_revision lost to a newer revision.
errorstringrequiredAlwaysrevision_conflict.current_revisioninteger (int64)requiredThe revision to read and retry against.
POST /api/config/library-consents/revoke body.
library_idstringrequiredLibrary id.plugin_keystringrequiredCanonical plugin key.
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.
One route: a channel, or the built-in "In app" target, and the least severity it takes.
destination_idstringrequiredThe channel's id, orin-appfor 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-appruns no plugin and is listed first.min_severitystringrequiredinfo,warningorcritical: notifications less urgent than this skip the channel.
Body of PUT /api/notifications/routes/{type}.
routesarray ofRouteJsonrequiredThe type's routes, replacing the old ones; at most 32. Empty sends the type nowhere. At most 32 items.
Every routing rule, by type.
routesmap of string to array ofRouteJsonrequiredType id to its routes.
Whether a [ScopeRule] lets matching books in or keeps them out.
Type: one of include, exclude
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).
Optional body for POST /api/library/scan.
accountstring or nullWhen set, scan this account even ifscan_enabledis false.plugin_instance_idstring or nullWhen set, scan only this deployed plugin instance.
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>orfrozen@<n>+<checksum>);nullwhen 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.
The book field a [ScopeRule] matches one value of.
Type: one of genre, series, author, narrator, tag, collection
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.
An item that matched a search.
libraryItemLibraryItemrequiredThe item.
GET /api/libraries/{id}/search.
bookarray ofSearchBookrequiredMatching items.podcastarray of objectrequiredAlways empty.narratorsarray ofNarratorrequiredMatching narrators.tagsarray of objectrequiredAlways empty.genresarray of objectrequiredAlways empty.seriesarray ofSearchSeriesrequiredMatching series.authorsarray ofAuthorrequiredMatching authors.
A series that matched a search.
seriesSeriesrequiredThe series.booksarray ofLibraryItemrequiredIts items.
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 ofLibraryItemor nullIts items in series order, on lists.progressSeriesProgressor nullThe patron's progress through it, when asked for.
A page of series.
resultsarray ofSeriesrequiredThe 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.
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.
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.
The server settings apps read.
idstringrequiredAlwaysserver-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.
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.
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 ofTrackJsonrequiredThe 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.
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 ofPlaybackSessionrequiredThe page's sessions, newest first.
JSON body for GET /api/auth/sessions.
sessionsarray ofSessionViewrequiredThe caller's sessions, newest first; empty for a Bearer-only caller, who has no session rows.
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
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 nullTargetusers.idwhen a provisioner sets another user's password.
One cell of a table setting row: the scalar kinds only.
Type: boolean or SettingNumber or string
Value type of a declared plugin setting.
Type: one of string, bool, integer, enum, secret, table
A finite JSON number; an integer for integer settings.
Type: number
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,secretortable.valuesarray ofSettingValueSpecor nullAllowed values of anenumsetting; 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 atablean array of row objects, as the setting'stypesays.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 ofSettingSpecor nullColumns of atablesetting, in display order: each a scalar entry naming one field of every row. Omitted for other kinds.
Settings page payload: file values, effective runtime, and plugin groups.
settingsmap of string to stringrequiredValues as written in config.toml (and env overlays), plusoutput.*from thecore.outputdatabase document.effectivemap of string to stringrequiredRuntime-effective values after the last successful reload (auth, plugins).pluginsarray ofPluginSettingsGrouprequiredPer-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 thecore.outputdocument theoutput.*values insettingswere read from; send it back asexpected_output_revision.effective["output.revision"]is the revision this host has applied, which lags the document until the host's next wakeup.
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.
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
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.
GET /api/config/shared-branches body.
node_idstringrequiredId of the node that answered.nodesarray ofNodeViewrequiredThis node and the shared branches the caller may see.
JSON body once this install joined a library as a shared branch.
connectionstringrequiredAlwaysshared_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 (postgresord1).master_key_wrappedbooleanrequiredWhether the shared master key was wrapped with this install's password.restartingbooleanrequiredAlwaystrue: the daemon restarts as a shared node right after answering.
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.
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 ornullkeeps 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 ornullkeeps 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 ornullkeeps 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 ornullkeeps the stored setting.
JSON body after POST /api/config/join/sharing.
libraryLibraryLinkViewrequiredThe link with its settings as stored now.
JSON body for GET /api/config/join/sharing.
librariesarray ofLibraryLinkViewrequiredEvery library this install is a branch of, with its sharing and work settings.
A personalized shelf on the home screen.
idstringrequiredThe shelf id, such ascontinue-listening.labelstringrequiredThe shelf's English label.labelStringKeystringrequiredThe key apps translate the label by.typestringrequiredWhat the shelf holds:book,seriesorauthors.entitiesShelfEntitiesrequiredThe shelf's entries.totalinteger (int64)requiredEntries in all. At least 0.
A shelf's entries.
Type: array of LibraryItem or array of Series or array of Author
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.
One integration that signs people in with its own credentials.
idstringrequiredIntegration id, used in/api/integrations/{id}/login.namestringrequiredButton label.
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 ofSigninOidcProviderrequiredEnabled OIDC identity providers, in configuration order.integrationsarray ofSigninIntegrationrequiredIntegrations that accept their own credentials at sign-in.require_second_factorbooleanrequiredWhetherdaemon.auth.require_second_factoris on, so clients can explain the enrollment step.
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.
One storefront config option (key, label, allowed values).
keystringrequiredConfig table key (for examplecontainer).labelstringrequiredOperator-facing option name.valuesarray ofConfigOptionValueInforequiredAllowed values the SPA may offer for this option.
JSON body of a connected store account.
okbooleanrequiredAlwaystrue.account_idstringrequiredThe store's id for the account.sourcestringrequiredThe source's id, as listed byGET /api/portal/sources.plugin_keystringrequiredThe plugin that owns the account.
One enabled storefront as shown on the portal Accounts page.
idstringrequiredSource plugin id (audible,libro, …).namestringrequiredOperator-facing storefront name.authstringrequiredPortal auth mode (passwordoroauth).config_optionsarray ofSourceConfigOptionInfoStore-specific knobs the SPA can present (omitted when empty).brandBrandInforequiredStorefront colors and logo href for the Accounts UI.
JSON body for GET /sources.
sourcesarray ofSourceInforequiredEnabled storefronts the SPA may offer for connect / login.
The result of a split.
work_idstringrequiredThe new work the expressions moved to.split_fromstringrequiredThe work that was split.
POST /api/config/join/start body.
addressstringThe library's address. Left out withfrom_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, soaddressandfingerprintare left out, and the branch name defaults to the card's name. Not withshared_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.
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.
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 isacquired.pendinginteger (int64)requiredHeld works still needing acquire (not_acquired).errorinteger (int64)requiredHeld works stuck inerrorafter a failed acquire.in_progressinteger (int64)requiredHeld works currentlyqueuedordownloading.listenstringrequiredComma-joineddaemon.listenaddresses from live config.storage_backendstringrequiredComma-joined enabled destination plugin ids, ornone.auth_enabledbooleanrequiredWhether the live auth middleware requires operator credentials.eventsEventQueueStatusrequiredDurable domain-event delivery-queue counters.
A fresh second factor for a shared branch consent. Debug prints no code.
Type: object
The state of a destination's change feed, as the API reports it.
Type: one of off, healthy, gap, failing
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) orfailing(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.
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 ofReportEventViewrequiredIts events, oldest first.
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, …).
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.
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.
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.
POST /api/session/local-all.
resultsarray ofSyncResultrequiredOne outcome per entry, in the order sent.
Operator-facing TCP grant (host + ports).
hoststringrequiredHostname or*.wildcard.portsarray of integer (int32)requiredDestination ports.
The answer to a test send.
notification_idstringrequiredThe stored test notification.delivery_idstringrequiredIts delivery; follow it in the delivery log.
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 whencover_urlis anhttpsURL. Append/128(thumbnail),/360(card) or/full, so a client can show covers without loadingcover_urlfrom 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 (Audiblenum_ratings).review_countinteger (int64) or nullCount of written reviews (Audiblenum_reviews).reviewsarray ofTitleReviewDeprecated: reviews load via/api/discover/title-reviews. Kept empty for older clients; prefer the paginated reviews endpoint.
Body for batched title-metadata lookups (max 24 queries).
queriesarray ofTitleMetaQueryPer-title metadata queries in this batch.
Title-metadata results aligned with the request; failed items are null.
resultsarray ofTitleMetaor nullrequiredOne optional metadata payload per query; enrichment errors becomeNone.incompletearray of booleanrequiredPer query, in order:truewhen itsnullis 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.
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 ofStoreEditionStore editions that listed this title (the search hit's or card'sstore_editions), at most 16. A sparse record is filled from each of these stores that declareddetailByProductId, by the product id it gave the title, before the stores that declareddetailByIsbnare asked by ISBN.
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 toportal_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 whencover_urlis anhttpsURL. Append/128(thumbnail),/360(card) or/full, so a client can show covers without loadingcover_urlfrom another site.sourcesarray ofTitleRequestSourceRecordPer-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 ofWishlistStoreEditionDistinct storefront editions contributing to this wishlist item.purchase_hintsarray ofWishlistPurchaseHintPurchase 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.
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 totitle_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.
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).
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 (MostHelpfulorMostRecent, as applied).reviewsarray ofTitleReviewrequiredReview rows on this page.
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) orMostRecent.
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.
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
application/x-www-form-urlencoded body for POST /oidc/token.
grant_typestringrequiredGrant:authorization_codeorrefresh_token; anything else is 400.codestring or nullAuthorization code from the redirect (authorization_codegrant).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_tokengrant).
Successful token-endpoint JSON (access, optional refresh, and ID tokens).
access_tokenstringrequiredHS256 JWT access token bound to the User (token_use=access).token_typestringrequiredAlwaysBearerfor 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.
Password accepted, but an authenticator-app code is needed before a session is issued.
okbooleanrequiredAlwaystrue: the password step succeeded.mfaTotpChallengeDetailsrequiredThe second step the client must complete.
The pending second-factor step after a password login.
methodstringrequiredAlwaystotp: finish withPOST /api/auth/totp/login.challenge_idstringrequiredChallenge to send with the code; expires after five minutes.
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.
Optional current password for enroll/disable step-up.
current_passwordstring or nullPassword used for recent-reauth when the user already has a credential.
JSON body for GET /api/auth/totp.
enabledbooleanrequiredWhether an authenticator app is confirmed for the caller.
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 asaudio/mp4.bitrate_kbpsinteger (int32) or nullAverage bitrate in kilobits per second, once probed. At least 0.losslessbooleanrequiredTrue for a lossless encoding.
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.
errorstringrequiredAlwaystransport_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).
JSON returned to the tray after a successful prepare.
codestringrequiredSingle-use loopback handoff code forGET /api/auth/tray-handoff?code=.expires_in_secsinteger (int64)requiredSeconds until this ticket expires (matches the in-process deadline). At least 0.
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, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
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 whenfinishis set.
One upload.
idstringrequiredThe upload id (32 hex digits).statestringrequiredopen(taking bytes),committed(queued),running,done,failedorcancelled.sourcestringrequiredupload, orintakefor 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 ofUploadMemberJsonor nullIts files; left out of lists.
The caller's uploads, newest first.
uploadsarray ofUploadJsonrequiredAt most 50 uploads, without their files.
POST /api/uploads body: the files of one batch.
filesarray ofManifestFilerequiredEvery file of the batch, in the order their numbers follow.
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 aPATCHhere. At least 0.outcomestringrequiredWhat became of it:pending,expanded(an archive),matched,needs_review,duplicate,refusedorfailed.reasonstring or nullWhy it was refused or failed, as a stable code.editionIdstring or nullThe edition it was stored under.
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.typestringrequiredAlwaysuser: 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 ofMediaProgressrequiredProgress on every item the patron has started.seriesHideFromContinueListeningarray of stringrequiredSeries hidden from continue listening: none.bookmarksarray ofBookmarkrequiredEvery 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.
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.
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_ownerorlast_administrator.
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.
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.
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.
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).
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, whenmint_invitewas true.invite_urlstring or nullInvite link that redeems the claim ticket, when one was minted.
Body of DELETE /api/users/{id}.
okbooleanrequiredAlways true; the status code says the user was deleted.
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.
Standard OIDC claims for GET /oidc/userinfo, limited to the token's scopes.
substringrequiredSubject: the Bookclerkusers.idas a string.namestring or nullDisplay name (profilescope), when the user has one.preferred_usernamestring or nullLogin name (profilescope), when the user has one.emailstring or nullEmail (emailscope), when the user has one.email_verifiedboolean or nullAlwaystruewhenemailis present: Bookclerk trusts the address the Owner recorded.
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.
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.
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 ofUserSsoPictureSummaryrequiredPictures the user's identity providers supplied.listeningUserListeningHintor nullThe most recent unfinished listen within the last 30 minutes, if any.integrationsarray ofUserIntegrationHintrequiredStorefront and integration accounts linked to the user.controlsMemberControlsrequiredWhat the user may do here (the member controls that apply to them; seeGET /api/users/{id}/controlsfor the default and overrides).identitiesarray ofUserIdentitySummaryrequiredExternal sign-in identities linked to the user.
Body of GET /api/users.
usersarray ofUserListEntryrequiredEvery first-party user.
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.
First-party user role (owner | administrator | member).
Type: one of owner, administrator, member
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.
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 ofpicture_urlfor 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.
First-party user status.
Type: one of active, disabled
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.
JSON body for GET /api/config/join/window.
librariesarray ofLibraryLinkViewrequiredThe libraries this install is an active branch of.cardsarray ofClerkLinkViewrequiredThe libraries this install holds an active library card for.booksarray ofWindowEntryViewrequiredTheir 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.
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.requestWindowRequestViewor 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 (fromisbranch) or one of its own store accounts holds it (fromislibrary). Absent otherwise.
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 ofWindowEditionViewrequiredThe editions, in library then store order; the first names the entry.
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.
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.
Storefront edition key for wishlist / queue payloads.
sourcestringrequiredContent-source plugin id (audible,libro, …).product_idstringrequiredStorefront product id (ASIN, ISBN, UUID, …).
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 inseries.editionsarray ofEditionJsonrequiredEditions; a show's episodes' editions included.stateWorkStateJsonor 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.
Book or podcast (works.kind).
Type: one of book, podcast
A page of GET /api/library/works.
worksarray ofWorkSummaryJsonrequiredThe works, in the requested order.next_cursorstring or nullPass ascursorfor the next page; absent on the last page.
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).
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;nullclears it.rating_performancenumber (double) or nullNarration rating, 0 to 5;nullclears it.rating_storynumber (double) or nullStory rating, 0 to 5;nullclears it.tagsstring or nullTags separated by whitespace (at most 32, each at most 64 bytes, 1024 bytes in all);nullor an empty string clears them.
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.
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 inseries, 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 ofMediaKindJsonrequiredCarriers 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.
One library tag on a work.
valuestringrequiredThe tag as written.sourceWorkTagSourcerequiredWhere it came from.
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.
A work's library tags.
work_idstringrequiredThe work.tagsarray ofWorkTagrequiredEvery tag, by key, with where it came from.
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