Skip to main content

Session

POST /session is the entry point to music playback. It mints a client id on first call and reports whether this listener can play any music at all. Nothing else on the API is much use before it.

This call returns a subset of all stations that the client may play. These stations are immutable and will not update or go away when referred by their id, although songs in any station might disappear due to rights restrictions. To retrieve new stations or station updates, a new call must be made to POST /session. We recommend you make this call at least once every 24 hours.

This page assumes you have read REST API overview for the terms it uses and Credentials for how requests are authenticated. Every command below was run against https://feed.fm/api/v3 with the demo/demo test credentials and shows what actually came back.

Starting a session​

Omit client_id the first time. The server mints one and returns it in session.client_id; store it and send it back on every later call.

curl -sS -u demo:demo -X POST https://feed.fm/api/v3/session \
  -H 'Content-Type: application/json' \
  -d '{}'
{
  "success": true,
  "session": {
    "available": true,
    "client_id": "mu7kfa0w:r3:xyw8tboqxvn",
    "time": 1789772751,
    "log": true
  },
  "placement": { "id": "149548", "options": {} },
  "stations": [
    { "id": "199835928", "name": "Station One", "uuid": "9ebd57dc-c034-4373-a424-51764406bfcb", "...": "..." },
    { "id": "199835930", "name": "Station Two", "uuid": "94102d35-60d5-4494-bc0a-5288cdb29319", "...": "..." }
  ]
}

The examples across these pages chain together with shell variables. Set the first one from the response above:

export CLIENT_ID="mu7kfa0w:r3:xyw8tboqxvn"

Check session.available first​

An unavailable session still returns HTTP 200 with success: true. The signal is inside the body: session.available is false, stations and placement are absent, and session.message explains why in words you can show a listener.

The badgeo test credential reproduces it on demand:

curl -sS -u badgeo:badgeo -X POST https://feed.fm/api/v3/session \
  -H 'Content-Type: application/json' -d '{}'
{
  "success": true,
  "session": {
    "available": false,
    "message": "Sorry, there is no music available for your client",
    "client_id": "mu8zj44q:2d8:xxbi32s6eq",
    "time": 1789858492,
    "log": true
  }
}

A client that branches on the HTTP status, or on success, will sail past this and then fail confusingly at POST /play. Branch on session.available.

Territory​

Licenses are jurisdiction-specific, and the server resolves territory from the caller's IP address. That is what a false available usually means: the listener opened your app somewhere you have no rights.

warning

Do not proxy API requests on behalf of your listeners. Proxying relocates every listener to your server's country, which streams the wrong catalog under the wrong license. Clients call Feed.fm directly.

Refreshing a session​

Send the stored client_id back and the same listener is recognized, with play history, likes and skip limits intact:

curl -sS -u demo:demo -X POST https://feed.fm/api/v3/session \
  -H 'Content-Type: application/json' \
  -d "{\"client_id\":\"$CLIENT_ID\"}"

There is no session to close and no session object to fetch afterwards. Calling POST /session again just returns a fresh view of what that client may play.