John O'Keefe
fa00d6d3cb
Beam drafted 15 frontmatter'd docs (saved-filters CRUD, dashboard
sections/preferences/restore, system config/settings, series list + books);
Claude verified shapes against handlers and pinned the registry:
- saved-filters: SavedFilterResponse pinned by type (RFC3339 timestamps here,
unlike most of the API); create/update share CreateSavedFilterRequest
(resource_type oneof media-items|collections|devices)
- dashboard: preferences GET pin {hidden_collections, collection_order,
items_per_section}; PUT returns full UserDashboardPreferences row; sections
wrapper {sections}
- system: GET+PUT /api/system/config are admin-defined key/value maps — new
AnyJSONObject sentinel (gate shape-checks without key comparison; request
side too). UpdateSystemConfiguration returns {status, message} — verified,
not guessed. GET /api/system/settings returns []SettingEntry.
- series: {series[{name, library_id, book_count, total_in_series,
cover_paths, last_entry_at}], total, limit, offset}; books by
?name=&library_id= with family-lens 403
Dedupe: deleted dashboard.md, system/config.md, system/settings.md — each
covered the same endpoints as Beam's per-endpoint files (content merged by
the gate-verified shapes; old prose recoverable from git).
Beam clarifications confirmed: scanner routes are WO5 (docs exist);
progress/books-match are WO5.
1.5 KiB
1.5 KiB
method, path, auth, area
| method | path | auth | area |
|---|---|---|---|
| PUT | /api/dashboard/preferences | jwt | dashboard |
Update Dashboard Preferences
Saves or updates the signed-in user's dashboard preferences for a library.
Example request
{
"library_id": "550e8400-e29b-41d4-a716-446655440000",
"hidden_collections": ["not-started"],
"collection_order": ["recently-added", "continue-reading", "recently-read"],
"items_per_section": 20
}
Example response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"user_id": "550e8400-e29b-41d4-a716-446655440000",
"library_id": "550e8400-e29b-41d4-a716-446655440000",
"hidden_collections": ["not-started"],
"collection_order": ["recently-added", "continue-reading", "recently-read"],
"items_per_section": 20,
"created_at": "2026-10-24T13:57:01Z",
"updated_at": "2026-10-24T13:57:01Z"
}
Fields
| Field | Type | Required | Notes |
|---|---|---|---|
| library_id | string (uuid) | No | null/absent = global scope; empty string is rejected |
| hidden_collections | array | No | Collection ids to hide |
| collection_order | array | No | Ordered list of collection ids |
| items_per_section | int | No | Items per section |
Errors
| Status | Body | When |
|---|---|---|
| 400 | {"error": "Invalid request"} / {"error": "invalid library_id"} |
malformed body or library_id |
| 500 | {"error": "Failed to save preferences"} |
unexpected server error |