SessionResponse

The POST /session response. The placement and station blocks are emitted only when the corresponding placement exists for the credentials, so a client with no offline placement gets neither offline_placement nor offline_stations.

successbooleanrequired

Always true on this payload.

Example: true

session objectrequired

The session object returned by POST /session. There is no session resource to fetch or delete afterwards; this reports whether the client can stream, who the client is, and the server's clock.

availablebooleanrequired

true when a streaming placement with at least one playable station was found for this client and country. When false, no music can be played and message explains why.

client_idstringrequired

The client's uuid. Pass this back on subsequent calls (as a client_id body property or query parameter) to keep play history, likes and skip limits attached to the same listener. If a client_id was passed to the call, then this entry will match that value.

Example: FgT1_Yzvr_e05ANk2uCYdZi

timeintegerrequired

The server's current time as a Unix timestamp in seconds (not milliseconds).

Example: 1754265600

messagestring

Why streaming is unavailable. Present only when available is false.

Example: Sorry, there is no streaming music available for your client

placement object

A placement — an immutable collection of stations and the playback options that apply across them.

idstringrequired

The placement id. Numeric, but always serialized as a string.

Example: 10955

options objectrequired

Free-form, customer-configured placement options, passed through verbatim. Contents vary per customer.

property name*any

Free-form, customer-configured placement options, passed through verbatim. Contents vary per customer.

stations object[]

A selected subset of stations available for streaming in this placement. This is meant to return 'global' or 'default' stations that clients would otherwise always make an additional GET /station call on startup to retrieve.

Array [

idstringrequired

The station id. Numeric, but always serialized as a string. This value changes with the 'placement id', and so should not be persisted - use the uuid property instead.

Example: 727

namestringrequired

The station's display name.

Example: Pop Rock

on_demandintegerrequired

Whether the station is an on-demand station: 1 for yes, 0 for no.

Possible values: [0, 1]

pre_gainnumbernullablerequired

Station-level gain adjustment in dB, to be applied before playback. null when the station has no adjustment configured.

options objectrequired

Free-form, customer-configured options attached to a station. Contents vary per customer; unknown keys should be passed through rather than rejected.

crossfade_secondsnumber

Crossfade duration for the station, in seconds.

property name*any

Free-form, customer-configured options attached to a station. Contents vary per customer; unknown keys should be passed through rather than rejected.

uuidstringrequired

The station's stable external identifier. Unlike id, it does not change over time.

Example: FgT1_Yzvr_e05ANk2uCYdZi

crossfade_secondsnumbernullablerequired

The station's own crossfade duration in seconds. null when unset. This may differ from the customer-configured options.crossfade_seconds; the two can disagree.

single_playbooleanrequired

true when the station is a single-play station — one track, not a continuous stream.

last_updateddate-timerequired

When the station's contents last changed. Clients use this to decide whether a cached offline copy is stale.

last_play_startdate-time

When this client last started a play on this station. Emitted only when such a play exists, so it is absent for new clients and for stations the client has never played.

expire_datedate-time

When a downloaded offline copy of this station should be considered expired — three weeks from the moment of the response. Emitted only for entries in offline_stations on the session response; it never appears on streaming stations, nor on the station-list routes even when those are listing offline stations.

country_inclusion_modestring

How the countries list should be read: include means the station is available only in those countries, exclude means it is available everywhere but those.

Example: include

countriesstring[]

Two-letter ISO 3166-1 alpha-2 country codes the country_inclusion_mode applies to. Emitted only when country_inclusion_mode is exactly include or exclude, and never null in that case — when the property is present it always carries the list. Absent for any other mode.

]

offline_placement object

A placement — an immutable collection of stations and the playback options that apply across them.

idstringrequired

The placement id. Numeric, but always serialized as a string.

Example: 10955

options objectrequired

Free-form, customer-configured placement options, passed through verbatim. Contents vary per customer.

property name*any

