Bookhoard/bookhoard
0
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 70 Wiki Activity
Files
3e98fadb9f669877f49b907d11f81e64524400f7
bookhoard/docs/developer/api/api-reference.md
T
John O'Keefe 8fbacd9f46 feat(devices): pairing codes replace the registration broadcast 
A pending device registration used to be announced to EVERY account's
Devices page, and whoever clicked Approve first bound the device — and
its freshly minted sync token — to their account. Worse, the pending
card displayed the registration UUID, which is also the bearer
credential on the unauthenticated /api/devices/register/status poll
channel: any family user who could see the list already held everything
needed to take the device. On a family server that is a
wrong-account-binding bug (accidental or deliberate); this commit
removes the class of problem rather than patching the race.

The new model is the Netflix/YouTube TV device flow: the registering
device displays a 6-digit pairing code, and the only person who can
read it — whoever holds the device — types it into THEIR account on the
Devices page. Possession of the device screen becomes the credential;
nothing is broadcast; the reject-on-someone-else's-behalf hole dies
with the list.

Server changes:
- POST /api/devices/register now mints pairing_code (crypto/rand,
  rejection-sampled for uniformity, collision-checked against live
  registrations) and retires prior unclaimed registrations with the
  same device_identifier, so re-registering leaves exactly one live
  attempt.
- POST /api/devices/claim (JWT) binds the registration behind a code to
  the caller's account, reusing the rotate-or-create approval logic
  factored out of ApproveDevice (shared bindRegistrationToUser helper;
  the Android self-approval route keeps working unchanged).
- POST /api/devices/claim/lookup (JWT) returns the confirm-card data
  without binding. Lookup and claim share a per-account budget (12
  attempts/min, DeviceRateLimiter gained a claim case) — the 1M-code
  space over a 5-minute TTL makes guessing infeasible without it.
- POST /api/devices/register/cancel lets the registering device end its
  own attempt (registration UUID bearer, idempotent, never touches a
  claimed registration).
- ListPendingRegistrations / GetPendingRegistrationsData are
  deprecated-by-emptiness: unclaimed registrations return to nobody.
- RejectDevice and its route are deleted — the broadcast list was its
  only consumer, and there is nothing left for anyone to reject.

Additive-only for pinned surfaces: the register response gains
pairing_code (Android DTO untouched), the four KOReader sync surfaces
and approve keep byte-identical shapes. contract_pins.md changelog
records the widening and the reject removal. Docs, schema registry, and
bruno mirrors move together per the drift gate; bruno_gen.go now keeps
hand-authored bruno/podcasts/ (API docs never existed for them, so the
next -update run would have swept them — latent landmine, defused).

Unit tests: code shape, live-collision avoidance, typed-code
normalization, and the resolve scopes (live/expired/claimed/miss).
2026-11-02 16:11:03 -05:00

293 lines
13 KiB
Markdown
Raw Blame History

# API Documentation
Complete reference for Bookhoard REST API endpoints.
## Quick Links
- [Authentication](authentication/login.md) - User registration, login, tokens
- [Users](users/get_profile.md) - Profile management
- [Admin](admin/list_users.md) - Admin operations (user management)
- [Libraries](libraries/list_libraries.md) - Library management
- [Media Items](media-items/get_media_item.md) - Media item operations
- [Progress](progress/get_media_progress.md) - Reading progress tracking
- [Notes](notes/get_notes.md) - User notes management
- [Highlights](highlights/get_highlights.md) - Book highlights
- [Ratings](ratings/get_ratings.md) - Book ratings
- [Devices](devices/get_devices.md) - Device registration, sync, and shelf management
- [Analytics](analytics/get_analytics.md) - Usage statistics
- [Book Matching](book-matching/search_books.md) - Search and link books
See [Collections Endpoints](collections/list_collections.md)
- [Conflicts](conflicts/list_conflicts.md) - Sync conflict resolution
- [Queue](queue/list_all_queue_items.md) - Sync queue management
- [Scanner](scanner/scan_library.md) - Library scanning and watch mode (admin)
- [System](system/get_settings.md) - Tunable system settings and configuration (admin)
- [OPDS](opds/feeds.md) - Open Publication Distribution
- [KOReader](koreader/sync_progress.md) - KOReader sync protocol
- [Kobo](kobo/initialization.md) - Kobo sync protocol (coming soon)
- [WebSocket](websocket/protocol.md) - Real-time sync events
---
## Authentication
See [Authentication Endpoints](authentication/login.md)
- 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/list_users.md)
- 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/get_profile.md)
## Libraries
See [Library Management](libraries/list_libraries.md)
- 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_media_item.md)
- 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](media-items/download_media_item_file.md))
- 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_media_progress.md) — in particular the
[Position Contract](progress/position-contract.md) (verification,
healing, the OPF spine numbering hazard, and offset currencies) before
writing a client.
- GET /api/media-items/:id/progress - Get reading progress + restore handles
- PUT /api/media-items/:id/progress - Submit reading progress (verified/healed server-side)
- DELETE /api/media-items/:id/progress - Delete reading progress
- GET /api/progress/:id/history - Get progress history
## Notes & Highlights
See [Notes Management](notes/get_notes.md) and [Highlights Management](highlights/get_highlights.md)
## Ratings
See [Ratings System](ratings/get_ratings.md)
## Device Management
See [Device Registration & Sync](devices/get_devices.md)
- 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 (always empty — pairing codes replaced the broadcast list)
- GET /api/devices/approve/:registration_id - Approve registration by UUID (Android self-approval path)
- POST /api/devices/claim - Claim a registration by its pairing code ([Pairing codes](devices/claim_device.md))
- POST /api/devices/claim/lookup - Resolve a pairing code without binding ([Lookup](devices/lookup_pairing_code.md))
- POST /api/devices/register/cancel - The registering device cancels its own pairing attempt ([Cancel](devices/cancel_device_registration.md))
- 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_settings.md)
- 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_analytics.md)
- 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/search_books.md)
- 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 Endpoints](collections/list_collections.md)
## Conflicts
See [Conflict Resolution](conflicts/list_conflicts.md)
- 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/list_all_queue_items.md)
- 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/scan_library.md)
- [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/feeds.md)
- 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/sync_progress.md) 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/initialization.md) and [Sync Protocol](sync/kobo-protocol.md)
- POST /api/sync/kobo/:token/markup - Sync markup highlights
- POST /api/sync/kobo/:token/bookmark - Sync bookmarks
- POST /api/sync/kobo/:token/v1/analytics/gettests - Analytics endpoint
- GET /api/sync/kobo/:token/v1/initialization - Initialize Kobo sync
- POST /api/sync/kobo/:token/sync-from-server - Push content to device
## WebSocket
See [WebSocket API](websocket/protocol.md)
- 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