John O'Keefe
c4b62af213
New frontmatter'd docs with handler-compatible examples: - devices/get_device.md (DeviceInfo shape) - devices/regenerate_device_token.md (token + sync_urls) - devices/get_device_mappings.md (wrapper + DeviceMappingSummary) - devices/update_device_mapping.md (UpdateDeviceMappingRequest) - devices/download_sidecar_config.md (sidecar config JSON file) - devices/link_book.md (LinkBookRequest; one UNVERIFIED marker on required-tag) Schema registry: 6 new entries; DeviceMappingSummary hoisted to package scope. Gate passes (the UNVERIFIED marker is logged, not a failure). Excludes /api/devices-page (htmx page route, per ground rules).
1.6 KiB
1.6 KiB
method, path, auth, area
| method | path | auth | area |
|---|---|---|---|
| POST | /api/devices/:deviceId/sync/link-book | jwt | devices |
Link Book
Links a device file (by path + SHA256) to a media item, optionally with a confidence score. Used by the book-matching flow.
Example request
{
"device_file": {
"file_path": "/books/1984.epub",
"sha256": "abc123...",
"title": "1984"
},
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
"confidence_score": 0.95
}
Example response
{
"status": "linked",
"device_file_alias": {
"id": "660e8400-e29b-41d4-a716-446655440000",
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
"device_id": "770e8400-e29b-41d4-a716-446655440000",
"file_path": "/books/1984.epub",
"file_sha256": "abc123...",
"confidence_score": 0.95
}
}
Request fields
| Field | Type | Required | Notes |
|---|---|---|---|
| device_file.file_path | string | no | path on the device |
| device_file.sha256 | string | no | file content hash |
| device_file.title | string | no | device-side title |
| media_item_id | string (uuid) | yes | services.LinkBookRequest declares it as uuid; the gate only checks the Bind struct — UNVERIFIED: confirm required tag on LinkBookRequest fields |
| confidence_score | number | no | match confidence (0-1) |
Errors
| Status | Body | When |
|---|---|---|
| 400 | {"error": "Invalid device ID"} / {"error": "Invalid request body"} |
malformed id or body |
| 500 | {"error": "Failed to link book: ..."} |
service failure |