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

288 lines
11 KiB
Markdown
Raw Blame History

# API Documentation
Complete reference for Bookhoard REST API endpoints.
## Quick Links
- [Authentication](authentication/) - User registration, login, tokens
- [Users](users/) - Profile management
- [Admin](admin/) - Admin operations (user management)
- [Libraries](libraries/) - Library management
- [Books](books/) - Bulk book operations and downloads
- [Media Items](media-items/) - Media item operations
- [Progress](progress/) - Reading progress tracking
- [Notes](notes/) - User notes management
- [Highlights](highlights/) - Book highlights
- [Ratings](ratings/) - Book ratings
- [Devices](devices/) - Device registration, sync, and shelf management
- [Analytics](analytics/) - Usage statistics
- [Book Matching](book-matching/) - Search and link books
- [Collections](collections/) - See [Collections API](../collections-api.md)
- [Conflicts](conflicts/) - Sync conflict resolution
- [Queue](queue/) - Sync queue management
- [Scanner](scanner/) - Library scanning and watch mode (admin)
- [System](system/) - Tunable system settings and configuration (admin)
- [OPDS](opds/) - Open Publication Distribution
- [KOReader](koreader/) - KOReader sync protocol
- [Kobo](kobo/) - Kobo sync protocol (coming soon)
- [WebSocket](websocket/) - Real-time sync events
---
## Authentication
See [Authentication Endpoints](authentication/)
- 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](admin/)
- 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](admin/hash-conflicts.md)
- POST /api/admin/hash-conflicts/:id/resolve - Resolve a conflict (keep / keep_all) (admin)
## Users & Profiles
See [User Management](users/)
## Libraries
See [Library Management](libraries/)
- 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](media-items/)
- 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](progress/)
- 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](notes/) and [Highlights Management](highlights/)
## Ratings
See [Ratings System](ratings/)
## Device Management
See [Device Registration & Sync](devices/)
- 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](devices/get_sidecar_config.md)
- GET /api/devices/:id/sidecar/download - Download sidecar config as a file
## System Settings & Configuration
See [System API](system/)
- 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](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](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](../collections-api.md) or [Collections Endpoints](collections/)
## Conflicts
See [Conflict Resolution](conflicts/)
- 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](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/)
- [Scanner Overview](scanner/overview.md) - 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](opds/)
- 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](koreader/) and [Sync Protocol](sync/koreader-protocol.md)
- 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](kobo/) and [Sync Protocol](sync/kobo-protocol.md)
- 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](websocket/)
- 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