### Example JSONP Response for a Tag

Source: https://www.mixcloud.com/developers

This example demonstrates how a JSONP response is wrapped with a callback function when the 'callback' query parameter is used. This is useful for cross-domain requests.

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

--------------------------------

### Example API Response for a Tag

Source: https://www.mixcloud.com/developers

This is an example of a JSON response when requesting information about a tag. It includes the URL, name, and key for the tag.

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

--------------------------------

### Rate Limit Response Example

Source: https://www.mixcloud.com/developers

This example shows the structure of a rate limit error response, including HTTP headers and JSON body. It indicates the time to wait before retrying.

```http
HTTP/1.1 403 Forbidden  
Retry-After: 452  
```

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

--------------------------------

### Initialize and Use Widget API

Source: https://www.mixcloud.com/developers/widget

Instantiate a widget controller using the iframe ID. The API is available after the widget is ready, indicated by a resolved promise. This setup is required before interacting with the widget.

```javascript
var widget = Mixcloud.PlayerWidget(document.getElementById("my-widget-iframe"));
    widget.ready.then(function() {
        // Put code that interacts with the widget here
    });
  
    var widget2 = Mixcloud.PlayerWidget(document.getElementById(... // if you have more than one widget to control
```

--------------------------------

### load

Source: https://www.mixcloud.com/developers/widget

Loads a new Mixcloud upload into the widget. Playback can optionally start automatically after loading.

```APIDOC
## load(cloudcastKey, startPlaying)

### Description
Loads a new upload specified by its key. Optionally starts playback immediately after loading.

### Method
JavaScript

### Endpoint
N/A (JavaScript API)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
* **cloudcastKey** (string) - Required - The key of the Mixcloud upload to load (e.g., \"/spartacus/lambiance/\").
* **startPlaying** (boolean) - Optional - If true, playback will start automatically once the upload is loaded.

### Request Example
```javascript
widget.load("/artist/track", true).then(function() {
    console.log("Track loaded and playing.");
});
```

### Response
#### Success Response
Returns a promise that resolves once the new upload has loaded.
```

--------------------------------

### play

Source: https://www.mixcloud.com/developers/widget

Starts or resumes playback of the current Mixcloud upload.

```APIDOC
## play()

### Description
Starts playback if the widget is paused or has not yet started. Note: Autoplay policies may affect this method's reliability.

### Method
JavaScript

### Endpoint
N/A (JavaScript API)

### Parameters
N/A

### Request Example
```javascript
widget.play();
```

### Response
#### Success Response
Initiates playback.
```

--------------------------------

### Example API Response with Metadata and Connections

Source: https://www.mixcloud.com/developers

This JSON response includes metadata about a user, specifically their available connections such as followers, favorites, following, cloudcasts, and listens. This is obtained by adding 'metadata=1' to the query string.

```json
{
  
    "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/"
        }
    }
  
}
```

--------------------------------

### Upload Show via Mixcloud API

Source: https://www.mixcloud.com/developers

Use this curl command to upload a show to Mixcloud. Ensure you replace INSERT_ACCESS_TOKEN_HERE with your actual access token. This example includes an MP3 file, name, tags, sections (chapter and track), and a description.

```bash
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=INSERT_ACCESS_TOKEN_HERE
```

--------------------------------

### Load and Play Cloudcast

Source: https://www.mixcloud.com/developers/widget

Loads a new upload by its key and optionally starts playback. This method returns a promise that resolves once the new upload has finished loading.

```javascript
widget.load("/spartacus/lambiance/", true);
```

--------------------------------

### Retrieve a User

Source: https://www.mixcloud.com/developers

Get information about a specific user profile.

```APIDOC
## GET /spartacus/

### Description
Retrieves details for a specific user.

### Method
GET

### Endpoint
https://api.mixcloud.com/{username}/

### Example Response
{
  "url": "https://www.mixcloud.com/spartacus/",
  "name": "Spartacus",
  "key": "/spartacus/"
}
```

--------------------------------

