Bose-SoundTouch/docs/API-Endpoints-Overview.md

Bose SoundTouch Web API - Endpoints Overview

This document provides a comprehensive overview of the available API endpoints verified against the official Bose SoundTouch Web API v1.0 specification (January 7, 2026).

Implementation Status Legend

• ✅ Implemented - Fully implemented with tests and real device validation
• 🔍 Extra - Implemented but not in official API v1.0 (may be newer version or undocumented)
• ⚠️ Different - Implemented with different approach than official API
• ℹ️ N/A - Documented but officially unsupported or non-functional on real hardware

API Basics

• Protocol: HTTP REST-like
• Data Format: XML Request/Response
• Standard Port: 8090
• Base URL: http://<device-ip>:8090/
• Authentication: No complex authentication required
• Real-time Updates: WebSocket connection available

Device Information

GET /info ✅ Implemented

Retrieves basic device information.

Response XML Structure:

<info deviceID="..." type="..." name="..." ...>
  <name>Device Name</name>
  <type>Device Type</type>
  <margeAccountUUID>UUID</margeAccountUUID>
  <components>...</components>
</info>

Playback Control

GET /now_playing ✅ Implemented

Retrieves information about the currently playing music.

Response XML Structure:

<nowPlaying deviceID="..." source="...">
  <ContentItem source="..." type="..." location="..." sourceAccount="...">
    <itemName>Track Name</itemName>
    <containerArt>Album Art URL</containerArt>
  </ContentItem>
  <track>Track Name</track>
  <artist>Artist Name</artist>
  <album>Album Name</album>
  <stationName>Station Name</stationName>
  <art artImageStatus="...">Art URL</art>
  <playStatus>PLAY_STATE</playStatus>
  <shuffleSetting>...</shuffleSetting>
  <repeatSetting>...</repeatSetting>
</nowPlaying>

POST /key ✅ Implemented

Sends key commands to the device.

Important: Proper key simulation requires sending both press and release states:

Request XML (Press + Release):

<key state="press" sender="Gabbo">KEY_NAME</key>
<key state="release" sender="Gabbo">KEY_NAME</key>

Available Keys:

Playback Controls:

• PLAY - Start playback
• PAUSE - Pause current playback
• STOP - Stop current playback
• PREV_TRACK - Go to previous track
• NEXT_TRACK - Go to next track

Rating and Bookmark Controls:

• THUMBS_UP - Rate current content positively (Pandora, etc.)
• THUMBS_DOWN - Rate current content negatively
• BOOKMARK - Bookmark current content

Power and System Controls:

• POWER - Toggle device power state
• MUTE - Toggle mute state

Volume Controls:

• VOLUME_UP - Increase volume
• VOLUME_DOWN - Decrease volume

Preset Controls:

• PRESET_1 to PRESET_6 - Select preset 1-6

Input Controls:

• AUX_INPUT - Switch to auxiliary input

Shuffle Controls:

• SHUFFLE_OFF - Turn shuffle mode off
• SHUFFLE_ON - Turn shuffle mode on

Repeat Controls:

• REPEAT_OFF - Turn repeat mode off
• REPEAT_ONE - Repeat current track
• REPEAT_ALL - Repeat all tracks in playlist

Volume Control

GET /volume ✅ Implemented

Retrieves the current volume.

Response XML:

<volume deviceID="...">
  <targetvolume>50</targetvolume>
  <actualvolume>50</actualvolume>
  <muteenabled>false</muteenabled>
</volume>

POST /volume ✅ Implemented

Sets the volume.

Request XML:

<volume>50</volume>

Bass Settings

GET /bass ✅ Implemented

Retrieves the current bass settings.

Response XML:

<bass deviceID="...">
  <targetbass>0</targetbass>
  <actualbass>0</actualbass>
</bass>

POST /bass ✅ Implemented

Sets the bass settings (-9 to +9).

Request XML:

<bass>0</bass>

Source Management

GET /sources ✅ Implemented

Retrieves the available audio sources.

Response XML:

