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.1 KiB

Raw Blame History

method, path, auth, area

method	path	auth	area
GET	/api/sync/unlinked-books/:id/suggestions	jwt	book-matching

Get Unlinked Book Suggestions

Get suggested matches for unlinked books on a device.

Endpoint: GET /api/sync/unlinked-books/:id/suggestions Auth: Required

Path Parameters

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

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of suggestions per book (default: 5)
threshold	float	No	Minimum confidence threshold (default: 0.5)

Request Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token

Example Request

GET /api/sync/unlinked-books/550e8400-e29b-41d4-a716-446655440000/suggestions?limit=3&threshold=0.6
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response (200 OK)

{
  "suggestions": [
    {
      "book_id": "book-123",
      "book_title": "Foundation",
      "book_author": "Isaac Asimov",
      "matches": [
        {
          "media_item_id": "uuid",
          "title": "Foundation",
          "authors": [
            "Isaac Asimov"
          ],
          "confidence": 0.95
        },
        {
          "media_item_id": "uuid-2",
          "title": "Foundation and Empire",
          "authors": [
            "Isaac Asimov"
          ],
          "confidence": 0.75
        }
      ]
    }
  ],
  "action": null,
  "sha256": null,
  "title_from_device": null,
  "total_suggestions": null,
  "unlinked_book_id": null
}

Error Responses

Code	Description
401	Invalid or expired token
404	Device not found

2.1 KiB Raw Blame History