How likely are you to recommend Mixcloud to a friend?Not likely12345678910Very likely
Thank you for participating in our survey!
Retry×
Create new application

Introduction

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.

Documentation for the Widget Javascript API can be found here.

Contents

Shows, Users and Discover

Objects in the Mixcloud API can be found by taking the URL where you would find them on the site and changing https://www.mixcloud.com/ to https://api.mixcloud.com/.

Take a look at the following links in a browser to see example responses:

For example https://api.mixcloud.com/discover/funk/ {
    "url": "https://www.mixcloud.com/discover/funk/",
    "name": "Funk shows",
    "key": "/discover/funk/",
}

JSONP is supported. Adding a callback query string parameter with the name of a function wraps the response - for example https://api.mixcloud.com/discover/funk/?callback=callbackfn callbackfn({
    "url": "https://www.mixcloud.com/discover/funk/",
    "name": "Funk shows",
    "key": "/discover/funk/",
})

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 https://api.mixcloud.com/spartacus/?metadata=1 {
...
    "metadata": {
        "connections": {
            "feed": "https://api.mixcloud.com/spartacus/feed/",
            "comments": "https://api.mixcloud.com/spartacus/comments/",
            "followers": "https://api.mixcloud.com/spartacus/followers/",
            "favorites": "https://api.mixcloud.com/spartacus/favorites/",
            "following": "https://api.mixcloud.com/spartacus/following/",
            "cloudcasts": "https://api.mixcloud.com/spartacus/cloudcasts/",
            "listens": "https://api.mixcloud.com/spartacus/listens/"
        }
    },
    "type": "user",
...
}

Most connections return lists of items. Other available lists are:

Paging

limit and offset query string parameters can be used to page lists.

Lists of items with dates (such as uploads) 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.

Me

The URL https://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 Uploads, Users and Tags using the following URL with a type query string parameter which is either upload, user or tag and a q parameter with the search string - for example https://api.mixcloud.com/search/?q=party+time&type=cloudcast

Authorization

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
https://www.mixcloud.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI
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
https://www.mixcloud.com/oauth/access_token?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&client_secret=YOUR_CLIENT_SECRET&code=OAUTH_CODE.

This will respond with an access token: access_token=YOUR_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, Favoriting, Reposting and adding to Listen Later

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 an upload API key with favorite/ on the end - for example https://api.mixcloud.com/spartacus/party-time/favorite/?access_token=ACCESS_TOKEN

The URL for reposting is an upload API key with repost/ on the end - for example https://api.mixcloud.com/spartacus/party-time/repost/?access_token=ACCESS_TOKEN

The URL for adding to listen later is an upload API key with listen-later/ on the end - for example https://api.mixcloud.com/spartacus/party-time/listen-later/?access_token=ACCESS_TOKEN

To follow, favorite, repost or add to listen later an access token is required. Simply send a POST request to the URL to follow/favorite/repost/add to listen later and a DELETE request to unfollow/unfavorite/unrepost/remove from listen later. It is also possible to send a POST request with a parameter of method=delete to simulate a DELETE request.

For example: 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"

Embedding

Embed code for the widget can be retrieved by adding embed-html/ to an Upload API key - for example https://api.mixcloud.com/spartacus/party-time/embed-html/.

JavaScript applications (requiring JSONP for cross domain requests) can use embed-json/ instead of embed-html/ to get the HTML wrapped in JSON. width, height and color (6 digit hex code) query parameters can be used to change the widget's appearance.

Mixcloud also supports oEmbed discovery. For example you can get the embed code for an upload like this:
https://www.mixcloud.com/oembed/?url=https%3A//www.mixcloud.com/spartacus/party-time/&format=json

Uploads

Shows 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 (if a track). The track section song title.
  • picture
    A picture for the upload. The file should not be larger than 10485760 bytes.
  • description
    A description for the upload. Maximum of 1000 characters.
  • tags-X-tag
    Where X is a number 0-4, a tag name for the upload. Up to 5 tags can be provided.
  • publish_date
    ONLY FOR UPLOADING TO PRO ACCOUNTS. Scheduled publish date for the upload in the format YYYY-MM-DDTHH:MM:SSZ (e.g. 2015-11-21T14:05:00Z). Note: the date MUST be UTC so you may need to convert for your local timezone first.
  • disable_comments
    ONLY FOR UPLOADING TO PRO ACCOUNTS. Disable comments for this upload
  • hide_stats
    ONLY FOR UPLOADING TO PRO ACCOUNTS. Hide play, favorite and repost counts for this upload
  • unlisted
    ONLY FOR UPLOADING TO PRO ACCOUNTS. Make this upload unlisted. The upload will not appear under your profile page when other users visit it. Only users who know the upload's link will have access to it.

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 "upload.jpg". curl -F [email protected] \
     -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 upload" \
     https://api.mixcloud.com/upload/?access_token=INSERT_ACCESS_TOKEN_HERE

