API Documentation

Welcome to the API documentation. Our API is available at /api/v1 and provides some endpoints described below.

API StatusAvailable
API architecture schema

Easily search or generate playlists from YouTube, SoundCloud, Mixcloud, Bandcamp, Vimeo, custom files, and more — powered by the Mixider API and AI.

Getting Started

To get started with the API, you need to follow these steps.

Obtaining an API Key

To use the API, you need to follow these steps to obtain an API key:

  1. Create an account on Mixider
  2. Once logged in, go to your "Settings" page
  3. Scroll to the "Applications" section
  4. Click on "Create Application"
  5. Once the application created, you can retrieve the App key which is your API key

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

Media Objects

Media objects are the core of our API. They represent various media items available on different platforms, but managed by Mixider.

Each media object contains the following fields:

Name
Type
Description
id
String
Unique ID on Mixider for the media item.
title
String
Title visible on the platform.
author
String
Author (or media publisher) visible on the platform.
image
String
Thumbnail image URL.
platform
Enum:youtubesoundcloudmixcloudbandcampvimeo
Platform where the media comes from.
url
String
Media public URL.
duration
Number
Media duration in seconds.

Endpoints

The API provides several endpoints for interacting with the media library. Below are the details of each endpoint.

Search Media

Search for media items based on specified criteria.

POST /api/v1/media/search

Request

Request body should be a JSON object with the following fields:

Name
Type
Default
Description
platform
Enum:urlyoutubesoundcloudmixcloudbandcampvimeo
-
Platform to search on.
  • url
    • Search on URL if query starts with "http".
    • Search on every other platforms otherwise.
  • youtube: Search on YouTube, by query term or URL.
  • soundcloud: Search on SoundCloud, by query term or URL.
  • mixcloud: Search on Mixcloud, by query term or URL.
  • bandcamp: Search on Bandcamp, by query term or URL.
  • vimeo: Search on Vimeo, by query term or URL.
query
String
-
Search query term or URL.

Response

Response body will be a JSON array of maximum 30 .

Example

Request
POST /api/v1/media/search
Authorization: Bearer <YOUR_API_KEY>
{
  "platform": "url",
  "query": "example"
}
Response
[
  {
    "id": "mixcloud-Q2xvdWRjYXN0OjE2ODA2NzI4Nw==",
    "title": "Cantus Orbis: Some Examples of Medieval Drone - Vol.1",
    "author": "Michael Tanner",
    "image": "https://thumbnailer.mixcloud.com/unsafe/320x320/extaudio/2/3/b/a/53ae-b8ef-4634-8010-dc644fe52a33.png",
    "platform": "mixcloud",
    "url": "https://www.mixcloud.com/cloisters/an-introduction-to-medieval-drone-volume-1/",
    "duration": 2594
  },
  {
    "id": "souncloud-40644970",
    "title": "Changed The Way You Kiss Me feat. Ludacris (Remix)",
    "author": "Example",
    "image": "https://i1.sndcdn.com/artworks-000020386682-cmwg7x-large.jpg",
    "platform": "souncloud",
    "url": "https://soundcloud.com/example/changed-the-way-you-kiss-me",
    "duration": 208.153
  },
  {
    "id": "youtube-_G1soKzXJUo",
    "title": "Example - 'All Night' (OUT NOW)",
    "author": "Example",
    "image": "https://i.ytimg.com/vi/_G1soKzXJUo/hq720.jpg?sqp=-oaymwE2CNAFEJQDSFXyq4qpAygIARUAAIhCGAFwAcABBvABAfgB_gmAAtAFigIMCAAQARh_IEgoHzAP&rs=AOn4CLC7dlyNjEWL2r5_ubReCLIhY5rR6A",
    "platform": "youtube",
    "url": "https://youtube.com/watch?v=_G1soKzXJUo",
    "duration": 166
  },
  // More items...
]

Errors

Common error responses include:

  • 400 Bad Request: Invalid request parameters or missing required fields.
  • 401 Unauthorized: Invalid or missing API key.
  • 404 Not Found: The requested resource was not found.
  • 500 Internal Server Error: An unexpected error occurred on the server.

Generate PlaylistAI friendly

