API Reference
HTTP API endpoints for interacting with Alex programmatically
Alex exposes a REST API for core operations. The UI is built on top of these endpoints.
Authentication
Authenticated endpoints require a valid session cookie (web) or a valid x-alex-desktop-auth header (Electron desktop mode).
Roles:
- admin - Full access, including user management and admin settings.
- user - Can read books, manage personal collections, and track progress.
Authenticated endpoints
Books
| Method | Endpoint | Description |
|---|---|---|
GET | /api/books | List books with pagination, search, and filters. Query params: q, type, status, sort, page, limit. |
GET | /api/books/now-reading | List current user's in-progress books, ordered by most recently read. |
GET | /api/books/[id] | Get metadata for a single book. |
DELETE | /api/books/[id] | Delete a book. |
PATCH | /api/books/[id] | Update book metadata. |
GET | /api/books/[id]/file | Stream a book file (PDF or EPUB) with HTTP range support. |
GET | /api/books/[id]/book.epub | Serve an EPUB file at a .epub URL (required by some clients). |
GET | /api/books/[id]/cover | Serve a book cover image. |
GET | /api/books/[id]/progress | Get current user's reading progress. |
PUT | /api/books/[id]/progress | Update progress. Body: { currentPage, totalPages } (PDF) or { epubLocation } (EPUB). |
Collections
| Method | Endpoint | Description |
|---|---|---|
GET | /api/collections | List current user's collections with book counts. |
POST | /api/collections | Create a collection. Body: { name, description? }. |
GET | /api/collections/[id] | Get a collection with its books. |
PATCH | /api/collections/[id] | Update a collection. Body: { name?, description? }. |
DELETE | /api/collections/[id] | Delete a collection (books are not deleted). |
GET | /api/collections/[id]/books | List books in a collection. |
POST | /api/collections/[id]/books | Add a book to a collection. |
DELETE | /api/collections/[id]/books/[bookId] | Remove a book from a collection. |
GET | /api/collections/[id]/now-reading | List in-progress books inside a collection. |
POST | /api/collections/[id]/share | Enable sharing. Returns { shareToken, shareUrl }. |
DELETE | /api/collections/[id]/share | Disable sharing and revoke token. |
Users (admin only)
| Method | Endpoint | Description |
|---|---|---|
GET | /api/users | List all users. |
POST | /api/users | Create a user. |
PATCH | /api/users/[id] | Update a user (role, password, display name). |
Admin (admin only)
| Method | Endpoint | Description |
|---|---|---|
POST | /api/admin/library/clear | Clear all books from the library. |
POST | /api/electron/clear-books | Clear books for Electron app reset (desktop only). |
Real-time updates
| Method | Endpoint | Description |
|---|---|---|
GET | /api/library/events | Server-Sent Events endpoint for library updates. |
Public endpoints
These endpoints require no auth and are scoped by share token.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/shared/[token] | Get shared collection metadata and paginated books. |
GET | /api/shared/[token]/books | Get paginated book list for a shared collection. |
GET | /api/shared/[token]/covers/[bookId] | Get cover image for a shared collection book. |
GET | /api/shared/[token]/books/[bookId]/file | Stream a shared collection book file. |
GET | /api/shared/[token]/books/[bookId]/book.epub | Serve EPUB from shared collection. |
Source-aware book streaming
The four file-serving routes (/file and /book.epub for authenticated and public access) all route through the same source-aware pipeline.
- For
source=local, bytes are streamed from disk. - For
source=s3, bytes are streamed throughwatcher-rsfrom your configured bucket.
This keeps API behavior stable even when your ingestion backend changes.