John O'Keefe
ae9588f1c6
Beam backfilled auth core (login/register/refresh/logout/profile) and devices
core (list/update/delete/shelf CRUD/sidecar/register flow) with frontmatter,
provenance, and labeled examples. All claimed shapes verified against
handlers: AuthResponse {access_token, refresh_token omitempty, token_type,
expires_in, user}, update device {device_updated, device}, shelf wrappers,
DeviceAuthStatusResponse.
Claude registry verification: 15 entries pinned by type (LoginRequest,
RegisterRequest, AuthResponse, RefreshTokenRequest/Response, UserProfile,
DeviceListResponse, DeviceUpdateRequest, AddToShelfRequest, SidecarConfig,
DeviceRegistrationRequest/Response, DeviceAuthStatusRequest/Response).
Removed revoke_device.md — name-only duplicate of delete_device.md (same
DELETE /api/devices/:id route; was the last audit-orphan doc).
Gate catches this round (subtle Go serialization facts, now pinned in docs):
- uuid.UUID arrays never serialize as omitted: register/status response
ALWAYS carries device_id (all-zeros while pending) despite omitempty
- update device request binds device_name, not name
- register response includes device_id alongside registration_id
- list devices response is a {devices, total} wrapper
2.2 KiB
2.2 KiB
method, path, auth, area
| method | path | auth | area |
|---|---|---|---|
| GET | /api/devices/:id/sidecar | jwt | devices |
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
booksmap 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 listsavailable_formatsfor the item. available_formatsincludeskepubwhen 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/jsonContent-Disposition: attachment; filename=".bookhoard.json"
Body: the sidecar JSON (same shape as above).