Collectoh
EN

This page is in English only for now. The main pages follow your choice.

Sign up free
Browse the docs

API reference

Playlists

Playlists, sharing and M3U import/export (P3-10).

Paths are relative to /api/v1 on your server.

GET/playlists#

List playlists

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
itemIdquerystring (uuid)
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
POST/playlists#

Create a playlist

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
  • 201Success. application/json · PlaylistDetail
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks playlist:own, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
GET/playlists/{id}#

Read a playlist

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
includequerystring
  • 200Success. application/json · PlaylistDetail
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
PATCH/playlists/{id}#

Update a playlist

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · Playlist
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks playlist:own, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
DELETE/playlists/{id}#

Delete a playlist

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 204Done; no body.
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks playlist:own, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
PUT/playlists/{id}/entries/{entryId}/position#

Move an entry

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring (uuid)
entryId requiredpathstring (uuid)
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks playlist:own, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/playlists/{id}/export.m3u#

Export as M3U

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. audio/x-mpegurl · string
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/playlists/{id}/items#

Add items

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · PlaylistDetail
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks playlist:own, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
DELETE/playlists/{id}/items#

Remove entries

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · PlaylistDetail
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks playlist:own, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/playlists/{id}/share#

Share with an account

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · Playlist
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks playlist:own, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
DELETE/playlists/{id}/share/{userId}#

Stop sharing with an account

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
userId requiredpathstring (uuid)
  • 200Success. application/json · Playlist
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks playlist:own, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/playlists/import#

Import an M3U

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
  • 201Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks playlist:own, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
POST/playlists/import/itunes#

Import the iTunes library’s playlists

Reads the iTunes or Music library file the server’s music.itunes_xml_path names, in a worker with its own memory and time limits, and makes each of the person’s own playlists in it — not Library, Music, Films and the others iTunes keeps itself, nor folders — a playlist of the caller’s, its first 5,000 tracks found here by their files (by name, then the longest run of the path that agrees: another drive or root is normal; where only the name agrees and several files share it, by the track’s name, artist and album, else left out as ambiguous). Importing again brings each playlist an earlier import made up to date by its Persistent ID, renamed or not, its tracks replaced — tracks added to it here by hand are dropped — rather than making another. An admin’s (settings:manage).

Authorisation
Bearer token or API key · Session cookie
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: no file is set, the path is not a full one, nothing this server can read is there, or it is no iTunes library, a damaged one, or one too slow to read application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 413PAYLOAD_TOO_LARGE: the file is larger than 256 MB, or needs more memory to read than an import may use application/json · ErrorEnvelope
POST/playlists/preview#

Preview a smart playlist’s rules

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope