Spotify

search

Search for a track.

Request body:

{
  "user_id": "...",
  "action": "search",
  "payload": { "query": "So Will I Hillsong Worship" },
  "target_app": "spotify"
}

provider_response.result shape:

{ "tracks": { "items": [{"uri":"spotify:track:...","name":"...","artists":[...]}] } }

play

Start playback of a specific track URI on the active device.

Request body:

{
  "user_id": "...",
  "action": "play",
  "payload": { "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" },
  "target_app": "spotify"
}

provider_response.result shape:

{} (204 No Content)

pause

Pause playback.

Request body:

{
  "user_id": "...",
  "action": "pause",
  "payload": {},
  "target_app": "spotify"
}

provider_response.result shape:

{} (204 No Content)

skip

Skip to the next track.

Request body:

{
  "user_id": "...",
  "action": "skip",
  "payload": {},
  "target_app": "spotify"
}

provider_response.result shape:

{} (204 No Content)

get_current

Get what's currently playing.

Request body:

{
  "user_id": "...",
  "action": "get_current",
  "payload": {},
  "target_app": "spotify"
}

provider_response.result shape:

{ "item": {"name":"...","artists":[...]}, "is_playing": true }

get_devices

List the user's active/available devices.

Request body:

{
  "user_id": "...",
  "action": "get_devices",
  "payload": {},
  "target_app": "spotify"
}

provider_response.result shape:

{ "devices": [{"id":"...","name":"iPhone","is_active":true}] }

add_to_queue

Add a track to the playback queue.

Request body:

{
  "user_id": "...",
  "action": "add_to_queue",
  "payload": { "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" },
  "target_app": "spotify"
}

provider_response.result shape:

{} (204 No Content)

get_recently_played

List recently played tracks.

Request body:

{
  "user_id": "...",
  "action": "get_recently_played",
  "payload": {},
  "target_app": "spotify"
}

provider_response.result shape:

{ "items": [{"track":{"name":"..."},"played_at":"..."}] }

404 "NO_ACTIVE_DEVICE" on play/pause/skip

Cause: Nothing is currently open/active in Spotify on any of the user's devices — Spotify's API has nothing to control.

Fix: Tell the user to open Spotify (phone or desktop) and start any playback first, or call get_devices to check first.

search / everything returns "no token" errors

Cause: Almost always a canonical user_id mismatch — the OAuth connection happened under a different session/device ID than the one calling now (this looks identical to "not connected" but a real connection exists).

Fix: Verify the exact user_id used to connect matches the one used for this call.

401 "The access token expired"

Cause: Token expired and couldn't auto-refresh (missing refresh token from an old/incomplete OAuth grant).

Fix: Have the user reconnect via the OAuth flow.