← API reference

Chains

Signal chains, gear, devices and bindings.

37 of 37 · v0.132.2
GET /api/v1/chains #
Session or Token read

Signal chains.

Scope: read (since v0.37). This is what lets a client offer a chain picker instead of taking unvalidatable free text for a field that has to match a name exactly.

Responses

200

OK.

application/json

object
chains array required
each item
object

A signal chain: the gear a listen ran through, in order.

There is no is_default. A chain is not default for anything by itself; being the default is a property of the thing pointing at it, and there are two: a device (PATCH /api/v1/devices/{id}) and an API token, whose default_chain_id is rung 3 of the chain ladder and is reported by GET /1/validate-token.

Absent is not null here. icon, and a component's equipment_id and since, are omitted entirely when unset rather than sent as null — a strict deserialiser wants those optional, not nullable. description, detail and status really are present-and-null.

id integer | null · int64
user_id integer · int64 required
name string required
description string | null
components array required
each item
object

One step of a chain.

type string required

What kind of box a step is.

sourcetransportdacamptransducernetworkbluetooth
name string required

Always written, so deleting the gear leaves the chain readable.

detail string | null

Free text about this step. Always present; null when there is none. Guessed from the gear type when a step is first picked and never re-applied, so an override sticks.

equipment_id integer | null · int64

The equipment row this step is, set when it was picked from your gear. Omitted for free text — a chain can name something you do not own (a friend's amp, a rental).

since integer | null · int64

Unix seconds from which this box was in the path. Omitted means "for as long as the chain has existed", which is what every step written before this field meant.

Chain and gear hours are derived from the listens, so without it a box added to a chain that already has history is credited with all of it. Stamped automatically on gear a chain did not name before; send one to correct the date, or null to say it was always there.

options array | null

The gear that can be on at this step, as equipment ids, the gear the step is wired with first. Two or more makes the step a slot: "what's on now" picks one, and every listen from then on is filed with that pick. Omitted when the step is not a slot.

On save, omitted keeps the options the step already had; send [] to stop it being a slot. Ids that are not your gear are dropped.

each item
integer · int64
slot_name string | null

What the slot is called on screen ("On the go"), when it has a name.

listening_context string required

How you listen through a chain. Attention, not company — the two are orthogonal, and who you were with is company on the listen.

activeactive-mobilepassivebackgroundunknown
icon string | null

A name from the UI's CHAIN_ICONS set. Omitted when unset, not null. Unvalidated on purpose — an unknown value falls back to a generic mark rather than erroring, and rejecting a save because the front end learned a new icon first would be the worse failure.

is_active boolean required
shared boolean

(since v0.76.1) Whether this chain may be named to a deck patched into yours, and whether its listens reach the parts of Patch that have no patch behind them — the Instance tab, Discover, and Shared Spool captures. Not the sharing unit since v0.93.0: what a patched deck sees is share_all_with_patched on the profile.

total_hours number · double required

Derived from the listens (SUM(duration) where chain_id matches and the listen is not a skip), never accumulated — so assigning a chain to an old listen moves the hours, and un-assigning takes them back. A source that reported no length contributes nothing, so this is a floor.

created_at integer · int64 required

Unix seconds.

last_used object required

When each chain last carried a listen, unix seconds, keyed by chain id. A chain nothing has played through is absent. Skips do not count.

each value
integer · int64
on_now object required

What is on now at each slot, for chains with slots: chain id → (step position → equipment id). See GET /api/v1/chains/{id}/whats-on.

friend_chain_id integer | null · int64

The built-in At a friend's chain, where Shared Spool plays land, once it exists. It has no steps.

spool_chain_id integer | null · int64

The chain Shared Spool plays land on instead, when one was named the old way (PUT /api/v1/profile/spool-chain).

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

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."
}
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

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"
}
POST /api/v1/chains #
Session

Create a chain.

Session-only.

There is no is_default, and until v0.115.1 this said there was — sending it got a 201 and no effect, because unknown fields are ignored. A chain is made the default by a device binding or an API token; see the Chain schema.

A new chain is never shared. Sharing is switched on deliberately, from the chain drawer or Patch → Decks, and never as a side effect of creating something.

Request body required

application/json

object
name string required
description string | null
components array required
each item
object

One step of a chain.

type string required

What kind of box a step is.

sourcetransportdacamptransducernetworkbluetooth
name string required

Always written, so deleting the gear leaves the chain readable.

detail string | null

Free text about this step. Always present; null when there is none. Guessed from the gear type when a step is first picked and never re-applied, so an override sticks.

equipment_id integer | null · int64

The equipment row this step is, set when it was picked from your gear. Omitted for free text — a chain can name something you do not own (a friend's amp, a rental).

since integer | null · int64

Unix seconds from which this box was in the path. Omitted means "for as long as the chain has existed", which is what every step written before this field meant.

Chain and gear hours are derived from the listens, so without it a box added to a chain that already has history is credited with all of it. Stamped automatically on gear a chain did not name before; send one to correct the date, or null to say it was always there.

options array | null

The gear that can be on at this step, as equipment ids, the gear the step is wired with first. Two or more makes the step a slot: "what's on now" picks one, and every listen from then on is filed with that pick. Omitted when the step is not a slot.

On save, omitted keeps the options the step already had; send [] to stop it being a slot. Ids that are not your gear are dropped.

each item
integer · int64
slot_name string | null

What the slot is called on screen ("On the go"), when it has a name.

listening_context string

How you listen through a chain. Attention, not company — the two are orthogonal, and who you were with is company on the listen.

activeactive-mobilepassivebackgroundunknown
icon string | null

A glyph name from the UI's set. Not validated here — an unknown value falls back to a generic mark on render, which is a better failure than rejecting a save because the front end learned a new icon first.

Responses

201

Created.

application/json

object

A row that was just created.

id integer · int64 required
status string required

created.

400

Malformed or rejected input.

application/json

object

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.

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

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."
}
409

