IP Audio Client API
Scope
This document is intended for users of IP Audio Client devices (Exstreamer M400, Exstreamer MPA400 and IP Former) who wants to interact with the devices via means of an API, thus enabling controls and monitoring functionality from a third party application.
In order to access the API the devices must run at least IP Audio Client firmware V2.9
Transport and format
The API is available over HTTP on port 80 or HTTPS on port 443
The message format used is JSON
Authentication
The API is always available after boot.
The authentication methods supported are:
Mechanism | Value | Description |
---|---|---|
None |
| Don’t use any authentication method |
API Key |
| Use the API Key generated by the device to authenticate the API communication. Use it in the request header |
By default, the chosen method is API Key, and the device uses a default random API Key. The user can generate a new API Key in the Settings page of the web interface.

API Methods
In the below paragraphs are the detailed descriptions of all the methods exposed in the API. Use this table for a quick lookup:
Image Version
GET Version
Get device image’s version.
Method | GET |
---|---|
Path | /api/v1/version |
Request Headers |
CODE
|
Request Body | NONE |
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
version |
| Image Version |
Master Volume Control
Set, get current volume and mute.
SET Volume
Set Master volume of the device. The volume value must be an integer between 0 and 100.
Method | PUT |
---|---|
Path | /api/v1/volume |
Request Headers |
CODE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers | NONE |
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Required API Key is invalid or missing |
GET Volume
Get volume of the device. The volume value must be an integer between 0 and 100.
Method | GET |
---|---|
Path | /api/v1/volume |
Request Headers |
CODE
|
Request Body | NONE |
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Mute
This command causes the device to mute if the value is true or unmute if value is false.
Method | PUT |
---|---|
Path | /api/v1/mute |
Request Headers |
CODE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers | NONE |
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Required API Key is invalid or missing |
SonicIP Control
Getting SonicIP configuration, enable/disable it or set its volume.
GET SonicIP configuration
Method | GET |
---|---|
Path | /api/v1/sonicip |
Request Headers |
CODE
|
Request Body | NONE |
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
enabled |
| SonicIP enable/disable status |
volume |
| SonicIP volume level in % |
Enable/Disable sonicIP and/or set sonicIP volume
The volume value must be an integer between 0 and 100.
Method | PUT |
---|---|
Path | /api/v1/sonicip |
Request Headers |
CODE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers | NONE |
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Required API Key is invalid or missing |
Reset to factory defaults
This command causes the device to reset to defaults.
Method | PUT |
---|---|
Path | /api/v1/reset |
Request Headers |
CODE
|
Request Body | NONE |
Response Status | 200, 400, 401, 404, 500 |
Response Headers | NONE |
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Failed to reset to defaults because new firmware is currently being installing | |
| Required API Key is invalid or missing |
Reboot device
This command causes the device to reboot.
Method | PUT |
---|---|
Path | /api/v1/reboot |
Request Headers |
CODE
|
Request Body | NONE |
Response Status | 200, 400, 401, 404, 500 |
Response Headers | NONE |
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Failed to reboot device because new firmware is currently being installing | |
| Required API Key is invalid or missing |
System Status
Retrieve complete system status page of the device.
GET System Status
Method | GET |
---|---|
Path | /api/v1/status |
Request Headers |
CODE
|
Request Body | NONE |
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
hardwareType |
| Device hardware type |
ipamType |
| IPAM type |
mac |
| MAC Address |
linuxKernelVersion |
| Linux Kernel version |
bootloaderVersion |
| Bootloader version |
connection |
| Network connection: wired or wireless |
status |
| Network status: up or down |
dhcp |
| DHCP enable (true) or disabled (false) |
ipaddress |
| IP address |
netmask |
| Netmask |
defaultGateway |
| Default gateway |
type |
| DNS type: Auto or Manual |
primaryDNS | DNS primary IP Address (only if DNS type is Auto | |
secondaryDNS | DNS secundary IP Address (only if DNS type is Auto | |
time |
| System current time |
uptime |
| Uptime |
name |
| License name |
status |
| License status |
issueDate |
| License issue date |
expireDate |
| License expire date |
id |
| License id |
features |
| License features |
signature |
| License signature |
Network settings
Retrieve network configuration.
GET network
Method | GET |
---|---|
Path | /api/v1/network |
Request Headers |
CODE
|
Request Body | NONE |
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
avahiAnnounce |
| Avahi announce enabled: true or false |
sonicIP |
| SonicIP enabled: true or false |
sonicIpVolume |
| SonicIP volume between 0 and 100 ( % ) |
webProtocol |
| Protocol used by the internal web server to connect with clients: http or https |
dhcp |
| DHCP enable (true) or disabled (false) |
ipaddress |
| IP address |
netmask |
| Netmask |
defaultGateway |
| Default gateway |
type |
| DNS type: Auto or Manual |
primaryDNS | DNS primary IP Address (only if DNS type is Auto | |
secondaryDNS | DNS secundary IP Address (only if DNS type is Auto |
Audio Sources
GET sources
Retrieve sources configuration.
Method | GET |
---|---|
Path | /api/v1/sources |
Request Headers |
CODE
|
Request Body | NONE |
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Configure all sources
The api supports two ways of setting audio sources’s configuration:
A - Upload a json file containing sources’s configuration
Method | PUT |
---|---|
Path | /api/v1/file/sources |
Request Headers |
CODE
|
Request Body |
HTML
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Required API Key is invalid or missing |
B - Send sources’s configuration as request data
Method | PUT |
---|---|
Path | /api/v1/file/sources |
Request Headers |
CODE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Required API Key is invalid or missing |
SET source enable/disable
Enable or disable an audio source. The id is an integer value between 1 and 5.
Note: IPAC application will be restarted if the value being set is different from the current configured value.
Method | PUT |
---|---|
Path | /api/v1/source/enable |
Request Headers |
CODE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Source is not configured | |
| Required API Key is invalid or missing |
SET source volume (excluding “scheduler”)
Set volume for a specific audio source. The id is an integer value between 1 and 5. The volume is an integer between 0 to 100.
Note: IPAC application will be restarted if the value being set is different from the current configured value.
Method | PUT |
---|---|
Path | /api/v1/source/volume |
Request Headers |
NONE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Source is not configured | |
| Required API Key is invalid or missing |
SET Source Volume (Scheduler)
Volume parameters must be an integer between 0 to 100.
Method | PUT |
---|---|
Path | /api/v1/source/volume |
Request Headers |
NONE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Source is not configured | |
| Required API Key is invalid or missin |
GET speaker source status
Retrieve the current status for all audio sources.
Method | GET |
---|---|
Path | /api/v1/sources/status |
Request Headers |
CODE
|
Request Body | NONE |
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Audio Files
GET all files
Get a list with the names of all the audio files stored on the device.
Method | GET |
---|---|
Path | /api/v1/audio-files |
Request Headers |
CODE
|
Request Body | NONE |
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Upload an Audio File
This command will be used to upload an audio file to IPAC device.
Supported audio file extensions: "mp3", "aac", "flac", "ac3", "dts", "wav", "ogg", "m4a", "zip"
Method | POST |
---|---|
Path | /api/v1/file/upload |
Request Headers |
CODE
|
Request Body |
HTML
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Required API Key is invalid or missing |
Delete an audio file
This command will be used to delete an audio file that is stored on IPAC device.
Method | DELETE |
---|---|
Path | /api/v1/file/delete |
Request Headers |
CODE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| ||
| Required API Key is invalid or missing |
Trigger to play an audio file
This command will try to play a specific audio file by specifying the correct LocalFileAudio source id. The id is an integer value between 1 and 5.
Method | PUT |
---|---|
Path | /api/v1/file/play |
Request Headers |
CODE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Source is not configured as a local file audio source | |
| ||
| Source id is still playing an audio file | |
| Required API Key is invalid or missing |
Trigger to stop playing an audio file
This command will order a specific Local File audio source id to stop playing an audio file. The id is an integer value between 1 and 5.
Method | PUT |
---|---|
Path | /api/v1/file/stop |
Request Headers |
CODE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Source is not configured as a local file audio source | |
| Required API Key is invalid or missing |
GET status of audio file playing
By specifying Local File Audio source id (integer value between 1 and 5) you’ll get the information regarding:
audio file name currently playing;
the status:
playing
stopped
Method | GET |
---|---|
Path | /api/v1/file/status |
Request Headers |
CODE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Enable/disable loop playback of a local file.
This will enable/disable the loop mode for a LocalAudioSource source id. The id is an integer value between 1 and 5.
Note: IPAC application will be restarted if the value being set is different from the current configured value.
Method | PUT |
---|---|
Path | /api/v1/file/loop |
Request Headers |
CODE
|
Request Body |
JSON
|
Response Status | 200, 400, 401, 404, 500 |
Response Headers |
CODE
|
Response Body |
JSON
|
Description and examples of the response body:
key | values | description |
---|---|---|
result |
| Success |
| Invalid or missing parameters | |
| Source is not configured as a local file audio source | |
| Required API Key is invalid or missing |