docs(api): add system/hash-conflict sections to API references

Monolithic api-reference.md: - New 'System Settings & Configuration' and 'Hash Conflicts' sections (endpoints, examples, response shapes) with TOC entries - Device Management: add the sidecar config/download endpoints - Fix stale registration flow: correct auth_url path, drop phantom device_id, add poll_interval/setup_instructions, status endpoint is POST /api/devices/register/status, and sync_endpoints point at /api/sync/koreader/* - Mark PUT /api/libraries/scan-settings as legacy/superseded - Repair Additional Resources and Collections links (dead COLLECTIONS_API.md / KOBO*_SETUP.md / missing-guide references) Split api-reference.md index: - Quick links and sections for System (settings + config) and the admin hash-conflict endpoints; device sidecar endpoints under Device Management; browse + legacy scan-settings routes under Libraries
2026-08-20 14:41:05 -04:00
parent c49a9605ff
commit 078c4b1f3f
2 changed files with 148 additions and 16 deletions
@@ -26,14 +26,16 @@ Complete API documentation for Bookhoard v1.0 with Universal Cross-Platform Sync
 8. [Device Management](#device-management)
 9. [Analytics](#analytics)
 10. [Book Matching & Linking](#book-matching--linking)
-11. [Collections](#collections) → See [COLLECTIONS_API.md](COLLECTIONS_API.md)
+11. [Collections](#collections) → See [Collections API](collections-api.md)
 12. [OPDS](#opds-open-publication-distribution-system)
 13. [Sync Protocol - KOReader](#sync-protocol---koreader)
 14. [Sync Protocol - Kobo](#sync-protocol---kobo)
 15. [Universal Progress](#universal-progress)
 16. [Conflicts](#conflicts)
 17. [Sync Queue](#sync-queue)
-18. [WebSocket](#websocket)
+18. [System Settings & Configuration](#system-settings--configuration)
+19. [Hash Conflicts](#hash-conflicts)
+20. [WebSocket](#websocket)

 ## Base URL

@@ -201,7 +203,9 @@ Content-Type: application/json
 }
 ```

-### Update Scan Settings
+### Update Scan Settings (Legacy)
+
+> Superseded by `PUT /api/system/settings` (see [System Settings & Configuration](#system-settings--configuration)); kept for backward compatibility.

 ```http
 PUT /api/libraries/scan-settings
@@ -665,18 +669,23 @@ Content-Type: application/json

 ```json
 {
-  "device_id": "uuid",
  "registration_id": "registration-uuid",
-  "auth_url": "https://bookhoard.com/devices/auth/confirm/abc123",
+  "auth_url": "https://bookhoard.com/devices/approve/abc123",
  "qr_code": "data:image/png;base64,iVBORw0KG...",
-  "expires_in": 300
+  "expires_in": 300,
+  "poll_interval": 3,
+  "setup_instructions": {
+    "koreader": "Calibre URL: https://bookhoard.com/api/sync/koreader"
+  }
 }
 ```

+Open `auth_url` (or scan the QR code) while logged in to approve; the registration expires after 5 minutes.
+
 ### Check Registration Status

 ```http
-POST /api/devices/auth/status
+POST /api/devices/register/status
 Content-Type: application/json

 {
@@ -688,13 +697,13 @@ Content-Type: application/json

 ```json
 {
-  "status": "pending|approved|expired",
+  "status": "pending|approved",
  "auth_token": "device-bearer-token...",
  "device_id": "uuid",
  "sync_endpoints": {
-    "progress": "https://bookhoard.com/api/sync/progress",
-    "metadata": "https://bookhoard.com/api/sync/metadata",
-    "annotations": "https://bookhoard.com/api/sync/annotations"
+    "progress": "https://bookhoard.com/api/sync/koreader/progress",
+    "metadata": "https://bookhoard.com/api/sync/koreader/metadata",
+    "bookmarks": "https://bookhoard.com/api/sync/koreader/bookmarks"
  }
 }
 ```
@@ -747,6 +756,22 @@ DELETE /api/devices/{device_id}
 Authorization: Bearer <token>
 ```

+### Get Device Sidecar Config
+
+Returns the `.bookhoard.json` sidecar config for a device (server endpoints, books keyed by per-format SHA-256, collections) used by the KOReader plugin to self-configure.
+
+```http
+GET /api/devices/{device_id}/sidecar
+Authorization: Bearer <token>
+```
+
+Also available as a file download:
+
+```http
+GET /api/devices/{device_id}/sidecar/download
+Authorization: Bearer <token>
+```
+
 ## Analytics

 ### Get Reading Statistics
@@ -953,7 +978,7 @@ Authorization: Bearer <token>

 ## Collections

-For complete collection management documentation, see **[COLLECTIONS_API.md](COLLECTIONS_API.md)**.
+For complete collection management documentation, see **[Collections API](collections-api.md)**.

 **Quick Reference**:

@@ -1540,6 +1565,96 @@ Authorization: Bearer <token>
 }
 ```

+## System Settings & Configuration
+
+### List All Settings
+
+Returns every tunable setting with current value and metadata (type, range, category, group, description, `requires_restart`, `is_default`).
+
+```http
+GET /api/system/settings
+Authorization: Bearer <admin_token>
+```
+
+**Response** (200):
+
+```json
+[
+  {
+    "key": "scan_poll_interval_seconds",
+    "value": "60",
+    "type": "int",
+    "min": "1",
+    "max": "3600",
+    "requires_restart": false,
+    "category": "scanner",
+    "group": "Scanning",
+    "description": "How often to scan all libraries (seconds)",
+    "is_default": true
+  }
+]
+```
+
+### Update a Setting
+
+Type-aware validation (int range, bool parse, IANA timezone for `default_timezone`), persists the value, reloads the registry, and reports whether a restart is needed.
+
+```http
+PUT /api/system/settings
+Authorization: Bearer <admin_token>
+Content-Type: application/json
+
+{
+  "key": "scan_poll_interval_seconds",
+  "value": "30"
+}
+```
+
+**Response** (200): the updated entry plus `reload_required`.
+
+Setting categories: scanner (`scan_poll_interval_seconds`, `auto_scan_enabled`), general (`default_timezone`), security (session duration, password rules, auth rate limit, login lockout), api (OPDS page sizes, device rate limits), sync (annotation tombstone TTL, sync queue interval/batch), performance (conversion cache TTL, worker pool size/capacity). See [System Settings API](api/system/settings.md) for the full catalog.
+
+### Get / Update Raw System Config
+
+Flat key/value configuration (e.g. `base_url`), including keys without registry metadata.
+
+```http
+GET /api/system/config
+PUT /api/system/config
+Authorization: Bearer <admin_token>
+```
+
+## Hash Conflicts
+
+Duplicate content discovered during hashing (import, rescan, or the startup backfill) is grouped into hash conflicts for an explicit keep/merge decision. Files on disk are never deleted.
+
+### List Hash Conflicts
+
+```http
+GET /api/admin/hash-conflicts
+Authorization: Bearer <admin_token>
+```
+
+**Response** (200): `{ "conflicts": [ { id, library_id, library_name, sha256, created_at, items: [ { id, title, author, file_path, file_size, created_at, progress_count, highlight_count, bookmark_count, note_count, collection_count } ] } ], "total": n }`
+
+### Resolve Hash Conflict
+
+```http
+POST /api/admin/hash-conflicts/:id/resolve
+Authorization: Bearer <admin_token>
+Content-Type: application/json
+
+{
+  "action": "keep",
+  "keep_uuid": "media-item-uuid-to-keep"
+}
+```
+
+- `action=keep` — merge every other copy's child rows (progress, highlights, bookmarks, notes, collections) into the kept item, then delete the losers
+- `action=keep_all` — copies are intentional; dismiss the conflict
+
+**Errors**: `400` (bad ID / missing `keep_uuid`), `404` (not found), `409` (already resolved).
+
 ## WebSocket

 ### Connect to WebSocket
@@ -1695,10 +1810,10 @@ bruno run bruno/devices/

 ## Additional Resources

- [README.md](README.md) - Getting started guide
- [UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md](UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md) - Sync architecture
- [KOBOREADER_SETUP.md](KOBOREADER_SETUP.md) - KOReader device setup
- [KOBO_SETUP.md](KOBO_SETUP.md) - Kobo device setup
+- [README.md](../../README.md) - Getting started guide
+- [Sync Guide](../user/sync-guide.md) - Sync concepts and conflict resolution
+- [KOReader Setup](../user/devices/koreader-setup.md) - KOReader device setup
+- [Kobo Setup](../user/devices/kobo-setup.md) - Kobo device setup (native sync coming soon)

 ---

@@ -21,6 +21,7 @@ Complete reference for Bookhoard REST API endpoints.
 - [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)
@@ -51,6 +52,8 @@ 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

@@ -71,7 +74,10 @@ See [Library Management](libraries/)
 - 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

@@ -138,6 +144,17 @@ See [Device Registration & Sync](devices/)
 - 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