A chain of that name already exists for this user.

application/json

object

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.

GET /api/v1/chains/{id} #
Session or Token read

One chain.

Scope: read (since v0.37).

Parameters

id path required

The chain.

integer · int64

Responses

200

OK.

application/json

object

A signal chain: the gear a listen ran through, in order.

There is no is_default. A chain is not default for anything by itself; being the default is a property of the thing pointing at it, and there are two: a device (PATCH /api/v1/devices/{id}) and an API token, whose default_chain_id is rung 3 of the chain ladder and is reported by GET /1/validate-token.

Absent is not null here. icon, and a component's equipment_id and since, are omitted entirely when unset rather than sent as null — a strict deserialiser wants those optional, not nullable. description, detail and status really are present-and-null.

id integer | null · int64
user_id integer · int64 required
name string required
description string | null
components array required
each item
object

One step of a chain.

type string required

What kind of box a step is.

sourcetransportdacamptransducernetworkbluetooth
name string required

Always written, so deleting the gear leaves the chain readable.

detail string | null

Free text about this step. Always present; null when there is none. Guessed from the gear type when a step is first picked and never re-applied, so an override sticks.

equipment_id integer | null · int64

The equipment row this step is, set when it was picked from your gear. Omitted for free text — a chain can name something you do not own (a friend's amp, a rental).

since integer | null · int64

Unix seconds from which this box was in the path. Omitted means "for as long as the chain has existed", which is what every step written before this field meant.

Chain and gear hours are derived from the listens, so without it a box added to a chain that already has history is credited with all of it. Stamped automatically on gear a chain did not name before; send one to correct the date, or null to say it was always there.

options array | null

The gear that can be on at this step, as equipment ids, the gear the step is wired with first. Two or more makes the step a slot: "what's on now" picks one, and every listen from then on is filed with that pick. Omitted when the step is not a slot.

On save, omitted keeps the options the step already had; send [] to stop it being a slot. Ids that are not your gear are dropped.

each item
integer · int64
slot_name string | null

What the slot is called on screen ("On the go"), when it has a name.

listening_context string required

How you listen through a chain. Attention, not company — the two are orthogonal, and who you were with is company on the listen.

activeactive-mobilepassivebackgroundunknown
icon string | null

A name from the UI's CHAIN_ICONS set. Omitted when unset, not null. Unvalidated on purpose — an unknown value falls back to a generic mark rather than erroring, and rejecting a save because the front end learned a new icon first would be the worse failure.

is_active boolean required
shared boolean

(since v0.76.1) Whether this chain may be named to a deck patched into yours, and whether its listens reach the parts of Patch that have no patch behind them — the Instance tab, Discover, and Shared Spool captures. Not the sharing unit since v0.93.0: what a patched deck sees is share_all_with_patched on the profile.

total_hours number · double required

Derived from the listens (SUM(duration) where chain_id matches and the listen is not a skip), never accumulated — so assigning a chain to an old listen moves the hours, and un-assigning takes them back. A source that reported no length contributes nothing, so this is a floor.

created_at integer · int64 required

Unix seconds.

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

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."
}
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

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"
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

PATCH /api/v1/chains/{id} #
Session

Update a chain.

Session-only, and a whole-record replace despite the verb — it takes the same body as the create. Every field the editor owns is written, so an omitted icon, description or listening_context is cleared. Send the full record back.

Two fields it deliberately does not touch: shared, which is switched from the chain drawer or Patch → Decks — writing it here would un-publish a chain as a side effect of renaming it — and total_hours, which is derived from the listens.

A component naming gear the chain did not name before is stamped with since at the moment of the save. That is what stops a box added to a chain with history being credited with all of it; send your own since to correct the date, which is usually a few days before anybody got round to recording it.

Parameters

id path required

The chain.

integer · int64

Request body required

application/json

object
name string required
description string | null
components array required
each item
object

One step of a chain.

type string required

What kind of box a step is.

sourcetransportdacamptransducernetworkbluetooth
name string required

Always written, so deleting the gear leaves the chain readable.

detail string | null

Free text about this step. Always present; null when there is none. Guessed from the gear type when a step is first picked and never re-applied, so an override sticks.

equipment_id integer | null · int64

