Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity
Files
b1eda696f1d16fa1612d3aca955f107aeedea1e9
bookhoard/docs/developer/api/api-reference.md
T
john-okeefe 44735554f7 docs(api): document the real book download route 
The documented GET /api/media-items/:uuid/download is not registered
anywhere - MediaHandler.DownloadBook exists but no route mounts it.
Book files (and covers) are actually served by the JWT-authenticated
GET /uploads/library-{id}/{path} route that the web reader uses.

Rewrite the download doc around the real file route (URL construction
from the item's library_id and relative file_path, MIME/Cache headers,
error codes), note the dead handler so nobody relies on the phantom
endpoint, and correct the API reference index. Mention the OPDS device
route as the conversion-capable alternative.
2026-08-29 10:25:59 -04:00

11 KiB
Raw Blame History

API Documentation

Complete reference for Bookhoard REST API endpoints.

Quick Links

Authentication

See Authentication Endpoints

  • POST /api/auth/register - Register new user
  • POST /api/auth/login - User login
  • POST /api/auth/refresh - Refresh access token
  • POST /api/auth/logout - User logout
  • GET /api/auth/profile - Get user profile
  • PUT /api/auth/profile - Update user profile (self-edit)
  • PUT /api/auth/profile/:id - Update user profile (admin)
  • DELETE /api/auth/profile - Delete account (self)
  • DELETE /api/auth/profile/:id - Delete user (admin)
  • PUT /api/auth/password - Change password (self)
  • PUT /api/auth/password/:id - Reset password (admin)
  • PUT /api/auth/theme - Update theme preference

Admin

See Admin Operations

  • GET /api/auth/users - List all users (admin)
  • PUT /api/auth/users/:id/max-devices - Update user device limit (admin)
  • GET /api/admin/hash-conflicts - List pending hash conflict groups (admin) — see Hash Conflicts
  • POST /api/admin/hash-conflicts/:id/resolve - Resolve a conflict (keep / keep_all) (admin)

Users & Profiles

See User Management

Libraries

See Library Management

  • GET /api/libraries/types - Get library types
  • POST /api/libraries - Create library (admin)
  • GET /api/libraries - List libraries (admin)
  • GET /api/libraries/:id - Get library (admin)
  • PUT /api/libraries/:id - Update library (admin)
  • DELETE /api/libraries/:id - Delete library (admin)
  • POST /api/libraries/:id/folders - Add library folder (admin)
  • GET /api/libraries/:id/folders - Get library folders (admin)
  • DELETE /api/libraries/:id/folders - Delete library folder (admin)
  • GET /api/libraries/:id/stats - Get library statistics (admin)
  • GET /api/libraries/:id/media-items - Get library media items (admin)
  • GET /api/libraries/browse - Browse server directories (admin)
  • POST /api/libraries/:id/scan - Scan library (admin)
  • GET /api/libraries/scan-settings - Legacy scan settings (admin; superseded by /api/system/settings)
  • PUT /api/libraries/scan-settings - Legacy scan settings update (admin; superseded by /api/system/settings)
  • GET /api/libraries/visibility - Get visible libraries
  • POST /api/libraries/visibility - Set library visibility

Media Items

