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:{householdId}/groups/createGroup

Here's more details about these path segments:

Path segmentDescription
base URLThe API gateway to the Sonos cloud:
versionThe major version number of the Sonos API that your client supports.

The current major version number is v1.
target & target IDWhere to route the command.
See Target players and groups below for details.
namespaceA set of related commands and events.

Subscribe to a namespace to receive event notifications of state changes, such as volume or group configuration.
command(Optional) the action that you'd like to take, such as play for group playback.

The command is optional. For example, to Get Volume, send a GET request to the groupVolume or playerVolume namespace.

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:

Target object typeSample path

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:

HTTP HeaderDescription
AuthorizationSend "Bearer {token}". See Authorize for details.
Content-TypeThe type of content. This should be "application/json".
Content-LengthThe number of characters in the content. When sending a POST or PUT request, if there is no request body, set the Content-Length header to 0.
User-Agent(Recommended) Information about the user agent originating the request. We suggest that you provide this as a best practice so that Sonos knows who is sending the request. If you don't provide a User-Agent, we may have to throttle large spikes. Here's an example: User-Agent: Apache-HttpClient/4.5.10 (Java/1.8.0_162)

See the User-agent section of the HTTP/1.1 RFC for details.

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:

HTTP HeaderDescription
Content-TypeThe type of content. This will be "application/json".
X-Sonos-TypeMessage 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:

200OKCommand succeeded.
400Bad RequestSyntax error in the command, missing or invalid parameters.
401UnauthorizedThe client token or API key is invalid, or the client does not have sufficient permission to run the command.
403ForbiddenThe current user does not have access to this resource or command.
404Not foundThe ID refers to a resource which doesn't exist and isn't known to have existed. For example, an unknown namespace or command.
410GoneThe ID refers to a resource that doesn't exist any more. For example, if a targeted group no longer exists in the household.
429Too Many RequestsThe number of requests have hit the rate limit.
499CustomPlayback, session, and other Control API errors. Sonos includes a globalError object in the body with the type of error.

Most of the the time, the error includes an errorCode and an optional reason property with a human readable message.
500Internal Server ErrorSome server component is not working correctly.

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
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
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
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.