Generate a playlist based on a AI prompt.

POST /api/v1/playlists/generate

Request

Request body should be a JSON object with the following fields:

Name
Type
Default
Description
query
String
-
AI prompt. Maximum 300 characters.
mode
Enum:smartplatformmanual
-
Mode to use for the search.
  • smart Smart Pick: Let the algorithm choose the best version from any platform automatically.
  • platform Platform Priority: Choose your preferred platform. The algorithm will pick from it first, then others if needed.
    The main platform is set with the mainPlatform parameter.
  • manual Manual Choice: See the top results from each platform for every track and pick the ones you like.
mainPlatform
Enum:youtubesoundcloudmixcloudbandcampvimeo
-
Main platform to search on, if parameter mode is set to platform.

Response

Response body will be a JSON object with the following fields:

Name
Type
Description
title
String
Playlist generated title.
description
String
Playlist generated short description.
items
Array
  • If mode is set to smart or platform, list of 1 item suggesting maximum 10 as follow:
    Name
    Type
    Description
    results
    Array
    Media list of maximum 10 .
  • If mode is set to manual, list of maximum 10 items each suggesting around 1 per platform as follow:
    Name
    Type
    Description
    title
    String
    Media title
    author
    String
    Media author
    results
    Array
    Media list generated for the current suggested media, with each item being a .

Example

Request
POST /api/v1/playlists/generate
Authorization: Bearer <YOUR_API_KEY>
{
  "query": "vintage jazz music to listen on the beach",
  "mode": "smart",
  "mainPlatform": "youtube"
}
Response (mode set to smart or platform)
{
  "title": "Vintage Jazz Beach Playlist",
  "description": "Relaxing jazz classics for a perfect beach day",
  "items": [
    {
      "results": [
        {
          "id": "souncloud-255954857",
          "title": "Moon River",
          "author": "Louis Armstrong",
          "image": "https://i1.sndcdn.com/artworks-JzzT3cRAO6e0-0-large.jpg",
          "platform": "souncloud",
          "url": "https://soundcloud.com/louisarmstrongofficial/moon-river",
          "duration": 30
        },
        {
          "id": "youtube-s61-e29Vr6Q",
          "title": "Stan Getz feat. Astrud Gilberto - The Girl From Ipanema (Official Video)",
          "author": "Verve Records",
          "image": "https://i.ytimg.com/vi/s61-e29Vr6Q/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLATIEtmI0o9XTVp7oob-HcSCnigcA",
          "platform": "youtube",
          "url": "https://youtube.com/watch?v=s61-e29Vr6Q",
          "duration": 168
        },
        // More items...
      ]
    }
  ]
}
Response (mode set to manual)
{
  "title": "Vintage Jazz Beach Playlist",
  "description": "Relaxing jazz classics for a perfect beach day",
  "items": [
    {
      "title": "Moon River",
      "author": "Louis Armstrong",
      "results": [
        {
          "id": "youtube-WQDaop9onHE",
          "url": "https://youtube.com/watch?v=WQDaop9onHE",
          "image": "https://i.ytimg.com/vi/WQDaop9onHE/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLCCudeX4TV7gHZ4J68x0dyloUx1iA",
          "title": "Louis Armstrong - Moon River (Audio)",
          "author": "Louis Armstrong",
          "duration": 176,
          "platform": "youtube"
        },
        {
          "id": "souncloud-255954857",
          "url": "https://soundcloud.com/louisarmstrongofficial/moon-river",
          "image": "https://i1.sndcdn.com/artworks-JzzT3cRAO6e0-0-large.jpg",
          "title": "Moon River",
          "author": "Louis Armstrong",
          "duration": 30,
          "platform": "souncloud"
        }
      ]
    },
    // More items...
  ]
}

Errors

Common error responses include:

  • 400 Bad Request: Invalid request parameters or missing required fields.
  • 401 Unauthorized: Invalid or missing API key.
  • 404 Not Found: The requested resource was not found.
  • 422 Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors.
  • 429 Too Many Requests: Rate limit exceeded. You have reached the maximum number of requests allowed.
  • 500 Internal Server Error: An unexpected error occurred on the server.