API Reference

The HomeBranch API is a NestJS REST API. All endpoints require a valid JWT access token issued by the Authentication service, except where noted.

Authentication

Include the JWT access token in the Authorization header of every request:

Authorization: Bearer <access_token>

Tokens are issued by the Authentication service. The HomeBranch API validates them using the shared JWT_ACCESS_SECRET.

Getting a token

OIDC single sign-on

Service configuration

Admin-only endpoints for managing the authentication configuration, including OIDC provider settings and whether self-registration is enabled.

Books

Manage your E-Book collection. Books are uploaded as multipart form data and stored on the server filesystem. The maximum upload size is 50 MB.

Pagination & search

List endpoints support pagination via ?page= and ?limit= query parameters, and full-text search via ?search=.

Upload example

curl -X POST http://localhost/api/books \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]"

Bookshelves

Bookshelves are user-defined collections. A book can belong to multiple bookshelves (many-to-many relationship).

Favorites

Users can mark any book as a favorite. The toggle endpoint favorites the book on the first call and removes it on a second call.

Authors

Authors are created automatically when books are uploaded and can be browsed separately.

Reading position sync

Saved positions store a CFI (Canonical Fragment Identifier) string and a percentage, allowing the reader to resume exactly where it left off on any device.

// Save position
PUT /api/saved-positions
{
  "bookId": "uuid-here",
  "cfi": "epubcfi(/6/4[chap01]!/4/2/2/2:0)",
  "percentage": 0.35
}

// Get position
GET /api/saved-positions/:bookId

User management

User management endpoints are restricted to users with the admin role. The first registered user is automatically assigned admin.

Book deduplication

These endpoints are restricted to users with the admin role. Use them to find and resolve duplicate EPUB files in the library.

Start by enqueuing a scan. Once the scan job completes, duplicates appear in the list endpoint. Resolve each pair by posting a resolution action:

• merge — keep the original, delete the duplicate and its file
• replace — promote the duplicate as canonical, delete the original
• keep_both — mark as resolved without deleting either book

OPDS catalog

HomeBranch exposes OPDS feeds for use with compatible e-reader apps (Kybook, Kavita-compatible readers, Panels, etc.). Both OPDS 1.2 (Atom XML) and OPDS 2.0 (JSON) are supported.

OPDS endpoints require authentication. Point your e-reader app at /api/opds/v1/catalog (or /api/opds/v2/catalog for OPDS 2.0) and use your HomeBranch credentials. The AUTH_SERVICE_URL environment variable must be set on the API service for OPDS authentication to work.

OPDS 1.2 (Atom XML)

OPDS 2.0 (JSON)

Health check