### Embed Footer Widget with Playback Control

Source: https://www.mixcloud.com/developers/widget

Include the Footer Widget script and use Mixcloud.FooterWidget to embed a persistent player. This example shows how to initialize the widget and attach an event listener for playback events.

```html
<script src="//widget.mixcloud.com/media/js/footerWidgetApi.js" type="text/javascript"></script>
```

```javascript
var promise = Mixcloud.FooterWidget("/username/show/");
promise.then(function(widget) {
    // Put code that interacts with the widget here e.g.
    widget.events.pause.on(pauseListener);
});
```

--------------------------------

### Get Connections Metadata

Source: https://www.mixcloud.com/developers

Retrieve metadata, including available connections, for an object.

```APIDOC
## GET /spartacus/?metadata=1

### Description
Appends metadata, including a list of available connections, to the response.

### Method
GET

### Endpoint
https://api.mixcloud.com/{resource}/?metadata=1

### Example Response
{
  "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/"
    }
  }
}
```

--------------------------------

### Get Embed HTML with Mixcloud API

Source: https://www.mixcloud.com/developers

Retrieve embed HTML for a Mixcloud upload by appending embed-html/ to the upload's API key.

```html
https://api.mixcloud.com/spartacus/party-time/embed-html/
```

--------------------------------

### Get oEmbed JSON with Mixcloud API

Source: https://www.mixcloud.com/developers

Fetch embed code for an upload using the oEmbed discovery endpoint. Specify the URL of the Mixcloud upload and request the format as JSON.

```json
https://app.mixcloud.com/oembed/?url=https%3A%2F%2Fwww.mixcloud.com%2Fspartacus%2Fparty-time%2F&format=json
```

--------------------------------

### JSONP Support

Source: https://www.mixcloud.com/developers

Demonstrates how to use JSONP by adding a callback query parameter.

```APIDOC
## GET /genres/funk/?callback=callbackfn

### Description
Supports JSONP by wrapping the response in a JavaScript function specified by the callback parameter.

### Method
GET

### Endpoint
https://api.mixcloud.com/{resource}/?callback={callback_function_name}

### Example Response
callbackfn({
  "url": "https://www.mixcloud.com/genres/funk/",
  "name": "Funk shows",
  "key": "/genres/funk/"
})
```

--------------------------------

### Paging with Limit and Offset

Source: https://www.mixcloud.com/developers

Demonstrates how to paginate through lists using limit and offset parameters.

```APIDOC
## GET /{resource}/?limit=10&offset=20

### Description
Allows pagination of lists by specifying the number of items to return (limit) and the number of items to skip (offset).

### Method
GET

### Endpoint
https://api.mixcloud.com/{resource}/

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of items to return.
- **offset** (integer) - Optional - The number of items to skip.
```

--------------------------------

### Get Embed JSONP with Mixcloud API

Source: https://www.mixcloud.com/developers

For JavaScript applications, use embed-json/ instead of embed-html/ to get the HTML wrapped in JSON, supporting cross-domain requests via JSONP. Query parameters like width, height, and color can customize the widget's appearance.

```javascript
https://api.mixcloud.com/spartacus/party-time/embed-json/
```

--------------------------------

### Paging with Since and Until

Source: https://www.mixcloud.com/developers

Demonstrates how to paginate lists with date-based parameters since and until.

```APIDOC
## GET /{resource}/?since=1678886400&until=1678972800

### Description
Allows pagination of lists containing dates using Unix timestamps or UTC date-time strings for 'since' and 'until' parameters.

### Method
GET

### Endpoint
https://api.mixcloud.com/{resource}/

### Parameters
#### Query Parameters
- **since** (integer or string) - Optional - Unix timestamp or 'YYYY-MM-DD HH:MM:SS' UTC date-time to start from.
- **until** (integer or string) - Optional - Unix timestamp or 'YYYY-MM-DD HH:MM:SS' UTC date-time to end at.
```

--------------------------------

### Get Playback State

Source: https://www.mixcloud.com/developers/widget

