Control

The Sonos Control API is a JSON-based application protocol for controlling audio playback on Sonos players. A player can be an all-in-one smart speaker such as the One or a device, such as the Amp, that sends audio to connected speakers. The protocol consists of commands and events. Commands tell Sonos products what to do. Players broadcast events to subscribed clients with information about the state of the Sonos system. This overview will guide you through the structure of the Control API. We look forward to how you'll use it to deliver the ultimate home music experience.

Accounts, households, and groups

A Sonos account includes product registration and contact information about the owner of a Sonos system. It also allows these owners to authenticate with third-party clients such as your integration.

A household is a set of players on the same network under an account. An account can include multiple households. For example, one household may represent an owner's home system, while another may represent their vacation home system. Sonos creates a household during setup. Users can add and remove players from a household.

Each household is represented by a householdId. The householdId is stable with one exception. The value will change if players are moved to a different network. For example, if a user moves some players from a household to a different network, the players that were moved will use a different householdId. If all of the players in a household are moved to a different network, the householdId will remain the same.

Sonos players are always in groups, even if the group has only one player. All players in a group play the same audio in synchrony. Users can easily move players from one group to another without interrupting playback. Transport controls, such as play, pause, skip to next track, and skip to previous track, target groups rather than individual players. Players must be part of the same household to be part of a group.

See Discover to learn how to find households, groups, and players.

Communicate using HTTP and JSON

The Sonos Control API uses HTTP for routing and JSON in the body of the request for including additional parameters, if any.

While JSON is not type-specific, Control API parameters must have specific types for their values. This can be a string, number, boolean, null, object, or array. For example, the muted parameter in the setMute command requires a boolean value. Players also accept custom object types, such as playback objects. Parameters that must have numbers can accept these numbers as strings (for example, volume). Likewise, parameters that must have strings can accept these strings as numbers. The Control API requires some parameters and some are optional.

Sonos ignores parameter values of the wrong type. For example, null is not an accepted type. So if your integration sends a parameter with a value of “”, Sonos ignores it. If the parameter is required and it is missing, or ignored due to an incorrect type, you will receive an ERROR_MISSING_PARAMETER. If the parameter value is a number and it is out of range, you will receive an ERROR_INVALID_PARAMETER. See GlobalError for details.

You may see some undocumented parameters in responses and events. These may be experimental. Your integration should take this into account and not fail if it encounters them.

Commands and events exist in namespaces

A namespace describes a set of related commands and event notifications. Your integration can subscribe to a namespace to receive event notifications whenever states change in that namespace. For example, you can use commands and events in the playback namespace to:

• Start or pause group playback.
• Skip to the next or previous track.
• Receive notifications of playback status, such as playing or paused.
• Receive notifications of play modes, such as repeat or shuffle.

Your integration can subscribe to all namespaces, or just one. Click a namespace on the Control API reference page to find out more.

Send commands to the Sonos cloud

The Sonos cloud handles communications between your integration and each household. It forwards commands to the household, group, or player target. The player processes commands one at a time, in the order in which they were received. The Sonos cloud cannot guarantee that the ordering of command requests will be preserved when processed on the player.

Send RESTful Control API commands to the Sonos cloud using the following objects in the path:

https://{base URL}/v{version}/{target}/{target ID}/{namespace}/{command}

For example:

https://api.ws.sonos.com/control/api/v1/households/{householdId}/groups/createGroup

Here's more details about these path segments:

When your integration sends a command, the player checks the values sent with expected values. For example, the groupId sent by your integration must match an available groupId. If this doesn’t match, the player sends an ERROR_INVALID_OBJECT_ID error. If any required parameters are missing, your integration will receive an ERROR_MISSING_PARAMETERS error. See GlobalError for details.

See the About Control API reference page for a list of namespaces and commands.

Target players and groups

You can target commands to households, groups, sessions, or players. Regardless of the target type, the Sonos cloud routes most commands to one specific player (the group coordinator) responsible for processing the command for the group and responding. For some commands, such as get households, the cloud handles the request and response without sending it to a player.

Here's a list of available targets and sample paths:

Household IDs are immutable and long-lived, but they can change or cease to exist so they are not permanent. Groups and session IDs are ephemeral. Player IDs are permanent and immutable, as they are tied to the MAC address of a physical device.

Send HTTP headers; send parameters in the body

If a command does not require any parameters in the body, or if the body is empty, set the Content-Length header to 0. HTTP GET commands do not have bodies. Send the following HTTP headers for commands:

Receive responses from Sonos

All commands are inherently synchronous. Your integration issues an HTTP request to the cloud. While you wait for a response, the cloud sends the command to the player. When the player responds, the cloud creates the HTTP response and sends it back. For some commands, the cloud handles the request and response without sending it to a player.

Sonos sends the headers in the HTTP header, including the type of the response:

The type indicates the object type, such as households for a household ID, none for an empty response, or groupVolume for a groupVolume object. See Types for details and the households namespace for details about the household object type.

Error Responses and Status codes

Sonos sends the following error responses and status codes:

Successful play example

For example, send the following to start playback on a group called RINCON_00012345678001400:0:

POST /groups/RINCON_00012345678001400:0/playback:1/play HTTP/1.1
Host: api.ws.sonos.com/control/v1
Content-Type: application/json
Authorization: Bearer <token>
User-Agent: Apache-HttpClient/4.5.10 (Java/1.8.0_162)

This would send the following response:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: 
Content-Type: application/json
Server: Apache-Coyote/1.1
X-Sonos-Group-Id: RINCON_00012345678001400:0
X-Sonos-Household-Id: Sonos_1bdj48fbvjJDSkwO90djantsse948J.GNR-OWd0284lDeq325dk
X-Sonos-MAC: 0003dk59fj23
X-Sonos-Type: none
X-Sonos-User-Id: 2049233325
Content-Length: 2
Expires: Mon, 30 Jul 2018 20:28:32 GMT
Cache-Control: max-age=0, no-cache, no-store
Pragma: no-cache
Date: Mon, 30 Jul 2018 20:28:32 GMT
Connection: close

{}

Custom error example

When your app sends a command, the player checks the values sent with expected values. For example, the groupId sent by your integration must match an available groupId. If it doesn’t match, the player sends a GlobalError object with the ERROR_INVALID_OBJECT_ID errorCode. If any required parameters are missing, your app will receive a GlobalError object with an ERROR_MISSING_PARAMETERS errorCode.

If you sent a play command to a Sonos player that didn't have any content to play:

POST /api/v1/groups/RINCON_00012345678001400:0/playback/play HTTP/1.1
Host: api.ws.sonos.com/control/v1
Content-Type: application/json
Authorization: Bearer <token>

You would receive a playbackError with the ERROR_NO_CONTENT errorCode:

HTTP/1.1 499
Content-Type: application/json
X-Sonos-Type: playbackError
  
{
 "errorCode": "ERROR_NO_CONTENT"
}

See GlobalError for more details about these errors.