← API reference

Radio

Stations, presets and the tuner that logs what they play. German public radio, via RadioDNS.

16 of 16 · v0.132.2
GET /api/v1/radio/stations #
Token reador Session

Every station that can be picked.

Scope: read. German public radio for now: every service the nine ARD broadcasters list in their RadioDNS service information, fetched by the server and kept for a day. FM frequency, DAB channel and city are not in that data, which is why a preset asks for them.

Responses

200

OK. Empty when no broadcaster could be reached.

application/json

object
stations array required
each item
object

One pickable station.

id string required

<gcc>.<pi>, e.g. de0.d3c3. In German public radio the FM PI code and the DAB service ID are the same number, so one id names the station on both bands.

name string required
short_name string | null

The 8-character name a radio display shows.

broadcaster string required

The broadcaster's FQDN, e.g. demdr.radiodns.ard.de.

provider string required

e.g. MDR.

region string required

The broadcaster's area — not where this station is heard.

description string | null
genres array required

The broadcaster's genre labels, e.g. Pop, Information.

each item
string
logo string | null

The best square logo, when there is one.

fm string | null

The FM bearer as published, e.g. fm:de0.d3c3.*. Absent for a DAB-only station.

dab array required

Every DAB bearer, one per ensemble it is carried in.

each item
string
stream object | null

The stream the tuner would read. Absent means it cannot be logged.

url string required
mime string | null
bitrate integer | null · int32

kbit/s.

regions array required

Every broadcaster area present, for the Browse chips.

each item
string
genres array required

Every genre label present, most common first.

each item
string
note 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."
}
GET /api/v1/radio/lookup #
Token reador Session

Any station by its broadcast identifiers.

Scope: read. Resolves a bearer through RadioDNS to its broadcaster and returns that broadcaster's description of the service and one day's schedule. Works for stations outside the station list — any broadcaster that runs RadioDNS — and is how one is identified from what a radio shows (PI code and frequency, or ensemble and service ID).

Parameters

bearer query required

fm:<gcc>.<pi>.<freq> or dab:<gcc>.<eid>.<sid>.<scids>, e.g. fm:de0.d3c3.09440.

string
date query

YYYY-MM-DD; today in your timezone when absent.

string

Responses

200

Found.

application/json

object

Everything one lookup found.

bearer string required

The bearer looked up, in canonical spelling.

broadcaster string required

The broadcaster RadioDNS pointed at, e.g. demdr.radiodns.ard.de.

spi_server string required

The SPI server the documents came from.

provider object | null

The broadcaster's own name for itself, when SI.xml gives one.

short string | null

At most 8 characters.

medium string | null

At most 16 characters.

long string | null

At most 128 characters.

service object | null

This bearer's service from SI.xml. Absent when the broadcaster's list does not carry it, which happens: the schedule is still tried.

names object required