Retrieves the current playback position, total duration, or paused state. The results are passed to the promise's callback function.

```javascript
widget.getPosition().then(function(position) {
    // "position" is the current position  
});
```

```javascript
widget.getDuration().then(function(duration) {
    // "duration" is the total duration
});
```

```javascript
widget.getIsPaused().then(function(isPaused) {
    // "isPaused" is a boolean indicating the playback state
});
```

--------------------------------

### Mixcloud.PlayerWidget

Source: https://www.mixcloud.com/developers/widget

Initializes a player widget object to control an embedded Mixcloud iframe. The widget must be visible and the ready promise must be resolved before API methods can be used.

```APIDOC
## Mixcloud.PlayerWidget

### Description
Creates an object to control an embedded Mixcloud widget.

### Method
JavaScript

### Endpoint
N/A (JavaScript API)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```javascript
var widget = Mixcloud.PlayerWidget(document.getElementById("my-widget-iframe"));
widget.ready.then(function() {
    // Interact with the widget here
});
```

### Response
#### Success Response
Returns a promise that resolves when the widget is ready for API interaction.

#### Response Example
N/A
```

--------------------------------

### Upload Content

Source: https://www.mixcloud.com/developers

Uploads can be made by posting to the /upload/ endpoint with an access token. The MP3, metadata, and image should be uploaded in a single multipart/form-data POST request. Validation of data before sending is recommended.

```APIDOC
## POST /upload/

### Description
Uploads audio files, metadata, and images to Mixcloud.

### Method
POST

### Endpoint
https://api.mixcloud.com/upload/

### Parameters
#### Request Body (multipart/form-data)
- **mp3** (file) - REQUIRED - The audio file to be uploaded. Max size: 4294967296 bytes.
- **name** (string) - REQUIRED (if a track) - The track section song title.
- **picture** (file) - Optional - A picture for the upload. Max size: 10485760 bytes.
- **description** (string) - Optional - A description for the upload. Max 1000 characters.
- **tags-X-tag** (string) - Optional - Where X is 0-4. A tag name for the upload. Up to 5 tags allowed.
- **unlisted** (boolean) - Optional - Make this upload private.
- **publish_date** (string) - Optional (Pro Accounts only) - Scheduled publish date in YYYY-MM-DDTHH:MM:SSZ format (UTC).
- **disable_comments** (boolean) - Optional (Pro Accounts only) - Disable comments for this upload.
- **hide_stats** (boolean) - Optional (Pro Accounts only) - Hide play, favorite, and repost counts.
- **hosts-X-username** (string) - Optional (Pro Accounts only) - Where X is 0-1. Username of another Mixcloud account to tag. Up to 2 users.

### Sections (for tracklist/chapter information)
- **sections-X-artist** (string) - REQUIRED (if a track) - The track section artist name.
- **sections-X-song** (string) - REQUIRED (if a track) - The track section song title.
- **sections-X-chapter** (string) - Optional - The name of a chapter section.
- **sections-X-start_time** (integer) - Optional - The time in seconds at which section X starts.

### Request Example
```bash
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=INSERT_ACCESS_TOKEN_HERE
```

### Response
(Success and error response details are not provided in the source text.)
```

--------------------------------

### Set Widget Options

Source: https://www.mixcloud.com/developers/widget

Allows setting various widget display options to true or false.

```APIDOC
## Set Widget Options

### Description
Allows modification of widget display properties.

### Method
JavaScript

### Endpoint
N/A (JavaScript API)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
Set one of the following options to `true` or `false`:
* `hide_cover`
* `hide_tracklist`
* `mini`
* `hide_artwork`
* `light`

### Request Example
```javascript
widget.setOption("hide_cover", true);
widget.setOption("mini", false);
```

### Response
#### Success Response
Updates the widget's display options.
```

--------------------------------

### Listen for Widget Events

Source: https://www.mixcloud.com/developers/widget

Subscribe to various widget events like play, pause, or progress. Use the `.on()` method to attach a listener and `.off()` to detach it. The progress event provides position and duration.