The equipment row this step is, set when it was picked from your gear. Omitted for free text — a chain can name something you do not own (a friend's amp, a rental).

since integer | null · int64

Unix seconds from which this box was in the path. Omitted means "for as long as the chain has existed", which is what every step written before this field meant.

Chain and gear hours are derived from the listens, so without it a box added to a chain that already has history is credited with all of it. Stamped automatically on gear a chain did not name before; send one to correct the date, or null to say it was always there.

options array | null

The gear that can be on at this step, as equipment ids, the gear the step is wired with first. Two or more makes the step a slot: "what's on now" picks one, and every listen from then on is filed with that pick. Omitted when the step is not a slot.

On save, omitted keeps the options the step already had; send [] to stop it being a slot. Ids that are not your gear are dropped.

each item
integer · int64
slot_name string | null

What the slot is called on screen ("On the go"), when it has a name.

listening_context string

How you listen through a chain. Attention, not company — the two are orthogonal, and who you were with is company on the listen.

activeactive-mobilepassivebackgroundunknown
icon string | null

A glyph name from the UI's set. Not validated here — an unknown value falls back to a generic mark on render, which is a better failure than rejecting a save because the front end learned a new icon first.

Responses

200

Updated.

application/json

object

A row that was just updated.

id integer · int64 required
status string required

updated.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

DELETE /api/v1/chains/{id} #
Session

Delete a chain.

Session-only. Clears referencing rows first — foreign keys are on.

Parameters

id path required

The chain.

integer · int64

Responses

204

Deleted.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/chains/variants #
Token reador Session

Every chain variant the caller owns.

Session or a token carrying read. A variant is a chain with one step swapped — two cartridges on one turntable, or the same commute on different IEMs. They are one chain and a choice, not two chains.

Flat rather than nested under each chain, because the page groups them itself and one list beats a request per chain.

total_hours here is the listening that went through this variant. A chain's own total_hours includes every variant of it, since they all ran through that chain.

Responses

200

OK.

application/json

object
variants array required
each item
object

A chain with one step swapped — two cartridges on one turntable, or the same commute with different IEMs, are one chain and a choice.

id integer · int64 required
user_id integer · int64 required
chain_id integer · int64 required

The chain this is a variant of.

name string required
overrides array required

Only the steps that differ from the chain.

each item
object

One step of a chain, replaced.

position indexes into the parent chain's components. Only the steps that differ are stored, which is what makes a variant an override rather than a copy: editing the shared part of a chain updates every variant of it, and two cartridges on one turntable stay one chain.

A position past the end of the base components adds a step, so a chain that never named a cartridge can gain one without being rewritten.

position integer · int64 required

Index into the chain's components. One past the end adds a step.

equipment_id integer | null · int64

The gear fitted at this step. Null removes the step for this variant — a chain run without its amp, say.

name string | null

Snapshot of the name, so a deleted gear row leaves the variant readable instead of blank.

created_at integer · int64 required

Unix seconds.

total_hours number · double required

The listening that went through this variant, which is a different question from a chain's total — a chain's hours include every variant of it, since they all ran through the same chain.

auto boolean required

Kept by Tapedeck for a set of slot picks ("what's on now"); its name is internal and never shown. False for a setup someone named.

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

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."
}
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

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"
}
POST /api/v1/chains/variants #
Session

Create a variant.

Session-only. Only the steps that differ are stored, which is what makes this an override rather than a copy: editing the shared part of a chain updates every variant of it.

The chain and every piece of gear named must be the caller's.

Request body required

application/json

object
chain_id integer · int64 required
name string required
overrides array
each item
object

One step of a chain, replaced.

position indexes into the parent chain's components. Only the steps that differ are stored, which is what makes a variant an override rather than a copy: editing the shared part of a chain updates every variant of it, and two cartridges on one turntable stay one chain.

A position past the end of the base components adds a step, so a chain that never named a cartridge can gain one without being rewritten.

position integer · int64 required

Index into the chain's components. One past the end adds a step.

equipment_id integer | null · int64

The gear fitted at this step. Null removes the step for this variant — a chain run without its amp, say.

name string | null

Snapshot of the name, so a deleted gear row leaves the variant readable instead of blank.

Responses

200

Created.

application/json

object

A new variant's id.

id integer · int64 required
400

Malformed or rejected input.

application/json

object

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.

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

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."
}
PATCH /api/v1/chains/variants/{id} #
Session

Rename a variant or change what it swaps.

Session-only. An omitted field is left alone.

Parameters

id path required

The variant.

integer · int64

Request body required

application/json

object
name string | null
overrides array | null
each item
object

One step of a chain, replaced.

position indexes into the parent chain's components. Only the steps that differ are stored, which is what makes a variant an override rather than a copy: editing the shared part of a chain updates every variant of it, and two cartridges on one turntable stay one chain.

A position past the end of the base components adds a step, so a chain that never named a cartridge can gain one without being rewritten.

position integer · int64 required

Index into the chain's components. One past the end adds a step.

equipment_id integer | null · int64

The gear fitted at this step. Null removes the step for this variant — a chain run without its amp, say.

name string | null

Snapshot of the name, so a deleted gear row leaves the variant readable instead of blank.

Responses

200

Saved. status is ok.

application/json

object

An acknowledgement with nothing else to report.

status names what happened — ok, updated, deleted, cleared, started and so on; the operation says which it sends. A client needs only the HTTP status to know it worked.

status string required
400

Malformed or rejected input.

application/json

object

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.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

DELETE /api/v1/chains/variants/{id} #
Session

Delete a variant.

Session-only. The listens that went through it keep their chain and fall back to its base components, which is what a null variant means everywhere else — they are not deleted along with it.

Parameters

id path required

The variant.

integer · int64

Responses

200

Deleted. status is deleted.

application/json

object

An acknowledgement with nothing else to report.

status names what happened — ok, updated, deleted, cleared, started and so on; the operation says which it sends. A client needs only the HTTP status to know it worked.

status string required
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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

POST /api/v1/chains/variants/{id}/promote #
Session

Make this setup the chain, and the chain a setup.

For the common case where the variant is the one you actually use — the other cartridge is in the headshell most of the time, so it should be what the chain is.

A relabelling, not a change. What was fitted for any given listen is identical afterwards, and so is every piece of gear's hours.

That is harder than it looks, and it is the whole of this endpoint. An override is {position, equipment_id} relative to the base, so another variant that swaps position 2 means "the base, but with X at 2" — change the base and that sentence names different gear at position 1, silently, with hours landing on a box that was never fitted. So every variant is resolved to an absolute list of steps first and re-expressed against the new base afterwards. Listens follow: those on the chain move to the new setup that restores it, and those on the promoted setup move to the chain.

name is what to call the setup the chain is demoted to — the old base has no name of its own, because it was the chain. Defaults to "Previous setup".

Refuses a setup that removes a step (400): removal shifts every later position, so promoting one would change what every other setup's overrides point at. Nothing in the UI creates such a setup.

Parameters

id path required

The variant to promote.

integer · int64

Request body required

application/json

