Updated October 10, 2013

API Documentation (version 3.0)

1 Introdution

Formats

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.

curl http://8tracks.com/mixes/1.xml curl http://8tracks.com/mixes/1.jsonp curl http://8tracks.com/mixes/1?format=json

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

Response

A typical response will look like this:

{ status: "200 OK", errors: null, notices: null, logged_in: false, api_version: 3 }

• 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:

curl http://8tracks.com/mixes/1.json?api_key=1234567890 - or - curl --header "X-Api-Key: 1234567890" http://8tracks.com/mixes/1.json

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

curl --request POST -d "login=remitest&password=password&api_version=3" https://8tracks.com/sessions.json { user : { user_token : "988;ca9c9d3b8cfc7a60047f5c9d87295b97ac135bd7", id : 988, login : "remitest", web_path : "/remitest", ... } }, status : "200 OK", errors : null, notices : "You are now logged in as remitest", logged_in : true, api_version : 3 }

Bad password

curl --request POST -d "login=remitest&password=badpass&api_version=3" https://8tracks.com/sessions.json { status : "422 Unprocessable Entity", errors : "Your login was unsuccessful", notices : null, logged_in : false, api_version : 3 }
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: curl --request POST -d "" http://8tracks.com/mixes/12345/toggle_like.json?user_token=1%3B123456789 - or - curl --header "X-User-Token: 1;123456789" --request POST -d "" http://8tracks.com/mixes/12345/toggle_like.json

(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: curl -u remitest:badpass --request POST -d "" http://8tracks.com/mixes/12345/toggle_like.json { status : "401 Unauthorized", failed_authentication : ["basic"], errors : "You must log in to do this.", notices : null, logged_in : false, }

This is what you get when you use correct credentials: curl -u remitest:password --request POST -d "" http://8tracks.com/mixes/12345/toggle_like.json { mix : { ... }, status : "200 OK", errors : null, notices : null, logged_in : true }

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. curl --header 'X-Api-Key: xxxxxx' --header 'X-Api-Version: 3' --request POST -d "user[login]=remitest&user[password]=password&user[email]=remitest@8tracks.com&user[agree_to_terms]=1" https://8tracks.com/users.json { type : "8tracks", status : "201 Created", user_created : true, user : { user_token : "7800938;d1b910ba3d07b91e706906022018b548f557f1da" id : 7800938, login : "remitest" ... }, errors : null, notices : null, logged_in : true, api_version : 3 }

---

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: curl http://8tracks.com/mix_sets/all.json?include=mixes { mix_set: { mixes: [ { id: 2568872, path: "/mixes/2568872", web_path: "/asprytan/solstices", name: "solstices", user_id: 4137083, published: true, cover_urls: { ... }, description: "we have lived past countless moons and long enough. (a folk mix)", plays_count: 247, tag_list_cache: "folk, instrumental, autumn, melancholy", first_published_at: "2013-10-09T17:30:55Z", likes_count: 33, certification: "gem" }, { id: 2588386, ... } { id: 2590115, ... } ... ], smart_id: "all", smart_type: "all", path: "/explore/all/hot", name: "Trending", web_path: "/explore/all" }, status: "200 OK", }

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.

Pagination

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. curl http://8tracks.com/mix_sets/all.json?include=mixes+pagination&page=2&per_page=10 { mix_set: { mixes: [...], pagination: { current_page: 2, per_page: 10, total_entries: 1033939, ... }, smart_id: "all", ... }, status: "200 OK", ... }

Includes

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:

curl http://8tracks.com/mix_sets/all.json?include=mixes[user] - or - curl http://8tracks.com/mix_sets/all.json?include=mixes[user+length]+details

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. curl http://8tracks.com/mixes/14.json - or - curl http://8tracks.com/dp/electrominimalicious.json

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. { mix: { id: 14, path: "/mixes/14", web_path: "/dp/electrominimalicious", name: "electrominimalicious", description: "Not all new but some favorite electronic stuff I've been listening to during the first half of 2007.", plays_count: 1986, likes_count: 198, certification: "gold", tag_list_cache: "minimal, electro", duration: 3556, tracks_count: 8, nsfw: false, liked_by_current_user: false, cover_urls: { sq56: "...", sq100: "...", sq133: "...", max133w: "...", max200: "...", sq250: "...", sq500: "http://images.8tracks.com/i/000/791/223/c/original-8032.gif?fm=jpg&q=65&fit=max&w=500&h=500&fit=max", max1024: "...", original: "..." }, first_published_at: "2007-09-06T08:56:48Z" user: { id: 2, login: "dp", path: "/users/2", web_path: "/dp", avatar_urls: { ... } followed_by_current_user: false, location: "Mission Dolores, SF, US", ... }, }, status: "200 OK", ... }

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:

curl http://8tracks.com/sets/new.json { play_token: "111696185", status: "200 OK", errors: null, notices: null, api_version: 3 }

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.

curl http://8tracks.com/sets/111696185/play.json?mix_id=14 { set: { at_beginning: true, at_last_track: false, at_end: false, skip_allowed: true, track: { id: 25, name: "Dexter", performer: "Ricardo Villalobos", release_name: "Alcachofa", year: null, track_file_stream_url: "https://dtp6gm33au72i.cloudfront.net/tf/000/000/025/YxgALb.48k.v3.m4a", buy_link: "http://redirect.viglink.com/?key=f4be5dc2078785c5846df105343edee0&out=https%3A%2F%2Fsearch.itunes.apple.com%2FWebObjects%2FMZSearch.woa%2Fwa%2Fsearch%3Fterm%3DRicardo%2520Villalobos%2520Dexter", faved_by_current_user: false, url: "http://8tracks.com/tracks/25", } }, status: "200 OK", ... }

• 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': curl http://8tracks.com/sets/111696185/next.json?mix_id=14

OR the user selects "skip track", then call 'skip': curl http://8tracks.com/sets/111696185/skip.json?mix_id=14

If skipping is not allowed you will get the following response: { status: "403 Forbidden", skip_allowed_in_seconds: 3596, errors: null, notices: "Sorry, but track skips are limited by law.", api_version: 3 }

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:

curl http://8tracks.com/sets/111696185/report.json?track_id=[track_id]&mix_id=[mix_id]

---

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. curl http://8tracks.com/sets/111696185/next_mix.xml?mix_id=14 { next_mix: { id: 613551, name: "Minimal Mix (vol. 3)", path: "/mixes/613551", web_path: "/chickenchaser01/minimal-mix-vol-3", user_id: 558983, ... }, smart_id: "similar:14", status: "200 OK", errors: null, notices: null, api_version: 3 }

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):

