Every endpoint exposed by the FastAPI app. All routes require authentication unless noted. Roles: read < write < admin.
Authentication is via Authorization: Bearer <token>. Get a token from POST /api/auth/login (username + password). The bearer token TTL is AUTH_ACCESS_TTL (8 h default). Refresh via POST /api/auth/refresh with a refresh token (TTL AUTH_REFRESH_TTL, 30 d default).
{username, password} → {access_token, refresh_token, expires_in, user}. Also sets the refresh token as the HttpOnly pf_refresh cookie (FP-1)
POST
/api/auth/refresh
none
Reads the refresh token from the HttpOnly pf_refresh cookie, falls back to a {refresh_token} body. Rotates the refresh token (P-02) and re-sets the cookie → new {access_token, refresh_token, user}
POST
/api/auth/logout
bearer
Revoke the access token and the HttpOnly refresh cookie's token (F-08), then clear the cookie
Without a valid access token: now and bridge reachability only. With one: library stats, indexer state, disk usage and config (footer + ? overlay data).
Update the schedule ({enabled, hour, minute, keep}); 400 with the rejected field names on invalid values
POST
/api/admin/checks
admin
Run the seven health checks on demand
POST
/api/admin/people/gc-empty
admin
Delete anonymous, face-less placeholder people rows ({deleted: N, ok: true}); idempotent sweep, never touches named people
POST
/api/admin/people/prune-small
admin
Retroactively apply MIN_CLUSTER_SIZE: body {min_photos?, dry_run?}; deletes anonymous clusters with fewer photos than the threshold, releasing their faces to the unassigned queue. dry_run: true returns candidate_count only. Named people are never touched.
POST
/api/admin/db/compact
admin
VACUUM the SQLite index and truncate the WAL; returns before_bytes, after_bytes, reclaimed_bytes. 409 while the indexer holds the write lock.