Listens

Scope: read (since v0.39). Newest first. Filterable.

Session-only and irreversible. Deliberately not reachable with a write token — this is the one listen operation where a lost phone would be unrecoverable. Clears listen-attached notes first, since foreign keys are enforced.

Scope: write (since v0.39). Only the caller's own rows.

Scope: write (since v0.39). Clears attached notes first.

An offset over a selection, not an absolute time, and that is the design rather than a limitation. A timestamp is almost never wrong on its own: a clock was out by an hour, an evening was reconstructed from times laid out by arithmetic, or a capture arrived carrying somebody else's clock. Every one of those moves a run of listens by a constant, and a constant cannot scramble an ordering the way a set of hand-typed times can. Correcting a single listen is this operation over one id — subtract to get the offset.

Where the listen has not been accepted yet, PATCH /api/v1/patch/captures/{id} is the cheaper place to do it: nothing is in a history there, so none of the consequences below apply.

What it takes care of:

• timestamp_original is written once, so a second correction does not overwrite the observation the first one replaced.
• Nothing is moved on top of another listen of the same track. Dedup runs at ingest and never again, so a duplicate created here is one nothing will ever reconcile. Such a listen is skipped and is not counted in moved.
• Sessions are recomputed — their aggregates, not their grouping.

What it reports, because it cannot fix them:

• already_forwarded — how many of the moved listens had already gone to Last.fm or ListenBrainz. Neither has an edit API, so their copy keeps the time it was sent with, permanently and silently. The edit is still right; a screen that did not say this would let somebody believe they had corrected a public record they had not.
• grouping_stale — whether a moved listen now sits further from its session's neighbours than the gap those sessions were grouped by. Sessions are stored rather than computed, which is what lets a manual merge survive, and sessions.uuid is what a handed-over sitting points at — so re-grouping silently on a time edit would move an identity somebody else holds a reference to. Rebuild stays something the user asks for.

Session-only. Records who you were listening with, on the listens themselves.

Marking is retroactive by design: nobody stops mid-record to note who is in the room. A Shared Spool fills the same column in automatically from its joined members; this is for the commoner case of somebody in the room who has no account on this instance, which is why it is free text rather than a list of users.

It is stored on the listen and not on the session, which is not a preference — POST /api/v1/sessions/rebuild deletes every session row and re-inserts it, so anything held there is erased by a regroup with nothing to say so.

company is required. Send an explicit null to unmark; an absent field is a 400, for the reason signal_chain_id on /api/v1/scrobbles/bulk-chain is — this overwrites the field on every listen in ids, so a misspelled key must not deserialise into "clear it". An empty or whitespace-only string is treated as null rather than becoming a listen marked as heard with nobody.

This never writes joint_session_id. That column says this exact play happened on several decks at once, which only a Shared Spool can know.

Session-only. Retro-attribution after adding gear — and since v0.46.0 the chain's hours follow the listens, so doing this moves the usage numbers for listening you already have rather than only for future plays.

The field is signal_chain_id, and it is required. This entry documented it as chain_id for several releases, alongside three parameters (from, to, source_name) the handler has never accepted — and the mismatch was silently destructive rather than an error: the body deserialised cleanly with the field missing, which meant "clear the chain", so a client following the spec wiped the attribution on every listen in ids and got 200 {"updated": N} back. An absent field is a 400 now.

Send an explicit null to clear. That case is real — it is how the History bulk edit removes a chain — which is why absent and null cannot be collapsed.

Scope: read (since v0.120). Searches scrobbles, not entities — searching entities would only find records you had already been to.

Scope: read (since v0.120). Skips are stored but excluded from every listening figure, so this is the only place they are readable.

listened_ms is how far in the listener got, and is null when nothing measured a playhead — a polled server reports one, a submitting client often does not. listened_fraction is derived only when both the playhead and the running time are known, rather than estimated.

played_before / played_after are the nearest real listens either side, which is the only context this application can honestly record for a skip. Both are null for a skip at the edge of a sitting. Nothing here says why a track was skipped and nothing should infer it.

Scope: read. In-memory only. Entries expire on read — past duration

• 10s, or after 10 minutes when the source reported no duration.

Unauthenticated — the one route that publishes someone's listening without a credential. It exists because a static site renders long before anyone visits it, so a live now-playing widget must be fetched from the reader's browser, where no credential of the owner's can safely go.

Sends Access-Control-Allow-Origin: * and Cache-Control: public, max-age=5. A GET with no custom headers is a CORS simple request, so there is no preflight and no OPTIONS.

A username that does not exist and one that has not published return the same 404. Anything that told them apart would make this a membership oracle for a private, invite-only instance.

Everything past title/artist/album appears only if its owner ticked it — see the publish switch above. An absent field means "not published" or "not known"; the two are deliberately not distinguished.

Session-only. A token gets 401 — the endpoint does not accept one at all, so scopes never enter into it. A scrobble client has no business deciding that its owner's listening is public.

Session-only. enabled is required — a body that merely misspelled the key must not be read as an answer either way, because getting this one wrong is published rather than merely wrong.

fields names the extra disclosures beyond title/artist/album. Unknown names are dropped rather than rejected, so a newer client cannot make an older server fail; it can only fail to grant something. Omitting fields while enabling publishes the base payload alone.

Scope: read (since v0.39).