Bose SoundTouch Web API – TypeScript Client & Postman Collection

This repository contains a TypeScript client for the Bose SoundTouch Web API, plus a Postman collection and the original PDF documentation from Bose for reference. It is intended to make exploring and integrating with SoundTouch speakers easier for developers, tinkerers, and home‑automation enthusiasts.

Repository Structure

The repository is organized as follows:

bose-soundtouch-client
├── src
│   └── index.ts
├── dist
├── originalDocs
│   └── 2025.12.18-SoundTouch-Web-API.pdf
└── postman
    └── soundtouch-rest-api.json

• src/index.ts The TypeScript source for the SoundTouch client library.

• dist/ The compiled JavaScript and type declarations published to npm.

• originalDocs/2025.12.18-SoundTouch-Web-API.pdf
  The official Bose SoundTouch Web API PDF, preserved for offline reference. Version 1.0

• postman/soundtouch-rest-api.json
  A ready‑to‑import Postman collection that exposes the HTTP endpoints and basic workflows described in the PDF (info, volume, presets, zones, etc.).

Using the TypeScript Client

The npm package provides a typed client for the local SoundTouch Web API (HTTP on port 8090). It targets Node.js 18+ and uses the built‑in fetch API with XML parsing to match the official Bose documentation.

Installation

npm install bose-soundtouch-client

Quick Start

import { SoundTouchClient } from "bose-soundtouch-client";

const client = new SoundTouchClient({ host: "192.168.1.50" });

async function main() {
  const info = await client.getInfo();
  console.log(info);

  const volume = await client.getVolume();
  console.log(volume);

  await client.setVolume(25);
}

main().catch(console.error);

Supported Methods (Core Subset)

The client currently wraps a commonly used subset of the SoundTouch Web API:

|TS func|Method|API| |--|--|--| |getInfo()|GET|/info| |getNowPlaying()|GET|/now_playing| |getVolume()|GET|/volume| |setVolume(value: number)|POST|/volume| |sendKey(key: string, state?: "press" \| "release" \| "click")|POST|/key| |getPresets()|GET|/presets| |selectPreset(presetId: number)|POST|/select|

For full details on each endpoint, including XML schemas and additional URLs, refer to the official PDF in originalDocs/.

Using the Postman Collection

This repository also includes a Postman collection that mirrors the Bose SoundTouch Web API endpoints, based on the official PDF.

1. Import postman/soundtouch-rest-api.json into Postman (or a compatible client).
2. Create an environment with variables:
   • soundtouch_ip: IP address of your SoundTouch device (for example, 192.168.1.50).
   • soundtouch_port: HTTP port (default 8090 in official PDF).
3. Start with the /info and /capabilities requests to discover what your device supports.
4. Use the other folders (volume, sources, presets, zones) to control and inspect the device.

The collection is intentionally close to the original Bose examples so you can cross‑reference requests, payloads, and responses directly with the PDF.

About the Bose SoundTouch Web API

Bose’s SoundTouch platform exposes an HTTP‑based API on the local network, typically on port 8090, plus a WebSocket interface (usually on port 8080) for real‑time events and updates. The API uses XML request and response bodies and covers functionality such as device info, volume control, source selection, presets, and multi‑room zones, as documented in the official PDF.

The PDF in originalDocs/ is a direct copy of the official SoundTouch Web API documentation V 1.0 from here and should be treated as the authoritative reference. The TypeScript client and Postman collection here are convenient mappings of that spec into practical code and HTTP requests.

Supported Devices (Context)

The SoundTouch Web API targets Bose SoundTouch smart speakers and related products that expose the local SoundTouch protocol.

Examples of device families reported to work with the documented API include:

• SoundTouch 10 / 20 / 30 speakers
• SoundTouch wireless adapters and some home‑theater / soundbar products with SoundTouch support

Compatibility and supported features can vary slightly by firmware and model; consult the PDF and test endpoints via the Postman collection against your actual hardware.

Credits & Licensing Notes

All SoundTouch API design, naming, and original documentation are the intellectual property of Bose Corporation.
This repository simply packages that public documentation into a developer‑friendly TypeScript client, a Postman collection, and preserves the original PDF for convenience.

If you use this client or collection in your own tools or projects, please:

• Attribute Bose as the source of the API and original documentation.
• Respect Bose’s terms for the SoundTouch Web API and related materials, as described in the PDF.

Developer Tools

The npm package contains only the runtime library (dist/). Developer tools are available via GitHub:

Postman collection + Bose PDF:

• Download developer-tools-v0.1.0.zip from GitHub Releases
• Or clone this repo: git clone https://github.com/ritz-ras1245/bose-soundtouch-client.git

Files included:

• postman/soundtouch-rest-api.json
• originalDocs/2025.12.18-SoundTouch-Web-API.pdf (official Bose docs)

Runtime library only (npm):

npm install bose-soundtouch-client  # ~25 kB, just the client