Appearance
library
7 endpoints at a glance
| Method | Path | Summary |
|---|---|---|
GET | /library/albums | List Library Albums |
GET | /library/artists | List Library Artists |
GET | /library/ask | Library Ask |
GET | /library/genres | List Library Genres |
POST | /library/playlist/create | Library Create Playlist |
POST | /library/playlist/generate | Library Generate Playlist |
GET | /library/tracks | List Library Tracks |
library
Library Ask
GET
/library/ask
Interpret a plain-language library request into query params.
Translates e.g. "hi-res jazz albums I haven't played in two years"
into the kind / sort / filter / genre / q params the
/library/{kind} endpoints already accept — the model returns
filters, never entity names, and every value is validated against
the same enums the router enforces.
Always 200. state is ok (with query), not_configured
(no DeepSeek key — the SPA hides the ask-bar) or failed (upstream
hiccup — the SPA keeps the manual filter controls). Never a 500: this
is an assist on top of a working UI, not a dependency of it.
Parameters
Query Parameters
q*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Library Generate Playlist
POST
/library/playlist/generate
Propose a playlist from the user's OWN library (roadmap #2).
Body: {"request": str, "genre": str|null, "max_tracks": int}.
Retrieval-first — we hand the model only playable canonical tracks and
it returns indexes into that list, so it cannot introduce music we
don't own. Every returned index is validated back to a canonical id.
This only proposes; nothing is written to Plex until the client
confirms via /library/playlist/create. Always 200 with a state
(ok / not_configured / no_candidates / failed).
Parameters
Request Body
application/json
JSON "additionalProperties": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Library Create Playlist
POST
/library/playlist/create
Materialise a confirmed proposal as a Plex playlist.
Body: {"title": str, "canonical_track_ids": [str, ...]} — the ids
come straight from a /generate proposal the user accepted, so the
write path never trusts model output directly.
Parameters
Request Body
application/json
JSON "additionalProperties": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
List Library Genres
GET
/library/genres
Distinct canonical genres present in the library + album counts.
Aggregated over canonical albums (genres live at the album level —
the per-track signal is sparse), newest-merged excluded, sorted by
count desc. Powers the Genres page: each genre filters the Library
(?genre=) and can seed a genre radio. Declared before the
/library/{kind} routes are matched (all literal, so order is
moot, but kept adjacent for clarity). limit 0 = all.
Parameters
Query Parameters
limit
Type
integer
Default
0Responses
Successful Response
application/json
JSON { "additionalProperties": "string" }
[
]