Playlists

The playlists API allows for the creation and editing of lists of recordings

GET /1/user/(playlist_user_name)/playlists

Fetch playlist metadata in JSPF format without recordings for the given user. If a user token is provided in the Authorization header, return private playlists as well as public playlists for that user.

Parameters:

  • count (int) – The number of playlists to return (for pagination). Default DEFAULT_NUMBER_OF_PLAYLISTS_PER_CALL

  • offset (int) – The offset of into the list of playlists to return (for pagination)

Status Codes:
Response Headers:
GET /1/user/(playlist_user_name)/playlists/createdfor

Fetch playlist metadata in JSPF format without recordings that have been created for the user. Createdfor playlists are all public, so no Authorization is needed for this call.

Parameters:

  • count (int) – The number of playlists to return (for pagination). Default DEFAULT_NUMBER_OF_PLAYLISTS_PER_CALL

  • offset (int) – The offset of into the list of playlists to return (for pagination)

Status Codes:
Response Headers:
GET /1/user/(playlist_user_name)/playlists/collaborator

Fetch playlist metadata in JSPF format without recordings for which a user is a collaborator. If a playlist is private, it will only be returned if the caller is authorized to edit that playlist.

Parameters:

  • count (int) – The number of playlists to return (for pagination). Default DEFAULT_NUMBER_OF_PLAYLISTS_PER_CALL

  • offset (int) – The offset of into the list of playlists to return (for pagination)

Status Codes:
Response Headers:
POST /1/playlist/create

Create a playlist. The playlist must be in JSPF format with MusicBrainz extensions, which is defined here: https://musicbrainz.org/doc/jspf . To create an empty playlist, you can send an empty playlist with only the title field filled out. If you would like to create a playlist populated with recordings, each of the track items in the playlist must have an identifier element that contains the MusicBrainz recording that includes the recording MBID.

When creating a playlist, only the playlist title and the track identifier elements will be used – all other elements in the posted JSPF wil be ignored.

If a created_for field is found and the user is not an approved playlist bot, then a 403 forbidden will be raised.

Request Headers:
Status Codes:

  • 200 OK – playlist accepted.

  • 400 Bad Request – invalid JSON sent, see error message for details.

  • 401 Unauthorized – invalid authorization. See error message for details.

  • 403 Forbidden – forbidden. The submitting user is not allowed to create playlists for other users.

Response Headers:
GET /1/playlist/search

Search for playlists by name or description. The search query must be at least 3 characters long.

Parameters:

  • q (str) – The search query string.

Status Codes:
Response Headers:
POST /1/playlist/edit/(playlist_mbid)

Edit the private/public status, name, description or list of collaborators for an exising playlist. The Authorization header must be set and correspond to the owner of the playlist otherwise a 403 error will be returned. All fields will be overwritten with new values.

Request Headers:
Status Codes:

  • 200 OK – playlist accepted.

  • 400 Bad Request – invalid JSON sent, see error message for details.

  • 401 Unauthorized – invalid authorization. See error message for details.

  • 403 Forbidden – forbidden. The subitting user is not allowed to edit playlists for other users.

Response Headers:
GET /1/playlist/(playlist_mbid)

Fetch the given playlist.

Parameters:

  • playlist_mbid (str) – The playlist mbid to fetch.

  • fetch_metadata (bool) – Optional, pass value ‘false’ to skip lookup up recording metadata

Status Codes:
Response Headers:
GET /1/playlist/(playlist_mbid)/xspf

Fetch the given playlist as XSPF.

Parameters:

  • playlist_mbid (str) – The playlist mbid to fetch.

  • fetch_metadata (bool) – Optional, pass value ‘false’ to skip lookup up recording metadata

Status Codes:
Response Headers:
POST /1/playlist/(playlist_mbid)/item/add
POST /1/playlist/(playlist_mbid)/item/add/(int: offset)

Append recordings to an existing playlist by posting a playlist with one of more recordings in it. The playlist must be in JSPF format with MusicBrainz extensions, which is defined here: https://musicbrainz.org/doc/jspf .

If the offset is provided in the URL, then the recordings will be added at that offset, otherwise they will be added at the end of the playlist.

You may only add MAX_RECORDINGS_PER_ADD recordings in one call to this endpoint.

Request Headers:
Status Codes:

  • 200 OK – playlist accepted.

  • 400 Bad Request – invalid JSON sent, see error message for details.

  • 401 Unauthorized – invalid authorization. See error message for details.

  • 403 Forbidden – forbidden. the requesting user was not allowed to carry out this operation.

Response Headers:
POST /1/playlist/(playlist_mbid)/item/move

To move an item in a playlist, the POST data needs to specify the recording MBID and current index of the track to move (from), where to move it to (to) and how many tracks from that position should be moved (count). The format of the post data should look as follows:

{
    "mbid": "<mbid>",
    "from": 3,
    "to": 4,
    "count": 2
}
Request Headers:
Status Codes:

  • 200 OK – move operation succeeded

  • 400 Bad Request – invalid JSON sent, see error message for details.

  • 401 Unauthorized – invalid authorization. See error message for details.

  • 403 Forbidden – forbidden. the requesting user was not allowed to carry out this operation.

Response Headers:
POST /1/playlist/(playlist_mbid)/item/delete

To delete an item in a playlist, the POST data needs to specify the recording MBID and current index of the track to delete, and how many tracks from that position should be moved deleted. The format of the post data should look as follows:

{
    "index": 3,
    "count": 2
}
Request Headers:
Status Codes:

  • 200 OK – playlist accepted.

  • 400 Bad Request – invalid JSON sent, see error message for details.

  • 401 Unauthorized – invalid authorization. See error message for details.

  • 403 Forbidden – forbidden. the requesting user was not allowed to carry out this operation.

Response Headers:
POST /1/playlist/(playlist_mbid)/delete

Delete a playlist. POST body data does not need to contain anything.

Request Headers:
Status Codes:
Response Headers:
POST /1/playlist/(playlist_mbid)/copy

Copy a playlist – the new playlist will be given the name “Copy of <playlist_name>”. POST body data does not need to contain anything.

Request Headers:
Status Codes:
Response Headers:
POST /1/playlist/(playlist_mbid)/export/(service)

Export a playlist to an external service, given a playlist MBID.

Request Headers:
Parameters:

  • playlist_mbid – The playlist mbid to export.

  • is_public – Should the exported playlist be public or not?

Status Codes:
Response Headers:
GET /1/playlist/import/(service)

Get playlists from Spotify.

Request Headers:
Status Codes:
Response Headers:
GET /1/playlist/(service)/(playlist_id)/tracks

Import a playlist tracks from a Spotify and convert them to JSPF.

Request Headers:
Parameters:

  • playlist_id – The Spotify playlist id to get the tracks from

Status Codes:
Response Headers:
POST /1/playlist/export-jspf/(service)

Export a playlist to an external service from JSPF POSTed to this endpoint.

Request Headers:
Parameters:

  • is_public – Should the exported playlist be public or not?

Status Codes:
Response Headers: