Books

See Library & Reading for what these operations do in the UI. A book’s id is a slug derived from its title (deduplicated with a hash suffix on collision), not a UUID.

GET /api/books

Lists every book in the library — this endpoint is not scoped to the active profile; ratings, read, and progress on each record reflect whichever profile last had them applied server-side. Use PATCH /api/books/:id to read/write the active profile’s own state, via its returned book object.

Response: { "books": BookRecord[] }

POST /api/books

Uploads an EPUB. multipart/form-data, one field:

Deduplicated by SHA-256 content hash — re-uploading identical bytes returns the existing book instead of creating a new one.

Response: 201 with { "book": BookRecord, "duplicate": false }, or 200 with { "book": BookRecord, "duplicate": true } if the file already exists. 400 if the file isn’t .epub or its metadata can’t be parsed.

PATCH /api/books/:id

Updates the active profile’s reading state for one book — rating, read status, and reading position all live per-profile, not on the shared book record.

Request body — all fields optional:

Response: { "book": Book } — the book merged with the active profile’s state.

DELETE /api/books/:id

Deletes the book’s files from storage, removes it from the index, and clears every profile’s reading state for it.

Response: { "ok": true }

GET /api/books/:id/readers

Lists other profiles (excluding the active one) that have read, rated, or made progress on this book — powers the “Readers” panel on a shared install.

Response: { "readers": [{ "profileId": string, "name": string, "color": string, "read": boolean, "progress"?: number, "rating"?: number }] }

POST /api/books/:id/send-to-ereader

Emails the book’s .epub to the active profile’s e-reader address. See Send to E-Reader for the SMTP and destination-address setup this depends on.

Response: { "ok": true, "sentTo": string }, or 400 if SMTP or the profile’s e-reader email isn’t configured yet, 502 if sending fails.

GET /api/books/:id/metadata/candidates

Looks up metadata candidates on Open Library by the book’s ISBN, title, and author. How many candidates come back is set admin-side — see Settings.

Response: { "candidates": [...] }, or 404 if Open Library has no match.

POST /api/books/:id/metadata

Applies edited or looked-up metadata. Accepts either JSON or multipart/form-data (use form data to upload a cover file directly).

Request body (JSON)

Request body (form data) — same title/author/description fields, plus a cover file field (must be an image) instead of coverUrl.

Response: { "book": BookRecord }