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

Header Parameters

authorization

x-api-key

Query Parameters

q*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/library/ask

Playground

Headers

authorization

x-api-key

Variables

Key

Value

q*

Samples

---

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

Header Parameters

authorization

x-api-key

Request Body

application/json

{

  

"additionalProperties": "string"

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/library/playlist/generate

Playground

Headers

authorization

x-api-key

Body

Samples

---

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

Header Parameters

authorization

x-api-key

Request Body

application/json

{

  

"additionalProperties": "string"

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/library/playlist/create

Playground

Headers

authorization

x-api-key

Body

Samples

---

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

Header Parameters

authorization

x-api-key

Query Parameters

limit

Type

integer

Default

0

Responses

Successful Response

Content-Type

application/json

[

  

{

  

  

"additionalProperties": "string"

  

}

]

GET

/library/genres

Playground

Headers

authorization

x-api-key

Variables

Key

Value

limit

Samples

---

List Library Artists

GET

/library/artists

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

sort

Type

string

Valid values

"recent""name""source_count"

Default

"recent"

filter

genre

page

Type

integer

Default

1

page_size

Type

integer

Default

50

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/library/artists

Playground

Headers

authorization

x-api-key

Variables

Key

Value

sort

filter

genre

page

page_size

Samples

---

List Library Albums

GET

/library/albums

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

sort

Type

string

Valid values

"recent""name""source_count"

Default

"recent"

filter

genre

page

Type

integer

Default

1

page_size

Type

integer

Default

50

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/library/albums

Playground

Headers

authorization

x-api-key

Variables

Key

Value

sort

filter

genre

page

page_size

Samples

---

List Library Tracks

GET

/library/tracks

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

sort

Type

string

Valid values

"recent""name""source_count"

Default

"recent"

filter

genre

page

Type

integer

Default

1

page_size

Type

integer

Default

50

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/library/tracks

Playground

Headers

authorization

x-api-key

Variables

Key

Value

sort

filter

genre

page

page_size

Samples

---