John O'Keefe
4a6fb033cb
New frontmatter'd docs:
- download (ServeFile — raw bytes, family-lens enforced; corrects the old
download doc's claim that no download route is registered: ServeFile IS
routed, DownloadBook is the dead code)
- set_audio_speed (speed range 0.25-4.0, NaN/Inf rejected)
- rescan (abridged example over the full 70+-column row; write-after-success
guarantee noted)
- purge-archived (destructive, admin), unarchive (204), merge (SHA-256
precondition, per-user collisions keep active copy)
- facets (two modes: facet+values, field autocomplete counts)
- filter_count (family lens)
Registry: RawMessage pins for map/abridged responses; Schema{} for non-JSON
body routes (download = raw bytes; unarchive = 204). Audit now:
missing docs down to ~55 (from 112), 0 orphans.
1.3 KiB
1.3 KiB
method, path, auth, area
| method | path | auth | area |
|---|---|---|---|
| GET | /api/media-items/facets | jwt | media-items |
Get Media Item Facets
Two modes, both returning small JSON objects:
- Facet values (primary):
?facet=<param>&library_id=<uuid>— lists the distinct values of a facet within one visible library. - Autocomplete counts:
?field=<key>&library_id=<uuid>— returns{"facets": {...}}value counts for dropdowns.
Example response
{
"facet": "author",
"values": [
{
"value": "George Orwell"
}
]
}
UNVERIFIED: exact element shape of values (service-returned rows).
Query parameters
| Param | Type | Notes |
|---|---|---|
| facet | string | facet param name; requires library_id |
| field | string | registry field key (autocomplete mode) |
| library_id | uuid | required for facet mode; must be visible to the requester |
| limit | number | caps facet values |
Errors
| Status | Body | When |
|---|---|---|
| 400 | {"error": "library_id is required"} / {"error": "unknown facet: ..."} / {"error": "facet does not list values: ..."} / {"error": "invalid library_id"} |
bad params |
| 403 | {"error": "library not visible"} |
family lens |
| 500 | {"error": "..."} |
unexpected server error |