curl http://8tracks.com/sets/111696185/next_mix.json?mix_id=14&smart_id=liked:1

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. curl http://8tracks.com/sets/111696185/tracks_played.json?mix_id=14 { tracks: [ { id: 25, name: "Dexter", performer: "Ricardo Villalobos", release_name: "Alcachofa", url: "http://8tracks.com/tracks/25", year: null, faved_by_current_user: false, track_annotation: null, buy_link: "http://redirect.viglink.com/?key=f4be5dc2078785c5846df105343edee0&out=https%3A%2F%2Fsearch.itunes.apple.com%2FWebObjects%2FMZSearch.woa%2Fwa%2Fsearch%3Fterm%3DRicardo%2520Villalobos%2520Dexter" } ], status: "200 OK" ... }

---

8 Users

View user info: curl http://8tracks.com/users/1.json { user: { id: 1, login: "remi", path: "/users/1", web_path: "/remi", avatar_urls: { sq56: "...", sq72: "...", sq100: "...", max200: "...", max250w:"...", original: "http://images.8tracks.com/avatars/000/000/001/48287.original.jpg?fm=jpg&q=65&sharp=15&vib=10&" } }, status: "200 OK", ... }

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

List mixes made by a user: curl http://8tracks.com/users/1/mixes.json - or - curl http://8tracks.com/mix_sets/dj:1.json?include=mixes+pagination { mix_set : { smart_id: "dj:1", smart_type: "dj", path: "/remi/mixes", name: "Mixes by remi", web_path: "/remi/mixes" mixes: [...], pagination: {...}, }, status: "200 OK", ... }

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: curl http://8tracks.com/mixes/14/reviews.json?per_page=10 { reviews: [ { id: 1589114, body: "Amazing remix! Thanks for sharing DP! <3 ", created_at: "2013-09-01T00:56:31Z", user: { id: 708424, login: "evelyn.carbajal", ... }, mix_id: 2116601, user_id: 708424, parent_id: null }, { id: 1589227, body: "Thanks Evelyn!", created_at: "2013-09-01T01:49:01Z", user: { id: 2, login: "dp", ... }, mix_id: 2116601, user_id: 2, parent_id: 1589114 }, ], total_entries: 6, ... status: "200 OK", }

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:

curl -u remi:good --request POST -d "review[mix_id]=14&review[body]=body" http://8tracks.com/reviews.json { review : { id : 1711801, body" : "body", created_at:"2013-10-11T01:56:16Z", mix_id:1126846, user_id:645, parent_id:null }, status:"200 OK" ... }

---

10 Tags

Tags are the preferred way for browsing 8tracks mixes.

Browse and search tags

Get the top tags: curl http://8tracks.com/tags.json { tag_cloud: { tags: [ { cool_taggings_count: "49,000+", name: "chill" }, { cool_taggings_count: "7,000+", name: "study" }, { cool_taggings_count: "97,000+", name: "indie rock" }, ... ] }, next_page: 2, previous_page: null, status: "200 OK" ... }
Search tags (very cool for autocompleting): curl http://8tracks.com/tags.json?q=roc { tag_cloud: { tags: [ { cool_taggings_count: "143,000+", name: "indie rock" }, { cool_taggings_count: "130,000+", name: "alternative rock" }, { cool_taggings_count: "149,000+", name: "rock" }, ... ] }, next_page: 2, previous_page: null, status: "200 OK" ... }

---

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

curl -u remi:good http://8tracks.com/mixes/14/toggle_like.json - or - curl -u remi:good http://8tracks.com/mixes/14/like.json - or - curl -u remi:good http://8tracks.com/mixes/14/unlike.json { mix: { liked_by_current_user: true, id: 14, ... } status: "200 OK", }

• 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

curl -u remi:good http://8tracks.com/tracks/25/toggle_fav.json - or - curl -u remi:good http://8tracks.com/tracks/25/fav.json - or - curl -u remi:good http://8tracks.com/tracks/25/unfav.json { track: { faved_by_current_user: true, id: 25, name: "Dexter", performer: "Ricardo Villalobos", release_name: "Alcachofa", url: "http://8tracks.com/tracks/25", year: null, uid: 25 }, status: "200 OK", ... }

• 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

curl -u remi:good http://8tracks.com/users/2/toggle_follow.json - or - curl -u remi:good http://8tracks.com/users/2/follow.json - or - curl -u remi:good http://8tracks.com/users/2/unfollow.json { user: { followed_by_current_user: true, id: 1, ... }, status: "200 OK" ... }

• 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:

curl http://8tracks.com/mix_sets/collection:645:favorite-artwork.json

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

curl http://8tracks.com/users/2/collections.jsonh?include=mix_sets[mixes] { mix_cluster: { mix_sets: [ { smart_id: "collection:2:chill-jazz", smart_type: "collection", path: "/mix_sets/collection:2:chill-jazz", name: "Chill jazz", web_path: "/dp/collections/chill-jazz", mixes : [ ... ] }, { smart_id: "collection:2:deep-house", smart_type: "collection", path: "/mix_sets/collection:2:deep-house", name: "Deep house", web_path: "/dp/collections/deep-house", mixes : [ ... ] }, ... ] }, status: "200 OK", ... }

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.

curl --request POST -d "collection[name]=New%20Collection&mix_id=14&login=remitest&password=password" https://8tracks.com/collections.json { collection : { id : 85260302, smart_id : "collection:988:new-collection", name: "New Collection", slug: "new-collection", mixes_count: 1, web_path: "/remitest/collections/new-collection", description: null, ... }, status:"200 OK" ... }

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.

curl http://8tracks.com/users/remitest/editable_collections.jsonh?mix_id=14 { collections: [ { id: 85260302, smart_id: "collection:988:new-collection", contains_mix : true, ... } ], status: "200 OK", }

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].

curl --request POST -d "collection_mix[collection_id]=85260302&collection_mix[mix_id]=14&login=remitest&password=password" http://8tracks.com/collections_mixes.jsonh

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

curl --request DELETE -d "collection_mix[collection_id]=85260302&collection_mix[mix_id]=14&login=remitest&password=password" http://8tracks.com/collections_mixes.jsonh

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.

curl --request POST -d "preset=tags:chill+hip_hop&login=remitest&password=password" http://8tracks.com/users/988/add_preset.jsonh { presets : [ "chill hip hop" ], preset_smart_ids : [ "tags:chill hip_hop" ], "status":"200 OK", ... }

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.

curl http://8tracks.com/users/988.json?include=presets { user : { id : 988, login : 'remitest', ... presets : [ "chill hip hop" ], preset_smart_ids : [ "tags:chill hip_hop" ] } "status":"200 OK", ... }

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

curl --request POST -d "preset=tags:chill+hip_hop&login=remitest&password=password" http://8tracks.com/users/988/remove_preset.jsonh


---




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