See Media Item Operations

  • GET /api/media-items - List media items
  • GET /api/media-items/:id - Get media item details
  • POST /api/media-items/bulk-delete - Bulk delete media items
  • POST /api/media-items/bulk-update - Bulk update media items (tags/contributors with normalization)
  • GET /uploads/library-{library_id}/{file_path} - Download book file / cover (JWT; see Download Media Item)
  • POST /api/media-items/:id/rating - Create rating
  • GET /api/media-items/:id/rating - Get rating
  • PUT /api/media-items/:id/rating - Update rating
  • DELETE /api/media-items/:id/rating - Delete rating
  • GET /api/media-items/:id/progress - Get reading progress
  • PUT /api/media-items/:id/progress - Update reading progress
  • DELETE /api/media-items/:id/progress - Delete reading progress
  • GET /api/media-items/:id/notes - Get notes
  • POST /api/media-items/:id/notes - Create note
  • GET /api/media-items/:id/notes/:noteId - Get note
  • PUT /api/media-items/:id/notes/:noteId - Update note
  • DELETE /api/media-items/:id/notes/:noteId - Delete note
  • GET /api/media-items/:id/highlights - Get highlights
  • POST /api/media-items/:id/highlights - Create highlight
  • GET /api/media-items/:id/highlights/:highlightId - Get highlight
  • PUT /api/media-items/:id/highlights/:highlightId - Update highlight
  • DELETE /api/media-items/:id/highlights/:highlightId - Delete highlight
  • GET /api/media-items/:id/bookmarks - Get bookmarks
  • GET /api/media-items/:id/annotations/deleted - List deleted annotations (history)
  • POST /api/media-items/:id/annotations/:annotationId/restore - Restore a deleted annotation
  • DELETE /api/media-items/:id/annotations/:annotationId?annotation_type=highlight|note|bookmark - Permanently delete a deleted annotation
  • POST /api/media-items - Create media item (admin)
  • PUT /api/media-items/:id - Update media item (admin)
  • DELETE /api/media-items/:id - Delete media item (admin)

Reading Progress

See Progress Tracking

  • GET /api/progress/:id - Get universal progress
  • POST /api/progress/:id - Update universal progress
  • GET /api/progress/:id/history - Get progress history

Notes & Highlights

See Notes Management and Highlights Management

Ratings

See Ratings System

Device Management

See Device Registration & Sync

  • POST /api/devices/register - Initiate device registration
  • POST /api/devices/register/status - Check registration status
  • GET /api/devices - List devices
  • GET /api/devices/:id - Get device
  • PUT /api/devices/:id - Update device
  • DELETE /api/devices/:id - Delete device
  • GET /api/devices/pending - List pending registrations (admin)
  • GET /api/devices/approve/:registration_id - Approve registration (admin)
  • POST /api/devices/reject/:registration_id - Reject registration (admin)
  • POST /api/devices/:id/shelves - Add to shelf (Kobo; used by native Kobo sync, coming soon)
  • GET /api/devices/:id/shelves - Get shelf contents
  • DELETE /api/devices/:id/shelves - Remove from shelf
  • DELETE /api/devices/:id/shelves/clear - Clear shelf
  • GET /api/devices/:id/sidecar - Get device sidecar config (.bookhoard.json) — see Sidecar Config
  • GET /api/devices/:id/sidecar/download - Download sidecar config as a file

System Settings & Configuration

See System API

  • GET /api/system/settings - List all tunable settings with metadata (admin)
  • PUT /api/system/settings - Validate, persist, and reload a single setting (admin)
  • GET /api/system/config - Raw key/value system configuration (admin)
  • PUT /api/system/config - Update raw config values (admin)

Analytics

See Usage Analytics

  • GET /api/analytics/reading-stats - Get reading statistics
  • GET /api/analytics/device-usage - Get device usage stats
  • GET /api/analytics/popular-books - Get popular books

Book Matching & Linking

See Book Matching

  • GET /api/media-items/search - Search media items
  • POST /api/sync/books/query - Query books for matching
  • POST /api/devices/:deviceId/sync/link-book - Link book to media item
  • GET /api/devices/:deviceId/sync/unlinked-books - Get unlinked books
  • POST /api/sync/bulk-link-books - Bulk link books
  • POST /api/sync/auto-link-books - Auto-link books
  • GET /api/sync/unlinked-books/:id/suggestions - Get match suggestions
  • GET /api/devices/:id/file-aliases - Get file aliases
  • POST /api/devices/:id/file-aliases - Create file alias
  • PUT /api/devices/:id/file-aliases/:aliasId - Update file alias
  • DELETE /api/devices/:id/file-aliases/:aliasId - Delete file alias
  • GET /api/books/match - Get book matches

