john-okeefe
df90938c5c
- 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)
69 lines
2.1 KiB
Markdown
69 lines
2.1 KiB
Markdown
# 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).
|