Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity
Files
b927ed9988e5a7ccdd78f922c9bc5bc1b25a0842
bookhoard/docs/developer/api/api-reference.md
T
john-okeefe d429534b12
Release / build-and-push (push) Successful in 2m24s
Details
docs(api): deleted-annotation history + KOReader deletion propagation 
New media-items/deleted_annotations.md for the list/restore/purge
endpoints; endpoint index updated. The KOReader protocol page documents
deleted_highlights/deleted_bookmarks on the progress push and the
deletion-propagation contract: keys learned only from server pulls,
explicit arrays only (never absence), tombstone convergence via the
metadata fetch, no resurrection from stale replays, and the web history
as the restore path.
2026-08-22 13:16:54 -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 /api/media-items/:uuid/download - Download media item file
  • 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