object

GET /api/v1/chains/variants — every variant the caller owns.

Flat rather than nested under each chain: the page needs them keyed by

name string | null

What to call the setup the chain is being demoted to. The old base has no name of its own — it was the chain — so one has to be supplied.

Responses

200

The promoted setup, and the id of the one the chain became.

application/json

object

A setup promoted to be the chain.

promoted integer · int64 required

The setup that is now the chain.

old_base_variant_id integer · int64 required

The variant the old chain became.

400

That setup removes a step, or has none.

application/json

object

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.

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

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."
}
404

No such setup.

application/json

object

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.

GET /api/v1/chains/duplicates #
Session

Chains that look like the same rig, and what folding one would do.

Session-only. The discovery half of the fold below, and the same preview-then-apply shape the metadata sanitiser uses: this reports, it never acts.

A pair is reported when the two chains disagree on at most two steps. distance is how many — 0 is the same wiring under two names, 1 is the swapped-box case (the same commute on different IEMs) that variants exist for. Past two they are simply different rigs, and a variant overriding half a chain is a copy wearing an override's clothes.

The chain with more listening is reported as the base, since it keeps its id and fewer rows move — but the fold takes an explicit direction, so this is a suggestion rather than the decision.

Responses

200

OK.

application/json

object

Pairs of chains that look like the same rig. Nothing has been changed.

duplicates array required
each item
object

One pair of chains that look like the same rig, and what folding would do.

Reported, never acted on — the same preview-then-apply discipline the metadata sanitiser follows, and for the same reason: a fold is not reversible, and a plurality of one step is a weak signal the operator should see before agreeing to it.

base_chain_id integer · int64 required
base_name string required
base_hours number · double required
fold_chain_id integer · int64 required
fold_name string required
fold_hours number · double required
distance integer · int64 required

How many steps disagree. 0 is the same wiring under two names.

overrides array required

What the folded chain becomes as a variant of the base.

each item
object

One step of a chain, replaced.

position indexes into the parent chain's components. Only the steps that differ are stored, which is what makes a variant an override rather than a copy: editing the shared part of a chain updates every variant of it, and two cartridges on one turntable stay one chain.

A position past the end of the base components adds a step, so a chain that never named a cartridge can gain one without being rewritten.

position integer · int64 required

Index into the chain's components. One past the end adds a step.

equipment_id integer | null · int64

The gear fitted at this step. Null removes the step for this variant — a chain run without its amp, say.

name string | null

Snapshot of the name, so a deleted gear row leaves the variant readable instead of blank.

matching_variant array | null

A variant of the base that is already wired this way, as [id, name] — the state someone is in when they built the variant and found the old chain still sitting in the list beside it.

each item
object
fold_blocked_by_variants boolean required

This one carries variants of its own, so it cannot be the side that folds. Surfaced here rather than left for the fold to refuse.

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

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."
}
POST /api/v1/chains/{id}/fold #
Session

Fold this chain into another as a variant of it.

Session-only. Not reversible.

Every listen, side, session, binding, device default and token default of this chain is repointed at into_chain_id carrying the variant, and this chain is then deleted. Because gear hours resolve per (chain, variant) pair, the moved listening lands on the gear that was actually fitted — which is what makes two near-duplicate chains' hours add up instead of sitting in two rows that cannot be compared.

Send either variant_id (a variant of the target chain you already built) or variant_name (derive a new one from the difference between the two chains). Sending both, or neither, is a 400: on an endpoint that cannot be undone, "use the one I built" and "make me another" must not be the same request with a typo between them.

Refused with a 400 naming the reason when: the chain is folded into itself, the variant belongs to a different chain (it would resolve to components never fitted together), the name is already taken on the target, or this chain carries variants of its own — their positions index into components the fold replaces, and re-deriving them would be a guess about which box was fitted.

Parameters

id path required

The chain to fold away.

integer · int64

Request body required

application/json

object

What a fold request has to say. Deliberately not one nullable field.

variant_id (land on one that exists) and variant_name (derive a new one from the two chains) are different intents, and a single nullable field would make "use the variant I built" and "make me another one" the same request with a typo between them — on an endpoint that is not reversible.

into_chain_id integer · int64 required
variant_id integer | null · int64
variant_name string | null

Responses

200

Folded. The counts are what actually moved.

application/json

object

What a fold moved, so the caller can say it rather than claim success.

Reported per table because they are different kinds of thing: listens are the hours, a token or a device default is future attribution, and a record on the shelf is the turntable it lives with.

variant_id integer · int64 required
variant_name string required
variant_created boolean required
listens integer · int64 required
sides integer · int64 required
sessions integer · int64 required
releases integer · int64 required
devices integer · int64 required
bindings integer · int64 required
tokens integer · int64 required
400

Malformed or rejected input.

application/json

object

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.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/devices #
Session or Token read

Devices that have reported listens.

Scope: read (since v0.37).

Responses

200

OK.

application/json

object
devices array required
each item
object

A player that has submitted listens — rung 4 of the chain ladder.

id integer · int64 required
user_id integer · int64 required
machine_id string required

tapedeck_device.machine_id — the key.

name string | null
platform string | null
product string | null
device_type string | null
default_chain_id integer | null · int64
first_seen integer · int64 required
last_seen integer · int64 required
total_listens integer · int64 required
equipment_id integer | null · int64

The box this device is, when it has been tied to one (the inbox asks).

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

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."
}
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

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"
}
PATCH /api/v1/devices/{id} #
Session

Set a device's default chain.

Session-only. Rung 4 of the chain ladder — the coarsest fallback.

Parameters

id path required

The device.

integer · int64

Request body required

application/json

object
chain_id integer | null · int64 required