```javascript
var widget = Mixcloud.PlayerWidget(myIframe);
widget.events.pause.on(pauseListener);
function pauseListener() {
    // This will be called whenever the widget is paused  
}
  
// To stop listening for events:
widget.events.pause.off(pauseListener);
```

```javascript
widget.events.progress.on(function(position, duration) {
    // Handle progress updates
});
```

--------------------------------

### Follow, Favorite, Repost, Add to Listen Later

Source: https://www.mixcloud.com/developers

Endpoints for users to follow, favorite, repost, or add content to their listen later list. These actions can be performed using POST requests, and unfollowing/unfavoriting/unreposting/removing from listen later can be done with DELETE requests or a POST request with method=delete.

```APIDOC
## POST /:username/follow/

### Description
Allows a user to follow another user.

### Method
POST

### Endpoint
https://api.mixcloud.com/:username/follow/

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your Mixcloud API access token.

### Request Example
```bash
curl -X POST "https://api.mixcloud.com/spartacus/follow/?access_token=_ACCESS_TOKEN_"
```

## DELETE /:username/follow/

### Description
Allows a user to unfollow another user.

### Method
DELETE

### Endpoint
https://api.mixcloud.com/:username/follow/

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your Mixcloud API access token.

### Request Example
```bash
curl -X DELETE "https://api.mixcloud.com/spartacus/follow/?access_token=_ACCESS_TOKEN_"
```

## POST /:username/:uploadname/favorite/

### Description
Allows a user to favorite an upload.

### Method
POST

### Endpoint
https://api.mixcloud.com/:username/:uploadname/favorite/

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your Mixcloud API access token.

### Request Example
```bash
curl -X POST "https://api.mixcloud.com/spartacus/party-time/favorite/?access_token=_ACCESS_TOKEN_"
```

## DELETE /:username/:uploadname/favorite/

### Description
Allows a user to unfavorite an upload.

### Method
DELETE

### Endpoint
https://api.mixcloud.com/:username/:uploadname/favorite/

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your Mixcloud API access token.

### Request Example
```bash
curl -X DELETE "https://api.mixcloud.com/spartacus/party-time/favorite/?access_token=_ACCESS_TOKEN_"
```

## POST /:username/:uploadname/repost/

### Description
Allows a user to repost an upload.

### Method
POST

### Endpoint
https://api.mixcloud.com/:username/:uploadname/repost/

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your Mixcloud API access token.

### Request Example
```bash
curl -X POST "https://api.mixcloud.com/spartacus/party-time/repost/?access_token=_ACCESS_TOKEN_"
```

## DELETE /:username/:uploadname/repost/

### Description
Allows a user to unrepost an upload.

### Method
DELETE

### Endpoint
https://api.mixcloud.com/:username/:uploadname/repost/

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your Mixcloud API access token.

### Request Example
```bash
curl -X DELETE "https://api.mixcloud.com/spartacus/party-time/repost/?access_token=_ACCESS_TOKEN_"
```

## POST /:username/:uploadname/listen-later/

### Description
Allows a user to add an upload to their listen later list.

### Method
POST

### Endpoint
https://api.mixcloud.com/:username/:uploadname/listen-later/

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your Mixcloud API access token.

### Request Example
```bash
curl -X POST "https://api.mixcloud.com/spartacus/party-time/listen-later/?access_token=_ACCESS_TOKEN_"
```

## DELETE /:username/:uploadname/listen-later/

### Description
Allows a user to remove an upload from their listen later list.

### Method
DELETE

### Endpoint
https://api.mixcloud.com/:username/:uploadname/listen-later/

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your Mixcloud API access token.

### Request Example
```bash
curl -X DELETE "https://api.mixcloud.com/spartacus/party-time/listen-later/?access_token=_ACCESS_TOKEN_"
```

## POST with method=delete

### Description
Simulates a DELETE request using a POST request with the `method=delete` parameter.

### Method
POST

### Endpoint
https://api.mixcloud.com/:username/follow/ (example)

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your Mixcloud API access token.
#### Request Body
- **method** (string) - Required - Set to "delete" to simulate a DELETE request.

### Request Example
```bash
curl -F "method=delete" "https://api.mixcloud.com/spartacus/follow/?access_token=_ACCESS_TOKEN_"
```
```

--------------------------------

### Retrieve New Items

Source: https://www.mixcloud.com/developers

Fetch a list of new items on Mixcloud.

```APIDOC
## GET /new/

### Description
Retrieves a list of new items.

### Method
GET

### Endpoint
https://api.mixcloud.com/new/

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of items to return.
- **offset** (integer) - Optional - The number of items to skip.
```

--------------------------------

### Retrieve a Show

Source: https://www.mixcloud.com/developers

Access information about a specific show by providing the username and show key.

```APIDOC
## GET /spartacus/party-time/

### Description
Retrieves details for a specific show.

### Method
GET

### Endpoint
https://api.mixcloud.com/{username}/{show_key}/

### Example Response
{
  "url": "https://www.mixcloud.com/spartacus/party-time/",
  "name": "Party Time",
  "key": "/spartacus/party-time/"
}
```

--------------------------------

### Trigger Footer Widget Content Load

Source: https://www.mixcloud.com/developers/widget

Add a 'data-mixcloud-play-button' attribute to any element to enable it as a button that loads new content into the footer widget when clicked.

```html
<div data-mixcloud-play-button="/my-upload/url-goes-here/">Click me to play my other upload!<div>
```

--------------------------------

### Favorite Upload with Mixcloud API

Source: https://www.mixcloud.com/developers

Send a POST request to the upload's favorite endpoint to favorite it. To unfavorite, send a DELETE request or a POST with method=delete.

```bash
https://api.mixcloud.com/spartacus/party-time/favorite/?access_token=_ACCESS_TOKEN_
```

--------------------------------

### Include Widget API Script

Source: https://www.mixcloud.com/developers/widget

Add this script tag to your HTML to enable the Mixcloud Widget Javascript API. Only one instance is needed per page, even with multiple widgets.

```html
<script src="//widget.mixcloud.com/media/js/widgetApi.js" type="text/javascript"></script>
```

--------------------------------

### togglePlay

Source: https://www.mixcloud.com/developers/widget

Toggles between playing and pausing the Mixcloud upload based on the current playback state.

```APIDOC
## togglePlay()

### Description
Switches between playing and paused states for the current upload.

### Method
JavaScript

### Endpoint
N/A (JavaScript API)

### Parameters
N/A

### Request Example
```javascript
widget.togglePlay();
```

### Response
#### Success Response
Toggles the playback state.
```

--------------------------------

### Retrieve a Tag

Source: https://www.mixcloud.com/developers

Fetch information about a specific tag.

```APIDOC
## GET /genres/funk/

### Description
Retrieves details for a specific tag or genre.

### Method
GET

### Endpoint
https://api.mixcloud.com/genres/{tag_name}/

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

--------------------------------

### Retrieve Popular Items

Source: https://www.mixcloud.com/developers

Fetch a list of popular items on Mixcloud.

```APIDOC
## GET /popular/

### Description
Retrieves a list of currently popular items.

### Method
GET

### Endpoint
https://api.mixcloud.com/popular/

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of items to return.
- **offset** (integer) - Optional - The number of items to skip.
```

--------------------------------

### Embedding Content

Source: https://www.mixcloud.com/developers

Endpoints for retrieving embed HTML for uploads and for using oEmbed discovery.

```APIDOC
## GET /:username/:uploadname/embed-html/

### Description
Retrieves the embed HTML code for a specific upload.

### Method
GET

### Endpoint
https://api.mixcloud.com/:username/:uploadname/embed-html/

### Parameters
None explicitly mentioned for this endpoint, but an Upload API key is implied by the context.

## GET /:username/:uploadname/embed-json/

### Description
Retrieves the embed HTML code wrapped in JSON for cross-domain requests (JSONP).

### Method
GET

### Endpoint
https://api.mixcloud.com/:username/:uploadname/embed-json/

### Parameters
#### Query Parameters
- **width** (integer) - Optional - Desired width of the widget.
- **height** (integer) - Optional - Desired height of the widget.
- **color** (string) - Optional - 6 digit hex code for the widget's color.

## GET /oembed/

### Description
Supports oEmbed discovery to get embed code for an upload.

### Method
GET

### Endpoint
https://app.mixcloud.com/oembed/

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the Mixcloud upload (URL-encoded).
- **format** (string) - Required - The desired format, e.g., "json".

### Request Example
```
https://app.mixcloud.com/oembed/?url=https%3A%2F%2Fwww.mixcloud.com%2Fspartacus%2Fparty-time%2F&format=json
```
```

--------------------------------

### Access Authorized User's Data (/me/)

Source: https://www.mixcloud.com/developers

Retrieve information and connections for the currently authenticated user.

```APIDOC
## GET /me/

### Description
Provides a shortcut to access the authenticated user's profile information and their connections. Requires an access token.

### Method
GET

### Endpoint
https://api.mixcloud.com/me/

### Notes
This endpoint is only available over HTTPS and requires a valid access token.
```

--------------------------------

### Retrieve a City

Source: https://www.mixcloud.com/developers

Fetch information about a specific city.

```APIDOC
## GET /genres/city:athens/

### Description
Retrieves details for a specific city.

### Method
GET

### Endpoint
https://api.mixcloud.com/genres/city:{city_name}/

### Example Response
{
  "url": "https://www.mixcloud.com/genres/city:athens/",
  "name": "Athens shows",
  "key": "/genres/city:athens/"
}
```

--------------------------------

### Add to Listen Later with Mixcloud API

Source: https://www.mixcloud.com/developers

Use a POST request to the upload's listen-later endpoint to add it to the user's listen later list. To remove, send a DELETE request or a POST with method=delete.

```bash
https://api.mixcloud.com/spartacus/party-time/listen-later/?access_token=_ACCESS_TOKEN_
```

--------------------------------

### Control Playback

Source: https://www.mixcloud.com/developers/widget

Methods to control the playback state of the widget. Note that due to browser policies, autoplay may not be guaranteed, and a user-initiated play button is recommended.

```javascript
widget.play();
```

```javascript
widget.pause();
```

```javascript
widget.togglePlay();
```

--------------------------------

### Retrieve Hot Items

Source: https://www.mixcloud.com/developers

Fetch a list of hot items on Mixcloud.

```APIDOC
## GET /popular/hot/

### Description
Retrieves a list of hot items.

### Method
GET

### Endpoint
https://api.mixcloud.com/popular/hot/

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of items to return.
- **offset** (integer) - Optional - The number of items to skip.
```

--------------------------------

### Event Listeners

Source: https://www.mixcloud.com/developers/widget

Provides a mechanism to listen for and react to various playback events from the Mixcloud widget.

```APIDOC
## Event Listeners

### Description
Allows subscribing to and unsubscribing from widget events to trigger custom logic.

### Method
JavaScript

### Endpoint
N/A (JavaScript API)

### Parameters
N/A

### Available Events
* `progress`: Fired during playback, provides `position` and `duration`.
* `buffering`
* `play`
* `pause`
* `ended`
* `error`

### Request Example
```javascript
// Listen for pause event
widget.events.pause.on(pauseListener);

function pauseListener() {
    console.log("Widget was paused.");
}

// Stop listening for pause event
widget.events.pause.off(pauseListener);

// Listen for progress event
widget.events.progress.on(progressListener);

function progressListener(position, duration) {
    console.log(`Progress: ${position}/${duration} seconds`);
}
```

