Playlists

A playlist is an ordered set of tracks with a name, description and a public share link. Playlists created through the API appear in the app immediately.

List playlists

GET /api/v1/playlists?limit=50&cursor=…

Scope read:playlists. Cursor-paginated, newest first.

data

{
  "data": [
    {
      "id": "cm2a…",
      "name": "A&R Shortlist - Week 36",
      "description": "Tracks to review with the team.",
      "image": null,
      "collaborative": false,
      "isPinned": true,
      "trackCount": 12,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ],
  "paging": { "limit": 50, "next_cursor": null }
}

Get a playlist

GET /api/v1/playlists/single/{playlistId}

Scope read:playlists. Returns the playlist with its tracks in order, each with its audio profile and download link, plus a modes array. The entry with mode: "SHARE_VIEW" holds the public link token: https://postal.music/playlist/{link}.

Returns { "ok": false, "error": "PLAYLIST_NOT_FOUND" } for a playlist you do not own.

Create a playlist

POST /api/v1/playlists

Scope create:playlists.

Request

{
  "name": "A&R Shortlist - Week 36",
  "description": "Tracks to review with the team.",
  "trackIds": ["cm1x…", "cm1y…"],
  "dedupe": true
}

Field	Type	Notes
`name`	string ≤ 120	Required
`description`	string ≤ 2000
`trackIds`	string[] or CSV string	Required, at least one. Order is preserved
`dedupe`	boolean	Drop repeated ids

data

{
  "ok": true,
  "playlist": {
    "id": "cm2a…",
    "privateLink": "https://postal.music/playlists/cm2a…",
    "publicLink": "https://postal.music/playlist/9k2f…",
    "name": "A&R Shortlist - Week 36",
    "description": "Tracks to review with the team."
  },
  "tracks": { "count": 2, "ids": ["cm1x…", "cm1y…"] }
}

If any id is not yours the playlist is not created:

{ "ok": false, "error": "TRACKS_NOT_FOUND", "message": "…", "missing": ["cm1z…"] }

Update a playlist

PATCH /api/v1/playlists/{playlistId}

Scope update:playlists. Body { "name"?: string, "description"?: string }.

Add tracks

POST /api/v1/playlists/{playlistId}/tracks

Scope create:playlists. Body { "trackIds": ["…"] }. Appends in the given order.

Remove a track

DELETE /api/v1/playlists/{playlistId}/tracks/{trackId}

Scope update:playlists.

Reorder

PATCH /api/v1/playlists/{playlistId}/order

Scope update:playlists. Body { "trackIds": ["…"] } in the desired order.