John O'Keefe
e21e1facde
All remaining endpoint docs frontmatter'd: media-item bulk ops + audio surface, collections book-listing/preview, koreader rating/review/stats plugin protocol, hash-conflicts JSON list. Scope call (Claude): resolve_hash_conflict.md DELETED — the resolve POST renders an htmx fragment (renderResolved), a web-admin flow under rule 3; only the GET list is a JSON API. update_media_review skipped by Beam (correct): ratings/upsert_media_review.md already covers the PUT. Registry: 16 entries. koreader rating/review/stats all bind koreaderBookRef (query or body) — odd=half-star rating scale; audio track endpoint serves raw bytes (ServeContent, Range) — response nil. Fixed drift: deleted_annotations doc's secondary restore/purge fences unlabeled (gate validates labeled blocks against the ONE frontmatter route); chapters example labeled. UNVERIFIED: 1 (koreader book-ref fields, push_stats). make test 9/9.
2.8 KiB
method, path, auth, area
| method | path | auth | area |
|---|---|---|---|
| GET | /api/media-items/:id/annotations/deleted | jwt | media-items |
Deleted Annotations History
List, restore, or permanently delete tombstoned annotations (highlights, notes, bookmarks) for a book. Deletions — from the web or propagated from a synced device — are soft-deleted and retained for the sync retention window (default 30 days), powering the book page's "Recently deleted" list. A restore returns the row to the active set on every synced device; a purge removes it immediately and irreversibly.
All endpoints require user JWT authentication and operate only on the caller's own annotations.
List Deleted Annotations
Endpoint: GET /api/media-items/:id/annotations/deleted
Returns tombstoned annotations for the book, newest deletion first.
Response (200 OK)
{
"deleted_annotations": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"annotation_type": "highlight",
"display_text": "the chosen text",
"secondary_text": "user note",
"color": "#ffd54f",
"deleted_at": "2026-08-22T15:04:05Z",
"created_at": "2026-08-01T10:00:00Z"
}
],
"total": 1
}
| Field | Description |
|---|---|
| annotation_type | highlight, note, or bookmark |
| display_text | Highlighted text / note content / bookmark title |
| secondary_text | Note text (highlights) or notes field (bookmarks) |
Restore Deleted Annotation
Endpoint: POST /api/media-items/:id/annotations/:annotationId/restore
Body (or query param) annotation_type must be highlight, note, or
bookmark. Clears the tombstone; the annotation reappears in the active
set and re-syncs to devices on their next pull.
{ "annotation_type": "highlight" }
Response (200 OK)
{ "restored": true }
404 when no matching deleted annotation exists for this user and book.
Permanently Delete Annotation
Endpoint: DELETE /api/media-items/:id/annotations/:annotationId?annotation_type=highlight|note|bookmark
Removes the tombstoned row from the history immediately. Irreversible — unlike the tombstone itself, which is restorable until the retention window lapses and the daily maintenance sweep purges it.
Response (200 OK)
{ "purged": true }
Error Responses
| Code | Description |
|---|---|
| 400 | Invalid IDs or missing/unknown annotation_type |
| 401 | Not authenticated |
| 404 | No matching deleted annotation |