John O'Keefe
ed0ce5d077
New frontmatter'd docs with real shapes (sqlc models pinned directly):
- bookmarks: get/create/update/delete (sync-aware rows: dedup_key,
last_modified_*, tombstones; delete is 204)
- review: upsert (empty string DELETES the review) / get (200 with
{review:null} when absent) / delete
- get single note + highlight (full sqlc row shapes)
- annotation history: restore (POST, kind via query or body) and purge
(DELETE, kind via required query; permanent)
Gate hardening forced by this batch:
- required-field walk now guards non-struct Request types (RawMessage pins)
- update_media_bookmark needed a full example block (no cross-reference
shortcuts — the gate checks every doc standalone)
37 lines
1.0 KiB
Markdown
37 lines
1.0 KiB
Markdown
---
|
|
method: DELETE
|
|
path: /api/media-items/:id/annotations/:annotationId
|
|
auth: jwt
|
|
area: media-items
|
|
---
|
|
<!-- source: internal/handlers/annotation_history.go:101 MediaHandler.PurgeDeletedAnnotation -->
|
|
|
|
# Purge Deleted Annotation
|
|
|
|
**Permanent** — removes a tombstoned annotation from history entirely. Kind
|
|
comes from the required `annotation_type` query parameter
|
|
(`highlight` | `note` | `bookmark`; no body fallback on DELETE).
|
|
|
|
## Example request
|
|
|
|
```text
|
|
DELETE /api/media-items/550e8400-.../annotations/440e8400-...?annotation_type=highlight
|
|
```
|
|
|
|
## Example response
|
|
|
|
```json example-response
|
|
{
|
|
"purged": true
|
|
}
|
|
```
|
|
|
|
## Errors
|
|
|
|
| Status | Body | When |
|
|
| ------ | ---- | ---- |
|
|
| 400 | `{"error": "annotation_type must be highlight, note, or bookmark"}` | missing/invalid kind |
|
|
| 404 | `{"error": "deleted annotation not found"}` | nothing tombstoned under that id |
|
|
| 500 | `{"error": "failed to purge annotation"}` | unexpected server error |
|
|
| 503 | `{"error": "annotation service unavailable"}` | service not constructed |
|