Skip to main content

Search for a station and start playing it.

POST 
/station

Station search: find a station matching one or more queries and create a play from it in a single call.

Failures are reported the same way as everywhere else on this surface, so this endpoint answers with the usual HTTP statuses: a validation error is a 400, a placement or station that could not be found is a 404, and an unexpected failure is a 500. As everywhere else, the errors whose mnemonics carry no status of their own — noMoreMusic (9) and formatUnavailable (24) — still arrive as HTTP 200 with success: false, so keep checking success rather than relying on the status line alone.

How the search runs:

  • q is an ordered array of queries. They are tried in order, and each query's matching stations are tried in turn; the first station that yields a playable track wins and the search stops there. A station that fails while creating a play (for example a sample station that is forbidden) is skipped rather than failing the request.
  • An empty q: [] is legal and means "give me the first playable station".
  • Each query's type, when present, must be one of radio, first_play or replay.
  • Each query's at, when present, must be a non-negative number.
  • Each query's filter selects on the station's name, uuid and options, and combines conditions with $and/$or; see StationSearchQuery for the grammar. The q filter on GET /station reads the same grammar, but its field names resolve against options alone.

On success, play.station is the full station object, not the minimal one returned by POST /play.

The returned play is reserved exactly as one from POST /play would be. Play it as the station's first song: call POST /play/{play_id}/start when its audio begins, without calling POST /play first. Like any reserved play, it stops being valid once a different play is started.

Request​

Responses​

A created play, or one of the two failures that carry no HTTP status of their own. Check success before reading anything else.

On success the body carries the created play (with the full station) and the placement it came from.

On failure the body is a FeedErrorPayload with one of:

  • noMoreMusic (9) — stations matched but none of them had a track left to play.
  • formatUnavailable (24) — no audio file matched the requested formats/max_bitrate.

Neither mnemonic has an HTTP status of its own, so both default to 200. A request that passes force200 also lands here whatever the failure, with the real status in error.status.