### Response
#### Success Response
Registers or de-registers an event listener.
```

--------------------------------

### Force Mixcloud App on Android

Source: https://www.mixcloud.com/developers

This Java code snippet demonstrates how to force content to open specifically in the Mixcloud app on Android by setting the package on the intent.

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

--------------------------------

### seek

Source: https://www.mixcloud.com/developers/widget

Seeks to a specific point in seconds within the current Mixcloud upload.

```APIDOC
## seek(seconds)

### Description
Moves the playback position to a specified number of seconds into the current audio.

### Method
JavaScript

### Endpoint
N/A (JavaScript API)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
* **seconds** (number) - Required - The number of seconds to seek to within the audio.

### Request Example
```javascript
widget.seek(60).then(function(seekAllowed) {
    if (seekAllowed) {
        console.log("Seek successful.");
    } else {
        console.log("Seek not allowed.");
    }
});
```

### Response
#### Success Response
Returns a promise that resolves with `true` if the seek operation was allowed, and `false` otherwise.
```

--------------------------------

### Follow User with Mixcloud API

Source: https://www.mixcloud.com/developers

Use a POST request to the user's follow endpoint to follow a user. A DELETE request or a POST with method=delete can be used to unfollow.

```bash
curl -X POST "https://api.mixcloud.com/spartacus/follow/?access_token=_ACCESS_TOKEN_"
```

```bash
curl -X DELETE "https://api.mixcloud.com/spartacus/follow/?access_token=_ACCESS_TOKEN_"
```

```bash
curl -F "method=delete" "https://api.mixcloud.com/spartacus/follow/?access_token=_ACCESS_TOKEN_"
```

--------------------------------

### Avoid Global Namespace Conflicts with noConflict

Source: https://www.mixcloud.com/developers/widget

Use the noConflict method when a variable named 'Mixcloud' already exists in the global scope to prevent conflicts. It returns the original 'window.Mixcloud' value after the widget API script is loaded.

```javascript
Mixcloud.noConflict(function(mixcloudApiObject) {
    mixcloudApiObject.PlayerWidget( ... 
});
```

--------------------------------

### getPosition

Source: https://www.mixcloud.com/developers/widget

Retrieves the current playback position in seconds of the Mixcloud upload.

```APIDOC
## getPosition()

### Description
Gets the current playback position in seconds.

### Method
JavaScript

### Endpoint
N/A (JavaScript API)

### Parameters
N/A

### Request Example
```javascript
widget.getPosition().then(function(position) {
    console.log("Current position: " + position + " seconds");
});
```

### Response
#### Success Response
Returns a promise that resolves with the current playback position in seconds.
```

--------------------------------

### Edit Upload

Source: https://www.mixcloud.com/developers

Uploads can be edited by posting to the edit endpoint with an access token. Metadata and images should be uploaded in a single multipart/form-data POST request. All fields allowed in an upload, except mp3, can be sent to this endpoint. Specific fields like name, description, tags, sections, and hosts will be overwritten if included in the request. You can also use 'publish' or 'unpublish' parameters to manage the upload's visibility.

```APIDOC
## POST /upload/[YOUR_SHOW_KEY]/edit/

### Description
Edits an existing upload with new metadata, image, or visibility settings.

### Method
POST

### Endpoint
https://api.mixcloud.com/upload/[YOUR_SHOW_KEY]/edit/

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your API access token.

#### Request Body
- **picture** (file) - Optional - The new image for the upload.
- **name** (string) - Optional - The new name for the upload.
- **description** (string) - Optional - The new description for the upload.
- **tags-[index]-tag** (string) - Optional - Tags for the upload. Posting any tag fields will overwrite all existing tags.
- **sections** (array) - Optional - Tracklist sections for the upload. Posting any section field will overwrite the entire tracklist.
- **hosts** (array) - Optional - Hosts for the upload. Posting any host field will overwrite all existing hosts.
- **publish** (boolean) - Optional - Make this upload public. Can only be used with unpublish or unpublish.
- **unpublish** (boolean) - Optional - Move this upload to drafts. Can only be used with publish or unpublish.

### Request Example
```bash
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=INSERT_ACCESS_TOKEN_HERE
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the upload was successfully edited.
```