Integrations
API reference
Every endpoint lives under /api and accepts either a JWT (from login) or a
tome_* bearer token. See API tokens
for how to create one. All request/response bodies are JSON unless noted.
Auth
| Method | Path | Description |
|---|---|---|
POST | /api/auth/login | Authenticate, returns JWT |
GET | /api/auth/me | Current user profile |
PUT | /api/auth/me | Update username / email |
PUT | /api/auth/me/password | Change password |
GET | /api/auth/me/stats | Reading stats for current user |
GET | /api/auth/me/backup | Export user data as JSON |
Books
| Method | Path | Description |
|---|---|---|
GET | /api/books | List books (supports ?q=, ?series=, ?author=, ?library_id=, ?per_page=) |
GET | /api/books/{id} | Book detail with files, tags, libraries |
PUT | /api/books/{id} | Update metadata fields |
DELETE | /api/books/{id} | Delete a book and its files |
POST | /api/books/upload | Upload a file (multipart form, file + optional book_type_id) |
POST | /api/books/scan | Scan TOME_LIBRARY_DIR for new files |
POST | /api/books/import | Import from TOME_INCOMING_DIR |
POST | /api/books/ingest | Programmatic ingest (used by Scribe) |
POST | /api/books/check-hashes | Check content hashes for deduplication |
Metadata
| Method | Path | Description |
|---|---|---|
GET | /api/books/{id}/fetch-metadata | Fetch candidates from Hardcover / Google / OpenLibrary |
POST | /api/books/{id}/apply-metadata | Apply selected metadata fields from a candidate |
PUT | /api/books/bulk-metadata | Bulk-update metadata on multiple books |
POST | /api/books/bulk-fetch-candidates | Fetch metadata candidates for up to 100 books |
POST | /api/books/bulk-fetch-metadata | Auto-fill empty fields from best match |
Covers
| Method | Path | Description |
|---|---|---|
GET | /api/books/{id}/cover | Serve cover image |
GET | /api/books/{id}/cover-candidates | Search for cover images (?q=) |
POST | /api/books/{id}/cover | Set cover from URL or file upload |
Downloads & reading
| Method | Path | Description |
|---|---|---|
GET | /api/books/{id}/download/{file_id} | Download a book file (with embedded metadata) |
POST | /api/downloads | Bulk download as streaming ZIP |
GET | /api/books/{id}/read.epub | Stream EPUB for web reader |
GET | /api/books/{id}/read.cbz | Stream CBZ for comic reader |
GET | /api/books/{id}/read.pdf | Stream PDF for viewer |
Reading status
| Method | Path | Description |
|---|---|---|
GET | /api/books/{id}/status | Get reading status for current user |
PUT | /api/books/{id}/status | Set status (unread / reading / read), progress, CFI |
POST | /api/books/statuses | Batch get statuses for multiple book IDs |
Series & facets
| Method | Path | Description |
|---|---|---|
GET | /api/books/series | List all series with volume counts |
GET | /api/books/series-detail | Full series page data (?name=) |
GET | /api/books/facets | Aggregated filter options (authors, tags, formats, etc.) |
GET | /api/books/export | Export library as JSON or CSV |
Libraries
| Method | Path | Description |
|---|---|---|
GET | /api/libraries | List libraries visible to current user |
POST | /api/libraries | Create library (name, icon, is_public) |
PUT | /api/libraries/{id} | Update library |
DELETE | /api/libraries/{id} | Delete library (books are unlinked, not deleted) |
POST | /api/libraries/{id}/books | Add books to library (body: {"book_ids": [...]}) |
DELETE | /api/libraries/{id}/books/{book_id} | Remove book from library |
POST | /api/libraries/{id}/users | Assign user to library (admin) |
DELETE | /api/libraries/{id}/users/{user_id} | Remove user from library (admin) |
Shelves (saved filters)
| Method | Path | Description |
|---|---|---|
GET | /api/saved-filters | List current user's shelves |
POST | /api/saved-filters | Save current filter params as a shelf |
PUT | /api/saved-filters/{id} | Update shelf name / icon |
DELETE | /api/saved-filters/{id} | Delete shelf |
Book types
| Method | Path | Description |
|---|---|---|
GET | /api/book-types | List all book types |
POST | /api/book-types | Create book type (admin) |
PUT | /api/book-types/{id} | Update book type |
DELETE | /api/book-types/{id} | Delete book type |
TomeSync (KOReader)
| Method | Path | Description |
|---|---|---|
GET | /api/tome-sync/resolve | Resolve a file hash to a canonical book ID |
GET | /api/tome-sync/position/{book_id} | Get reading position for a book |
PUT | /api/tome-sync/position/{book_id} | Update reading position |
POST | /api/tome-sync/session | Record a reading session |
GET | /api/tome-sync/series | List series available for download |
GET | /api/tome-sync/download/{book_id}/{file_id} | Download file (KOReader format) |
Home
| Method | Path | Description |
|---|---|---|
GET | /api/home/stats | Dashboard summary (streak, pages, reading time) |
GET | /api/home/activity | Recent reading activity |
GET | /api/home/forgotten-books | Books started but not touched recently |
Users (admin)
| Method | Path | Description |
|---|---|---|
GET | /api/users | List all users |
POST | /api/users | Create user |
PUT | /api/users/{id} | Update user role / active status |
DELETE | /api/users/{id} | Delete user |
POST | /api/users/{id}/impersonate | Impersonate user (returns their JWT) |
Admin
| Method | Path | Description |
|---|---|---|
GET | /api/admin/duplicates | Detect duplicate books |
POST | /api/admin/duplicates/merge | Merge duplicate pair |
POST | /api/admin/duplicates/dismiss | Dismiss duplicate pair |
GET | /api/admin/audit-logs | Audit log entries |
GET | /api/admin/stats | System-wide reading stats |
GET | /api/books/library-health | Misplaced files report |
POST | /api/books/reorganize | Move files to canonical paths |
POST | /api/books/purge-empty-dirs | Clean up empty directories |