# Playlist endpoints

All routes require an authenticated session (`spotify_user_id` after Spotify login). Responses are JSON (`application/json`).

---

## `GET /playlists`

Returns every playlist for the current user by following Spotify’s paginated [`GET /v1/me/playlists`](https://developer.spotify.com/documentation/web-api/reference/get-a-list-of-current-users-playlists) until all pages are loaded.

### Success (200)

| Field | Type | Description |
| --- | --- | --- |
| `ok` | `boolean` | Always `true` on success. |
| `total` | `number` | Count of playlists in `items`. |
| `items` | `array` | Each element is a **simplified playlist object** from Spotify |

**Typical fields on each element of `items`** (Spotify `SimplifiedPlaylistObject`):

| Field | Type |
| --- | --- |
| `description` | `string` \| `null` |
| `id` | `string` |
| `images` | `array` of `{ "url": string, "height": number \| null, "width": number \| null }` |
| `name` | `string` |
| `primary_color` | `string` \| `null` |
| `snapshot_id` | `string` |
| `tracks` | `object` — e.g. `{ "href": string, "total": number }` (track list stub, not full tracks) |

### Errors

`{ "ok": false, "error": string, ... }`

---

## `GET /playlists/<playlist_id>`

`<playlist_id>` is the Spotify playlist ID (the same id as in playlist URLs / `items[].id`).

Fetches [`GET /v1/playlists/{playlist_id}`](https://developer.spotify.com/documentation/web-api/reference/get-playlist) following pagination.

### Success (200)

| Field | Type | Description |
| --- | --- | --- |
| `ok` | `boolean` | Always `true` on success. |
| `playlist` | `object` | **Full playlist object** from Spotify, with `tracks` possibly expanded to every track as described above. |

**Typical fields on `playlist`** (Spotify `PlaylistObject`):

| Field | Type |
| --- | --- |
| `description` | `string` \| `null` |
| `id` | `string` |
| `images` | `array` (image objects, as above) |
| `name` | `string` |
| `primary_color` | `string` \| `null` |
| `snapshot_id` | `string` |
| `tracks` | `{"items": [Track, ...], ...}` |

**Typical fields on each element of `playlist.tracks.items`** (Spotify playlist track wrapper):

| Field | Type |
| --- | --- |
| `track` | `object` \| `null` — full or linked track; `null` if removed |

Nested objects use Spotify’s **Track**, **Artist** (simplified), and **Album** (simplified) shapes below (field availability can vary by market or API version; see Spotify’s reference).

#### `track` — Spotify `TrackObject`

Returned as the non-`null` value of `playlist.tracks.items[].track` (playlist context usually includes a **full** track with **simplified** `album` and `artists` entries).

| Field | Type |
| --- | --- |
| `album` | `object` — **SimplifiedAlbumObject** (see below) |
| `artists` | `array` of **SimplifiedArtistObject** (see below) |
| `duration_ms` | `number` |
| `id` | `string` |
| `name` | `string` |

#### `track.artists[]` — Spotify **SimplifiedArtistObject**

| Field | Type |
| --- | --- |
| `id` | `string` |
| `name` | `string` |

#### `track.album` — Spotify **SimplifiedAlbumObject**

| Field | Type |
| --- | --- |
| `artists` | `array` of **SimplifiedArtistObject** (album-level credits) |
| `id` | `string` |
| `images` | `array` of `{ "url": string, "height": number \| null, "width": number \| null }` |
| `name` | `string` |

### Errors

Same as `/playlists`: **401** when not logged in; otherwise Spotify errors and network errors per the global error handlers.

---

For authoritative field lists and edge cases, see [Spotify Web API reference](https://developer.spotify.com/documentation/web-api).