<sources deviceID="...">
  <sourceItem source="SPOTIFY" sourceAccount="..." status="READY" multiroomallowed="true">
    <itemName>Spotify</itemName>
  </sourceItem>
  <sourceItem source="BLUETOOTH" status="READY" multiroomallowed="false">
    <itemName>Bluetooth</itemName>
  </sourceItem>
  <!-- Additional sources -->
</sources>

Typical Sources:

• SPOTIFY
• AMAZON
• PANDORA
• IHEARTRADIO
• TUNEIN
• BLUETOOTH
• AUX
• STORED_MUSIC

POST /select ✅ Implemented

Selects an audio source.

Request XML:

<ContentItem source="SPOTIFY" sourceAccount="...">
  <itemName>Spotify</itemName>
</ContentItem>

Preset Management

GET /presets ✅ Implemented

Retrieves the configured presets.

Response XML:

<presets deviceID="...">
  <preset id="1" createdOn="..." updatedOn="...">
    <ContentItem source="..." sourceAccount="..." location="...">
      <itemName>Preset Name</itemName>
      <containerArt>Art URL</containerArt>
    </ContentItem>
  </preset>
  <!-- Additional presets -->
</presets>

POST /presets ℹ️ N/A

Creates or updates a preset.

Status: According to the official Bose SoundTouch API documentation, POST operations on /presets are marked as "N/A" - this endpoint officially does not support preset creation or modification via any API client.

Alternative Methods:

• Use the official Bose SoundTouch mobile app
• Use physical preset buttons on the device (long-press while content is playing)
• Changes made via these methods will be visible through the GET endpoint

Advanced Features

GET /getZone ✅ Implemented

Retrieves multiroom zone information.

POST /setZone ✅ Implemented

Configures multiroom zones.

GET /balance ✅ Implemented

Retrieves balance settings (stereo devices).

POST /balance ✅ Implemented

Sets balance settings.

GET /clockTime ✅ Implemented

Retrieves the device time.

POST /clockTime ✅ Implemented

Sets the device time.

GET /clockDisplay ✅ Implemented

Retrieves clock display settings.

POST /clockDisplay ✅ Implemented

Configures the clock display.

WebSocket Connection

WebSocket / ✅ Implemented

Establishes a persistent connection for live updates.

Event Types:

• nowPlayingUpdated
• volumeUpdated
• connectionStateUpdated
• presetUpdated

Network and System

GET /networkInfo ✅ Implemented

Retrieves network information.

GET /capabilities ✅ Implemented

Retrieves device capabilities.

GET /name 🔍 Extra

Retrieves the device name.

Note: Official API only documents POST /name for setting device name. Our GET implementation appears to be an undocumented extension.

POST /name ✅ Implemented

Sets the device name via SetName() method.

Official Request Format:

<name>$STRING</name>

GET /bassCapabilities ✅ Implemented

Checks if bass customization is supported on the device.

Official Response Format:

<bassCapabilities deviceID="$MACADDR">
    <bassAvailable>$BOOL</bassAvailable>
    <bassMin>$INT</bassMin>
    <bassMax>$INT</bassMax>
    <bassDefault>$INT</bassDefault>
</bassCapabilities>

GET /trackInfo ✅ Implemented

Gets track information (duplicate of /now_playing per official API).

Status: Fully implemented but times out on SoundTouch 10 & 20 test devices (AllegroWebserver timeout). May work on other SoundTouch models or firmware versions. Use /now_playing endpoint as reliable alternative.

Implementation: Available via GetTrackInfo() method. Consider using GetNowPlaying() method for guaranteed compatibility.

Zone Slave Management ✅ Implemented

Both official low-level endpoints and high-level zone management are available:

POST /addZoneSlave ✅ Implemented

Add individual device to existing zone using official API format.

Implementation: Available via AddZoneSlave() and AddZoneSlaveByDeviceID() methods

POST /removeZoneSlave ✅ Implemented

Remove individual device from existing zone using official API format.

Implementation: Available via RemoveZoneSlave() and RemoveZoneSlaveByDeviceID() methods

High-Level Zone API ✅ Enhanced