The three lengths of name SPI gives everything. medium is often a truncation of long (MDR's "MDR KULTUR am Mo"), so [Names::best] reads the longest one there is.

short string | null

At most 8 characters.

medium string | null

At most 16 characters.

long string | null

At most 128 characters.

description string | null
genres array required
each item
object

A TV-Anytime genre: the classification URN and the label the broadcaster gave it.

href string required

e.g. urn:tva:metadata:cs:ContentCS:2011:3.6.4.1.

name string | null
logos array required
each item
object

A station logo, as a URL on the broadcaster's server. Never fetched here.

url string required
width integer | null · int32
height integer | null · int32
kind string | null

logo_colour_square, logo_colour_rectangle or logo_unrestricted.

mime string | null
bearers array required
each item
object

One way to receive a service: fm:…, dab:…, or an http(s):// stream.

id string required

The bearer URI as published. An FM bearer may end in *, meaning every frequency the PI code is heard on.

cost integer | null · int32

The broadcaster's preference between bearers; lower is preferred.

mime string | null
bitrate integer | null · int32

kbit/s, given for streams.

links array required

Web pages the broadcaster lists (http(s) links only; postal and telephone links are left out).

each item
string
date string required

The day asked for, YYYY-MM-DD.

schedule_status string required

Whether a day's schedule came back, in words a client can show.

publishednot_publishedunavailable
programmes array required
each item
object

One programme from a PI.xml schedule.

id string | null

The broadcaster's CRID, e.g. crid://MDR.de/MDR+KULTUR/7409527.

names object required

The three lengths of name SPI gives everything. medium is often a truncation of long (MDR's "MDR KULTUR am Mo"), so [Names::best] reads the longest one there is.

short string | null

At most 8 characters.

medium string | null

At most 16 characters.

long string | null

At most 128 characters.

start integer · int64 required

Unix seconds. The broadcaster's actualTime when it gives one (the time it really went out), otherwise the scheduled time.

duration integer | null · int32

Seconds, from the matching actualDuration or duration.

description string | null
genres array required
each item
object

A TV-Anytime genre: the classification URN and the label the broadcaster gave it.

href string required

e.g. urn:tva:metadata:cs:ContentCS:2011:3.6.4.1.

name string | null
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

Not in RadioDNS, or the broadcaster publishes no service information.

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.

502

DNS or the broadcaster's server failed.

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/radio/presets #
Token reador Session

Your presets, in order.

Scope: read.

Responses

200

OK.

application/json

object
presets array required
each item
object

A station the listener saved, where it sits on their dial.

id integer · int64 required
station_id string required

<gcc>.<pi>, the directory's id.

name string required
short_name string | null
band string required

fm or dab.

dial string | null

MHz for FM (95.8), the channel block for DAB (5C).

city string | null
position integer · int64 required

Order on the preset row, from 1.

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/radio/presets #
Token writeor Session

Save a station as a preset.

Scope: write. One preset per station and band.

Request body required

application/json

object
station_id string required

A station list id, e.g. de0.d3c3.

band string required

fm or dab — which you listen to it on.

dial string | null

MHz for FM (95.8), the channel block for DAB (5C).

city string | null

At most 60 characters.

Responses

201

Saved.

application/json

object

A station the listener saved, where it sits on their dial.

id integer · int64 required
station_id string required

<gcc>.<pi>, the directory's id.

name string required
short_name string | null
band string required

fm or dab.

dial string | null

MHz for FM (95.8), the channel block for DAB (5C).

city string | null
position integer · int64 required

Order on the preset row, from 1.

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

Not in the station list.

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

Already a preset on that band.

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/radio/presets/{id} #
Token writeor Session

Change a preset's dial position, city or order.

Scope: write.

Parameters

id path required

Preset id

integer · int64

Request body required

application/json

object

Each field distinguishes absent ("leave alone") from null ("clear").

dial string | null
city string | null
position integer | null · int64

Order on the preset row, from 1.

Responses

200

Changed.

application/json

object

A station the listener saved, where it sits on their dial.

id integer · int64 required
station_id string required

<gcc>.<pi>, the directory's id.

name string required
short_name string | null
band string required

fm or dab.

dial string | null

MHz for FM (95.8), the channel block for DAB (5C).

city string | null
position integer · int64 required

Order on the preset row, from 1.

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/radio/presets/{id} #
Token writeor Session

Remove a preset.

Scope: write. The air log and any listens it produced stay.

Parameters

id path required

Preset id

integer · int64

Responses

204

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."
}
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/radio/tuner #
Token reador Session

What the tuner is doing.

Scope: read. tuned: false when it is off.

Responses

200

OK.

application/json

object

What GET /api/v1/radio/tuner returns.

tuned boolean required
preset object | null

A station the listener saved, where it sits on their dial.

id integer · int64 required
station_id string required

<gcc>.<pi>, the directory's id.

name string required
short_name string | null
band string required

fm or dab.

dial string | null

MHz for FM (95.8), the channel block for DAB (5C).

city string | null
position integer · int64 required

Order on the preset row, from 1.

session_id integer | null · int64
since integer | null · int64

Unix seconds.

ends_at integer | null · int64

When auto-stop will end it, if it will.

state string | null

What the faceplate shows.

tuningliveunknownbreakdropped
now object | null
artist string required
title string required
since integer · int64 required
tagged boolean required

MusicBrainz recognised it.

line string | null

The last thing the station said, verbatim.

source string | null

Where line came from: ICY today.

retry_at integer | null · int64

When a dropped stream is next retried.

signal integer · int32 required

0–5, the faceplate's bars: connection health, not RF signal.

chain_id integer | null · int64
chain_name string | null
logo string | null
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/radio/tuner #
Token writeor Session

Tune in to a preset.

Scope: write. From now until you turn it off, tune elsewhere or the auto-stop runs out, the server reads the station's stream for track names and logs them under your rules. Replaces whatever you were tuned to.

Request body required

application/json

object
preset_id integer · int64 required

Responses

200

Tuned in.

application/json

object

What GET /api/v1/radio/tuner returns.

tuned boolean required
preset object | null

A station the listener saved, where it sits on their dial.

id integer · int64 required
station_id string required

<gcc>.<pi>, the directory's id.

name string required
short_name string | null
band string required

fm or dab.

dial string | null

MHz for FM (95.8), the channel block for DAB (5C).

city string | null
position integer · int64 required

Order on the preset row, from 1.

session_id integer | null · int64
since integer | null · int64

Unix seconds.

ends_at integer | null · int64

When auto-stop will end it, if it will.

state string | null

What the faceplate shows.

tuningliveunknownbreakdropped
now object | null
artist string required
title string required
since integer · int64 required
tagged boolean required

MusicBrainz recognised it.

line string | null

The last thing the station said, verbatim.

source string | null

Where line came from: ICY today.

retry_at integer | null · int64

When a dropped stream is next retried.

signal integer · int32 required

0–5, the faceplate's bars: connection health, not RF signal.

chain_id integer | null · int64
chain_name string | null
logo string | null
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

The station is not in the list, or publishes no stream.

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/radio/tuner #
Token writeor Session

Turn the tuner off.

Scope: write. Whatever was playing is judged as cut short.

Responses

200

Off.

application/json

object

What GET /api/v1/radio/tuner returns.

tuned boolean required
preset object | null

A station the listener saved, where it sits on their dial.

id integer · int64 required
station_id string required

<gcc>.<pi>, the directory's id.

name string required
short_name string | null
band string required

fm or dab.

dial string | null

MHz for FM (95.8), the channel block for DAB (5C).

city string | null
position integer · int64 required

Order on the preset row, from 1.

session_id integer | null · int64
since integer | null · int64

Unix seconds.

ends_at integer | null · int64

When auto-stop will end it, if it will.

state string | null

What the faceplate shows.

tuningliveunknownbreakdropped
now object | null
artist string required
title string required
since integer · int64 required
tagged boolean required

MusicBrainz recognised it.

line string | null

The last thing the station said, verbatim.

source string | null

Where line came from: ICY today.

retry_at integer | null · int64

When a dropped stream is next retried.

signal integer · int32 required

0–5, the faceplate's bars: connection health, not RF signal.

chain_id integer | null · int64
chain_name string | null
logo string | null
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."
}
GET /api/v1/radio/schedule #
Token reador Session

