CreatePlayRequest

Body for POST /play, which reserves the next track for a client. Give a station_id to play a specific station, a placement_id to let the server pick within a placement, or an audio_file_id to request a specific track on an on-demand station.

client_idstring

The client this play belongs to. Required, but may instead arrive as a cid cookie or a client_id query parameter — see Identifying a client. Values longer than 23 characters are silently truncated.

Possible values: <= 23 characters

placement_idstring

The placement to pull from. Defaults to the credentials' default placement when omitted.

station_idstring

The station to pull from. Defaults to the placement's default station when omitted.

audio_file_idstring

Request a specific audio file. Only honoured for on-demand and replay stations; asking on a radio station gives notOnDemandOrReplay (code 23).

formatsstring

Comma-separated list of acceptable codecs, in preference order, e.g. aac,mp3. Valid codecs are mp3 and aac. If none of the requested formats exist for the selected track the call reports formatUnavailable (code 24) — which is delivered as HTTP 200 with success: false.

Default value: mp3

max_bitrateinteger

Upper bound on the delivered bitrate, in kbps. The server picks the highest available file at or below this value.

crossfadenumber

Crossfade duration in seconds to apply to this play, overriding the station's configured value. Read only when at is also supplied — sent on its own it is ignored, with no error and nothing in the response to say so.

previewboolean

When true, create a preview play rather than a reportable one. The resulting audio_file carries preview: true.

Default value: false

atnumber

Request the song that should play at this seconds offset within the station. Only meaningful for stations that allow seeking; surfaces as start_at on the returned play.

CreatePlayRequest

{
  "client_id": "FgT1_Yzvr_e05ANk2uCYdZi",
  "station_id": "727",
  "formats": "aac,mp3",
  "max_bitrate": 128
}