Collections

See Collections API or Collections Endpoints

Conflicts

See Conflict Resolution

  • GET /api/conflicts - List conflicts
  • GET /api/conflicts/:id - Get conflict details
  • POST /api/conflicts/:id/resolve - Resolve conflict
  • DELETE /api/conflicts/:id - Delete conflict
  • POST /api/conflicts/dismiss-all - Dismiss all resolved
  • POST /api/conflicts/bulk-resolve - Bulk resolve conflicts
  • POST /api/conflicts/bulk-dismiss - Bulk dismiss conflicts

Queue Management

See Sync Queue

  • GET /api/queue/devices/:device_id/stats - Get device queue stats
  • GET /api/queue/devices/:device_id/items - List device queue items
  • POST /api/queue/items/:item_id/retry - Retry queue item
  • DELETE /api/queue/items/:item_id - Delete queue item
  • DELETE /api/queue/devices/:device_id/clear - Clear device queue
  • GET /api/queue/items - List all queue items (admin)

Scanner (Admin)

See Scanner Operations

  • Scanner Overview - Supported formats, metadata extraction, and features
  • POST /api/scanner/scan - Scan library (one-time) (ebooks, manga, comics)
  • POST /api/scanner/start - Start automated scanner
  • POST /api/scanner/stop - Stop automated scanner
  • GET /api/scanner/status/:jobId - Get scan job status
  • POST /api/scanner/watch/start - Start watch mode (real-time monitoring)
  • POST /api/scanner/watch/stop - Stop watch mode
  • GET /api/scanner/watch/status - Get watch mode status

OPDS

See OPDS Feeds

  • GET /opds/devices/:deviceId/catalog - Get device catalog
  • GET /opds/devices/:deviceId/search - Search device catalog
  • GET /opds/devices/:deviceId/nav - Get device navigation
  • GET /opds/devices/:deviceId/download/:bookId - Download book
  • GET /opds/devices/:deviceId/cover/:bookId - Get cover image
  • GET /opds/devices/:deviceId/formats/:bookId - List formats

KOReader Sync Protocol

See KOReader Sync and Sync Protocol

  • POST /api/sync/koreader/progress - Sync reading progress
  • GET /api/sync/koreader/resolve?sha256={hash} - Resolve a book UUID by file SHA-256
  • GET /api/sync/koreader/metadata/:uuid - Get book metadata
  • GET /api/sync/koreader/library - Get device library
  • POST /api/sync/koreader/bookmarks - Sync bookmarks

Kobo Sync Protocol

Status: Coming Soon — Native Kobo sync is implemented server-side but not yet supported on real devices. These endpoints are under active development and may change.

See Kobo Sync and Sync Protocol

  • POST /api/sync/kobo/markup - Sync markup highlights
  • POST /api/sync/kobo/bookmark - Sync bookmarks
  • POST /api/sync/kobo/v1/analytics/gettests - Analytics endpoint
  • GET /api/sync/kobo/v1/initialization - Initialize Kobo sync
  • POST /api/sync/kobo/sync-from-server - Push content to device

WebSocket

See WebSocket API

  • WS /ws/sync - Real-time sync events and notifications

Frontend Pages

  • GET /login - Login page
  • GET /register - Registration page
  • GET / - Home page
  • GET /bookshelf - Bookshelf page
  • GET /dashboard - User dashboard
  • GET /admin - Admin panel
  • GET /devices-page - Device management page
  • GET /conflicts-page - Conflicts resolution page

Documentation

  • GET /docs - Documentation home
  • GET /docs/* - Show documentation pages
  • GET /docs/api/search - Search API documentation
  • GET /docs/search-index.json - Search index for documentation search

Health

  • GET /health - Health check endpoint
Reference in New Issue View Git Blame Copy Permalink