Smaller endpoints that don’t belong to one resource.
GET /api/health
GETNo session required
Checks connectivity to the configured storage backend — the same probe used in the Docker and Kubernetes health checks.
Response: 200 { "status": "ok" }, or 503 { "status": "error", "message": string }.
GET /api/trending
GETAny session
Open Library’s trending feed — see Metadata & Discovery.
Query parameters
| Field | Type | Required | Notes |
|---|---|---|---|
period |
"daily" | "weekly" | "monthly" |
No | Defaults to "weekly"; invalid values also fall back to it |
Response: { "books": [{ "key": string, "title": string, "authors"?: string[], "coverUrl"?: string }] } — up to 24 books.
GET /api/metadata/description
GETAny session
Fetches a work’s description from Open Library by its work key — used to fill in the description field for a metadata candidate that doesn’t carry one inline.
Query parameters: key (required) — an Open Library work key, e.g. /works/OL12345W.
Response: { "description": string | null }, or 400 if key is
missing.
OPDS catalog
GETNo session requiredAn OPDS catalog for e-reader apps — see OPDS
Catalog for how to use it. All routes return Atom XML
(application/atom+xml;profile=opds-catalog;kind=...), app-wide rather
than scoped to a profile.
| Route | Returns |
|---|---|
/opds |
Navigation feed — links to the catalogs below |
/opds/all |
Acquisition feed of every book, sorted by title, paginated with ?page= (50 per page) |
/opds/search?q= |
Acquisition feed matching q against title or author |
/opds/opensearch |
OpenSearch description document, so OPDS clients can build the search URL themselves |
GET /api/files/*key
GETAny session
Serves a raw file straight from the storage backend — this is what backs
book covers, the unpacked reader content, and EPUB downloads. Not
scoped to a book ID; key is the full storage path, for example
books/<id>/book.epub or books/<id>/cover.jpg.
Response: the file’s bytes, with Content-Type inferred from the
path and Cache-Control: public, max-age=31536000, immutable (safe
since every key is either content-hash-deduped or cover-versioned). 404
if the key doesn’t exist in storage.