Developers / Mixcloud API documentationCreate new application
The Mixcloud API has been designed to be simple to use and familiar. This page has all of the information you need to get going.
- Cloudcasts, Users etc
- Connections and lists
- Following and Favoriting
- Rate limits
- Audio Streams
- We're hiring!
Cloudcasts, Users etc
Objects in the Mixcloud API can be found by taking the URL where you would find them on the site and changing http://www.mixcloud.com/ to http://api.mixcloud.com/.
Take a look at the following links in a browser to see example responses:
For example http://api.mixcloud.com/artist/aphex-twin/
"name": "Aphex Twin",
JSONP is supported. Adding a callback query string parameter with the name of a function wraps the response - for example http://api.mixcloud.com/artist/aphex-twin/?callback=callbackfn
"name": "Aphex Twin",
Each object has a key which is the URL (from the first /) to the object in the API.
Connections and lists
To find out the available connections for an object add metadata=1 to the query string - for example http://api.mixcloud.com/spartacus/?metadata=1
Most connections return lists of items. Other available lists are:
limit and offset query string parameters can be used to page lists.
Lists of items with dates (such as Cloudcasts) can be paged using since and until query string parameters. These parameters accept either Unix timestamps (the number of seconds since 1970-1-1) or UTC date times of the format YYYY-MM-DD HH:MM:SS.
When a list is returned URLs for the previous and next pages are provided in the response. If you would like the paging links to use offset rather than defaulting to dates, add offset=0 to the first request.
The URL http://api.mixcloud.com/me/ is a shortcut to the authorized user's information and connections. /me/ URLs are only available over https with an access token (see the Authorization section for more information).
The /search/ URL can be used to perform searches across Cloudcasts, Users and Tags using the following URL with a type query string parameter which is either cloudcast, user or tag and a q parameter with the search string - for example http://api.mixcloud.com/search/?q=party+time&type=cloudcast
Access tokens are required to update any data or use the /me/ shortcut and must only be provided across https connections.
Extra information is added to some objects if an access token is provided - for example a following attribute is added to a User object to indicate whether or not the authorized user is following the requested User.
The Mixcloud API uses OAuth2 for authorization.
Getting an access token
First you'll need to create and application. Then you will be assigned a client_id and client_secret.
Only browser based authorization is supported currently. Redirect your user to
where they will be given the option to log in and allow or deny your application access to their data.
If the user accepts Mixcloud will redirect the user to YOUR_REDIRECT_URI?code=OAUTH_CODE.
Once you have received the OAUTH_CODE send a request to
This will respond with an access token:
which can be used on future requests as an access_token query string parameter to access protected resources.
Note it is possible for the user to revoke their access token so your application will need to handle "An invalid access token was provided" errors and re-authenticate the user.
Following and Favoriting
The URL for following is a User API key with follow/ on the end - for example https://api.mixcloud.com/spartacus/follow/?access_token=ACCESS_TOKEN
The URL for favoriting is a Cloudcast API key with favorite/ on the end - for example https://api.mixcloud.com/spartacus/party-time/favorite/?access_token=ACCESS_TOKEN
To follow or favorite an access token is required. Simply send a POST request to the URL to follow/favorite and a DELETE request to unfollow/unfavorite. It is also possible to send a POST request with a parameter of method=delete to simulate a DELETE request.
curl -X POST "https://api.mixcloud.com/spartacus/follow/?access_token=ACCESS_TOKEN"
curl -X DELETE "https://api.mixcloud.com/spartacus/follow/?access_token=ACCESS_TOKEN"
curl -F "method=delete" "https://api.mixcloud.com/spartacus/follow/?access_token=ACCESS_TOKEN"
Mixcloud also supports oEmbed discovery. For example you can get the embed code for a cloudcast like this:
Cloudcasts can be uploaded by posting to https://api.mixcloud.com/upload/ with an access token (see the Authorization section).
The MP3, metadata and image should all be uploaded in a single multipart/form-data POST. The same filesize and metadata restrictions apply as in the standard Mixcloud web interface so it is recommended that applications using the Mixcloud API validate the data before sending since the user will have to wait for the MP3 to be uploaded before any validation errors are returned.
The available fields and their restrictions are shown in the table below. Fields labelled REQUIRED are required - all other fields are optional.
|mp3||REQUIRED. The audio file to be uploaded. The file should not be larger than 524288000 bytes.|
|name||REQUIRED. The name of the cloudcast - this will be used to generate the URL, duplicate names should be avoided but will not cause an upload to fail.|
|picture||A picture for the cloudcast. The file should not be larger than 10485760 bytes.|
|description||A description for the cloudcast. Maximum of 1000 characters.|
|tags-X-tag||Where X is a number 0-4, a tag name for the cloudcast. Up to 5 tags can be provided.|
Tracklist/chapter information is provided using the fields in the table below where X represents the section (track or chapter) number - starting with 0.
|sections-X-artist||REQUIRED (if a track). The track section artist name.|
|sections-X-song||REQUIRED (if a track). The track section song title.|
|sections-X-chapter||The name of a chapter section.|
|sections-X-start_time||The time, in seconds (integer), at which section X starts.|
An example, using curl, is shown below uploading an MP3 called "cloudcast.mp3", with a name of "API Upload", 2 tags ("Test" and "API"), 2 sections (a chapter called "Introduction" and one track) and an image called "cloudcast.jpg".
curl -F email@example.com \
-F "name=API Upload" \
-F "tags-0-tag=Test" \
-F "tags-1-tag=API" \
-F "sections-0-chapter=Introduction" \
-F "sections-0-start_time=0" \
-F "sections-1-artist=Artist Name" \
-F "sections-1-song=Song Title" \
-F "sections-1-start_time=10" \
-F "description=My test cloudcast" \
There are rate limits on all actions in the API. We're still tweaking these so if you keep hitting them, do let us know at firstname.lastname@example.org
The response in the rate limit tells you how long you have to wait until you can try again in both the HTTP headers and the JSON/XML response.
HTTP/1.1 403 Forbidden
"message": "You have hit your rate limit. Retry after 452 seconds.",
The audio streams are not available through the Mixcloud API. There are two reasons for this.
Firstly, we need to know what has been listened to so that we can report usage, pay royalties and provide features such as "Suggested Cloudcasts". Secondly, Mixcloud needs to pay the bills! We can't give away the audio for free outside of mixcloud.com simply because it costs us to host and stream the files and pay royalties.
Examples of people using the the Mixcloud API can be found at:
Let us know if you're using the API on:
If you like hacking things together on APIs (particularly the Mixcloud API) you might like working for us. Check out our jobs page.