john-okeefe
d429534b12
New media-items/deleted_annotations.md for the list/restore/purge endpoints; endpoint index updated. The KOReader protocol page documents deleted_highlights/deleted_bookmarks on the progress push and the deletion-propagation contract: keys learned only from server pulls, explicit arrays only (never absence), tombstone convergence via the metadata fetch, no resurrection from stale replays, and the web history as the restore path.
2.6 KiB
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 |