Things somebody suggested that you do not own.
Scope: read (since v0.120). Each entry carries first_played_at, derived from the
listens rather than stored — whether the suggestion actually landed.
That is the thing only a scrobbler can answer, and it is what makes this
more than a wantlist: a recommendation is a prediction, and Tapedeck is
the only party that can score it.
landed counts how many entries have since turned up in the history.
Responses
application/json
object
Everything in the crate, and how much of it landed.
crate array required
each item object
A crate entry with the bit only Tapedeck can supply: whether the
recommendation actually landed.
A recommendation is a prediction, and a scrobbler is the only thing in the
room that can score it. first_played_at is derived from the listens rather
than stored, so it cannot drift from them.
id integer · int64 required
origin string required
user, or the name of the connection that suggested it.
status string required
open, acquired or dismissed.
created_at integer · int64 required
acted_at integer | null · int64
first_played_at integer | null · int64
When this first turned up in the listening history, if it ever did.
Derived from the listens, not stored, so it cannot drift from what
it summarises.
plays integer · int64 required
landed integer required
How many suggestions were actually played.
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."
}
Add something to the crate.
Session-only for this endpoint; an assistant uses the MCP add_to_crate
tool, which shares the same validation.
Two refusals, both deliberate. because is required — what in your
own listening prompted this — which is the vision doc's pipeline
(analytics, candidate selection, explanation) enforced at the door
rather than asked for in a prompt. And anything already in the
history is refused with its play count: that is not a suggestion, it
is rediscovery, and letting it through would turn the crate into a
worse copy of a screen that already exists.
Request body required
application/json
object
What a hand-filed crate entry says, plus where it came from.
name string | null
Album or track title. Omitted for an artist, whose name is already in
artist.
reason string | null
Why you would like it, in the suggester's words.
because string required
Required. What in your own listening prompted the suggestion. A
recommendation with no grounding in the history is free association,
and is refused.
from string | null
Optional. The username of a deck you are patched into — the Reel's
"into my crate" button. Resolved and checked server-side, and a deck
you cannot read is a 403: the Crate groups by origin and shows
"suggested by X", so a client writing that string itself would be
asserting a provenance rather than earning one. The patch must point
from you to them; somebody who follows you has told you nothing.
Omit it for something you found yourself, which files under the
origin user.
Responses
200 Filed. created is false when it was already there and the reason was updated.
application/json
object
id integer · int64 required
created boolean required
False when it was already there and its reason was updated.
400 Missing grounding, malformed, or already in the history.
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 from named a deck you are not patched into.
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.