Today's programmes on a preset's station.

Scope: read. From RadioDNS; status says when the broadcaster publishes none. Cached for half an hour.

Parameters

preset_id query required
integer · int64

Responses

200

OK.

application/json

object

What GET /api/v1/radio/schedule returns.

station_id string required
date string required

YYYY-MM-DD.

source string required

RadioDNS — the only source today.

status string required

Whether a day's schedule came back, in words a client can show.

publishednot_publishedunavailable
programmes array required
each item
object

One programme from a PI.xml schedule.

id string | null

The broadcaster's CRID, e.g. crid://MDR.de/MDR+KULTUR/7409527.

names object required

The three lengths of name SPI gives everything. medium is often a truncation of long (MDR's "MDR KULTUR am Mo"), so [Names::best] reads the longest one there is.

short string | null

At most 8 characters.

medium string | null

At most 16 characters.

long string | null

At most 128 characters.

start integer · int64 required

Unix seconds. The broadcaster's actualTime when it gives one (the time it really went out), otherwise the scheduled time.

duration integer | null · int32

Seconds, from the matching actualDuration or duration.

description string | null
genres array required
each item
object

A TV-Anytime genre: the classification URN and the label the broadcaster gave it.

href string required

e.g. urn:tva:metadata:cs:ContentCS:2011:3.6.4.1.

name string | null
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

The station is not in the list right now.

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/radio/log #
Token reador Session

The air log and the review queue.

Scope: read. Every line a station sent while you were tuned in — tracks, guesses, breaks — and what became of it. Only scrobbled and kept lines are listens.

Parameters

limit query
integer · int64

Responses

200

OK.

application/json

object
entries array required

Newest first.

each item
object

One thing a station said while you were tuned in.

id integer · int64 required
session_id integer · int64 required
station_id string required
station_name string required
band string required
started_at integer · int64 required
ended_at integer | null · int64
raw string required

Exactly what the station sent.

artist string | null
title string | null
kind string required

track, guess, break or other.

source string required

ICY today.

status string required

playing, scrobbled, review, kept, dropped, held, partial, skipped or logged.

source_id string | null

The listen this became, as scrobbles.source_id.

mbid_recording string | null
review array required

Lines waiting for Keep or Drop, oldest first, however far back.

each item
object

One thing a station said while you were tuned in.

id integer · int64 required
session_id integer · int64 required
station_id string required
station_name string required
band string required
started_at integer · int64 required
ended_at integer | null · int64
raw string required

Exactly what the station sent.

artist string | null
title string | null
kind string required

track, guess, break or other.

source string required

ICY today.

status string required

playing, scrobbled, review, kept, dropped, held, partial, skipped or logged.

source_id string | null

The listen this became, as scrobbles.source_id.

mbid_recording string | null
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/radio/log/{id}/keep #
Token writeor Session

Keep a line from the review queue: write it as a listen.

Scope: write. It is forwarded like any other listen.

Parameters

id path required

Air log line id

integer · int64

Responses

200

Kept.

application/json

object

One thing a station said while you were tuned in.

id integer · int64 required
session_id integer · int64 required
station_id string required
station_name string required
band string required
started_at integer · int64 required
ended_at integer | null · int64
raw string required

Exactly what the station sent.

artist string | null
title string | null
kind string required

track, guess, break or other.

source string required

ICY today.

status string required

playing, scrobbled, review, kept, dropped, held, partial, skipped or logged.

source_id string | null

The listen this became, as scrobbles.source_id.

mbid_recording string | null
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

Already settled, or already in your history.

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/radio/log/{id}/drop #
Token writeor Session

Drop a line from the review queue.

Scope: write. It stays in the air log, marked dropped, and never becomes a listen.

Parameters

id path required

Air log line id

integer · int64

Responses

200

Dropped.

application/json

object

One thing a station said while you were tuned in.

id integer · int64 required
session_id integer · int64 required
station_id string required
station_name string required
band string required
started_at integer · int64 required
ended_at integer | null · int64
raw string required

Exactly what the station sent.

artist string | null
title string | null
kind string required

track, guess, break or other.

source string required

ICY today.

status string required

playing, scrobbled, review, kept, dropped, held, partial, skipped or logged.

source_id string | null

The listen this became, as scrobbles.source_id.

mbid_recording string | null
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

Already settled.

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/radio/recent #
Token reador Session

Stations you tuned to recently.

Scope: read.

Responses

200

OK.

application/json

object
recent array required

Newest first, one per station and band.

each item
object

One stretch of listening to one station.

id integer · int64 required
station_id string required
station_name string required
band string required
dial string | null
city string | null
chain_id integer | null · int64
started_at integer · int64 required
ended_at integer | null · int64
end_reason string | null
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."
}
GET /api/v1/radio/settings #
Token reador Session

