John O'Keefe
85cdaf7196
New frontmatter'd docs with handler-compatible shapes:
- get_library_types.md (public; []LibraryTypes)
- list_libraries.md (admin; {data: ListLibrariesRow})
- get_library_folders.md (admin; []LibraryFolders)
- list/get stats/resolve/delete processing issues (admin; family-lens 403s
documented)
- scan_library.md (202 + 409 coalescing with active_job_id)
- get/update scan-settings (ScanSettingsResponse)
Gate improvements forced by this batch:
- Array responses: registered slice -> doc example must be a JSON array; key
set compared against the element type
- RawMessage pins may now be arrays
- update scan-settings uses a RawMessage pin: handler always sets Message but
the struct's omitempty would reject correct docs via zero-value marshal
Registry: sqlc models pinned directly (LibraryTypes, LibraryFolders,
ListLibrariesRow — json tags verified in the generated code).
1.2 KiB
1.2 KiB
method, path, auth, area
| method | path | auth | area |
|---|---|---|---|
| POST | /api/libraries/:id/scan | jwt+admin | libraries |
Scan Library
Enqueues a full scan of one library's configured folders. The library id comes
from the path — no request body is needed (the generic POST /api/scanner/scan
variant is the one that takes folder_paths).
Scans are coalesced: if a scan for this library is already pending or running you get 409 with the active job id instead of a second scan.
Example response (202 Accepted)
{
"message": "scan job enqueued",
"job_id": "dd0e8400-e29b-41d4-a716-446655440000",
"status": "pending"
}
Errors
| Status | Body | When |
|---|---|---|
| 400 | {"error": "invalid library id"} / {"error": "library has no folders configured"} |
malformed id / empty library |
| 404 | {"error": "library not found or has no folders"} |
unknown library |
| 409 | {"error": "a scan for this library is already pending or running", "active_job_id": "..."} |
scan coalescing |
| 500 | {"error": "failed to enqueue scan job: ..."} |
queue failure |