Updated October 10, 2013

API Documentation (version 3.0)

1 Introdution


This developer API offers a pretty typical RESTful interface and all calls are available in 3 formats: JSON, XML, and JSONP. You can pick your format by appending what you need at the end of the URL or by passing a parameter called format.

In this documentation we will show examples of the JSON version of the API but you can use any of these 3 formats.


A typical response will look like this:

  • status: it is the same as the HTTP Status code and is only here to make the API easier to use. You can expect to see the following status codes:
    • 200 OK
    • 301 Moved Permanently
    • 302 Moved
    • 401 Unauthorized
    • 403 Forbidden
    • 404 Not Found
    • 500 Internal Server Error
  • errors: a string that lists errors that occurred during this request.
  • notices: a string of what happened during the request such as 'logged in successfully'
  • logged_in: indicates if you are currently logged in

And when you're being returned paginated content:

  • page: this is the page you're on
  • per_page: this is how many items there are per page.
  • total_entries: this is how many items there are, total.

2 Developer Authentication

If you don't have one yet, go get a Developer API key. Don't lose it because you'll need to pass this key on every request.
You can pass your API key in 2 ways: as a parameter or as a custom HTTP header:

Note that you must also pass the api_version=3 parameter or X-Api-Version: 3 header on every call if you wish to use the latest API features. For legacy reasons, the API will default to the version 2.1 (which is documented in the legacy docs).

3 User Authentication

Step 1: Verify credentials

Before you can call our API with user credentials, you must first verify that you have the correct login/password.
You can use HTTPS/SSL in order to avoid passing user credentials in clear.

Good Password

Bad password

We currently support 2 kinds of authentication:
- User token Authentication (the preferred way)
- Basic HTTP Authentication

Step 2: User token Authentication

This is the preferred authentication method. Once you verified the user credentials, you need to save the "user-token" value passed in the response. You can then use this token as a parameter or as a header to login the user on all subsequent requests:

(Alternate) Step 2: Basic Authentication

Once you verify user credentials, you can use Basic Authentication for any call requiring authentication. If you use incorrect credentials:

This is what you get when you use correct credentials:

Signing up Users

Creating a user account is similar to logging in. It will return the same user object and user authentication token.
Status returned can be 201 if successful or 422 is there's a validation error.

4Mix Sets - find a mix

Smart IDs

The MixSet system replaces the older Mixes API. It allows much more varied and granular retreival of mixes, as well as unique identifiers (called smart ids) for each list. The smart id is colon-separated string made from a keyword, called the smart type, and some additional parameters. The parameters needed depend on the smart type, and can include a numerical ID, url-escaped string, and additional keywords for sorting.

The simplest call possible is to get the 12 currently trending mixes, using the smart id all with no modifiers:

This returns a list of mixes and some relevant data about the set. This list is unfiltered (all mixes) and the sort is unspecified, so it defaults to the "Trending" sort (aka "hot"). We can specify another sort by modifying the smart id in the request — for example all:recent or all:popular. The most common kinds of smart ids are exemplified below for convenience.

Smart ID    Description
all:popular all mixes
tags:chill mixes tagged "chill"
tags:chill+hip_hop:recent new mixes tagged "chill" & "hip hop"
artist:Radiohead mixes including songs by Radiohead
keyword:ocarina mixes including the text "ocarina"
dj:1 mixes published by the user with id=1
liked:1 mixes liked by the user with id=1
similar:14 mixes similar to mix with id=14

For more on using smart IDs and all of the available mix sets, see the appendix on smart ids →

Hiding NSFW mixes
If you know 8tracks, you know that some mix covers are pretty hot but unfortunately inappropriate in some environments. We let our users report these mixes as NSFW (Not Safe For Work). Logged-in users have the ability to hide/show NSFW mixes directly in their settings so you don't need to do anything special for them.

If you want to hide NSFW mixes everywhere, you have 2 options:
- you can add the "safe" parameter to any smart_id, for instance: http://8tracks.com/mix_sets/tags:hip_hop:safe.json
- or, you can look at the "nsfw" value on each mix returned and hide its cover when nsfw=true.


While changing smart id results in a different set of results being returned, other parameters can be used to access more data from the set:

  • page: the page of results to be retreived
  • per_page: how many items to return per page
  • include: specify field groups to return for the mix set

To view the next page of results, we specify the page number and include the "pagination" field group. NOTE: The page & per_page parameter works for all paginated API calls.


Includes let you specify which fields you want to retreive for a given call. For example Mix Sets can respond to the field groups mixes, pagination, details, and user (when applicable). As you'd expect, including each of these field groups will add data to the response. You can join multiple field groups in a list with commas or plus signs (, or +).

Includes can be nested using [square brackets], to specify which properties should be returned for child objects. For example, it may interest you to know about the users for each mix in a set:

Click here to see auto-generated documentation for MixSet includes →

5 Mixes - show a mix

To get information on a single mix, you can access it using the mix's numerical ID or the full_slug, or path property.

This will return a Mix object, identical to the one returned as part of a MixSet mixes[] list, and able use the same include properties.

Click here to see auto-generated documentation for Mix includes →

6Play tokens - play a mix

Play Tokens are used to control access and playback of mixes and tracks. Rules, such as randomized tracks after the first listen of a mix, are applied accordingly. Play tokens are scoped around a single user for unlimited mix playback. To create a new play token call:

