lockstep-jukebox/docs/playlists.md

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 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} 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.