john-okeefe
f65db5ab4f
Verified against the Echo routes and handler structs, fixing drift that
would break API clients:
- login: response field is access_token, not token (AuthResponse struct)
- register status: status is only pending|approved; expiry is HTTP 410
(not a status value), approved responses are single-use, and pending
registrations do not survive server restarts
- visible libraries: endpoint is GET /api/libraries/visibility and
returns a top-level array of full library rows, not a wrapped object
- media items list: response is {"data": [...]}, library_id is optional,
limit defaults to 50 (max 1000), no total field; document the sort
parameter, the two response shapes, and raw-vs-resolved file paths
refresh and device-registration docs verified accurate; no changes.
2.0 KiB
Get Device / Check Registration Status
Check device registration status or get device details.
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)
Request Body (Status Check)
| Field | Type | Required | Description |
|---|---|---|---|
| registration_id | string | Yes | Registration UUID |
Example Request (Status Check)
{
"registration_id": "registration-uuid"
}
Response (200 OK)
{
"status": "pending|approved",
"message": "awaiting user approval",
"expires_in": 123,
"auth_token": "device-bearer-token...",
"device_id": "uuid",
"sync_endpoints": {
"progress": "https://bookhoard.com/api/sync/progress",
"metadata": "https://bookhoard.com/api/sync/metadata",
"annotations": "https://bookhoard.com/api/sync/annotations"
}
}
status is pending or approved. While pending, the response includes message and expires_in (seconds remaining). Once approved, the response includes auth_token, device_id, and sync_endpoints; auth_token fields are empty when pending.
The approved response is single-use: the registration is deleted from the pending map once returned, so store the auth_token immediately. A repeat status check for the same registration_id returns 404.
Error Responses
| Code | Description |
|---|---|
| 400 | Invalid or missing registration_id |
| 404 | Registration not found (unknown or already issued) |
| 410 | Registration expired ({"error": "registration expired"}) |
Note: expiration is signaled by HTTP 410 Gone, not a "status": "expired" value. Pending registrations are held in server memory, so a server restart also invalidates them (subsequent checks return 404).