Editing uploads

Uploads can be edited by posting to https://api.mixcloud.com/upload[YOUR_SHOW_KEY]edit/ (e.g. https://api.mixcloud.com/upload/my-username/my-upload/edit/) with an access token (see the Authorization section). You can edit uploads that were not uploaded with the API.

The metadata and image should all be uploaded in a single multipart/form-data POST. All fields that are allowed in an upload except mp3 can be sent to this endpoint.

The name, description and picture fields will only be updated if they are included in the request (e.g. if the description parameter is not included the description of the upload will not be changed).

If any tag fields are posted all tags will be overwritten (if you want to just add a tag, you will have to post the tags that are already on the upload for them to remain). Also for sections if any section field is posted the entire tracklist will be overwritten.

An example, using curl, is shown below: curl -F [email protected] \
     -F "name=A new name" \
     -F "tags-0-tag=Test" \
     -F "tags-1-tag=API" \
     -F "description=My test upload" \
     https://api.mixcloud.com/upload/my-username/my-upload/edit/?access_token=INSERT_ACCESS_TOKEN_HERE

Rate limits

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 [email protected]

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
Retry-After: 452

{
    "error": {
        "message": "You have hit your rate limit. Retry after 452 seconds.",
        "type": "RateLimitException",
        "retry_after": 452
    }
}

Audio Streams

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 Shows". 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.

The Mixcloud apps conform to the same structure as the website. Should you wish to link to a piece of Mixcloud content from your own app, you can link directly to that content in our app.

Converting a Mixcloud URL to an App Link

Almost all Mixcloud URLs can be viewed within our mobile apps. To generate a mixcloud mobile app link simply replace https://www.mixcloud.com with the url scheme mc://.

For example:

https://www.mixcloud.com/avici/

becomes

mc://avicii/ (on iOS)

mc://www.mixcloud.com/avicii/ (on Android)

Linking in iOS:

If you want to link to our app from your own app you can do so by using the code below. The code links to the content in the Mixcloud app if it is installed, else it will open the link in Safari.

Objective C:
NSString *urlPath = @"avicii/";
BOOL mixcloudInstalled = [[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:@"mc://"]];
NSString *urlRoot = @"https://www.mixcloud.com";
if(mixcloudInstalled) {
    urlRoot = @"mc://";
}
NSURL *mixcloudURL = [NSURL URLWithString:[urlRoot stringByAppendingPathComponent:urlPath]];
[[UIApplication sharedApplication] openURL:mixcloudURL];
Swift:
let urlPath = "avicii/"
let mixcloudInstalled = UIApplication.sharedApplication().canOpenURL(NSURL(string:"mc://")
var urlRoot = "https://www.mixcloud.com"
if(mixcloudInstalled) {
    urlRoot = "mc://"
}
let mixcloudURL = NSURL(string: urlRoot.stringByAppendingPathComponent(urlPath))
UIApplication.sharedApplication().openURL(mixcloudURL)

Linking in Android:

The android operating system will, by default, ask the user if they want to open a https://www.mixcloud.com link in the Mixcloud app if it is installed. This will automatically link to the relevant content with in the app. To always link to the Mixcloud app by default you can link using the mc:// url scheme. Below is some example code to do this:

Java:
String path = "avicii/";
try {
    Intent mixcloudIntent = new Intent(Intent.ACTION_VIEW);
    mixcloudIntent.setData(Uri.parse("mc://www.mixcloud.com/"+path));
    startActivity(mixcloudIntent);
} catch (ActivityNotFoundException e) {
    Intent mixcloudIntent = new Intent(Intent.ACTION_VIEW);
    mixcloudIntent.setData(Uri.parse("https://www.mixcloud.com/"+path));
    startActivity(mixcloudIntent);
}

Example

Examples of people using the the Mixcloud API can be found at:

Let us know if you're using the API on:

[email protected]

Start typing to search.
Oh snap, there was a playback error!

Press play to try again.

Streaming on Mixcloud requires Flash!

You can get it here.

[[player.currentCloudcast.title]]
By Follow
Leave a comment
Comment submitted
0:00:00
-0:00:00
Due to licensing issues in your country it is not possible to seek backwards. Why is this?
by   — BuyStarting in ...
NEXT
To add radio shows, DJ mixes and podcasts here use the buttons marked  
[[cloudcast.title]]
By
[[playerQueue.queue.upNext.nextCloudcast.title]]
By
Suggested:Featured:
You have another browser tab or window open with an active Mixcloud player. Close this message