The chain this device's listens default to — rung 4 of the ladder. Required: null clears it; absent is a 400. Must be one of your chains.

Responses

200

Updated. status is ok.

application/json

object

An acknowledgement with nothing else to report.

status names what happened — ok, updated, deleted, cleared, started and so on; the operation says which it sends. A client needs only the HTTP status to know it worked.

status string required
400

chain_id absent, or not one of your chains.

application/json

object

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.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/equipment #
Session or Token read

Your gear.

Scope: read (since v0.37). Hours are derived from the chains that use each piece.

Responses

200

OK.

application/json

object
equipment array required
each item
object

A piece of gear.

The type field is equipment_type on the way out and type on the way in. POST/PATCH take type, every read returns equipment_type.

id integer · int64 required
user_id integer · int64 required
name string required
equipment_type string required

dac, amp, transducer, cartridge, headshell, phono, turntable, tape-deck, transport, …

brand string | null
model string | null
total_hours number · double required

Derived — summed from every chain referencing this gear, never accumulated. Free-text chain steps report zero, which is honest.

first_used integer | null · int64

When Tapedeck first saw it, unix seconds.

last_used integer | null · int64

Unix seconds.

notes string | null
purchased_at integer | null · int64

When it was bought, unix seconds. Distinct from first_used — gear is usually owned for a while before anyone gets round to cataloguing it, and burn-in hours are counted from the purchase.

sources array required

(since v0.70.4) What total_hours is made of, largest first — the same per-(chain, variant) seconds the hours are derived from, so the parts always add to the whole. Empty for gear nothing has logged time through.

each item
object

Where one piece of gear's hours came from.

chain_id integer · int64 required
chain_name string required
variant_id integer | null · int64

Set when the listening went through a variant of that chain — which is the case the breakdown exists for, since that is when one piece of gear accrues hours through a chain that does not name it.

variant_name string | null
hours number · double required
status string | null

Why this piece is not in a chain — new, spare or lent. Null is the usual state and means nothing has been said. Free text: the UI owns the vocabulary.

aliases array required

Other names this box reports as (a phone's model number), remembered from inbox answers or typed in. A reporter matching one is suggested as this box, never tied to it without asking.

each item
string
reporters array required

The devices and tokens tied to this box, by name: the apps and players that report plays from it.

each item
string
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

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."
}
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

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"
}
POST /api/v1/equipment #
Session

Add gear.

Session-only. The type field is type here and comes back as equipment_type — see the Equipment schema.

Request body required

application/json

object
name string required
type string required
brand string | null
model string | null
notes string | null
purchased_at integer | null · int64

When it was bought, unix seconds. Distinct from first_used, which is when Tapedeck first saw it — gear is usually owned for a while before anyone gets round to cataloguing it, and burn-in hours are counted from the purchase.

Responses

201

Created — or matched. Gear is keyed on (user, name): posting a name you already own returns that row's id and stamps last_used, and every other field you sent is ignored rather than applied. Use PATCH /api/v1/equipment/{id} to change one. Always 201, even when nothing was created.

application/json

object

A row that was just created.

id integer · int64 required
status string required

created.

400

Malformed or rejected input.

application/json

object

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.

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

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."
}
PATCH /api/v1/equipment/{id} #
Session

Update gear.

Session-only. A whole-record replace, not a partial patch — every field is written, so an omitted brand clears the brand. Send the full record back.

Parameters

id path required

The gear.

integer · int64

Request body required

application/json

object

The update body is deliberately its own type rather than a reuse of CreateEquipmentRequest: status is settable here and not at creation (gear is tagged from the "Not in a chain yet" table, once it exists), and a shared struct would mean POST accepting a field it silently threw away.

Every field is written unconditionally — this endpoint is a whole-record replace, not a partial patch, which is why an omitted brand has always cleared the brand. Clients must send the full record back.

name string required
type string required
brand string | null
model string | null
notes string | null
purchased_at integer | null · int64
status string | null

Why it is not in a chain: new, spare, lent. Absent clears it.

aliases array | null

Other names this box reports as. The one field absent leaves alone rather than clearing: gear editors that predate it send the record without it, and must not wipe what the inbox remembered.

each item
string

Responses

200

Updated.

application/json

object

A row that was just updated.

id integer · int64 required
status string required

updated.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

DELETE /api/v1/equipment/{id} #
Session

Delete gear.

Session-only. Chains referencing it stay readable — every component keeps a name snapshot alongside its optional equipment_id.

Parameters

id path required

The gear.

integer · int64

Responses

204

Deleted.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/bindings #
Session or Token read

Output-device bindings.

Scope: read (since v0.37). Rung 2 of the chain ladder.

Responses

200

OK.

application/json

object
bindings array required

Outputs by name, from anything not tied to a box: rung 3.

each item
object

An output device, and the chain it maps to — rung 2 of the chain ladder.

id integer · int64 required
user_id integer · int64 required
identifier string required

The output device, as a client reports it in tapedeck_device.output_device.

interface string | null
chain_id integer | null · int64

Null for one seen but not mapped yet — offered for one-tap assignment.

chain_variant_id integer | null · int64

Which setup (variant) of that chain listens through this output get. Null is the chain as wired.

last_seen integer · int64 required

Unix seconds.

hits integer · int64 required

Listens that reported it.

device_bindings array required

Outputs learned per box, from devices and tokens tied to one: rung 2.

each item
object

An output seen from one box, and the chain it is mapped to.

id integer · int64 required
equipment_id integer · int64 required

The box it was seen from.

equipment_name string required
identifier string required
interface string | null
chain_id integer | null · int64

Null when seen but not mapped yet.

chain_variant_id integer | null · int64

Which setup of that chain it carries; null is the chain as wired.