Your radio scrobble rules.

Scope: read.

Responses

200

OK.

application/json

object

The listener's rules, stored in their preferences under radio. Every field defaults the way the design draws it: all on, a three-hour stop.

skip_breaks boolean

Skip ads, talk & jingles: such lines are logged as skipped. Off, they are logged as logged. Neither ever becomes a listen.

tagged_only boolean

Forward tagged tracks only: a guess waits rather than being written.

review boolean

Guesses wait in the review queue. Off, they are held in the log.

tag_radio boolean

Save radio listens with listening_context = radio.

auto_stop boolean

End the session by itself after auto_stop_hours.

auto_stop_hours integer · int32

1–12.

attach_chain boolean

File radio listens under chain_id.

chain_id integer | null · 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."
}
PUT /api/v1/radio/settings #
Token writeor Session

Replace your radio scrobble rules.

Scope: write. The whole object; a missing field takes its default. A running tuner picks up the change at once — the auto-stop moves, and the next track is judged by the new rules — except the chain, which a session keeps from when it started.

Request body required

application/json

object

The listener's rules, stored in their preferences under radio. Every field defaults the way the design draws it: all on, a three-hour stop.

skip_breaks boolean

Skip ads, talk & jingles: such lines are logged as skipped. Off, they are logged as logged. Neither ever becomes a listen.

tagged_only boolean

Forward tagged tracks only: a guess waits rather than being written.

review boolean

Guesses wait in the review queue. Off, they are held in the log.

tag_radio boolean

Save radio listens with listening_context = radio.

auto_stop boolean

End the session by itself after auto_stop_hours.

auto_stop_hours integer · int32

1–12.

attach_chain boolean

File radio listens under chain_id.

chain_id integer | null · int64

Responses

200

Saved.

application/json

object

The listener's rules, stored in their preferences under radio. Every field defaults the way the design draws it: all on, a three-hour stop.

skip_breaks boolean

Skip ads, talk & jingles: such lines are logged as skipped. Off, they are logged as logged. Neither ever becomes a listen.

tagged_only boolean

Forward tagged tracks only: a guess waits rather than being written.

review boolean

Guesses wait in the review queue. Off, they are held in the log.

tag_radio boolean

Save radio listens with listening_context = radio.

auto_stop boolean

End the session by itself after auto_stop_hours.

auto_stop_hours integer · int32

1–12.

attach_chain boolean

File radio listens under chain_id.

chain_id integer | null · int64
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."
}