Note:

  • The Spotify Connect Web API endpoints are currently released in their Beta version phase. While we encourage you to include them in your build, be aware that without prior notice we may disable some or all of the functionality and/or change the way they work.
  • Please report any issues in our GitHub issue tracker.
  • With Connect Web API you can only control Spotify Premium users’ playback.

Use the Spotify Connect Web API Endpoints to create a smooth user experience:

Enabling the Initial Request

When a user interacts with the Connect Web API for the first time, the response code from any endpoint may be 202 ACCEPTED. This is when you create an initial population of the available devices for that user, and start listening to events. In most cases this happens only once for every user.

We recommend that your integration:

  • Limits the number of repeated attempts to cater for this scenario
  • In the event of a 202 ACCEPTED response pauses execution for up to 5 seconds
  • Renews attempt of the call

Note: Do not implement an infinite retry loop. If the initial call continues to respond with a 202 ACCEPTED code it is likely that that the user has no devices that are currently active.

Viewing Active Device List

To view a user list of current and active devices, make a request to the /v1/me/player/devices endpoint.

{
  "devices" : [ {
    "id" : "b46689a4cd5",
    "is_active" : false,
    "is_restricted" : false,
    "name" : "Your MacBook",
    "type" : "Computer",
    "volume_percent" : 70
  }, {
    "id" : "0d184899bc8",
    "is_active" : false,
    "is_restricted" : false,
    "name" : "Living Room",
    "type" : "TV",
    "volume_percent" : 25
  }, {
    "id" : "2f3c360198ede6",
    "is_active" : false,
    "is_restricted" : false,
    "name" : "Office Speaker",
    "type" : "Unknown",
    "volume_percent" : 82
  } ]
}

The devices on the list are the ones that you can control.

Note: To determine if you should send controlling commands to a certain device, check the is_restricted flag on a device object. If you receive the 403 FORBIDDEN code back, this means that the currently active device (or targeted device) is not controllable through the Web API.

There may be occasions when you see a device in the /v1/me/player and /v1/me/player/currently-playing endpoints that you do not see in /v1/me/player/devices. This can happen while playback takes place on a restricted device.

Devices not Appearing on Device List

Connect Web API relies on local network connections to discover and interact with some devices.

For example, when:

  • A new device is added to the network
  • A device is in “sleep” mode
  • A device on the local network is currently tied to another user account, or
  • Other reasons specific to the device

As a result, some devices that appear in the Connect picker within the Spotify application may not always be visible or available on the Connect Web API Endpoints.

Targeting a Specific Device

A Device ID is unique and persistent to some extent. However, this is not guaranteed and any cached device_id should periodically be cleared out and re-fetched as necessary.

All the Connect Web API command endpoints include the device_id parameter in the called URL. This can be used to control specific devices rather than the currently active device.

For example, to set the volume on a specific device, run:

https://api.spotify.com/v1/me/player/volume?volume_percent=55&device_id=TARGETDEVICEID

Commands Execution Order

The order of command execution is not guaranteed. The commands are mostly operated on by the devices in the order you call them via the Connect Web API.

An example a command to transfer playback to a specific device followed directly by a volume command could, in theory, raise the volume of the currently active device before the hand-over to the new device happens. You can circumvent some of these issues by targeting the commands (such as setting the volume) towards specific devices with the optional device_id parameter available on all endpoints.

curl -X PUT "https://api.spotify.com/v1/me/player" -H "Authorization: Bearer {your access token}" -H "Content-Type: application/json" --data "{device_ids:[\"74ASZWbe4lXaubB36ztrGX\"]}"

curl -X PUT "https://api.spotify.com/v1/me/player/volume?volume_percent=50" -H "Authorization: Bearer {your access token}"