last_seen integer · int64 required
hits integer · int64 required
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

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."
}
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

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"
}
PUT /api/v1/bindings #
Session

Bind an output device name to a chain, and to a setup of it.

Session-only. Rung 2 of the chain ladder, and the only rung that also names a setup: listens through this output are saved with chain_variant_id, so their hours land on the gear that setup fits. Sending a chain always rewrites the setup.

Request body required

application/json

object
identifier string required

The output device, as a client reports it in tapedeck_device.output_device.

chain_id integer | null · int64 required

The chain it maps to. Required: null clears the mapping; absent is a 400. Must be one of your chains.

chain_variant_id integer | null · int64

Which setup (variant) of that chain this output carries. Absent or null is the chain as wired. Must be a variant of chain_id.

equipment_id integer | null · int64

The box this output belongs to, for an output learned per box (see device_bindings in the list). Absent maps the output by name, from anything — the rung below.

Responses

200

Saved. status is ok.

application/json

object

An acknowledgement with nothing else to report.

status names what happened — ok, updated, deleted, cleared, started and so on; the operation says which it sends. A client needs only the HTTP status to know it worked.

status string required
400

chain_id absent, not one of your chains, or chain_variant_id not a setup of it.

application/json

object

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.

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

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."
}
DELETE /api/v1/bindings/{id} #
Session

Remove a binding.

Session-only.

Parameters

id path required

The binding.

integer · int64

Responses

204

Deleted.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/chains/inbox #
Session

The questions about plays that landed in no chain, and about slots.

Session-only. From the last 30 days, grouped by where the plays came from: first which box a device or token is (same_box, which_box), then where unfiled plays should have gone (where), most plays first. Then chains that differ at one box and could be one chain with an option (merge), and named setups that change no gear (moods). Questions put off with "not now" are left out for 30 days.

Responses

200

OK.

application/json

object
questions array required
each item
object

One question in the inbox.

key string required

Stable for as long as the question stands; what "not now" stores.

kind string required

same_box — are these reporters this box? which_box — which box is this reporter? where — plays landed nowhere; where were you? merge — two chains differ at one box; make it an option? moods — named setups that change no gear; make them session titles? spool — Shared Spool plays on no chain; file them At a friend's?

equipment_id integer | null · int64

same_box: the box suggested, by a name or model it matches.

equipment_name string | null
reporters array

same_box: every reporter not yet tied to a box that matches it. which_box: the one reporter asked about.

each item
object

One device or token, as the inbox names it.

kind string required

device or token.

id integer · int64 required
name string required
sub string required

What it is: the platform for a device, "a token" for a token.

equipment_id integer | null · int64

The box it is already tied to, if any.

plays integer | null · int64

where: how many unfiled plays, and over what span.

first integer | null · int64
last integer | null · int64
since integer | null · int64

where: the start of the window counted. Send it back with the answer so "also file them" moves exactly the plays that were counted.

device object | null

where: what the plays came through.

kind string required

device or token.

id integer · int64 required
name string required
sub string required

What it is: the platform for a device, "a token" for a token.

equipment_id integer | null · int64

The box it is already tied to, if any.

token object | null

One device or token, as the inbox names it.

kind string required

device or token.

id integer · int64 required
name string required
sub string required

What it is: the platform for a device, "a token" for a token.

equipment_id integer | null · int64

The box it is already tied to, if any.

output string | null
source_name string | null
rule string | null

where: what an answer will set so future plays find the chain: device_output (an output of a box), output (an output name from anything), token, device, or none when nothing identifies the source and only the counted plays can be filed.

merge object | null

merge: the two chains and the step they differ at.

chain_id integer · int64 required

The chain kept: the one with more hours.

chain_name string required
chain_hours number · double required
other_chain_id integer · int64 required

The chain that becomes an option on it.

other_chain_name string required
other_hours number · double required
position integer · int64 required
gear string required

The gear at that step on each.

other_gear string required
setups array

moods: every setup that changes no gear.

each item
object

The mood setups the inbox offers to turn into session titles.

id integer · int64 required
name string required
chain_id integer · int64 required
chain_name string required
plays integer · int64 required

Plays filed with it, skips excluded.

sessions integer · int64 required

Sittings those plays are in that have no title yet.

spool object | null

spool: accepted Shared Spool plays on no chain.

plays integer · int64 required

Plays, skips excluded.

first integer | null · int64
last integer | null · int64
window_days integer · int64 required

How far back the questions look, in days.

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

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."
}
POST /api/v1/chains/inbox/where #
Session

Answer "where were you?" for plays that landed in no chain.

Session-only. Writes the most specific rule the plays allow, so future ones find the chain: an output (of the box when the reporter is tied to one), else the token's default chain, else the device's. With none of those (rule: none) nothing can be remembered and only the counted plays can be filed. backfill files the plays the question counted, no others.

Request body required

application/json

object
device_id integer | null · int64

Echo the question's device, token, output and source_name: they identify the plays and decide which rule is written.

token_id integer | null · int64
output string | null
source_name string required
since integer · int64 required

The question's since, so "also file them" moves exactly the plays it counted.

chain_id integer · int64 required

Where they should have gone. One of your chains.

chain_variant_id integer | null · int64

A setup of that chain; only remembered on an output rule.

backfill boolean required

Also file the counted plays. Required, because it changes history.

Responses

200

The rule written and the plays filed.

application/json

object

What a where answer did.

rule string required

The rule written, as in InboxQuestion.rule.

moved integer · int64 required

How many counted plays were filed. Zero unless asked.

400

Malformed or rejected input.

application/json

object

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.

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

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."
}
POST /api/v1/chains/inbox/box #
Session

Tie devices and tokens to the box they are.

