Skip to main content

Start (or resume) a session for a client.

POST 
/session

The entry point to the API. This endpoint serves to create your client id, bind the client to a specific placement, and express if the client will be able to play any music at all.

A session returns a specific placement, which has a unique id and a list of stations. As new stations are published or their contents are changed, a new placement with a new id is created with those updated stations, but the original placement and stations continue to exist and are still available to clients. If your client is short lived, and you don't want to deal with stations disappearing or reappearing during a session, then you should use endpoints (like GET /placement/\{placement_id\}/station) that bind the request to a specific placement. For station-related calls that don't accept a placement argument (like POST /station and GET /station), the operation will be run against the most recently created placement. The returned placement and list of stations shouldn't be cached for more than 24 hours.

This is the only route that will mint a client for you. When the request carries no client_id the server creates one and returns it as session.client_id. Every other route will fail with missingParameter instead. Store the returned client_id and send it back on subsequent calls so the same listener is recognised; values longer than 23 characters are silently truncated.

Calling this again for a known client_id simply returns a fresh view of what that client may play.

When no music is available the call still succeeds with HTTP 200. The response is { "success": true } with session.available: false and a human-readable session.message (for example Sorry, there is no streaming music available for your client), and placement, stations, offline_placement and offline_stations are all absent. Check session.available, not the HTTP status. offline_placement and offline_stations are present only for apps configured for offline listening; the stations in that list carry an expire_date.

Request​

Responses​

The session was created. Inspect session.available to find out whether this client may actually play music — an unavailable session is reported here, not as an error status.