• Enhanced: CreateZone(), AddToZone(), RemoveFromZone() methods via /setZone
• Status: Provides both official low-level API and enhanced high-level operations

Advanced Audio Controls ✅ Conditionally Available

Professional/high-end device features (only available on devices that list these capabilities):

/audiodspcontrols - GET/POST ✅ Implemented

Access DSP settings including audio modes and video sync delay.

Availability: Only available if audiodspcontrols is listed in the reply to GET /capabilities

Implementation: Available via GetAudioDSPControls(), SetAudioDSPControls(), SetAudioMode(), SetVideoSyncAudioDelay() methods with automatic capability checking

/audioproducttonecontrols - GET/POST ✅ Implemented

Advanced bass and treble controls (beyond basic /bass endpoint).

Availability: Only available if audioproducttonecontrols is listed in the reply to GET /capabilities

Implementation: Available via GetAudioProductToneControls(), SetAudioProductToneControls(), SetAdvancedBass(), SetAdvancedTreble() methods with automatic capability checking

/audioproductlevelcontrols - GET/POST ✅ Implemented

Speaker level controls for front-center and rear-surround speakers.

Availability: Only available if audioproductlevelcontrols is listed in the reply to GET /capabilities

Implementation: Available via GetAudioProductLevelControls(), SetAudioProductLevelControls(), SetFrontCenterSpeakerLevel(), SetRearSurroundSpeakersLevel() methods with automatic capability checking

Clock and Network Endpoints 🔍 Extra

These endpoints work with real hardware but are NOT in official API v1.0:

• GET/POST /clockTime ✅ Implemented - Device time management
• GET/POST /clockDisplay ✅ Implemented - Clock display settings
• GET /networkInfo ✅ Implemented - Network information

Balance Control 🔍 Extra

• GET/POST /balance ✅ Implemented - Stereo balance adjustment

Note: Not documented in official API v1.0 but works with real devices.

Coverage Summary

Official API Coverage: 100%

• Total Official Endpoints: 19
• Implemented: 19 (100%)
• Conditionally Available: 3 (16%) - Advanced audio endpoints require device support
• Device-Dependent: 1 (5%) - GET /trackInfo times out on some models
• Excluded: 1 endpoint (POST /presets officially N/A)

Feature Coverage: 100%

• ✅ All available user functionality implemented
• ✅ All functional device operations supported
• ✅ Complete WebSocket event system
• ✅ Full multiroom capabilities
• ✅ Complete advanced audio controls (where supported by device)
• 🔍 Additional features beyond official specification

Error Handling

The API uses standard HTTP status codes:

• 200 OK - Successful request
• 400 Bad Request - Invalid request
• 404 Not Found - Endpoint or resource not found
• 500 Internal Server Error - Internal device error

Example Implementation

// Example for a GET request
func GetNowPlaying(deviceIP string) (*NowPlaying, error) {
    url := fmt.Sprintf("http://%s:8090/now_playing", deviceIP)
    resp, err := http.Get(url)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var nowPlaying NowPlaying
    err = xml.NewDecoder(resp.Body).Decode(&nowPlaying)
    return &nowPlaying, err
}

// Example for a POST request
func SendKey(deviceIP string, key string) error {
    url := fmt.Sprintf("http://%s:8090/key", deviceIP)
    xmlData := fmt.Sprintf(`<key state="press" sender="GoClient">%s</key>`, key)
    
    resp, err := http.Post(url, "application/xml", strings.NewReader(xmlData))
    if err != nil {
        return err
    }
    resp.Body.Close()
    return nil
}

Notes

1. XML Namespace: Most responses use no explicit XML namespace
2. Encoding: UTF-8 is used for all XML documents
3. Timeouts: Recommended timeout for HTTP requests: 10 seconds
4. Rate Limiting: No explicit limits documented, but moderate usage recommended
5. Device Discovery: Devices can be found via UPnP on the local network

Reference

Based on the official Bose SoundTouch Web API documentation: https://assets.bosecreative.com/m/496577402d128874/original/SoundTouch-Web-API.pdf