Session-only. Answers "are these your Xperia?" and "which box is this?". Hours never move: grouping changes how reporters are drawn and which outputs are learned per box, not where any listen was attributed. Ids that are not yours are ignored. alias is remembered on the box.

Request body required

application/json

object
equipment_id integer · int64 required

The box they are. One of your gear.

device_ids array
each item
integer · int64
token_ids array
each item
integer · int64
alias string | null

Remember this as another name the box reports as (a model number), so the next reporter carrying it is suggested. Optional.

Responses

200

Tied. status is ok.

application/json

object

An acknowledgement with nothing else to report.

status names what happened — ok, updated, deleted, cleared, started and so on; the operation says which it sends. A client needs only the HTTP status to know it worked.

status string required
400

Malformed or rejected input.

application/json

object

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.

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

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."
}
POST /api/v1/chains/inbox/dismiss #
Session

Put an inbox question off for 30 days.

Session-only.

Request body required

application/json

object
key string required

The question's key.

Responses

200

Put off. status is ok.

application/json

object

An acknowledgement with nothing else to report.

status names what happened — ok, updated, deleted, cleared, started and so on; the operation says which it sends. A client needs only the HTTP status to know it worked.

status string required
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

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."
}
DELETE /api/v1/device-bindings/{id} #
Session

Remove an output learned per box.

Session-only.

Parameters

id path required

The output.

integer · int64

Responses

204

Deleted.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/rooms #
Session or Token read

Your rooms, in order, with the chains in each.

Scope: read. The built-in "On the go" room is created the first time this is asked, so it is always there to pick. A chain may appear in several rooms' chain_ids.

Responses

200

OK.

application/json

object
rooms array required
each item
object

One room and the chains in it.

id integer · int64 required
name string required
icon string | null

A glyph name from the UI's set, or null.

kind string required

room for your own, portable (On the go) or elsewhere for the built-ins, which cannot be renamed or deleted.

sort integer · int64 required
created_at integer · int64 required
chain_ids array required

The chains in this room, by id. A chain may be in several rooms.

each item
integer · int64
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

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."
}
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

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"
}
POST /api/v1/rooms #
Session

Make a room of your own.

Session-only. Names are unique per person, ignoring case.

Request body required

application/json

object
name string required

Up to 60 characters; whitespace is collapsed.

icon string | null

A glyph name from the UI's set. Not validated, like a chain's icon.

Responses

201

Created.

application/json

object

A row that was just created.

id integer · int64 required
status string required

created.

400

Malformed or rejected input.

application/json

object

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.

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

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."
}
409

You already have a room with that name.

application/json

object

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.

PATCH /api/v1/rooms/{id} #
Session

Rename a room, change its icon, or move it in the order.

Session-only. A built-in room can be reordered and given an icon, never renamed.

Parameters

id path required

The room.

integer · int64

Request body required

application/json

object
name string | null

A new name. Absent leaves it; a built-in room cannot be renamed.

icon string | null

A new icon, or null to clear it. Absent leaves it alone.

sort integer | null · int64

Position in the order; lower comes first.

Responses

200

Updated.

application/json

object

A row that was just updated.

id integer · int64 required
status string required

updated.

400

Malformed or rejected input.

application/json

object

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.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

409

You already have a room with that name.

application/json

object

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.

DELETE /api/v1/rooms/{id} #
Session

Delete a room of your own.

Session-only. Its chains leave the room and are otherwise untouched: deleting a room never deletes a chain. Built-in rooms cannot be deleted.

Parameters

id path required

The room.

integer · int64

Responses

204

Deleted.

400

Malformed or rejected input.

application/json

object

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.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

PUT /api/v1/chains/{id}/rooms #
Session

Put a chain in exactly these rooms.

Session-only. Replaces the chain's rooms; [] takes it out of all of them. Refused whole if the chain or any room is not yours.

Parameters

id path required

The chain.

integer · int64

Request body required

application/json

object
room_ids array required

Every room the chain is in. Required: [] takes it out of every room; an absent field is a 400, because this replaces what was there.

each item
integer · int64

Responses

200

Updated.

application/json

object

A row that was just updated.

id integer · int64 required
status string required

updated.

400

Malformed or rejected input.

application/json

object

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.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/chains/{id}/whats-on #
Session or Token read

What is on at each slot of a chain, and what the picker offers.

Scope: read. Each option carries its purchase date and first play ("in use since"), and the outputs that pick it by themselves. last_play_end is when the chain's last play ended, for "right after the last play here".

Parameters

id path required

The chain.

integer · int64

Responses

200

OK.

application/json

object

A chain's slots, and what a "since when?" needs to offer.

chain_id integer · int64 required
slots array required
each item
object

One slot of a chain, as the "what's on now" picker shows it.

position integer · int64 required

The step's index in the chain's components.

slot_name string | null
wired integer · int64 required

The gear the step is wired with, which is what "as wired" and every listen before the first switch mean.

on integer · int64 required

The gear on now.

on_since integer | null · int64

When the gear on now went on, if a switch says so. Null when it has been on since the chain began (no switch of this step recorded).

options array required
each item
object

One piece of gear that can be on at a slot.

equipment_id integer · int64 required
name string required
brand string | null
equipment_type string | null
purchased_at integer | null · int64

When you bought it, if the gear record says.

first_play integer | null · int64

Its first play through any chain, skips excluded. "In use since" is the purchase date when there is one, else this.

picked_by array required

Outputs that pick this option by themselves (a Bluetooth name that says which earbuds), by their reported name.

each item
string
last_play_end integer | null · int64

When the last play through this chain ended: "right after the last play here". Null when it has none.

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

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."
}
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

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"
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

POST /api/v1/chains/{id}/fit #
Session

Switch what is on at a slot, now or since a moment.

