Library

Scope: read (since v0.120). Aggregated over scrobbles by name. Track rows carry the raw quality columns, not a formatted label — the client formats them, so a server-side copy of that logic cannot drift.

An entity with zero plays still renders rather than 404ing: something annotated once and since deleted from the history is still a real record.

Scope: read (since v0.120). Everything else on the album page is aggregated from listens, so a record played twice renders as a two-track record. This asks MusicBrainz what is actually on it.

Nothing is stored. The caller matches these against the plays it already holds; writing a tracklist into scrobbles would invent listens that never happened. It is a separate call rather than part of /api/v1/albums/{id} because it costs a rate-limited request to an external service and the page must render without one.

The release is chosen in order: the entity's own MBID, then the release MBID a plurality of the album's listens claim (a tagger works per track, so one listen in twelve routinely carries a compilation's), then a search, which is a guess.

404 is a normal answer — a great deal of any real library is not in MusicBrainz, and those are exactly the records worth keeping.

Scope: read (since v0.120). Same shape and same rules as the album page.

Scope: write (since v0.120), although it is a GET, because it creates the entity on first visit — a write on a read path, on purpose. The browser knows names, not ids, so without this every link out of the history would be dead until you happened to annotate the thing it points at. POST /api/v1/notes/preview takes write for the same reason.

Scope: read (since v0.120). Proxies the user's own library server, which the browser usually cannot reach and must not hold credentials for.

Scope: read (since v0.120).

Session-only. A manual override beats every provider — this is a journal, and whoever keeps it gets the last word.

Session-only. Takes the artist row id (artist_row_id on the artist page), not the entity id — the artists row is keyed by name and shared across users, which is what the portrait proxy addresses too.

A different photograph from the portrait rather than a crop of it: the Reports chapter tile is 16/11, where a square either pillarboxes or crops the head off. Nothing Tapedeck can reach supplies a landscape, so it is present only where the user chose one, and a chapter with none keeps the enormous faint initial — that is the design, not a placeholder.

An empty string clears it.

Session-only. The counterpart of the artist portrait override: an album otherwise wears whatever artwork the newest listen of it happens to carry, which is unfixable when it is the wrong edition's.

400s when the id is not a release entity — an artist's picture has its own endpoint, and two places to set one would leave no rule about which wins. Like every entity write, this is not scoped per user: entities is shared.

Scope: read (since v0.120). Cached private, immutable — the name is random per upload, so the bytes behind a given URL never change.

name is validated, not trusted: it must be exactly the 24 hex characters this server generates plus a known image extension. The override columns accept any /-prefixed string, so a route that read a path out of one would serve arbitrary files from the uploads directory.

Session-only. The counterpart of the PUT above, for a picture that is on your disk rather than already somewhere on the web.

The extension is taken from the declared content type, never from the filename — the path is one this server writes. The stored name is random, so the served URL is immutable-cacheable and a replaced picture is a new URL rather than the same URL with new bytes.

Replaces the override exactly as a pasted URL does, and the file it supersedes is deleted. artists carries no user column, so this is an instance-wide edit.

Session-only. Same rules as the portrait upload.

This is the one image override nothing can fill automatically — no provider Tapedeck reaches supplies a landscape — so before this it was a URL or the big initial.

Session-only. Same rules as the artist uploads. Takes an entity id.

Replaces the derived cover the way the PUT does, so the page still offers Reset (back to whatever the listens carry) rather than Clear. Entities are shared, so this is an instance-wide edit.

Scope: write.

The precondition of an upload, so the common case costs one small GET rather than a megabyte of JPEG. A client reads the picture off disk only when this answers false.

write, not read — this exists only to decide a write, and requiring read would force a scrobbling token that wants to offer a sleeve to carry read access to the whole listening history as well.

held is true when any listen of this album carries artwork (a Cover Art Archive id counts, -1 excluded), or when a cover has been set by hand on the album — one set that way is what the album page prefers over everything else, so answering false would invite a picture that would never be shown.

Deliberately not album_artwork's question, which excludes skips because its job is choosing a cover to display. An album whose only listens are skips would otherwise answer "nothing held" for ever and the same sleeve would be re-uploaded on every run.

Creates nothing. GET /api/v1/resolve would mint the entity as a side effect of being asked, which is right for a browser about to annotate something and wrong for a player asking whether to bother.

Scope: write.

Writes scrobbles.artwork_url on every listen of this album that has none, and nothing else. That column is the artwork backfill's queue and the album page reads it back, so a sleeve arriving with the listens is exactly what a Plex-sourced listen carries. A cover override would claim somebody set it by hand, and nobody did.

Rows holding the artwork_url = '' tombstone are filled too, and that is the point rather than an oversight: the tombstone means "asked every provider, nobody had a picture", and the premise here is that the listener's own file does. Skipped listens are filled as well — artwork is not a count.

The held check runs again before the bytes are written, so a cover that arrived between the GET and this costs no file on disk and is reported rather than treated as an error.

Scope: read (since v0.39). Needed to render a note's target.