0 Fork 0

Files

T

John O'Keefe 18084de7a6 docs(book-matching,collections): Beam batch 10 — 15 endpoints

WO3 sync internals resolved: the book-matching docs ARE the sync surface
(books/query, link-book, bulk/auto-link, unlinked-books, suggestions,
file-alias CRUD) + collections rule/test/bulk-assign/shelf-mapping
surface.

Dedupe resolved (Claude call): search_books.md declared
GET /api/books/match but its BODY documents POST /api/sync/books/query —
both routes exist and are distinct (query-param device protocol vs JSON
body plugin protocol). Repointed search_books.md frontmatter to the POST
route; get_book_matches.md keeps the GET.

Claude registry: 15 entries (one pre-existing link-book entry deduped).
Drift fixed by gate: auto-link request {confidence_threshold, limit} not
{device_id, threshold}; bulk-link link objects {unlinked_book_id,
media_item_id, confidence_score} not {device_id, book_id, ...};
responses {results,total,successful,failed}/{auto_linked,results}; added
missing example-responses (bare delete, remove-rule is_smart-after
semantics, bulk-assign per-book results). make test 9/9.

2026-10-24 17:59:27 -04:00

2.4 KiB

Raw Blame History

method, path, auth, area

method	path	auth	area
POST	/api/devices/:id/collections	jwt	collections

Create Shelf Mapping

Map a collection to a device shelf for syncing.

Endpoint: POST /api/devices/{deviceId}/collections Auth: Required Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
deviceId	string (UUID)	Yes	Device UUID

Request Body

Field	Type	Required	Description
collection_id	string (UUID)	Yes	Collection UUID to map
device_shelf_name	string	Yes	Name of the shelf on the device
sync_direction	string	No	Sync direction (default: "bidirectional")

Sync Directions

Direction	Description
bidirectional	Sync both ways between Bookhoard and device
book_to_hoard	Bookhoard → Device only
device_to_hoard	Device → Bookhoard only
none	No sync (mapping only for reference)

Example Request

{
  "collection_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_shelf_name": "Sci-Fi",
  "sync_direction": "bidirectional"
}

Response (201 Created)

{
  "id": "990e8400-e29b-41d4-a716-446655440000",
  "collection_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_shelf_name": "Sci-Fi",
  "sync_direction": "bidirectional",
  "created_at": "2026-02-01T10:00:00Z",
  "device_id": null
}

Use Case

Collections can be synced to device-specific shelves (Kobo, KOReader). This allows automatic organization of books on your e-reader based on your Bookhoard collections.

Error Responses

Code	Description
400	Invalid request (validation failed)
401	Authentication required
404	Device or collection not found
409	Mapping already exists
500	Internal server error

2.4 KiB Raw Blame History