Session-only. Only plays filed with the pick in effect at their time move, so a play an output picked by itself stays where it is. Other slots' picks are never changed. moved counts plays, skips excluded.

Parameters

id path required

The chain.

integer · int64

Request body required

application/json

object
position integer · int64 required

The slot: the step's position in the chain.

equipment_id integer · int64 required

The gear to put on, one of the slot's options.

since integer | null · int64

From when, unix seconds. Absent is now. Earlier is a backdate: the plays from then up to the next recorded switch of this step move to the new pick, and later switches stay as they are.

dry_run boolean required

true counts what would move and writes nothing. Required, so a preview can never be sent as the real thing by leaving it out.

Responses

200

Switched, or what a switch would move.

application/json

object

What a switch did, or would do.

moved integer · int64 required

Plays (skips excluded) that are, or would be, filed with the new pick.

since integer · int64 required

From when the pick counts.

until integer | null · int64

Where the change stops: the next recorded switch of the same step. Null when there is none, so the new pick is what's on now.

now_on boolean required

The new pick is what's on now.

400

Malformed or rejected input.

application/json

object

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.

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

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."
}
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

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

POST /api/v1/chains/{id}/merge #
Session

Merge a chain that differs at one box into this one, as an option there.

Session-only, and not reversible. The two must differ at exactly one step past the player (a different player is a different chain). The other chain's listens, outputs, defaults and rooms move here, filed with that option, and the other chain is deleted.

Parameters

id path required

The chain kept.

integer · int64

Request body required

application/json

object
from_chain_id integer · int64 required

The chain that becomes an option on this one, and is then deleted.

Responses

200

Merged. The counts are what moved.

application/json

object

What a fold moved, so the caller can say it rather than claim success.

Reported per table because they are different kinds of thing: listens are the hours, a token or a device default is future attribution, and a record on the shelf is the turntable it lives with.

variant_id integer · int64 required
variant_name string required
variant_created boolean required
listens integer · int64 required
sides integer · int64 required
sessions integer · int64 required
releases integer · int64 required
devices integer · int64 required
bindings integer · int64 required
tokens integer · int64 required
400

Malformed or rejected input.

application/json

object

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.

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

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."
}
POST /api/v1/chains/inbox/moods #
Session

Turn named setups that change no gear into session titles.

Session-only. Each one's name becomes the title of the sittings its plays are in, where a sitting has no title yet, and the setup is removed. The plays keep their chain; the gear was the same, so no hour moves. Ids that are not such a setup of yours are ignored.

Request body required

application/json

object
variant_ids array required

The setups to retire, from the moods question.

each item
integer · int64

Responses

200

What changed.

application/json

object

What retiring mood setups did.

sessions_titled integer · int64 required

Sittings that gained a title.

removed integer · int64 required

Setups removed.

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

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."
}
PUT /api/v1/chains/{id}/route #
Session

Save a chain's route from the route editor.

Session-only. With past: keep the old route is kept as hidden history: past plays stay on it, every other variant keeps naming the gear it did, and a switch now starts the new route with whatever was on at its slots (outputs that pick gear by themselves keep picking it). With past: rewrite the steps are replaced and every past play is read through them. Name, icon and the rest stay with PATCH /api/v1/chains/{id}.

Parameters

id path required

The chain.

integer · int64

Request body required

application/json

object
components array required

The steps in order, as the editor wired them. Slot options travel on the steps; leaving them out keeps the ones a step had.

each item
object

One step of a chain.

type string required

What kind of box a step is.

sourcetransportdacamptransducernetworkbluetooth
name string required

Always written, so deleting the gear leaves the chain readable.

detail string | null

Free text about this step. Always present; null when there is none. Guessed from the gear type when a step is first picked and never re-applied, so an override sticks.

equipment_id integer | null · int64

The equipment row this step is, set when it was picked from your gear. Omitted for free text — a chain can name something you do not own (a friend's amp, a rental).

since integer | null · int64

Unix seconds from which this box was in the path. Omitted means "for as long as the chain has existed", which is what every step written before this field meant.

Chain and gear hours are derived from the listens, so without it a box added to a chain that already has history is credited with all of it. Stamped automatically on gear a chain did not name before; send one to correct the date, or null to say it was always there.

options array | null

The gear that can be on at this step, as equipment ids, the gear the step is wired with first. Two or more makes the step a slot: "what's on now" picks one, and every listen from then on is filed with that pick. Omitted when the step is not a slot.

On save, omitted keeps the options the step already had; send [] to stop it being a slot. Ids that are not your gear are dropped.

each item
integer · int64
slot_name string | null

What the slot is called on screen ("On the go"), when it has a name.

past string required

keep: plays already logged keep the route they had (from now on). rewrite: every play ever logged here is read through the new route. Required: on an endpoint that can move every hour of a chain, "which one" must never be a default.

Responses

200

Saved.

application/json

object

What a route save did.

past string required

keep (past plays keep the old route) or rewrite.

kept integer · int64 required

Plays (skips excluded) now filed with the old route. 0 for rewrite.

unchanged boolean required

The route did not change; only slot options or names were saved.

400

Malformed or rejected input.

application/json

object

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.

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

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."
}
POST /api/v1/chains/inbox/spool #
Session

File accepted Shared Spool plays that landed on no chain.

Session-only. Every such play goes to the chain given, or to At a friend's. They were accepted before At a friend's existed; new ones land there on their own.

Request body required

application/json

object
chain_id integer | null · int64

The chain to file them under; absent or null is At a friend's (made if it does not exist yet).

Responses

200

Filed.

application/json

object

What filing Shared Spool plays did.

moved integer · int64 required

Plays filed, skips excluded.

chain_id integer · int64 required

The chain they went to.

400

Malformed or rejected input.

application/json

object

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.

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

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."
}