Using the Spotify Connect Web API Beta
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.
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
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}"