Free-form, customer-configured placement options, passed through verbatim. Contents vary per customer.

offline_stations object[]

The stations available for offline download. Present only when offline_placement is. These are the only stations anywhere in the API that carry expire_date.

Array [

idstringrequired

The station id. Numeric, but always serialized as a string. This value changes with the 'placement id', and so should not be persisted - use the uuid property instead.

Example: 727

namestringrequired

The station's display name.

Example: Pop Rock

on_demandintegerrequired

Whether the station is an on-demand station: 1 for yes, 0 for no.

Possible values: [0, 1]

pre_gainnumbernullablerequired

Station-level gain adjustment in dB, to be applied before playback. null when the station has no adjustment configured.

options objectrequired

Free-form, customer-configured options attached to a station. Contents vary per customer; unknown keys should be passed through rather than rejected.

crossfade_secondsnumber

Crossfade duration for the station, in seconds.

property name*any

Free-form, customer-configured options attached to a station. Contents vary per customer; unknown keys should be passed through rather than rejected.

uuidstringrequired

The station's stable external identifier. Unlike id, it does not change over time.

Example: FgT1_Yzvr_e05ANk2uCYdZi

crossfade_secondsnumbernullablerequired

The station's own crossfade duration in seconds. null when unset. This may differ from the customer-configured options.crossfade_seconds; the two can disagree.

single_playbooleanrequired

true when the station is a single-play station — one track, not a continuous stream.

last_updateddate-timerequired

When the station's contents last changed. Clients use this to decide whether a cached offline copy is stale.

last_play_startdate-time

When this client last started a play on this station. Emitted only when such a play exists, so it is absent for new clients and for stations the client has never played.

expire_datedate-time

When a downloaded offline copy of this station should be considered expired — three weeks from the moment of the response. Emitted only for entries in offline_stations on the session response; it never appears on streaming stations, nor on the station-list routes even when those are listing offline stations.

country_inclusion_modestring

How the countries list should be read: include means the station is available only in those countries, exclude means it is available everywhere but those.

Example: include

countriesstring[]

Two-letter ISO 3166-1 alpha-2 country codes the country_inclusion_mode applies to. Emitted only when country_inclusion_mode is exactly include or exclude, and never null in that case — when the property is present it always carries the list. Absent for any other mode.

]

SessionResponse

{
  "success": true,
  "session": {
    "available": true,
    "client_id": "FgT1_Yzvr_e05ANk2uCYdZi",
    "time": 1754265600,
    "message": "Sorry, there is no streaming music available for your client"
  },
  "placement": {
    "id": "10955",
    "options": {}
  },
  "stations": [
    {
      "id": "727",
      "name": "Pop Rock",
      "on_demand": 0,
      "pre_gain": 0,
      "options": {
        "crossfade_seconds": 0
      },
      "uuid": "FgT1_Yzvr_e05ANk2uCYdZi",
      "crossfade_seconds": 0,
      "single_play": true,
      "last_updated": "2024-07-29T15:51:28.071Z",
      "last_play_start": "2024-07-29T15:51:28.071Z",
      "expire_date": "2024-07-29T15:51:28.071Z",
      "country_inclusion_mode": "include",
      "countries": [
        "US"
      ]
    }
  ],
  "offline_placement": {
    "id": "10955",
    "options": {}
  },
  "offline_stations": [
    {
      "id": "727",
      "name": "Pop Rock",
      "on_demand": 0,
      "pre_gain": 0,
      "options": {
        "crossfade_seconds": 0
      },
      "uuid": "FgT1_Yzvr_e05ANk2uCYdZi",
      "crossfade_seconds": 0,
      "single_play": true,
      "last_updated": "2024-07-29T15:51:28.071Z",
      "last_play_start": "2024-07-29T15:51:28.071Z",
      "expire_date": "2024-07-29T15:51:28.071Z",
      "country_inclusion_mode": "include",
      "countries": [
        "US"
      ]
    }
  ]
}