Books OPDS Catalog

ryOS exposes each user's synced /Books EPUBs as an OPDS 1.x acquisition feed. This is intended for e-readers and other catalog clients, including CrossPoint firmware.

Endpoint

Set the OPDS server URL to:

https://<your-ryos-host>/api/opds

Use the same username and password as the ryOS account. The client must send HTTP Basic authentication over HTTPS.

Method	Path	Purpose
GET	`/api/opds`	List the user's active, top-level `/Books/*.epub` files
GET	`/api/opds/books/:bookId.epub`	Download an EPUB acquisition

The catalog response is an Atom acquisition feed with content type application/atom+xml;profile=opds-catalog;kind=acquisition. Each book link uses the exact EPUB type application/epub+zip.

Authentication

Requests use preemptive HTTP Basic authentication:

Authorization: Basic <base64(username:password)>

Missing or invalid credentials return 401 with:

WWW-Authenticate: Basic realm="ryOS Books", charset="UTF-8"

ryOS verifies the password against the account's bcrypt hash. Failed attempts share the normal per-account login lockout, and the endpoint also limits authentication attempts per IP.

Because Basic auth sends reusable credentials on every request, configure only an HTTPS ryOS URL outside a trusted local network.

Book selection and downloads

Only active EPUB files directly under /Books are listed.

A book must have both synced file metadata and a Sync v2 book blob.
The feed follows the Books shelf's pinned-top and pinned-bottom ordering.
Acquisition URLs stay on the ryOS host, so OPDS clients can reuse the same

Basic credentials for the download.

ryOS unwraps the private gzip Sync v2 envelope and returns the original EPUB

bytes. Private object-storage URLs never appear in the feed.

CrossPoint sends Basic auth preemptively, resolves the relative acquisition links, and downloads these .epub URLs without extra configuration.