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

'none'

Don’t use any authentication method

API Key

'api-key'

Use the API Key generated by the device to authenticate the API communication. Use it in the request header X-API-Key

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

X-API-Key: API_KEY
CODE

Request Body

NONE

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "version" : "string"
}
JSON

Description and examples of the response body:

key

values

description

version

"2.9.0"

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

X-API-Key: API_KEY 
Content-Type: application/json
CODE

Request Body

{
    "volume" : int
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

NONE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

INVALID_API_KEY

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

X-API-Key: API_KEY
CODE

Request Body

NONE

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "volume" : int
}
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

X-API-Key: API_KEY 
Content-Type: application/json
CODE

Request Body

{
    "mute" : bool
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

NONE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

INVALID_API_KEY

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

X-API-Key: API_KEY
CODE

Request Body

NONE

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "enabled" : bool,
    "volume" : int
}
JSON

Description and examples of the response body:

key

values

description

enabled

true or false

SonicIP enable/disable status

volume

0 to 100

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

X-API-Key: API_KEY 
Content-Type: application/json
CODE

Request Body

{
    "enabled" : bool,
    "volume": int
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

NONE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

INVALID_API_KEY

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

X-API-Key: API_KEY
CODE

Request Body

NONE

Response Status

200, 400, 401, 404, 500

Response Headers

NONE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

FAIL_CURR_SW_INST

Failed to reset to defaults because new firmware is currently being installing

INVALID_API_KEY

Required API Key is invalid or missing

Reboot device

This command causes the device to reboot.

Method

PUT

Path

/api/v1/reboot

Request Headers

X-API-Key: API_KEY
CODE

Request Body

NONE

Response Status

200, 400, 401, 404, 500

Response Headers

NONE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

FAIL_CURR_SW_INST

Failed to reboot device because new firmware is currently being installing

INVALID_API_KEY

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

X-API-Key: API_KEY
CODE

Request Body

NONE

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
  "deviceInfo": {
    "hardwareType": "string",
    "ipamType": "string",
    "mac": "string",
    "linuxKernelVersion": "string",
    "bootloaderVersion": "string"
  },
  "network": {
    "connection": "string",
    "status": "string",
    "dhcp": bool,
    "ipaddress": "string",
    "netmask": "string",
    "defaultGateway": "string",
    "dns": {
      "type": "string",
      "primaryDNS": "string",
      "secondaryDNS": "string"
    }
  },
  "system": {
    "time": "string",
    "uptime": "string"
  },
  "licenses": [
    {
      "name": "string",
      "status": "string",
      "issueDate": "string",
      "expireDate": "string",
      "id": "string",
      "features": [],
      "signature": "string"
    }
  ]
}
JSON

Description and examples of the response body:

key

values

description

hardwareType

"IPAM400-FLEXA-Package ..."

Device hardware type

ipamType

"IPAM400 (ID 8)"

IPAM type

mac

"00:08:E1:08:54:3B"

MAC Address

linuxKernelVersion

"Linux version 5.5.8-yocto ..."

Linux Kernel version

bootloaderVersion

"U-Boot 2017.03 ..."

Bootloader version

connection

"wired"

Network connection: wired or wireless

status

"up"

Network status: up or down

dhcp

true

DHCP enable (true) or disabled (false)

ipaddress

"192.168.1.88"

IP address

netmask

"255.255.255.0"

Netmask

defaultGateway

"192.168.1.254"

Default gateway

type

"Auto"

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

"Fri Feb 4 15:40:01 UTC 2022"

System current time

uptime

"0 days, 5 hours, 53 minutes, 7 seconds"

Uptime

name

"core-image-barix-ipspeaker"

License name

status

"active"

License status

issueDate

"24/8/2020"

License issue date

expireDate

"24/8/2050"

License expire date

id

"4499"

License id

features

"InformaCast"

License features

signature

"Valid"

License signature

Network settings

Retrieve network configuration.

GET network

Method

GET

Path

/api/v1/network

Request Headers

X-API-Key: API_KEY
CODE

Request Body

NONE

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
  "avahiAnnounce": bool,
  "sonicIP": bool,
  "sonicIpVolume": int,
  "webProtocol": "string",
  "dhcp": bool,
  "dhcpHostName": "string",
  "ipaddress": "string",
  "netmask": "string",
  "gateway": "string",
  "dns": {
    "type": "string",
    "primaryDNS": "string",
    "secondaryDNS": "string"
  }
}
JSON

Description and examples of the response body:

key

values

description

avahiAnnounce

true

Avahi announce enabled: true or false

sonicIP

true

SonicIP enabled: true or false

sonicIpVolume

70

SonicIP volume between 0 and 100 ( % )

webProtocol

"http"

Protocol used by the internal web server to connect with clients: http or https

dhcp

true

DHCP enable (true) or disabled (false)

ipaddress

"192.168.1.88"

IP address

