REST API

Overview​

The Feed.fm REST API works over HTTPS, uses basic HTTP authentication for all calls, and uses JSON syntax for all responses. The API was designed to power DMCA Internet Radio style playback, but has been extended to support a simple form of on-demand music playback.

The basic process for music playback is as follows:

• Client requests a new 'session' (POST session) on startup, and is handed back a unique client id (cid) plus a (partial) list of available music stations. The cid should be stored on the client device indefinitely and sent with all future requests to the API (including future session requests).
• Client searches for a specific station or list of stations from the server, based on metadata attached to the station (genre, foreign key, e.t.c.)
• Client requests a new 'play' (POST play) for some specific station id, maximum bitrate, and audio encoding format. The server returns song metadata (track name, artist name, release/album name) and a URL to an audio file.
• Client retrieves and begins playback of the audio file, and immediately reports to the server that song playback has started (POST play/{id}/start).
• Periodically, during playback, the client may tell the server how much playback has elapsed (POST play/{id}/elapse\).
• When the client has completed playback of the current song, it reports this to the server (POST play/{id}/complete).
• Client repeats the process of requesting, starting, and completing songs.

Additionally, the client can report likes and dislikes (POST play/{id}/like) and (POST play/{id}/dislike), can request permission to skip the current song (POST play/{id}/skip), and can report that it was unable to begin playback of a certain play (POST play/{id}/invalidate).

In order to adhere to DMCA playback restrictions, repeated requests for music from a specific station will return the same song until the song is reported as started (POST play/{id}/start) or invalidated (POST play/{id}/invalidate). A client, therefore, cannot queue up more than one song in a station.

Some music stations are considered on-demand. For these stations, the client may retrieve a listing of all the songs available in each station for playback (GET station/{id}/audio_file), and the client may begin playback of any of those songs at any time.

Location​

When this documentation uses relative paths in commands such as GET station/{id}/audio_file or POST session, the base URL for those commands is https://feed.fm/api/v2/. The full url for POST session is therefore https://feed.fm/api/v2/session. The full url for GET station/{id}/audio_file is, similarly, https://feed.fm/api/v2/station/{id}/audio_file.

Response Format​

Responses to all resource calls are represented as JSON objects. Minimally, every response indicates wether the call was successful or not and, if not, includes an error code and descriptive message explaining why the call wasn't successful.

A successful request always minimally returns:

{
  "success": true
}

A failed request always minimally returns an error object to describe what went wrong, which contains a feed-specific error code, a human readable description of the error, and the HTTP status code associated with the error (see 'Error codes' below for why the HTTP status code is included).

{
  "success": false,
  "error": {
    "code": 123,
    "message": "human readable error for code 123",
    "status": 200
  }
}

Error Codes​

Listed below are general error codes that could be returned from any resource call.

Note that the response message returned from the server will often have more detailed information about why a particular error occurred. For instance, error 17 (missing object) should describe which object is missing in the message response.

For clients that are unable to access response bodies for non-200 status HTTP responses, all endpoints accept a 'force200=1' parameter, which causes the server to always respond with HTTP 200 status.

Each resource may have additional error codes, specific to the resource. These are listed in the documentation for each resource.

Authentication​

All requests require authentication, which is an encoding of the app-specific token and secret values in the HTTP request using 'Basic' HTTP authentication defined in RFC 2617

The 'Basic' scheme requires a simple 'Authorization' header to be passed with the request, along with base-64 encoded credentials:

Authorization: Basic Yjg4MTU1MGU5MmUwOWIwMzQyN2Q0MTEzMzMzOWNhNjVhNWMzM2EwMDphNzVlNjMzMzFkOGZlMzhhN2I0YWYxNzJlMGY5NGJiY2QwNzkxYmU4

The encoded portion of the header above is the base64 encoding of the concatentation of

token ":" secret

