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:

Viewing Device List

To view a user’s list of currently connected devices, make a request to the /v1/me/player/devices endpoint.

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

The devices in 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

All the Connect Web API command endpoints include the device_id parameter in the called URL. This can be used to control a specific device. If you do not specify a device_id, the currently active one (see "is_active": true in the device list response) will be targeted.

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

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

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.

For 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}"