name: spotify description: Spotify Web API — playback control, search, playlists, and user library integration: spotify

Spotify API

Authentication

• Env var: $SPOTIFY_TOKEN (auto-injected via execute tool)
• Credentials: Pass credentials=["spotify"] to the execute tool
• Base URL: https://api.spotify.com/v1
• Token auto-refreshes on 401 response

Get Currently Playing

curl -s -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player/currently-playing"

Returns null if nothing is playing. When active, response includes item.name, item.artists[].name, item.album.name.

Get Playback State

curl -s -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player"

Returns device info, progress, shuffle/repeat state.

Play / Resume

# Resume playback
curl -s -X PUT \
  -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player/play"

# Play specific track
curl -s -X PUT \
  -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uris": ["spotify:track:TRACK_ID"]}' \
  "https://api.spotify.com/v1/me/player/play"

# Play a playlist
curl -s -X PUT \
  -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context_uri": "spotify:playlist:PLAYLIST_ID"}' \
  "https://api.spotify.com/v1/me/player/play"

Pause

curl -s -X PUT \
  -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player/pause"

Skip Track

# Next
curl -s -X POST \
  -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player/next"

# Previous
curl -s -X POST \
  -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player/previous"

Set Volume

curl -s -X PUT \
  -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player/volume?volume_percent=50"

Set Shuffle / Repeat

# Shuffle on/off
curl -s -X PUT \
  -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player/shuffle?state=true"

# Repeat: off, track, context
curl -s -X PUT \
  -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player/repeat?state=track"

Search

curl -s -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/search?q=artist:Daft+Punk&type=track&limit=5"

Types: track, artist, album, playlist, show, episode

Get User Playlists

curl -s -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/playlists?limit=20"

Recently Played

curl -s -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player/recently-played?limit=10"

Transfer Playback to Device

curl -s -X PUT \
  -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device_ids": ["DEVICE_ID"]}' \
  "https://api.spotify.com/v1/me/player"

Get Available Devices

curl -s -H "Authorization: Bearer $SPOTIFY_TOKEN" \
  "https://api.spotify.com/v1/me/player/devices"

Rate Limits

• ~180 requests per minute per user
• No official hard limit published

Error Handling

• 401: Token expired — auto-refreshes, retry
• 403: Insufficient scope for this action
• 404: Resource not found or no active device
• 429: Rate limited — respect Retry-After header