Playlists

← Back to Home

Playlists

Shared Playlists (no auth required)

Public, anonymous-link playlists. Anyone with the share ID can read them.

POST /playlists/share/

// Request
{ "paths": ["Compilation/song1.mp3", "Compilation/song2.mp3"] }

// Response
{ "share_id": "abc123..." }

GET /playlists/shared/{share_id}/

Full shared playlist with all track metadata.

GET /playlists/shared/{share_id}/info/

Lightweight preview — name + track count without full fetch.

Personal Library Playlists (auth required)

Private, account-synced playlists. Any logged-in user (including standard accounts) can use these — does not require editor role.

Method	Path	Description
GET	/library/playlists/	List all playlists for logged-in user (supports ?omit_cover_image=true)
POST	/library/playlists/	Create a playlist
GET	/library/playlists/{id}/	Get playlist with full track list
PATCH	/library/playlists/{id}/	Update name, description, cover, visibility, or reorder tracks
DELETE	/library/playlists/{id}/	Delete a playlist
POST	/library/playlists/{id}/items/	Add a track
DELETE	/library/playlists/{id}/items/{song_id}/	Remove a track

?omit_cover_image=true drops the (large, base64) cover_image field from the response — use it for list views that only need cover_image_url.

Create:

POST /library/playlists/
Authorization: Token <token>

{
  "name": "My Playlist",
  "description": "optional",
  "cover_image": undefined  // optional base64 string
}

Update (all fields optional, including track reorder):

PATCH /library/playlists/{id}/

{
  "name": "New name",
  "description": "New description",
  "cover_image": "",         // base64, or "" to clear
  "is_public": true,         // toggle public sharing (see below)
  "order": [123, 456, 789]  // song IDs in desired order
}

List response — each item:

{
  "id": 1,
  "name": "My Playlist",
  "description": "optional",
  "cover_image": "...",
  "cover_image_url": "...",  // fallback to first track image_url
  "track_count": 12,
  "is_public": false,
  "created_at": "...",
  "updated_at": "..."
}

Detail response — same fields plus items[]:

{
  "id": 1,
  "name": "My Playlist",
  "is_public": false,
  "items": [
    {
      "id": 501,
      "position": 0,
      "added_at": "...",
      "song": {
        "id": 123, "public_id": 163, "name": "Maze",
        "path": "Compilation/.../Maze.mp3",
        "length": "2:24", "credited_artists": "Juice WRLD",
        "category": "released", "album": "...",
        "image_url": "/assets/drfl.png",
        "era": { /* era object */ },
        "lyrics": "...", "synced_lyrics": "..."
      }
    }
  ]
}

The song object in playlist items is a trimmed shape — no producers, engineers, or bitrate.

Public Library Playlists (no auth required)

A personal library playlist with is_public: true can be fetched anonymously by its numeric id — distinct from the ephemeral, no-account "Shared Playlists" above. Toggle visibility via PATCH /library/playlists/{id}/ with { "is_public": true }.

Method	Path	Description
GET	/library/playlists/public/{id}/	Full playlist detail (same shape as the authed detail response)

Making a playlist public does not change its owner or contents — it only exposes this read-only endpoint.

Favorites (auth required)

Method	Path	Description
GET	/library/favorites/	List favorite tracks
POST	/library/favorites/	Add a favorite — body: { song_id }
DELETE	/library/favorites/{song_id}/	Remove a favorite