105 lines
3.5 KiB
Markdown
105 lines
3.5 KiB
Markdown
# 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).
|