(where 'token' and 'secret' are provided via the developer interface). The example above was constructed with a 'token' value of 'b881550e92e09b03427d41133339ca65a5c33a00' and a 'secret' value of 'a75e63331d8fe38a7b4af172e0f94bbcd0791be8'.

For testing purposes, you may use a token and secret value of 'demo', which encodes to:

Authorization: Basic ZGVtbzpkZW1v

New token/secret pairs can be created from the initial token/secret provided to you, via the credentials endpoints describe below.

Identity​

In addition to authorization credentials, the client must include a unique identity token along with all requests except for the very first session creation call (POST session). This value is used to record playback history and enforce DMCA playback restrictions.

When a session is created (POST session), a 'client_id' is returned along with station data. That value should be cached on the client and passed to all future calls as either

• an HTTP Cookie value named 'cid'
• a query parameter named 'client_id'
• a form parameter in the body of the request named 'client_id'

The returned client id must be passed to future POST session calls, and the same value will be returned in the response.

Station Country Availability​

Our API servers may return different stations to clients based on their geo-ip-mapped country. For instance, a client in the United States may receive a different set of stations than one in Yemen. This is done due to country-level licensing restrictions. Normally a client need not care about this - the API will only render stations available to the client. However, the https://feed.fm/api/v2/station endpoint allows you to retrieve the list of all station available everywhere. To determine what countries each station is available to, the station metadata contains a "country_inclusion_mode" string and an optional "countries" array.

"country_inclusion_mode" may be one of the following values:

• "include_all" - this means the station is available everywhere
• "exclude_all" - this means the station is not available anywhere (this is not a common mode)
• "include" - this means the station is available to all the countries listed in the "countries" array
• "exclude" - this means the station is available to all countries except those listed in the "countries" array

The "countries" array, when present, is an array of 2-letter country ISO codes.

A station available only to clients in the United States and Canada would have the following:

{
  "id": "15546",
  "name": "For US and Canada users",
  "on_demand": 0,
  "country_inclusion_mode": "include",
  "countries": ["US", "CA"],
  "options": {
    "foo": "bar"
  }
}

A station available only to clients not in the United States and Canada would have the following:

{
  "id": "15546",
  "name": "For users outside of US and Canada",
  "on_demand": 0,
  "country_inclusion_mode": "exclude",
  "countries": ["US", "CA"],
  "options": {
    "foo": "bar"
  }
}

A station available globally would look like:

{
  "id": "15546",
  "name": "For users everywhere",
  "on_demand": 0,
  "country_inclusion_mode": "include_all",
  "options": {
    "foo": "bar"
  }
}

Credentials management​

Rather than give all clients the same token and secret value, which could be abused, you can generate time-limited token/secret values instead. These limited token/secret values can be created on demand and will automatically expire after some period of time, or can be revoked on demand.

POST https://feed.fm/api/v2/access_token​

This method creates a new token/secret pair that can be used in place of the token/secret pair provided to you.

This method must be authenticated with your original token/secret pair.

Body Parameters​

• ttl_seconds

  The number of seconds the new token/secret should be valid for. This defaults to 86,400 (one day). This parameter has a maximum value of 15,552,000 (6 months).

Error Codes​

This endpoint has no special error codes:

Response​

The returned object will contain a new token and secret value that is available for immediate use:

{
  "success": true,
  "access_token": {
    "token": "123123123123123",
    "secret": "464564564564564"
  }
}

DELETE https://feed.fm/api/v2/access_token/:token​

This method revokes a token/secret that was previously created via POST /access_token.

This method must be authenticated with your original token/secret pair.

Path Parameters​

• :token A token values that was created via POST /access_token

Error Codes​

This endpoint has no special error codes:

Response​

The returned object will only indicate if the deletion was successful.

{
  "success": true
}

Session creation/client registration​

POST https://feed.fm/api/v2/session​

At the start of an application run, the application should use this call to ask the server for a 'session', which

