GET /api/v1/albums/{id}/tracklist # Token reador Session
The record's own tracklist, including tracks never played.
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.
Responses
application/json
object
The record as MusicBrainz has it, including tracks you have never played.
Nothing is stored.
mbid_release string | null
year integer | null · int64
tracks array required
A CD is one side, a double LP four.
each item object
One track on a physical side.
side string required
"A", "B", "C"… Cassettes have two, a double LP four.
position integer · int64 required
Position within the side, from 1.
duration_secs integer | null · int64
disc integer | null · int64
Which physical disc of the set this track is on, from 1.
Null means nobody recorded which disc, not disc 1.
mbid_recording string | null
The MusicBrainz ids the release lookup returns for this track — the
recording, and this track on this release. Kept on the tracklist (a
JSON blob, so no migration) and carried onto every listen of the side.
mbid_release_track string | null
artists array | null
Everyone the track credits, in order, with their MBIDs — set only when
MusicBrainz credits the track itself (it does whenever the track's
artist differs from the release's).
400 That entity is not an album.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
404 No matching release, or no such album.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
502 MusicBrainz could not be reached.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
GET /api/v1/artists/{id}/dossier # Token reador Session
Your history with one artist.
Scope: read. When they took off, whether they are a habit or a burst,
the days, months and hours they were played, their longest runs and
album playthroughs, and how often they were your number one. Local days and
weeks, by your timezone and week start.
Every count of their listens comes with the count of all listens over the
same window, both skip-free; capped says that window is the most recent
part of a history longer than the instance reads for analytics.
Parameters
id path required
The artist's entity id, from GET /api/v1/resolve.
Responses
application/json
object
plays integer · int64 required
Their skip-free listens in the window.
all_plays integer · int64 required
Everyone's — the population every share here is of.
days integer · int64 required
Local days they were played on.
all_days integer · int64 required
Local days with any listening.
first integer | null · int64
last integer | null · int64
took_off string | null
The local day (YYYY-MM-DD) your listening to them stepped up —
step.date, kept as its own field for the clients that read it.
Absent under twenty listens, or without a clear step up.
step object | null
The step itself, with the rates either side. Absent like took_off.
date string required
YYYY-MM-DD, local: the first day at the new rate.
before_per_week number · double required
Their listens a week before that day.
after_per_week number · double required
habit object | null
Absent under five listens, where there is no pattern to score.
return_rate number · double required
Days they were played, over the days from their first listen to their
last.
span_coverage number · double required
How much of the whole window those first and last listens span.
top_day_share number · double required
The share of their listens that fell on their single biggest day.
score number · double required
0–100; high is a habit, low a burst.
daily array required
Every day they were played, oldest first.
each item object
A day, as the local midnight it began at (Unix seconds).
day integer · int64 required
date string required
The same day as YYYY-MM-DD in your timezone. A browser elsewhere
would put day on the wrong date; lay out by this.
plays integer · int64 required
all integer · int64 required
Every listen that day — the population plays is a share of.
months array required
Every month from their first to the last of the history, oldest first,
including months they were not played in.
each item object
plays integer · int64 required
all integer · int64 required
weeks array required
Every week of the history, oldest first, including weeks they were
not played in.
each item object
A week, by the local date it began on (your first day of the week).
week string required
YYYY-MM-DD, local: the week's first day.
plays integer · int64 required
all integer · int64 required
Every listen that week — the population plays is part of.
rivals array required
Your five most-played other artists across the same weeks.
each item object
One of your other most-played artists, week by week, to set this one
against.
plays integer · int64 required
Credited listens over the whole window.
weekly array required
Credited listens per week, aligned with Dossier::weeks.
next object required
Who you play next after them.
total integer · int64 required
Times one of their listens was followed, within a quarter of an hour,
by somebody else's — the population each plays below is part of.
artists array required
Most often first. A listen crediting two artists counts for both, so
these can add up to more than total.
each item object
plays integer · int64 required
clock array required
7 × 24, rows Sunday first like the Statistics heatmap; the page
rotates them by week_start.
week_start integer · int32 required
First day of the week, 0 = Sunday.
top_days array required
each item object
A day, as the local midnight it began at (Unix seconds).
day integer · int64 required
date string required
The same day as YYYY-MM-DD in your timezone. A browser elsewhere
would put day on the wrong date; lay out by this.
plays integer · int64 required
all integer · int64 required
Every listen that day — the population plays is a share of.
runs array required
The three longest runs, longest first.
each item object
Their listens back to back, nobody else in between and no half-hour
silence.
start integer · int64 required
end integer · int64 required
playthroughs array required
Up to ten, most tracks first.
each item object
One of their records played in order — track N, then N+1, … — in one
sitting.
start integer · int64 required
date string required
Local YYYY-MM-DD of start.
first_track integer · int32 required
last_track integer · int32 required
months_at_top object required
Is somebody your number one, and how often.
periods integer · int64 required
Periods in which they had the most listens (ties included).
of integer · int64 required
Periods with any listening at all.
weeks_at_top object required
Is somebody your number one, and how often.
periods integer · int64 required
Periods in which they had the most listens (ties included).
of integer · int64 required
Periods with any listening at all.
capped boolean required
The instance caps analytics reads and this history is longer than the
cap: everything above describes only the most recent part of it.
400 That entity is not an artist.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
404 No such resource, or it belongs to another user.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
PUT /api/v1/albums/{id}/cover # Session
Override an album cover.
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.
Request body required
application/json
object
url string required
An http(s) URL, or a path on this server such as
/api/v1/artists/img/12 or /api/v1/art/914 — which is how you point
at your own library through the proxy. Empty clears it.
Responses
200 Saved. Null when cleared.
application/json
object
An album cover, set or cleared. Null when cleared — the page then falls
back to the cover from your listens.
artwork_url string | null
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
404 No such album, or that entity is not a release.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
GET /api/v1/art/upload/{name} # Token reador Session
Serve an uploaded picture.
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.
Parameters
name path required
As it appears in the stored URL.
Responses
200 Image bytes, Cache-Control: private, immutable.
image/*
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
404 No such picture, or the file is no longer on this server.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
POST /api/v1/albums/{id}/cover/upload # Session
Upload an album cover.
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.
Request body required
multipart/form-data
object
A multipart/form-data upload of one file.
The server takes the first file part whatever its field name; file is the
name to use. Its declared Content-Type decides how the file is stored — a
filename from the client never reaches a path on disk.
file string · binary required
Responses
200 Saved. The body carries the new URL, which is a path on this server.
application/json
object
An album cover, set or cleared. Null when cleared — the page then falls
back to the cover from your listens.
artwork_url string | null
400 Malformed or rejected input.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
404 No such resource, or it belongs to another user.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
415 Not an image type this server stores (JPEG, PNG, WebP, GIF, AVIF, TIFF).
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
GET /api/v1/art/library # Token writeor Session
Does this album already have a cover?
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.
Responses
200 Whether a cover is already held.
application/json
object
Whether the album already has a cover.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
403 Authenticated, but not permitted. Either the token lacks the required
scope, or the endpoint needs the admin role. Deliberately not a 401 —
re-authenticating will not help.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 403,
"error": "This token does not have the 'write' scope"
}
POST /api/v1/art/library # Token writeor Session
Offer a cover read from the client's own files.
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.
Request body required
multipart/form-data
object
A cover a player read off its own files, offered as multipart/form-data.
artist string required
The album's artist, as you would submit it.
album string required
The album, as you would submit it.
file string · binary required
The image. Its declared Content-Type decides how it is stored.
release_mbid string | null
Accepted and not read — the cover is keyed on names like every other
album query. Send the MBID on a listen's additional_info instead.
Responses
application/json
What became of an offered cover.
one of option 1 object
Something filled the cover since the client asked; nothing was stored.
already_held boolean required
option 2 object
artwork_url string required
Where the stored picture is served from.
listens_covered integer · int64 required
Your listens of the album that now carry it.
400 No image, or a blank artist or album.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
403 Authenticated, but not permitted. Either the token lacks the required
scope, or the endpoint needs the admin role. Deliberately not a 401 —
re-authenticating will not help.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 403,
"error": "This token does not have the 'write' scope"
}
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
415 Not an image type this server stores.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
GET /api/v1/artists/{id}/pictures # Session
Every picture on offer for one tab of the picker.
Session-only. Asks each of your enabled media servers — Plex's poster or
background list, Jellyfin's and Emby's held images plus the ones they can
find online, Navidrome's artist picture — and, for a portrait, Deezer. The
servers are asked at once, with ten seconds each; one that does not answer
is named in unreachable rather than failing the list.
Library tiles preview through this server, since the browser cannot reach
your servers. Online finds and Deezer's are public URLs and load directly.
Parameters
id path required
The artists row — artist_row_id on an artist page.
kind query
portrait (the default) or wide.
Responses
application/json
object
Everything the picker draws for one tab.
current object | null
What you chose, if anything. Null means you see the shared picture.
source string required
upload, link, deezer, plex, jellyfin, emby or navidrome.
source_ref integer | null · int64
source_label string | null
The server's label for a library choice; null otherwise.
shared_url string | null
The picture everyone sees who has not chosen one — what the backfill
found. Null when it found nothing.
candidates array required
each item object
source string required
plex, jellyfin, emby, navidrome or deezer.
source_ref integer | null · int64
The connected server it came from; null for Deezer.
source_label string required
What to call that source on the tile — the server's own label.
provider string | null
The outside provider a server found it through, when it says
(TheAudioDB, fanart.tv, a Plex agent).
key string required
Opaque. Send it back unchanged to choose this picture.
preview string required
What to draw on the tile.
width integer | null · int64
height integer | null · int64
server_selected boolean required
The server itself currently shows this one.
chosen boolean required
This is the picture you chose.
unreachable array required
Sources that did not answer, by label, so the picker can say why a
server's pictures are missing rather than looking empty.
400 Malformed or rejected input.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
404 No such resource, or it belongs to another user.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
PUT /api/v1/artists/{id}/pictures/{kind} # Session
Choose a picture.
Session-only. Only you see it; everyone else keeps their own choice or
the shared picture.
Send back a candidate's source, source_ref and key from
GET /api/v1/artists/{id}/pictures, or {"source": "link", "key": "https://…"}
for a URL of your own. A key is checked against the shape that source
offers, so a made-up one is a 400 rather than a request to your server.
Uploads have their own route.
Request body required
application/json
object
Choose a picture: a candidate from the list, or a link.
source string required
A candidate's source, or link for a URL of your own.
source_ref integer | null · int64
A candidate's source_ref. Required for a library source.
key string required
A candidate's key, or the URL for link.
Responses
200 Chosen. The body carries what the browser should load.
application/json
object
What you see now. Null when nothing is left to show.
400 Malformed or rejected input.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
404 No such resource, or it belongs to another user.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
POST /api/v1/artists/{id}/pictures/{kind}/upload # Session
Upload a picture and choose it.
Session-only. Same rules as every upload here: up to 8 MB, the extension
from the declared content type, a random name per file. Only you see it,
and it is deleted when you choose something else.
Request body required
multipart/form-data
object
A multipart/form-data upload of one file.
The server takes the first file part whatever its field name; file is the
name to use. Its declared Content-Type decides how the file is stored — a
filename from the client never reaches a path on disk.
file string · binary required
Responses
200 Saved and chosen. The URL is a path on this server.
application/json
object
What you see now. Null when nothing is left to show.
400 Malformed or rejected input.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
404 No such resource, or it belongs to another user.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
415 Not an image type this server stores (JPEG, PNG, WebP, GIF, AVIF, TIFF).
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.