john-okeefe
d429534b12
Release / build-and-push (push) Successful in 2m24s
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.
85 lines
2.6 KiB
Markdown
85 lines
2.6 KiB
Markdown
# 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)
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{ "annotation_type": "highlight" }
|
|
```
|
|
|
|
### Response (200 OK)
|
|
|
|
```json
|
|
{ "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)
|
|
|
|
```json
|
|
{ "purged": true }
|
|
```
|
|
|
|
## Error Responses
|
|
|
|
| Code | Description |
|
|
| ---- | -------------------------------------------------- |
|
|
| 400 | Invalid IDs or missing/unknown `annotation_type` |
|
|
| 401 | Not authenticated |
|
|
| 404 | No matching deleted annotation |
|