Skip to main content

Reserve a play for playback.

POST 
/play

Reserves the next song for this client and returns the play, including the audio file and the URL to stream it from. The play is not yet playing: call POST /play/{play_id}/start when audio actually begins playback. Repeated calls to this endpoint with the same parameters and no intervening POST /play/{play_id}/start or POST /play/\{play_id\}/invalidate call will return the same song (but with a newly signed URL pointing to its audio).

The play object returned from this call is valid until a POST /play/\{play_id\}/start call is made against any other play. That is, if you make multiple POST /play calls with different station_id values, only one of the returned play ids may be sent to a POST /play/\{play_id\}/start and the rest should be discarded.

noMoreMusic is not an error status. When no song can be selected — the station is exhausted for this client, or audio_file_id names a song that cannot be played — the server answers HTTP 200 with a body of { "success": false, "error": { "code": 9, ... } }. Always inspect success; do not treat 200 as proof a play was reserved. Each noMoreMusic is also counted against the client and feeds the throttle described under 429.

Licensing and option behaviour:

  • audio_file_id requests one specific song. It is only honoured on on-demand or replay stations (or when preview is set); anywhere else the request fails with notOnDemandOrReplay (code 23, HTTP 403).
  • at queues the song that would be playing at that offset into the station. It is honoured only when the station is single_play/first_play, or is on-demand or replay and unshuffled. On any other station type at is silently ignored — no error, no warning in the response — so that the caller gets the wrong-but-playable music instead of no music. crossfade is only read alongside at.
  • preview: true selects the preview transcode of the song and forces audio_file.duration_in_seconds to 30, regardless of the real length.
  • formats is a comma-separated codec list (default mp3) and max_bitrate caps the transcode chosen.

Request​

Responses​

Either a reserved play, or one of the two failures that have no HTTP status of their own and so arrive here with success: false:

  • noMoreMusic (code 9) — no song could be selected for this client and station.
  • formatUnavailable (code 24) — a song was selected but no transcode of it matched the requested formats and max_bitrate.

Both are detectable only by inspecting success.