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

1.5 KiB

Raw Blame History

Register Device

Endpoint: POST /api/devices/register Auth: Not required (device registration flow) Content-Type: application/json

Request Body

Field	Type	Required	Description
device_name	string	Yes	Device name
device_type	string	Yes	Device type: kobo, koreader, web, mobile
device_identifier	string	Yes	Hardware-specific ID

Example Request

{
  "device_name": "My Kobo Clara",
  "device_type": "kobo",
  "device_identifier": "hardware-specific-id"
}

Response (201 Created)

{
  "registration_id": "registration-uuid",
  "auth_url": "https://bookhoard.com/devices/approve/abc123",
  "qr_code": "data:image/png;base64,iVBORw0KG...",
  "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
400	Invalid device data
409	Device already registered

1.5 KiB Raw Blame History