OPDS

OPDS

OPDS (Open Publication Distribution System) is the standard catalog format used by e-reader apps. Bindery serves its whole library as OPDS at /opds/, so you can browse and download books directly from KOReader, Moon+ Reader, Aldiko, PocketBook, FBReader, or any other OPDS-speaking app.

Endpoints

Path	Feed
/opds/	Navigation root — entry points for Authors / Series / Recent
/opds/authors	Alphabetical list of every author with at least one book in the library
/opds/authors/{id}	Every book by one author
/opds/series	All series
/opds/series/{id}	Every book in one series, ordered by position
/opds/recent	Most recently imported — great for "what's new" homepage on the reader
/opds/book/{id}	Single-book entry with format download links
/opds/book/{id}/file	The actual file stream (EPUB / MOBI / PDF)

The root feed links everything else — point your reader at /opds/ and let it navigate.

Authentication

The /opds/* subtree uses a dedicated auth middleware that honours all of the following, in order:

1. auth.mode = disabled — everyone in.
2. auth.mode = local-only + RFC1918/loopback client IP — allowed without credentials.
3. X-Api-Key header or ?apikey=... query parameter — allowed when the value matches the configured API key.
4. Signed session cookie (set by logging into the web UI from the same browser) — allowed.
5. HTTP Basic Auth with a Bindery username + password — allowed.
6. Otherwise — 401 Unauthorized with WWW-Authenticate: Basic realm="Bindery OPDS". Clients then retry with credentials.

In practice: reader apps want Basic auth (username + password), while scripts want the API key via header. Both are supported on the same URL.

Client setup

KOReader

Tools → OPDS catalog → + (new):

• Catalog name: Bindery
• Catalog URL: https://bindery.example.com/opds/
• Username: your Bindery username
• Password: your Bindery password

KOReader remembers the credentials and uses them on every navigation.

Moon+ Reader (Android)

Books → OPDS → +:

• Display name: Bindery
• URL: https://bindery.example.com/opds/
• Username / Password: your Bindery credentials

Aldiko Next / FBReader / PocketBook

All three follow the same pattern: add a custom catalog with the /opds/ URL and supply Bindery credentials. The WWW-Authenticate header triggers the app's credential prompt automatically on first connect.

Script access (API key)

curl -H "X-Api-Key: $KEY" https://bindery.example.com/opds/recent

Or embed the key in the URL for apps that can't do custom headers:

https://bindery.example.com/opds/recent?apikey=YOUR_KEY

Why HTTPS matters

Basic auth sends credentials on every request, base64-encoded (which is not encryption). Always put /opds/ behind TLS — either directly (TLS termination in Bindery is not supported; use a reverse proxy) or via WireGuard/Tailscale if the reader stays on a private network.

If TLS is in play, Bindery auto-flips session cookies to Secure and emits HSTS. See Reverse proxy and SSO for Traefik / Caddy / Nginx recipes.

Known limitations

• No search endpoint — OPDS 1.2 defines /opds/search as an OpenSearch descriptor; Bindery doesn't serve one yet. Reader apps fall back to client-side filtering over the feeds. Tracked on the roadmap.
• No cover thumbnails in the nav feed — covers show on single-book entries but the author-list and series-list feeds don't embed them. This is deliberate (keeps the feed small over slow reader connections); per-book pages do include the cover.
• Facets / sort order are fixed — alphabetical for authors, by series position for series feeds, most-recent-first for /opds/recent. Not configurable via query string.

See also

• Security — full auth story including the precedence matrix.
• Reverse proxy and SSO — exempting /opds/* from ForwardAuth so reader apps can authenticate directly.