With a play token you can select a mix for playback. To select the mix, you'll need the mix id, available from the Mix Set API.

  • at_beginning: true if you are at the first track in the mix.
  • at_last_track: true if you reached the final track in the mix.
  • at_end: true if you are past the final track.
  • skip_allowed: true if you can skip at this point, false if the maximum number of skips has been reached. (This field is only meaningful after you have first called skip.json)

After the track has finished playing simply call 'next':

OR the user selects "skip track", then call 'skip':

If skipping is not allowed you will get the following response:

In your code you must distinguish between the end of a song and the user skipping to the next song. If you call skip.json, you will get the next song in the mix — if 'skip' has not been called at least three times on that mix during the current 60 minute timeframe. If 'skip' has been called more than three times you will get the response header listed above. Each time you call skip, you should check the status field of the response, or check the code in the response-headers before you attempt to parse the results. You can also keep track of the skip_allowed parameter to disable skips in your client.

DON'T FORGET: Reporting the song

In order to be legal and pay royalties properly, 8tracks must report every performance of every song played to SoundExchange. A "performance" is counted when the 1 second mark of a song is reached. So at 1 second, you must call the following:

7More on playing mixes

Get a similar mix
When playback reaches the end of the mix, it's nice for users to redirect them to another similar mix so music keeps playing.
Get the next mix in the set

Getting a similar mix is nice, but to keep the experience as consistent as possible with the website, it's even better to keep users in context. For instance, if a user is listening to his/her liked mixes and is done with the first mix in the list, we want to redirect him/her to the 2nd mix on that list. To do this, you just need to pass the smart_id parameter, using the smart id the mix set you want to use (in this case, liked:user_id):

Get the list of tracks already played
When loading a mix, the user may have already started listening to it before so it's best to show the tracks they've already heard when they view the mix.

8 Users

View user info:

Click here to see auto-generated documentation for User includes →

List mixes made by a user:

To access, other user-specific mix sets, including Liked mixes, the activity feed, recommendations, and collections, you must use the advanced smart_ids.

9 Reviews

Getting the paginated reviews (aka comments) from a mix:

Comments on a mix are returned in reverse-chronological order but with replies inserted directly after their parent comments. If a comment has a parent_id, it should always have a parent review directly antecedent in the list. Replies are not counted in the per_page calculation when retreiving reviews.

Click here to see auto-generated documentation for Review includes →

Posting a review on a mix:

10 Tags

Tags are the preferred way for browsing 8tracks mixes.

Browse and search tags
Get the top tags:
Search tags (very cool for autocompleting):

11 Like Mixes, Tracks or Users

There are 3 kinds of actions that users can take towards mixes, tracks and other users:
- for a mix: like / unlike / toggle_like
- for a track: fav / unfav / toggle_fav
- for a user: follow / unfollow / toggle_follow

For these actions, you must be logged in.

Liking a Mix
  • liked_by_current_user: lets you know if the current user likes this mix. This can be incnluded anywhere in the API when you get a mix (field group: liked).

Favoriting a Track
  • faved_by_current_user: lets you know if the current user faved this track. This can be included anywhere in the API when you get a track (field group: faved).

Following a User
  • followed_by_current_user: lets you know if the current user follows this user. This can be returned anywhere in the API when you get a user (field group: followed).

    • 12 Collections

      Collections are user-collected lists of mixes. They can be accessed like any other MixSet through the collection smart type, which uses the user ID and the collection slug, like so:

      To get these slugs, you can also list all of the collections for a particular user:

      This request returns a MixCluster, an abstract object containing a list of mix sets.

      Creating and editing collections

      When logged in, a user can create, edit, and add to collections. Often this is done by picking one mix from which to start a collection. The optional mix_id parameter lets us create a collection and add a mix to it at the same time.

      Once you've created a collection, you can retreive the list of editable collections for a user. This is useful when a user selects a mix to add to a collection, so you can show them all the possible destinations.

      This request is similar to viewing a user's public collections, but includes the collections' numerical IDs, which are used to add and remove mixes. It also includes private collections, like "Listen Later." If we pass a mix_id parameter, it will also include a contains_mix bit for each collection, telling us whether the mix with that ID is already included.

      To add a mix to a collection, we make a POST request to the /collections_mixes endpoint, passing collection_mix[collection_id] and collection_mix[mix_id].

      To remove a mix from a collection, we make the a DELETE request with identical parameters.

      Click here to see auto-generated documentation for Collection includes →

      13 Presets

      Presets allow a user to save certain MixSets for easy retreival. For example, Remi always listens to chill+hip hop and wants to have a shortcut straight to this search. We can save a preset by sending the smart ID to the user's add_preset endpoint.

      This returns the new list of the user's presets. To get a user's list of presets without adding one, we can just use the presets include.

      To remove a preset, we make the same request as we did to create one, only to the /remove_preset endpoint.

      Further topics

      You may see some features on the website or official apps that are not documented here. You may get what you need simply by reverse-engineering the website, but we're always trying to improve our documentation and community knowledge, so please post your requests and discoveries over on the 8tracks Developer Forum.

      Syntax highlighting in this document by SyntaxHighlighter 3.0.83 © 2004-2010 Alex Gorbatchev