HomeBranch

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

Method POST
Path /auth/login
Description Authenticate and receive access + refresh tokens
Method POST
Path /auth/register
Description Register a new user account
Method POST
Path /auth/refresh
Description Exchange a refresh token for a new access token
Method POST
Path /auth/logout
Description Invalidate the refresh token
Auth endpoints are served at /auth/* by the nginx proxy, routed to the Authentication service. The HomeBranch API itself handles all /api/* routes.

Books

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

Method GET
Path /api/books
Description List all books (paginated, supports search)
Method GET
Path /api/books/:id
Description Get a single book by ID
Method POST
Path /api/books
Description Upload a new EPUB file (multipart/form-data, field: file)
Method PATCH
Path /api/books/:id
Description Update book metadata
Method DELETE
Path /api/books/:id
Description Delete a book and its file
Method GET
Path /api/books/:id/file
Description Download the raw EPUB file

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).

Method GET
Path /api/book-shelves
Description List all bookshelves for the current user
Method GET
Path /api/book-shelves/:id
Description Get a bookshelf and its books
Method POST
Path /api/book-shelves
Description Create a new bookshelf
Method PATCH
Path /api/book-shelves/:id
Description Rename a bookshelf
Method DELETE
Path /api/book-shelves/:id
Description Delete a bookshelf (books are not deleted)
Method POST
Path /api/book-shelves/:id/books
Description Add books to a bookshelf
Method DELETE
Path /api/book-shelves/:id/books/:bookId
Description Remove a book from a bookshelf

Authors

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

Method GET
Path /api/authors
Description List all authors (paginated)
Method GET
Path /api/authors/:id
Description Get an author and their books

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
Method GET
Path /api/saved-positions/:bookId
Description Get the saved reading position for a book
Method PUT
Path /api/saved-positions
Description Save or update a reading position

User management

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

Method GET
Path /api/users
Description List all users (admin only)
Method GET
Path /api/users/me
Description Get the current authenticated user's profile
Method PATCH
Path /api/users/:id
Description Update a user's role or details (admin only)
Method DELETE
Path /api/users/:id
Description Delete a user account (admin only)

Health check

Method GET
Path /api/health
Description Returns 200 OK when the API is running (no auth required)