• confirms the cient has access to music (and is in a geographic region Feed.fm may stream to)
• returns a list of stations the client can pull music from
• assigns the user a unique client id (if one hasn't been assigned already)

This request must be authenticated.

Body Parameters​

• client_id (optional)

  The client identifier cached from a past POST session call. When passed, the response 'client_id' will match this value.

Error Codes​

In addition to the generic error codes, there are:

Response​

A session object, containing the client's unique id and a boolean indicating whether music is available or not.

A 'placement' object, with an id of the current placement. This id may be thought of as the 'version #' for the group of stations and their contents that are returned with this call. This value is passed on to POST play requests to ensure that the server pulls music from the same collection that was presented to the app at startup.

An array of 'station' objects, each of which has a station id, name, and 'options' object. These stations represent a select list of the stations currently available to the client. The 'options' object in each station will contain arbitrary app-data for the client.

Stations are flagged as 'on_demand' or not. For a station that is on-demand, the client may make an additional request to retrieve the list of tracks/audio files (see GET station/{id}/audio_file). When a POST play call is made later, the client can pass an audio file id corresponding to one of the on demand songs, and the server will return a play object for that specific song.

Despite being an attribute of the 'session' value, the user's client id should not be considered a session attribute - it should be cached and used with all future calls across all sessions.

Sample Response:

{
  "success": true,
  "session": {
    "available": true,
    "client_id": "123-123-123"
  },
  "placement": {
    "id": "123"
  },
  "stations": [
    {
      "id": "15546",
      "name": "Station One",
      "on_demand": 0,
      "options": {
        "subheader": "featuring music by artist A, B, and C!",
        "background_image_url": "https://dgase5ckewowv.cloudfront.net/feedfm-ps/1451428228-42921.jpg",
        "image": "https://dgase5ckewowv.cloudfront.net/feedfm-ps/1451428228-42921.jpg",
        "mixtape-bg": "https://dgase5ckewowv.cloudfront.net/feedfm-ps/1452640087-22634.jpg",
        "subhead": "featuring great music acts from the 2016 lineup",
        "images": "https://dgase5ckewowv.cloudfront.net/feedfm-ps/fab-dance-[[d]].jpg"
      }
    },
    {
      "id": "15547",
      "name": "Station Two",
      "on_demand": 1,
      "options": {
        "subheader": "Tunes to soothe your bad self",
        "background_image_url": "https://dgase5ckewowv.cloudfront.net/feedfm-ps/1451428258-29239.jpg",
        "image": "https://dgase5ckewowv.cloudfront.net/feedfm-ps/1451428258-29239.jpg",
        "mixtape-bg": "https://dgase5ckewowv.cloudfront.net/feedfm-ps/1449620480-44870.jpg",
        "images": "https://dgase5ckewowv.cloudfront.net/feedfm-ps/fab-indie-[[d]].jpg"
      }
    }
  ]
}

Station discovery​

Not all stations that a client has access to are returned in the POST /session call. In order to find other stations that are available to the client, or to search for a specific station, you must use one of the endpoints below. The GET /placement/:placementId/station endpoint should be be used by musical clients, and will search stations available in the given placement (which would normally be obtained from the POST /session call). The GET /station call will perform the same search against the latest stations published for the given application - and this call is mostly useful for content management systems that are looking to see the latest available stations for some application.

GET https://feed.fm/api/v2/placement/:placementId/station​

GET https://feed.fm/api/v2/station​

Retrieve a paginated list of stations that are available to the client. Both endpoints take the same arguments. The /placement/:placementId/station version should be used by clients to ensure that the list of stations doesn't change during the course of a session. The /station version searches against the most recently published list of stations (and is well suited to CMS applications that want to know what stations are available via the API).

These requests must be authenticated.

Path Parameters​

• placementId

  The placement id returned from the POST /session call.

Query Parameters​

• client_id

  The client identifier returned from POST /session or POST /client.

• page

  The page number to return. This is 0-indexed, and defaults to 0.

• per_page

  Number of stations to return per page. This defaults to 20.

• q station-query

  A search query to filter the results by. This optional parameter is a string. If the query starts with a { and is parsable as a JSON Object, then its properties their values will be used to search through the options JSON object associated with every station. If the query is not a JSON object, then it will be a case-sensitive substring search of all station names.

  If the parameter parses as a JSON object with { <field1>: <value1>, ... }, then all stations that have field1 set to value1 or to an array of values that includes value1 will be returned. If there are multiple field values in the query, then all must match against returned stations (that is, this is a conjunctive search).

  For example, given the following stations:

  • station A with options value: { "genre": "foobar" }
  • station B with options value: { "genre": "rock" }
  • station C with options value: { "genre": [ "rock", "hip-hop" ] }

  Then the following queries will return the following results:

  • a search for { "genre": "rock" } will return stations B and C
  • a search for { "genre": "hip-hop" } will return station C
  • a search for { "genre": "foobar" } will return station A
  • a search for cool station will return all stations with cool station in their name

  We are modelling our search after the MongoDB query syntax. If you need additional search operators, please contact us.

• all_countries

  This argument only applies to the /station endpoint. When present and set to any value, the search will return all stations that are available to the client, regardless of the country that the request is made from. Normally a call to /station will only return stations available in the client's geo-ip-mapped country.

• and_countries

• or_countries

  These are optional comma-separated lists of 2-letter country codes to filter the stations by. The and_countries parameter will return only stations that are available in all of the countries listed. The or_countries parameter will return stations that are available in any of the countries listed. Providing either of these parameters implicitly sets the all_countries parameter to true.

  For example, to only return stations that are streamable in the US and CA, you would pass: and_countries=US,CA. To return stations that are streamable in the US or CA or both, you would pass or_countries=US,CA. You could return stations that are streamable in the US and either MX or GB with and_countries=US&or_countries=MX,GB.

• replay

• firstplay

• radio

  When any of these parameters are present, the search will be limited to stations that are of the specified type.

Error Codes​

Any generic error codes may be returned.

Response​

The response is a JSON object that represents a page of stations

Sample Response

{
  "success": true,
  "stations": [
    {
      "id": "123",
      "name": "Dance Pop High",
      "on_demand": 0,
      "pre_gain": 10.07,
      "options": {
        "genre": [
          "dance_pop"
        ],
        "bpm": [
          "110-130"
        ]
      },
      "single_play": false,
      "last_updated": "2021-06-17T03:29:00.000Z",
      "can_skip": true,
      "can_like": true,
      "country_inclusion_mode": "include",
      "countries": [ "US", "CA" ]
    },
    {
      "id": "456",
      "name": "Shoe Gaze Low",
      "on_demand": 0,
      "pre_gain": 10.07,
      "options": {
        "genre": [
          "shoe_gaze"
        ],
        "bpm": [
          "130"
        ]
      },
      "single_play": false,
      "last_updated": "2021-06-17T03:29:00.000Z",
      "can_skip": true,
      "can_like": true,
      "country_inclusion_mode": "include",
      "countries": [ "US", "CA" ]
    },
    {
      "id": "789",
      "name": "Shoe Gaze Low",
      "on_demand": 0,
      "pre_gain": 10.07,
      "options": {
        "genre": [
          "shoe_gaze"
        ],
        "bpm": [
          "130"
        ]
      },
      "single_play": false,
      "last_updated": "2021-06-17T04:10:00.000Z",
      "can_skip": true,
      "can_like": true,
      "country_inclusion_mode": "exclude",
      "countries": [ "US", "CA" ]
    }
  ],
  "total": 2,
  "page": 0,
  "per_page": 20
}

GET https://feed.fm/api/v2/station​

Retrieve a paginated list of the latest stations that are available

Query Parameters​

• client_id

  The client identifier returned from POST /session or POST /client. A client id is not required for this call.

• page

  The page number to return. This is 0-indexed, and defaults to 0.

• per_page

  Number of stations to return per page. This defaults to 20.

• q

  This is the same syntax and semantics as here.

• _all_countries

  By default, this endpoint searches only through stations available in the country that the client is requesting from. When all_countries is present in the query string with any value, this endpoint will search through all stations available to all users.

Error Codes​

Any generic error codes may be returned.

Response​

The response is a JSON object that represents a page of stations

Sample Response

{
  "success": true,
  "stations": [
    {
      "id": "123",
      "name": "Dance Pop High",
      "on_demand": 0,
      "pre_gain": 10.07,
      "options": {
        "genre": [
          "dance_pop"
        ],
        "bpm": [
          "110-130"
        ]
      },
      "single_play": false,
      "last_updated": "2021-06-17T03:29:00.000Z",
      "can_skip": true,
      "can_like": true,
      "country_inclusion_mode": "include",
      "countries": [ "US" ]
    },
    {
      "id": "456",
      "name": "Shoe Gaze Low",
      "on_demand": 0,
      "pre_gain": 10.07,
      "options": {
        "genre": [
          "shoe_gaze"
        ],
        "bpm": [
          "130"
        ]
      },
      "single_play": false,
      "last_updated": "2021-06-17T03:29:00.000Z",
      "can_skip": true,
      "can_like": true,
      "country_inclusion_mode": "include_all"
    }
  ],
  "total": 2,
  "page": 0,
  "per_page": 20
}

Song retrieval and playback​

Song playback requires the client to ask the server for something to play, followed by status updates to the server for auditing purposes.

POST https://feed.fm/api/v2/play​

Retrieve a song for playback. This method retrieves all the meta-data about the song along with pointers to the actual song data itself.

Unless a station is 'on_demand', the server will make the selection of which song to return for playback. This selection is made based on client playback history, DMCA rules, and past like/dislikes.

If a station is 'on_demand', then the client can request playback of a specific song by passing an 'audio_file_id' parameter (retrieved via a GET station/{id}/audio_file call).

Repeated calls to this method will return the same song in response until a successful POST play/{id}/start, POST play/{id}/skip, or POST play/{id}/invaldate call has been made to let the server know whether the song has begun playback not.

For single play (also called first play) stations where the server knows the order of the songs in the station, a client can request the song that would be playing at time X if the client played the station from the start (while honoring crossfades and song trims). See the at parameter, below.

This method must be authenticated.

Body Parameters​

• client_id

  The client identifier returned from the POST client call.

• placement_id

  The id of the placement from which music is drawn.

• station_id (optional)

  id of station in placement to draw music from. If no station id is provided the service will pick a default station.

• formats (optional)

  Comma separated list of formats that the client is capable of playing. Available values are aac and mp3. The client can specify multiple values by separating them with commas. The server will use this information, along with the max_bitrate parameter, to pick a specific version of the audio file to return to the client.

• max_bitrate (optional)

  This specifies the maximum bitrate for any audio files that are sent to the client. The value should be expressed as an integer and a multiple of 1,000. A value of "96" would imply a maximum bitrate of 96kb/s.

• audio_file_id (optional, for on-demand stations only)

  This indicates a specific song/audio file that the client wants to play in the given station. The audio file must exist in the requested station, and have been provided earlier to the client via the POST session call.

at (optional, for first play stations)

This parameter is a float value, and indicates the number of seconds into the station that the client wishes to start music playback. When provided, the server will compute which song would be playing at the given time if the client played all the songs from the start, while honoring trims and performing crossfades. This parameter allows a user to 'fast forward' into a station. When this option is provided, the returned object will contain an additional start_at property, which tells the client where to being playback of the returned song so it will appear as if the user skipped ahead to exactly the timestamp provided in the request.

This parameter does not allow a user to jump 'back' to some period of time or to repeat a song. If the user requests a play at timestamp 310, they may not then request any song that would have started before 310.

If the client provides an at parameter, and the station from which music is being pulled is not single play (first play), an error will be returned.

The addional start_at property returned in the response is an offset from the start of the given audio file, ignoring any start trim. When this property is present, the client should begin playback of the song at that time offset and inform the server that playback has started.

Error Codes​

In addition to the generic error codes, there are:

Response​

The returned play object will contain track title, release title, and artist name information, along with a URL pointing to a file with audio data. The encoding of the audio data will be presented as one of 'aac', 'he-aac', or 'mp3'. The response format will be the same for on-demand and regular stations.

The URL to the audio data should be considered time sensitive, client specific, and may contain query parameters. If it isn't used within the next 30 minutes, the URL may expire and return 404 not found.

Sample Response

{
  "success": true,
  "play": {
    "id": "27555",
    "station": {
      "id": "599",
      "name": "East Bay"
    },
    "audio_file": {
      "id": "665",
      "duration_in_seconds": "300",
      "track": {
        "id": "15224887",
        "title": "3030"
      },
      "release": {
        "id": "1483477",
        "title": "Deltron 3030"
      },
      "artist": {
        "id": "766824",
        "name": "Del the Funky Homosapien"
      },
      "codec": "aac",
      "bitrate": "128",
      "url": "https://feed.fm/audiofile-665-original.aac"
    }
  }
}

POST https://feed.fm/api/v2/play/{id}/start​

Inform the server that the user has started playing a song. This call must be made as soon as the client starts playing the song returned from a POST play call.

Immediately after this call is made, and before a POST play/{id}/skip or POST play/{id}/complete call has been made, the client may make another call to POST play to queue up the next song for playback.

This method must be authenticated.

Path Parameters​

• id

  The id of the play that has begun playback.

Error Codes​

Only the generic error codes.

Response​

This method returns a boolean result value. If true, the user may skip this song. If false, the user should not be allowed to skip the current song and must hear it to completion before another song may be started. Note: if 'canskip' returns false, the client may definitely not skip playback of this song, but if the 'can_skip' value returns true, the user still _might not be able to skip the song (the client won't know until after calling POST play/{id}/skip and getting the response code).

Sample Response

{
  "success": true,
  "can_skip": true
}

POST https://feed.fm/api/v2/play/{id}/elapse​

During song playback, this call may be made periodically to indicate how many seconds of playback have elapsed for the user. This call isn't required, but is useful for reporting. The 'seconds' value should never be greater than the full duration of the song and it should always measure time from the start of song playback (as opposed to elapsed time since the last 'elapse' call). Only the most recent value passed to this call is saved.

This method must be authenticated.

Path Parameters​

• id

  The id of the play that is being referenced.

Body Parameters​

• seconds

  The number of seconds of playback that has elapsed, expressed as an integer or floating point number. This value should never be less than 0 and will always be capped by the server to be no more than the duration of the song.

Error Codes​

Only the generic error codes.

Response​

Sample Response

{
  "success": true
}

POST https://feed.fm/api/v2/play/{id}/skip​

If the user wishes to skip the current song, this call should be made to inform the server and receive confirmation that the user can skip the call.

If this call returns a value of 'true' for 'success', then the client may stop playback of the current song and begin playing the next song retrieved from POST play. The client should not make a call to POST play/{id}/complete for the song being skipped if the skip is successful.

If playback rules prohibit this song from being skipped, the response will have a 'success' value of 'false'. The user must listen to the song through to completion before the next play may begin.

This method must be authenticated.

Path Parameters​

• id

  The id of the play that is being referenced.

Body Parameters​

• seconds (optional)

  Elapsed seconds of music that the client has played

Error Codes​

In addition to the generic error codes, there are:

Response​

Unlike other resource calls, this method has no return value per se - it only successfully skips or not.

Sample Response

{
  "success": true
}

POST https://feed.fm/api/v2/play/{id}/invalidate​

If the client application is unable to start a song returned from a POST play call (the media file is missing or unexpectantly doesn't appear to work on the client platform), then this call may be used to inform the server and mark the play as invalid so a subsequent POST play call doesn't return the same play.

This method should only be used when the client has technical difficulty playing a song. It should not be used for user-initiated skipping - the POST play/{id}/skip should be used in that case.

This method must be authenticated.

Path Parameters​

• id

  The id of the play that is being referenced.

Error Codes​

Only the generic error codes.

Response​

This method always returns a 'success' status of 'true'.

Sample Response

{
  "success": true
}

POST https://feed.fm/api/v2/play/{id}/complete​

Inform the server that the given song has played to completion.

This method must be authenticated.

Path Parameters​

• id

  The id of the play that is being referenced.

Error Codes​

Only the generic error codes.

Response​

This method always returns a 'success' status of 'true'.

Sample Response

  "success" : true
}

POST https://feed.fm/api/v2/play/{id}/like​

A POST to this endpoint informs the server that the client 'likes' this song.

Path Parameters​

• id

  The id of the play that is being referenced.

Error Codes​

Only the generic error codes.

Response​

This method always returns a 'success' status of 'true'.

Sample Response

  "success" : true
}

DELETE https://feed.fm/api/v2/play/{id}/like​

A DELETE to this endpoint informs the server that the client no longer 'likes' this song. note this is not the same as a 'dislike', which indicates that the user has negative feelings about a song.

Path Parameters​

• id

  The id of the play that is being referenced.

Error Codes​

Only the generic error codes.

Response​

This method always returns a 'success' status of 'true'.

Sample Response

  "success" : true
}

POST https://feed.fm/api/v2/play/{id}/dislike​

A POST to this endpoint informs the server that the client does not like this song. This does not trigger any kind of automated skip of the current song.

Path Parameters​

• id

  The id of the play that is being referenced.

Error Codes​

Only the generic error codes.

Response​

This method always returns a 'success' status of 'true'.

Sample Response

  "success" : true
}

