Unauthenticated by design — it describes the shape of the API, not any data, and a client needs to read it before it has a credential.
Served from the binary because it is the one thing a separately hosted docs site cannot do: describe this instance at this version. For a self-hosted app that beats any version dropdown — ask your own server what it supports rather than guessing.
The OpenAPI document.
application/yaml
Up, and the database answers.
application/json
What /health answers.
status string required ok, or degraded when the database cannot be reached.
service string required Always tapedeck.
database string required ok or unreachable.
version string required The running binary's version.
replica boolean required Whether this instance is a replica — a full copy that forwards no listens, publishes no actor and makes no MusicBrainz request. A staging instance restored from a production snapshot is byte-identical on every other screen, so this is the only thing that tells them apart. Always present; its absence means a binary older than 0.109.0.
{
"database": "ok",
"replica": false,
"service": "tapedeck",
"status": "ok",
"version": "0.109.0"
}Up, but the database does not answer. Same body, status: degraded.
application/json
What /health answers.
status string required ok, or degraded when the database cannot be reached.
service string required Always tapedeck.
database string required ok or unreachable.
version string required The running binary's version.
replica boolean required Whether this instance is a replica — a full copy that forwards no listens, publishes no actor and makes no MusicBrainz request. A staging instance restored from a production snapshot is byte-identical on every other screen, so this is the only thing that tells them apart. Always present; its absence means a binary older than 0.109.0.
Never open — an admin session, or Authorization: Bearer $TAPEDECK_METRICS_TOKEN. The metrics that matter are the per-job import
gauges and process_resident_memory_bytes (Linux only), which is what
distinguishes a stall from a slowdown from an OOM on a small host.
Prometheus text exposition format.
text/plain
Neither the bearer token nor an admin session. A non-admin session is refused the same way — every gauge is instance-wide. The body is plain text saying how to get in, not the JSON error.
text/plain
Session-only, admin role.
OK.
application/json
The live tracing filter.
current_level string required 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
Every error body in the API has this shape.
code integer · int32 required Mirrors the HTTP status.
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."
}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
Every error body in the API has this shape.
code integer · int32 required Mirrors the HTTP status.
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"
}Swaps the live EnvFilter. No restart, no config edit. Session-only,
admin role.
application/json
level string required An EnvFilter directive — a level, or per-target levels.
Applied. current_level echoes the request, upper-cased.
application/json
The live tracing filter.
current_level string required Malformed or rejected input.
application/json
Every error body in the API has this shape.
code integer · int32 required Mirrors the HTTP status.
error string required Human-readable. Not a stable identifier — do not branch on it.
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
Every error body in the API has this shape.
code integer · int32 required Mirrors the HTTP status.
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."
}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
Every error body in the API has this shape.
code integer · int32 required Mirrors the HTTP status.
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"
}