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.
53 lines
2.0 KiB
Markdown
53 lines
2.0 KiB
Markdown
# 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)
|
|
|
|
```json
|
|
{
|
|
"registration_id": "registration-uuid"
|
|
}
|
|
```
|
|
|
|
## Response (200 OK)
|
|
|
|
```json
|
|
{
|
|
"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).
|