Welcome
Select an endpoint from the sidebar to test it. The player bar at the top controls playback.
Click any track URI in the output to play it.
GET
/api/me
Returns the current user's Spotify profile.
Returns: display_name, email, country, product (premium/free), followers, images
Scope: user-read-email, user-read-private
Scope: user-read-email, user-read-private
GET
/api/playback
Get the current playback state (track, device, progress, shuffle, repeat).
Returns: is_playing, item (track object), device, progress_ms, shuffle_state, repeat_state
Note: Returns null/204 if nothing is playing. Updates reflect ~1s delay.
Scope: user-read-playback-state
Note: Returns null/204 if nothing is playing. Updates reflect ~1s delay.
Scope: user-read-playback-state
GET
/api/devices
List all available Spotify Connect devices.
Returns: Array of devices with id, name, type (Computer/Smartphone/Speaker), is_active, volume_percent
Note: Devices disappear ~10min after going inactive. Web Playback SDK devices show as "Computer".
Tip: Use the device id with /api/transfer or /api/play?device_id= to target a specific device.
Note: Devices disappear ~10min after going inactive. Web Playback SDK devices show as "Computer".
Tip: Use the device id with /api/transfer or /api/play?device_id= to target a specific device.
PUT
/api/play
Start or resume playback. Optionally play specific tracks.
Body options:
•
•
•
•
•
Note: Fails with 404 if no active device. Use /api/transfer first or pass device_id.
Scope: user-modify-playback-state
•
{} — resume current playback•
{"uris": ["spotify:track:ID"]} — play specific track(s)•
{"context_uri": "spotify:album:ID"} — play album/playlist•
{"context_uri": "...", "offset": {"position": 2}} — start at track index•
{"device_id": "abc123", "uris": [...]} — play on specific deviceNote: Fails with 404 if no active device. Use /api/transfer first or pass device_id.
Scope: user-modify-playback-state
PUT
/api/pause
Pause playback on the active device.
Note: Returns 403 if already paused. Returns 404 if no active device.
Scope: user-modify-playback-state
Scope: user-modify-playback-state
POST
/api/next
Skip to the next track.
Note: Requires an active device. Skips based on current context (playlist, album, queue).
Scope: user-modify-playback-state
Scope: user-modify-playback-state
POST
/api/previous
Skip to the previous track.
Note: If >3s into current track, restarts it instead of going back. Requires active device.
Scope: user-modify-playback-state
Scope: user-modify-playback-state
PUT
/api/transfer
Transfer playback to a different device.
Body:
Note: Automatically starts playing on the target device. Get device IDs from /api/devices.
Scope: user-modify-playback-state
{"device_id": "..."}Note: Automatically starts playing on the target device. Get device IDs from /api/devices.
Scope: user-modify-playback-state
GET
/api/search
Search the Spotify catalog for tracks, artists, albums, or playlists.
Params: q (query), type (track|artist|album|playlist, default: track), limit (1-50, default: 20)
Query tips:
•
•
•
•
• Combine:
Query tips:
•
artist:Radiohead — filter by artist•
album:OK Computer — filter by album•
year:2020-2024 — filter by year range•
genre:jazz — filter by genre• Combine:
artist:Radiohead year:1997
GET
/api/recently-played
Get the user's recently played tracks.
Params: limit (1-50, default: 50)
Returns: Array of {track, played_at} objects sorted by most recent
Limitation: Spotify only stores the last ~50 tracks. For longer history, you'd need to poll and store locally.
Scope: user-read-recently-played
Returns: Array of {track, played_at} objects sorted by most recent
Limitation: Spotify only stores the last ~50 tracks. For longer history, you'd need to poll and store locally.
Scope: user-read-recently-played
GET
/api/recommendations
Get track recommendations based on seed tracks, artists, or genres.
Params (up to 5 seeds total across all types):
•
•
•
Tuning params (all 0.0-1.0 unless noted):
•
•
•
•
Note: Great baseline to compare against your own ML algo. Returns max 100 tracks.
•
seed_tracks — comma-separated track IDs•
seed_artists — comma-separated artist IDs•
seed_genres — comma-separated genres (e.g. pop,rock,jazz)Tuning params (all 0.0-1.0 unless noted):
•
target_energy, min_energy, max_energy•
target_valence (happiness), target_danceability•
target_tempo (BPM, e.g. 120), target_acousticness•
target_instrumentalness, target_speechinessNote: Great baseline to compare against your own ML algo. Returns max 100 tracks.
GET
/api/audio-features/:id
Get audio analysis features for a track. Essential for ML models.
Returns (all 0.0-1.0 unless noted):
•
•
•
•
•
•
•
•
•
•
•
•
ML tip: Cluster tracks by [energy, valence, tempo, danceability] for mood zones.
•
danceability — how danceable (tempo, rhythm, beat strength)•
energy — intensity and activity (distortion, loudness, dynamics)•
valence — musical positiveness/happiness•
tempo — estimated BPM (e.g. 120.5)•
acousticness — acoustic vs. electronic•
instrumentalness — vocal vs. instrumental•
speechiness — spoken words (>0.66 = mostly speech)•
liveness — audience presence probability•
loudness — dB (-60 to 0)•
key — pitch class (0=C, 1=C#, ..., 11=B)•
mode — 0=minor, 1=major•
time_signature — beats per bar (3, 4, 5, etc.)ML tip: Cluster tracks by [energy, valence, tempo, danceability] for mood zones.
GET
/api/token
Get the current access token (used by Web Playback SDK).
Returns:
Note: Token auto-refreshes. Expires after ~1 hour. Used internally by the browser player.
{"access_token": "..."}Note: Token auto-refreshes. Expires after ~1 hour. Used internally by the browser player.