Files

T

john-okeefe df90938c5c docs(api): document device sidecar endpoints; fix registration docs

- 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)

2026-08-20 14:40:54 -04:00

2.1 KiB

Raw Blame History

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)

{
  "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

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=".bookhoard.json"

Body: the sidecar JSON (same shape as above).

2.1 KiB Raw Blame History

Get Device Sidecar Config

Response (200 OK)

Example Request

Download Device Sidecar Config

Response (200 OK)

2.1 KiB

Raw Blame History