Sonos API: control Sonos from code, a browser or AI

Sonos has an official cloud Control API for code, and a community route that talks to speakers directly on your home network. For a browser, Sonos has its own web app. For an AI assistant, you need something that exposes your speakers over MCP. Port OS offers that last piece, and a REST API that reaches the same speakers, once you link your Sonos account.

Port OS publishes this article, so read it with that interest in mind. It draws on Sonos's documentation, the project pages linked below and Port OS's own OpenAPI file. We did not benchmark any of these routes, and nothing here claims one is better than another. Vendor facts are as of November 2026.

The three ways to reach Sonos from code

The official Control API

Sonos documents the Control API for apps that control a customer's system from the cloud. Its authorize guide says you create a control integration in the Sonos integration manager at developer.sonos.com and generate a client credential key. You also register a public HTTPS redirect URL that users return to after they sign in.

After a user approves access, your code lists their households, then the groups and players in each household. Sonos documents one scope today, playback-control-all, which covers reading what is playing, changing playback and volume, and changing rooms and groups. Transport commands such as play and pause target groups. Calls carry a bearer token, and access tokens expire, so the integration refreshes them.

This is the right route if you ship an app to many Sonos owners and want the vendor's own interface, with every feature Sonos exposes.

Local libraries

If you want no cloud at all, community projects talk to speakers on your network. SoCo is a Python library, so it is the usual answer to "python sonos api". node-sonos-http-api runs a small server that turns HTTP requests into speaker commands, which suits "node sonos http api" searches.

These are unofficial and not maintained by Sonos. They work offline, need no account registration and respond from inside your house. The trade-offs are that your code must run on the same network as the speakers, and the local protocol is not a published Sonos API, so a Sonos update can break it. Check each project's repository for current status before you depend on it.

Is there a Sonos web app?

Yes. Sonos's web app at play.sonos.com lets you control your system from a browser after you sign in with your Sonos account. We could not read its marketing page automatically, and Sonos's help pages describe which services and features it supports, so check them for your setup. If you want a dashboard that also shows lights, locks and vacuums next to your speakers, the Port OS browser dashboard is another option.

Where Port OS fits

Port OS links your provider accounts and exposes the devices to AI assistants over MCP and to code over a REST API. For Sonos, the steps are short:

1. Choose Sonos on the connect page. Setup opens Sonos's authorization flow, where you review the access Sonos asks for. The Sonos integration page describes this as connecting through Port OS's cloud integration, and it does not ask you to register your own developer integration.
2. Check Your Devices for the discovered players and native groups.
3. Use the dashboard, call the REST API, or connect ChatGPT or Claude over MCP.

Supported controls, per the integration page: play, pause, halt, next and previous when the selected target exposes them, volume and mute, playback state and now-playing details, and native Sonos groups.

A REST example

Authentication, scopes and the idempotency rules match the smart home REST API article. Find your speakers with POST /endpoint-query:

curl -s https://api.portoperatingsystem.com/endpoint-query \
  -H "Authorization: Bearer $PORTOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": { "match": { "key": "type", "value": "SPEAKER" } },
    "paginationContext": { "maxResults": 10 }
  }'

Then pause one with POST /message-requests. The Idempotency-Key header is required, and the endpoint id below is a placeholder you copy from the query response:

PORTOS_REQUEST_KEY="$(uuidgen)"
curl -s https://api.portoperatingsystem.com/message-requests \
  -H "Authorization: Bearer $PORTOS_TOKEN" \
  -H "Idempotency-Key: $PORTOS_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": {
      "type": "ENDPOINT",
      "id": "port1/systems/home/endpoints/kitchen-speaker"
    },
    "message": {
      "header": {
        "namespace": "port1/systems/zero/capability-interfaces/media-player",
        "name": "pause",
        "version": "1.0"
      },
      "body": {}
    },
    "responseType": "SYNC"
  }'

Volume uses the speaker capability: the set-volume message takes a body of {"volume": 20}, a number from 0 to 100. Look at the target's returned capabilities before sending; a target only accepts what it declares. The full request and response schemas are in the HTTP reference.

An accepted request is not proof that you heard a change. Read fresh state if it matters. The media playback guide covers this.

Limits to know

• Alpha. Sonos support in Port OS is in public alpha, and availability can change. Contact us for pricing or compatibility commitments.
• Groups and players differ. A speaker that is grouped with others may need the native group as its target. Port OS does not silently ungroup speakers to make a command work.
• No Spotify link. Linking Sonos does not link Spotify or grant access to a music library. Port OS does not promise playback of arbitrary tracks or URLs.
• Cloud path. Requests go through Port OS's hosted service and Sonos's cloud, so the internet must be up. The local libraries have no such dependency.
• Smaller surface. Port OS exposes the controls listed above. If you need a Sonos feature outside them, use the official API.

Which should you pick?

Use the official Control API if you are building a product for Sonos owners. Use SoCo or node-sonos-http-api if you want local, offline control on your own network and accept that they are unofficial. Use the Sonos web app for plain listening from a browser. Use Port OS if you want AI assistants and scripts to reach your Sonos system next to other linked devices without registering a Sonos developer integration.

FAQ

Is there an official Sonos API? Yes. The Sonos Control API is documented at docs.sonos.com and uses OAuth with a developer integration.

Is there a Python Sonos API? SoCo is the best-known Python library. It is unofficial and controls speakers on your local network.

Is there a Node Sonos HTTP API? node-sonos-http-api is a community server that exposes speaker commands over local HTTP. It is unofficial.

Can I control Sonos from a web browser? Sonos's web app at play.sonos.com does this. Port OS's dashboard is another browser route for supported controls.

Can ChatGPT or Claude control my Sonos? After you link Sonos and connect your assistant, yes for the supported controls above, in alpha.

All posts