Station/Song Metadata retrieval​

GET https://feed.fm/api/v2/station/{id}/audio_file​

This endpoint retrieves a listing of songs (referred to as 'audio files') contained in an on-demand station. The returned audio file metadata may be displayed to users to select for playback. This method does not return URLs to actual encoded audio - only metadata. The audio data for each song may be retrieved by sending a POST play command with the 'audio_file_id' parameter set to the id of the desired audio file retrieved from this call.

Path Parameters​

• id

  The id of the station that we are retrieving songs/audio files from. These ids are returned in the POST session response.

Query Parameters​

• client_id

  The current user's client id, as returned from the POST session call.

• per_page

  This call returns up to 'per_page' number of songs from the specified station. The default value is 20.

• page

  The 0-based index of the page of audio files to return, where the 'per_page' parameter defines how many audio files are in a page. The default value is 0.

Error Codes​

Only the generic error codes.

If a request is made to retrieve audio files for a station that is not flagged as an 'on_demand' station, this call will return an empty list, as if the station had no songs in it, and not an error.

Response​

This method always returns a 'success' status of 'true'.

Sample Response

{
  "success": true,
  "total": 7,
  "page": 0,
  "per_page": 2,
  "audio_files": [
    {
      "id": "171432",
      "duration_in_seconds": 292,
      "track": {
        "id": "15393794",
        "title": "Good Thing"
      },
      "release": {
        "id": "1618797",
        "title": "It's About Time"
      },
      "artist": {
        "id": "1206212",
        "name": "Eddie Roberts' West Coast Sounds"
      },
      "extra": {}
    },
    {
      "id": "171436",
      "duration_in_seconds": 311,
      "track": {
        "id": "15393797",
        "title": "Now Is the Time"
      },
      "release": {
        "id": "1618797",
        "title": "It's About Time"
      },
      "artist": {
        "id": "1206212",
        "name": "Eddie Roberts' West Coast Sounds"
      },
      "extra": {
        "artwork": ""
      }
    }
  ]
}