Files

T

John O'Keefe b10bf3e8c7 docs(api): real progress endpoint contract; remove nonexistent-endpoint docs

The progress documentation described GET/POST /api/progress/:id —
endpoints that do not exist in the router — while the endpoint every
client actually uses (GET/PUT/DELETE /api/media-items/:id/progress) had
no field-level docs at all.

New:
- progress/position-contract.md: the canonical position model — server
  as position authority, the three-tier submission (percentage /
  context_text / epubcfi), ingest verification and healing, the restore
  handles, the OPF spine numbering hazard (canonical CFI spine steps
  include linear="no" items; clients resolve documents by anchor_href
  and land by css_selector + char_offset, never by spine step), the
  offset currencies (UTF-16 at the wire, runes internal), and
  context_text rules.
- progress/get_media_progress.md and update_media_progress.md: the real
  endpoints with full field tables, conditionality of the restore
  handles, the first-page anti-clobber guard, and healed-response
  semantics.
- progress/delete_media_progress.md: the real DELETE route.
- koreader/sync_progress.md and koreader/get_metadata.md rewritten to
  the actual payloads: the plugin sends a single-book array whose
  "epubcfi" field is a CRE xpointer; the metadata response navigates
  via koreader_xpointer (canonical CFI converted back to CRE), with
  page as the canonical locator for fixed-layout books.

Removed: the five files documenting the nonexistent /api/progress/:id
GET/POST/DELETE endpoints. Kept get_progress_history.md (that route
exists). The legacy developer/api-reference.md and the indexed
api/api-reference.md progress sections now match the wire and link the
new docs; the duplicate "Universal Progress" section points at Reading
Progress.

2026-09-26 21:27:44 -04:00

2.2 KiB

Raw Blame History

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.2 KiB Raw Blame History