Mixcloud API

Read shows, users and tags, upload and edit shows, and act on behalf of a listener. Everything you need to build on Mixcloud is on this page.

To control an embedded player rather than call the REST API, see the Widget JavaScript API documentation.

Base URL: https://api.mixcloud.com/
Response format: JSON over https, CORS enabled
Authentication: None to read; OAuth 2.0 to write

Your applications

Create an application

You haven't created an application yet.

Shows, users, tags and cities

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

Open any of these in a browser to see an example response:

For example, https://api.mixcloud.com/genres/funk/ responds with:

{
    "url": "https://www.mixcloud.com/genres/funk/",
    "name": "Funk shows",
    "key": "/genres/funk/"
}

Every object has a key, which is the path (from the first /) to that object in the API. Keys are what you pass to the widget and to most of the write endpoints below.

The API sends CORS headers, so you can call it directly from browser JavaScript on your own domain. JSONP is still supported for clients that need it — add a callback query parameter naming a function and the response comes back wrapped in a call to it:

callback({
    "url": "https://www.mixcloud.com/genres/funk/",
    "name": "Funk shows",
    "key": "/genres/funk/"
})

Connections and lists

To find out which connections an object has, add metadata=1 to the query string — for example https://api.mixcloud.com/spartacus/?metadata=1:

{
    "metadata": {
        "connections": {
            "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/"
        }
    }
}

Most connections return lists of items. There are also these site-wide lists:

Paging

Use the limit and offset query parameters to page through a list.

Lists whose items have dates (uploads, for instance) can also be paged with since and until. Both accept either a Unix timestamp (seconds since 1970-01-01) or a UTC date and time in the format YYYY-MM-DD HH:MM:SS.

Every list response includes URLs for the previous and next pages. Those links page by date by default; add offset=0 to your first request if you would rather they page by offset.

The /me/ shortcut

https://api.mixcloud.com/me/ is a shortcut to the authorized user's own information and connections. It is available only over https and only with an access token — see Authorization.

Search

/search/ searches shows, users and tags. Pass the search string as q and the kind of thing you are looking for as type, which must be one of cloudcast (a show), user or tag.

For example: https://api.mixcloud.com/search/?q=party+time&type=cloudcast

Authorization

An access token is required to change any data or to use the /me/ shortcut, and must only ever be sent over https.

Some objects gain extra fields when a token is provided — a User object, for instance, gains a following field telling you whether the authorized user follows them.

Authorization uses OAuth 2.0.

Getting an access token

First create an application, which gives you a client_id and a client_secret. Keep the secret on your server — never ship it in a browser or mobile app.

Only browser-based authorization is supported. Send your user to:

https://www.mixcloud.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

There they can log in and allow or deny your application access to their data.

Always URL-encode your redirect_uri. It can take any of these forms:

Full URL: For example https://yourapp.com/callback. Recommended.
App scheme: For example yourapp://callback, to redirect into a native app.
Host only: For example yourapp.com, which is accepted and treated as https://yourapp.com. Including the scheme is clearer.
Omitted: Leave it out and Mixcloud shows the authorization code on screen for the user to copy into your app. Use this when your app has no callback URL.

If the user accepts, Mixcloud redirects them to YOUR_REDIRECT_URI?code=OAUTH_CODE. If you left redirect_uri out, the OAUTH_CODE is shown to the user on screen instead, for them to enter into your app.

Exchange that code for a token by requesting:

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

The response contains the token:

access_token=YOUR_ACCESS_TOKEN

Send it as an access_token query parameter on subsequent requests to reach protected resources.

The redirect_uri you send here must match the one from your authorize request. If you omitted it there, omit it here too.

Users can revoke a token at any time, so your application needs to handle An invalid access token was provided errors by sending the user through authorization again.

Following, favoriting and reposting

Each of these actions has its own endpoint, formed by appending a path to a user or show key. All of them require an access token.

follow/: Follow a user. Append to a user key — for example https://api.mixcloud.com/spartacus/follow/
favorite/: Favorite a show. Append to a show key — for example https://api.mixcloud.com/spartacus/party-time/favorite/
repost/: Repost a show. Append to a show key — for example https://api.mixcloud.com/spartacus/party-time/repost/
listen-later/: Add a show to Listen Later. Append to a show key — for example https://api.mixcloud.com/spartacus/party-time/listen-later/

POST to the endpoint to perform the action and DELETE to undo it. If your client can't send DELETE, send a POST with a method=delete parameter instead.

# Follow
curl -X POST "https://api.mixcloud.com/spartacus/follow/?access_token=ACCESS_TOKEN"

# Unfollow
curl -X DELETE "https://api.mixcloud.com/spartacus/follow/?access_token=ACCESS_TOKEN"

# Unfollow, from a client that cannot send DELETE
curl -F "method=delete" "https://api.mixcloud.com/spartacus/follow/?access_token=ACCESS_TOKEN"

Embedding

Add embed-html/ to a show key to get the embed code for its player widget — for example https://api.mixcloud.com/spartacus/party-time/embed-html/.

Use embed-json/ instead to get the same HTML wrapped in JSON, for JavaScript clients that need JSONP for cross-domain requests.

These query parameters change the widget's appearance:

width: Width of the widget, in pixels.
height: Height of the widget, in pixels.
color: Accent colour as a six-digit hex code, without the leading #.

To control an embedded player from your own page — play, pause, seek, listen for events — see the Widget JavaScript API documentation.

oEmbed

Mixcloud supports oEmbed discovery, so you can fetch embed code for any show URL:

https://app.mixcloud.com/oembed/?url=https%3A%2F%2Ffd.xuwubk.eu.org%3A443%2Fhttps%2Fwww.mixcloud.com%2Fspartacus%2Fparty-time%2F&format=json

Uploading shows

Upload a show by posting to https://api.mixcloud.com/upload/ with an access token — see Authorization.

The audio, metadata and cover art all go in a single multipart/form-data POST. The same size and metadata limits apply as in the upload flow on the site, so validate what you can before sending: the audio finishes uploading before any validation errors come back, and your user has to wait through it.

Fields

mp3Required: The audio file. No larger than 4.0GB.
nameRequired: The title of the show.
picture: Cover art for the show. No larger than 10.0MB.
description: A description for the show. Up to 1000 characters.
tags-X-tag: A tag name, where X is a number from 0 to 4. Up to 5 tags per show. These are usually genres — the upload flow on the site suggests a curated list that helps people find your show, but you can use any tags you like.
unlisted: Keep the show private. It won't appear on your profile for other visitors, and only people who know its link can reach it. Setting this ignores any scheduled publish_date and makes the show private straight away.
publish_datePro only: Schedule when the show goes public, in the format YYYY-MM-DDTHH:MM:SSZ — for example 2030-11-21T14:05:00Z. The date must be in UTC, so convert from your local timezone first. Scheduling only applies to shows that have never been public.
disable_commentsPro only: Turn off comments on the show.
hide_statsPro only: Hide the play, favorite and repost counts on the show.
hosts-X-usernamePro only: The username of another Mixcloud account to tag on the show, where X is a number from 0 to 1. Up to 2 accounts can be tagged. Their followers are notified alongside yours, and the show also appears on their profiles as long as they are below their upload limit (otherwise it lands in their drafts).

Each username must already have accepted an invitation to be associated with the uploading account, and so appear in the Hosts tab of your dashboard. Usernames that don't are ignored. When editing, a single incorrect username means none of the host changes in that request are applied. Get the usernames right first time when uploading: the extra reach of notifying their followers only happens when the show is first published.

To remove every host, send an empty username — for example hosts-0-username=.

Tracklist and chapters

Describe the tracklist with the fields below, where X is the section number, starting at 0. A section is either a track (artist plus song) or a chapter (a name).

sections-X-artist: The artist, for a track section. Required if the section is a track.
sections-X-song: The song title, for a track section. Required if the section is a track.
sections-X-chapter: The name, for a chapter section.
sections-X-start_time: How far into the show the section starts, in whole seconds.

Example

This uploads upload.mp3 as "API Upload" with two tags, a chapter, one track and cover art:

curl -F mp3=@upload.mp3 \
     -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=ACCESS_TOKEN"

Editing uploads

Edit a show by posting to https://api.mixcloud.com/upload/YOUR_SHOW_KEY/edit/ — for example https://api.mixcloud.com/upload/my-username/my-upload/edit/ — with an access token. This works for shows that were not uploaded through the API.

Metadata and cover art go in a single multipart/form-data POST. Every upload field except mp3 is accepted.

name, description and picture are only changed when you include them — leave description out and the existing description stays as it is.

Tags, tracklist sections and hosts are replaced wholesale, not merged. Posting any one tag replaces every tag, so to add a tag you must also re-post the existing ones. The same goes for sections and for hosts.

These fields are only available when editing. You can use at most one of unlisted, publish and unpublish per request.

publish: Make the show public. Applies to private (unlisted) shows and to shows sitting in your drafts. Implied when the show already has a scheduled publish_date, since it will go public then.
unpublish: Move the show to your drafts. It stays unavailable to the public until you publish it again.

Example

curl -F picture=@mypicture.jpg \
     -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=ACCESS_TOKEN"

Rate limits

Every action in the API is rate limited. Reads, writes, comments, deletes and uploads are counted separately, so a busy read workload won't stop you uploading.

When you hit a limit, the response tells you how long to wait — both in the Retry-After header and as retry_after in the body. Wait that long rather than retrying immediately.

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
    }
}

If your application keeps hitting a limit and you think it needs a higher one, get in touch with support and tell us which application it is and what it does.

Audio streams

Audio streams are not available through the Mixcloud API, for two reasons.

First, we need to know what has been listened to so that we can report usage, pay royalties and power features such as suggested shows.

Second, hosting, streaming and licensing the audio costs us money, so we can't give it away for free outside of mixcloud.com. To play Mixcloud audio on your own site, embed the player widget instead.

Deep linking

Both our iOS and Android apps support deep linking from ordinary web URLs, so you can open a show, profile or playlist in the Mixcloud app straight from your own app.

iOS

Swift

if let url = URL(string: "https://www.mixcloud.com/profile/content/") {
    UIApplication.shared.open(url)
}

Objective-C

NSURL *url = [NSURL URLWithString:@"https://www.mixcloud.com/profile/content/"];
[[UIApplication sharedApplication] openURL:url options:@{} completionHandler:nil];

Android

Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(Uri.parse("https://www.mixcloud.com/profile/content/"));
context.startActivity(intent);

That lets the user choose between opening the link in a browser and opening it in the Mixcloud app, if they have it installed. To send them straight to the app, set the package on the intent as well:

intent.setPackage("com.mixcloud.player");

Note that this will fail if the app isn't installed, so only force the package when you already know it is — otherwise leave the choice to the user.

Libraries and examples

The API is plain HTTP and JSON, so it works with whatever HTTP client your language already has — there is no SDK to install. These community-maintained wrappers exist if you would rather not write that yourself. They are not built or supported by Mixcloud.

Rubyhttps://github.com/actfong/mixcloud

Built something with the API, or stuck on something these docs don't cover? Let us know through support.