From df90938c5c559c60ca8582a48884f469b48791e4 Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Thu, 20 Aug 2026 14:40:54 -0400
Subject: [PATCH] docs(api): document device sidecar endpoints; fix
 registration docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New get_sidecar_config.md for GET /api/devices/:id/sidecar and
  /sidecar/download: the .bookhoard.json config served to devices
  (endpoints, books keyed by per-format SHA-256 with UUID fallback,
  collections, format availability) used by the KOReader plugin to
  self-configure
- register_device.md: correct the response — no device_id at
  registration; auth_url is /devices/approve/:id (was the nonexistent
  /devices/auth/confirm/:id); document poll_interval and
  setup_instructions, and the approve-then-poll flow
- get_devices.md: fix the status endpoint path to
  POST /api/devices/register/status (was /api/devices/auth/status)
---
 docs/developer/api/devices/get_devices.md     |  2 +-
 .../api/devices/get_sidecar_config.md         | 68 +++++++++++++++++++
 docs/developer/api/devices/register_device.md | 11 ++-
 3 files changed, 77 insertions(+), 4 deletions(-)
 create mode 100644 docs/developer/api/devices/get_sidecar_config.md

diff --git a/docs/developer/api/devices/get_devices.md b/docs/developer/api/devices/get_devices.md
index a7fef51..92b1531 100644
--- a/docs/developer/api/devices/get_devices.md
+++ b/docs/developer/api/devices/get_devices.md
@@ -2,7 +2,7 @@
 
 Check device registration status or get device details.
 
-**Endpoint**: `POST /api/devices/auth/status` or `GET /api/devices/{device_id}`
+**Endpoint**: `POST /api/devices/register/status` or `GET /api/devices/{device_id}`
 **Auth**: Not required for status check, Required for device details
 **Content-Type**: `application/json` (for status check)
 
diff --git a/docs/developer/api/devices/get_sidecar_config.md b/docs/developer/api/devices/get_sidecar_config.md
new file mode 100644
index 0000000..1a8b94a
--- /dev/null
+++ b/docs/developer/api/devices/get_sidecar_config.md
@@ -0,0 +1,68 @@
+# Get Device Sidecar Config
+
+Returns the KOReader/Kobo sidecar configuration (`.bookhoard.json`) for a device: server endpoints, the user's books (keyed by SHA-256 with UUID fallback), and collections. Used by the Bookhoard KOReader plugin to self-configure after approval.
+
+**Endpoint**: `GET /api/devices/{id}/sidecar`
+**Auth**: User JWT (device owner or admin)
+
+### Response (200 OK)
+
+```json
+{
+  "version": "1",
+  "bookhoard": {
+    "opds_catalog": "https://bookhoard.example.com/opds/devices/<device-id>/catalog",
+    "sync_api": "https://bookhoard.example.com/api/sync/kobo",
+    "opds_base_url": "https://bookhoard.example.com/opds",
+    "api_base_url": "https://bookhoard.example.com",
+    "device_id": "<device-id>",
+    "device_token": "dev_..."
+  },
+  "books": {
+    "abc123sha256...": {
+      "bookhoard_uuid": "media-item-uuid",
+      "title": "The Hobbit",
+      "author": "J. R. R. Tolkien",
+      "available_formats": ["epub", "kepub"],
+      "sha256": "abc123sha256...",
+      "file_path": "/books/hobbit.epub"
+    }
+  },
+  "collections": [
+    { "name": "Favorites", "shelf_mapping": "Favorites" }
+  ],
+  "opds_enabled": true,
+  "sidecar_enabled": true,
+  "last_updated": "2026-08-20T12:00:00Z"
+}
+```
+
+**Notes**:
+
+- The `books` map is keyed by per-format SHA-256 (falling back to the item UUID), so a book downloaded in a different format (e.g. KEPUB) still matches its primary entry. Each entry lists `available_formats` for the item.
+- `available_formats` includes `kepub` when the source is an EPUB (conversion available).
+
+### Example Request
+
+```bash
+curl https://bookhoard.example.com/api/devices/<device-id>/sidecar \
+  -H "Authorization: Bearer <token>"
+```
+
+---
+
+# Download Device Sidecar Config
+
+Generates the same configuration as a downloadable `.bookhoard.json` file for manual device setup.
+
+**Endpoint**: `GET /api/devices/{id}/sidecar/download`
+**Auth**: User JWT (device owner or admin)
+
+### Response (200 OK)
+
+**Headers**:
+
+- `Content-Type`: `application/json`
+- `Content-Disposition`: attachment; filename="<device-name>.bookhoard.json"
+
+**Body**: the sidecar JSON (same shape as above).
diff --git a/docs/developer/api/devices/register_device.md b/docs/developer/api/devices/register_device.md
index 644fad9..c16b4ad 100644
--- a/docs/developer/api/devices/register_device.md
+++ b/docs/developer/api/devices/register_device.md
@@ -28,14 +28,19 @@ Register a new device for sync.
 
 ```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. Poll `POST /api/devices/register/status` at `poll_interval` seconds until `status` is `approved`, at which point the response includes the device's `auth_token`, `device_id`, and `sync_endpoints`.
+
 ## Error Responses
 
 | Code | Description               |