netmask

"255.255.255.0"

Netmask

defaultGateway

"192.168.1.254"

Default gateway

type

"Auto"

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

X-API-Key: API_KEY
CODE

Request Body

NONE

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
  "sources": {
      "source1": {
        "enabled": true,
        "priority": 1,
        "type": "syn-apps",
        "name": "Synapps",
        "volume": 90,
        "config": "{\"server\":\"\"}"
      },
      "source2": {
        "enabled": false,
        "priority": 5,
        "type": "barix_radio",
        "name": "(not configured)",
        "volume": 90,
        "config": "{}"
      },
      "source3": {
        "enabled": false,
        "priority": 5,
        "type": "barix_radio",
        "name": "(not configured)",
        "volume": 90,
        "config": "{}"
      },
      "source4": {
        "enabled": false,
        "priority": 5,
        "type": "barix_radio",
        "name": "(not configured)",
        "volume": 90,
        "config": "{}"
      },
      "source5": {
        "enabled": false,
        "priority": 5,
        "type": "barix_radio",
        "name": "(not configured)",
        "volume": 90,
        "config": "{}"
      }
    }
}
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

X-API-Key: API_KEY 
Content-Type: multipart/form-data
CODE

Request Body

Content-Disposition: form-data; name="file"; filename="filename.ext"
HTML

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

INVALID_API_KEY

Required API Key is invalid or missing

B - Send sources’s configuration as request data

Method

PUT

Path

/api/v1/file/sources

Request Headers

X-API-Key: API_KEY 
Content-Type: application/json
CODE

Request Body

{
    "sources": {
        "source1": {
            "name": "Synapps",
            "type": "syn-apps",
            "config": {
                "server": ""
            },
            "volume": 90,
            "prio": 1,
            "enabled": true
        },
        "source2": {},
        "source3": {},
        "source4": {},
        "source5": {}
    }
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

INVALID_API_KEY

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

X-API-Key: API_KEY 
Content-Type: application/json
CODE

Request Body

{
    "id" : int,
    "enable" : bool
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

NOT_CONFIGURED

Source is not configured

INVALID_API_KEY

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

X-API-Key: API_KEY 
Content-Type: application/json
NONE

Request Body

{
    "id" : int,
    "volume" : int
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

NOT_CONFIGURED

Source is not configured

INVALID_API_KEY

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

X-API-Key: API_KEY 
Content-Type: application/json
NONE

Request Body

{
    "id" : int,
    "vol_announcement" : int,
    "vol_playlist": int
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

NOT_CONFIGURED

Source is not configured

INVALID_API_KEY

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

X-API-Key: API_KEY
CODE

Request Body

NONE

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
  "status": [
    {
      "state": "monitoring",
      "media": "not available",
      "counter": 0,
      "priority": 0,
      "type": "local_file"
    },
    {
      "state": "monitoring",
      "media": "not available",
      "counter": 0,
      "playing": "nothing",
      "registered": "unregistered",
      "priority": 1,
      "type": "syn-apps"
    }
  ],
  "timestamp": 1641484800.0245087
}
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

X-API-Key: API_KEY
CODE

Request Body

NONE

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
  "audio-files": [
    {
      "name": "Moo.mp3",
      "size": 65664
    }
  ]
}
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

X-API-Key: API_KEY 
Content-Type: multipart/form-data
CODE

Request Body

Content-Disposition: form-data; name="file"; filename="filename.ext"
HTML

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

INVALID_API_KEY

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

X-API-Key: API_KEY 
Content-Type: application/json
CODE

Request Body

{    
    "filename" : "string"
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

FILE_NOT_FOUND

INVALID_API_KEY

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

X-API-Key: API_KEY 
Content-Type: application/json
CODE

Request Body

{
    "id" : int,    
    "filename" : "string"
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

NOT_CONFIGURED

Source is not configured as a local file audio source

FILE_NOT_FOUND

ALREADY_PLAYING

Source id is still playing an audio file

INVALID_API_KEY

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

X-API-Key: API_KEY
Content-Type: application/json
CODE

Request Body

{
    "id" : int  
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

NOT_CONFIGURED

Source is not configured as a local file audio source

INVALID_API_KEY

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

X-API-Key: API_KEY
Content-Type: application/json
CODE

Request Body

{
    "id" : int  
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
  "status": "string",
  "name": "string"
}
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

X-API-Key: API_KEY
Content-Type: application/json
CODE

Request Body

{
    "id" : int, 
    "loop" : bool
}
JSON

Response Status

200, 400, 401, 404, 500

Response Headers

content-type: application/json
CODE

Response Body

{
    "result" : "string"
}
JSON

Description and examples of the response body:

key

values

description

result

OK

Success

INVALID_PARAMETERS

Invalid or missing parameters

NOT_CONFIGURED

Source is not configured as a local file audio source

INVALID_API_KEY

Required API Key is invalid or missing