Files

T

john-okeefe 91c8be8562 docs(api): document the KOReader resolve endpoint

Add koreader/resolve_book.md for GET /api/sync/koreader/resolve, list
the endpoint in the API reference, and describe the resolve-then-pull-
then-push linking flow in the KOReader protocol page — including why a
device pushing to bootstrap its identity creates progress conflicts for
books already mid-read from other sources.

2026-08-22 09:57:44 -04:00

1.6 KiB

Raw Blame History

Resolve Book

Map a book's file SHA-256 to its Bookhoard UUID without touching progress state. Used by devices to link a freshly downloaded book before their first pull, so the device's first-page position is never pushed (which would conflict with server-side progress for books already mid-read).

Endpoint: GET /api/sync/koreader/resolve Auth: Required (Device authentication)

Query Parameters

Parameter	Type	Required	Description
sha256	string	Yes	File content hash (64 hex characters)

Resolution is format-aware: the hash is checked against both media_items.file_sha256 and media_item_formats.file_sha256, so a converted file (KEPUB/PDF) matches its media item too.

Device Authentication

This endpoint requires device authentication (not user JWT). Devices authenticate using their device credentials.

Example Request

GET /api/sync/koreader/resolve?sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Authorization: Bearer {device_token}

Response (200 OK)

{
  "book_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "title": "Book Title",
  "author": "Author Name"
}

Error Responses

Code	Description
400	Missing or malformed `sha256` parameter
401	Device authentication failed
404	No book in the library matches the given hash

1.6 KiB Raw Blame History