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:

For example:

Here’s more details about these path segments:

Path segment Description
base URL The API gateway to the Sonos cloud:
version The major version number of the Sonos API that your client supports.

The current major version number is v1.

target & target ID Where to route the command. See Target players and groups below for details.
namespace A 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 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 type Sample 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 Header Description
Authorization Send “Bearer {token}”. See Authorize for details.
Content-Type The type of content. This should be “application/json”.
Content-Length The 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 Header Description
Content-Type The type of content. This will be “application/json”.
X-Sonos-Type Message 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:

Code Description Details
200 OK Command succeeded.
400 Bad Request Syntax error in the command, missing or invalid parameters.
401 Unauthorized The client token or API key is invalid, or the client does not have sufficient permission to run the command.
403 Forbidden The current user does not have access to this resource or command.
404 Not found The ID refers to a resource which doesn’t exist and isn’t known to have existed. For example, an unknown namespace or command.
410 Gone The ID refers to a resource that doesn’t exist any more. For example, if a targeted group no longer exists in the household.
429 Too Many Requests The number of requests have hit the rate limit.
499 Custom Playback, 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.

500 Internal Server Error Some server component is not working correctly.

Successful play example

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

This would send the following response:

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:

You would receive a playbackError with the ERROR_NO_CONTENT errorCode:

See globalError for more details about these errors.