0 Fork 0

Files

T

John O'Keefe 25ef0d12ba docs(kobo,koreader,collections): Beam WO5 batch 6 — 12 endpoints

Kobo emulation + KOReader calibre-compatible surface backfilled with
device-token auth; collections reorder + update_rule created.

Claude registry: 12 entries. kobo/koreader emulation endpoints all bind
arbitrary protocol POST bodies (markup/bookmark/gettests/sync-from-server,
koreader progress/bookmarks) — registered as AnyJSONObject, not bodyless as
first drafted. Initialization returns the library sync payload, not the init
response.

Contract correction in update_rule.md: the route is SetRuleEnabled ({enabled}
required -> {collection_id, is_smart}); Beam's draft invented rule-field
updates. Reordered response/status: {item_ids} -> {status: reordered}.

make test 9/9.

2026-10-24 16:25:00 -04:00

2.4 KiB

Raw Blame History

method, path, auth, area

method	path	auth	area
GET	/api/sync/koreader/metadata/:uuid	device-token	koreader

Get Metadata

Get a book's stored progress and annotations for a KOReader device — the pull half of the device sync. The reference client calls this after linking a book via Resolve Book and navigates to the returned position.

Endpoint: GET /api/sync/koreader/metadata/:uuid Auth: Required (Device authentication — Authorization: Bearer {device_token})

Path Parameters

Parameter	Type	Required	Description
uuid	string (UUID)	Yes	Book UUID

Example Request

GET /api/sync/koreader/metadata/774641f9-317b-4087-8e04-53bb4392ae56
Authorization: Bearer {device_token}

Response (200 OK)

{
  "uuid": "774641f9-317b-4087-8e04-53bb4392ae56",
  "title": "1984",
  "author": "George Orwell",
  "progress": {
    "percentage": 0.045,
    "koreader_xpointer": "/body/DocFragment[1]/body/p[29]/text().598",
    "chapter": null,
    "chapter_progress": null,
    "page": null,
    "total_pages": null
  },
  "annotations": {
    "highlights": []
  }
}

Progress Object

Field	Type	Description
`percentage`	float	Stored position as a book fraction.
`koreader_xpointer`	string	The stored canonical position converted back to a CRE xpointer (UTF-16 `text().N` offset). The device should navigate to this. Reflowable books only.
`epubcfi`	string	The stored canonical CFI, when the conversion to a CRE xpointer is unavailable. Fallback after `koreader_xpointer`.
`character`	int	Book-wide rune offset (internal currency).
`chapter`, `chapter_progress`	int, float	Chapter position when known.
`page`, `total_pages`	int	Fixed-layout page position — the canonical locator for image-based books (CFI/xpointer are omitted for them).

progress is null when the book has no stored progress.

The annotations object carries device-format highlights/bookmarks/notes synced from other clients; its presence depends on annotation sync being enabled.

Error Responses

Code	Description
400	Invalid book UUID
401	Device authentication failed
404	Book not found

2.4 KiB Raw Blame History