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

By default, the IPAC device always listens at incoming requests after boot. The API server can be disabled from the web interface at any time.

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 random API Key. The user can generate a new API Key in the Settings page of the web interface. When generating a new API Key the previous one becomes invalid.

API Methods

In the below chapters are the detailed descriptions of all the methods exposed in the API.

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 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

Get 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. All settings are defaulted except the network configuration.

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 (IPAM stands for IP Audio Module and is the core of every Barix IPAC device)
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
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	`"192.168.1.254"`	DNS primary IP Address (only if DNS type is Auto
secondaryDNS	`"192.168.1.254"`	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 only the 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 (multicast-dns service for auto-discovery)
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	`"192.168.1.254"`	DNS primary IP Address (only if DNS type is Auto
secondaryDNS	`"192.168.1.254"`	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: by uploading a JSON file containing the configuration or by passing directly the JSON configuration in the body of the request.

Changing the source configuration causes a reload the settings of the application, if the device is playing the moment the request is sent its output will be shortly silenced.

A - Upload a json file containing sources’s configuration

Method	PUT
Path	/api/v1/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/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

Specific source configuration examples

Barix Radio

Request Body

{
  "sources": {
    "source1": {
      "name": "Barix Radio Test",
      "type": "barix_radio",
      "config": { 
            "equalizer": {
                "enable": false,
                "config": [
                {
                    "name": "LOW",
                    "f": "80",
                    "t": "q",
                    "w": "1",
                    "g": "0"
                },
                {
                    "name": "LOW-MID",
                    "f": "500",
                    "t": "q",
                    "w": "1",
                    "g": "0"
                },
                {
                    "name": "HI-MID",
                    "f": "2000",
                    "t": "q",
                    "w": "1",
                    "g": "0"
                },
                {
                    "name": "HI",
                    "f": "4000",
                    "t": "q",
                    "w": "1",
                    "g": "0"
                }
            ]
            }
        },
      "volume": 90,
      "prio": 5,
      "enabled": true
    }
  }
}

JSON

Note: The equalizer setting is not mandatory. The default equalizer setting will be used if equalizer parameter is missing. Please check #equalizer-source-configuration

InformaCast

Request Body

{
  "sources": {
    "source1": {
      "name": "Informacast",
      "type": "informacast",
      "config": { 
            "url":"http://192.168.2.1:8081",
            "idleaudio":"rtp://@:10000",
            "idleaudio_format":"PCM_44KHZ"
        },
      "volume": 90,
      "prio": 5,
      "enabled": true
    }
  }
}

CODE

Specific parameters:

Parameter	Values	Description
`url`	`"http://<ICast_server_IP>:8081/InformaCast/admin"`	InformaCast server url
`url`	`""`	automatic InformaCast server discovery
`idleaudio` (optional)	`"rtp://<Stream_IP>:[port]"`	Idle audio url
`idleaudio_format` (optional)	`PCM_44KHZ`	Idle audio format
`idleaudio_format` (optional)	`ULAW_8KHZ`	Idle audio format

No Equalizer configuration allowed for InformaCast - SynApps and SIP sources.

Syn-apps

Request Body	`{ "sources": { "source1": { "name": "Synapps", "type": "syn-apps", "config": { "server": "" }, "volume": 90, "prio": 1, "enabled": true } } }` CODE

Specific parameters:

Parameter	Values	Description
`server`	`"xxx.xxx.xxx.xxx"`	Syn-apps server’s IP address
`server`	`""`	automatic Syn-apps server discovery

No Equalizer configuration allowed for InformaCast - SynApps and SIP sources.

SIP

Request Body

{
  "sources": {
    "source1": {
      "name": "SIP Test",
      "type": "sip",
      "config": { 
            "sip_mode":"server",
            "snd_play_latency":100,
            "call_timeout":30,
            "stream_timeout":10,
            "domain":"192.168.20.127",
            "user_name":"6004",
            "passwd":"10",
            "transport_and_encryption":"tls_srtp",
            "reg_timeout":30,
            "reg_retry_interval":10
        },
      "volume": 90,
      "prio": 5,
      "enabled": true
    }
  }
}

CODE

Specific parameters:

Parameter	Values	Description
`sip_mode`	`"peer_to_peer"`	Peer-to-peer SIP mode
	`"server"`	Server Sip mode
	`"server_and_peer_to_peer"`	Server and Peer-to-peer mode
`snd_play_latency`	`100`	Playback buffer in milliseconds
`call_timeout`	`30`	Maximum duration of an established call, in seconds. Set 0 to disable
`stream_timeout`	`10`	Timeout that the SIP client should wait to close the current call in the case it does not detect audio from the remote side. Set 0 to disable
`domain`	`"192.168.20.127"`	Server Domain name or IP address.
`user_name`	`"6004"`	SIP account user name.
`passwd`	`"10"`	SIP account user password.
`transport_and_encryption`	`"udp"`	UDP Transport with no security (port 5060)
	`"tls"`	SIP Secure with TLS transport (port 5061)
	`"tls_srtp"`	SIP Secure (port 5061) and Media Encryption
`reg_timeout`	`30`	Registration Timeout: interval for registration, in seconds. Range: 5 to 300 seconds.
`reg_retry_interval`	`30`	Registration Retry Interval: interval of auto registration retry upon registration failure,in seconds. Set to 0 to disable auto re-registration.

Note: Parameters in blue rows are only mandatory for “server” and “server_and_peer_to_peer” SIP modes.

No Equalizer configuration allowed for InformaCast - SynApps and SIP sources.

HTTP

Request Body	`{ "sources": { "source1": { "name": "HTTP", "type": "http", "config": { "url":"http://m1.mixhits.com:8002" }, "volume": 90, "prio": 5, "enabled": true } } }` CODE

Specific parameters:

Parameter	Values	Description
`url`	`"http://m1.mixhits.com:8002"`	URL of HTTP/S stream

Note: The equalizer setting is not mandatory. The default equalizer setting will be used if equalizer parameter is missing. Please check #equalizer-source-configuration

RTP

Request Body

{
  "sources": {
    "source1": {
      "name": "RTP Test",
      "type": "rtp",
      "config": { 
            "url":"rtp://239.0.0.1:9000?format=mulaw&channels=1&rate=8000&pt=97",
            "playback_mode": "regular"
        },
      "volume": 90,
      "prio": 5,
      "enabled": true
    }
  }
}

CODE

Specific parameters:

Parameter	Values	Description
`url`	`"rtp://239.0.0.1:9000"`	URL of RTP stream
`playback_mode`	`"regular"`	plays back audio maintaining a constant delay in place, which is the same across multiple devices that are part of a system. This allows the possibility to keep a synchronized playout.
`playback_mode`	`"low_latency"`	plays with the lowest possible latency

Note: The equalizer setting is not mandatory. The default equalizer setting will be used if equalizer parameter is missing. Please check #equalizer-source-configuration

Local File

Request Body	`{ "sources": { "source1": { "name": "Local File Test", "type": "local_file", "config": { "port":"8999", "loop": false }, "volume": 90, "prio": 5, "enabled": true } } }` CODE

Specific parameters:

Parameter	Values	Description
`port`	`"8999"`	Trigger UDP port (between 8000 and 8999) used to receive the UDP datagram to trigger audio file play.
`loop`	`false`	loop (true or false) to allow audio file to be played in loop

Note: The equalizer setting is not mandatory. The default equalizer setting will be used if equalizer parameter is missing. Please check #equalizer-source-configuration

USB

Request Body	`{ "sources": { "source1": { "name": "USB", "type": "usb", "config": { "path":"my/folder" }, "volume": 90, "prio": 5, "enabled": true } } }` CODE

Specific parameters:

Parameter	Values	Description
`path`	`"my/folder"`	path to a specific music folder inside the pen-drive i. e. this/is/my/folder . Leave this empty to use the pen-drive base path.

Note: The equalizer setting is not mandatory. The default equalizer setting will be used if equalizer parameter is missing. Please check #equalizer-source-configuration

Paging (IC Paging)

Request Body

{
  "sources": {
    "source1": {
      "name": "Paging Test",
      "type": "paging",
      "config": { 
            "paging_mode":"ic paging",
            "barp_station_id": 16,
            "barp_address":"239.0.0.1",
            "barp_audio_port":5555,
            "barp_control_port":5556,
            "barp_status_port":5557,
            "sample_rate":24000,
            "audio_format":"alaw"
        },
      "volume": 90,
      "prio": 5,
      "enabled": true
    }
  }
}

CODE

Specific parameters:

Parameter	Values	Description
`paging_mode`	`"simple paging"`	Simple paging
`paging_mode`	`"ic paging"`	IC paging
`barp_station_id`	`16`	Unique identifier of this paging endpoint.
`barp_address`	`"239.0.0.1"`	IP Address used by client to listen/send on the BARP ports. Modify the BARP IP address to use multicast if communication across different networks is desired, or if your LAN policy is not allowing broadcast. Default: 0.0.0.0
`barp_audio_port`	`5555`	Local BARP port number to which the master will send audio for paging and established calls. If the multicast port and address are configured, this port will be used only for incoming calls. Paging will be done using the multicast group. Default: 5555 (use any unused port between 5555 - 5999)
`barp_control_port`	`5556`	Local BARP port number to receive control messages from the master. Default: 5556 (use any unused port between 5555 - 5999)
`barp_status_port`	`5557`	Destination BARP port number to send status messages to the master. Default: 5557 (use any unused port between 5555 - 5999)
`sample_rate`	`24000`	24Khz
`sample_rate`	`8000`	8Khz
`audio_format`	`"mulaw"`	u-law
`audio_format`	`"alaw"`	a-law

Note: The equalizer setting is not mandatory. The default equalizer setting will be used if equalizer parameter is missing. Please check #equalizer-source-configuration

Paging (Simple Paging)

Request Body	`{ "sources": { "source1": { "name": "Paging Test", "type": "paging", "config": { "paging_mode":"simple paging", "barp_station_id": 1, }, "volume": 90, "prio": 5, "enabled": true } } }` CODE

Specific parameters:

Parameter	Values	Description
`paging_mode`	`"simple paging"`	Simple paging
`paging_mode`	`"ic paging"`	IC paging
`barp_station_id`	`"16"`	Unique identifier of this paging endpoint.

Note: The equalizer setting is not mandatory. The default equalizer setting will be used if equalizer parameter is missing. Please check #equalizer-source-configuration

Scheduler

Request Body	`{ "sources": { "source1": { "name": "Scheduler", "type": "scheduler", "config": {}, "volume": 90, "prio": 5, "enabled": true } } }` CODE

Note: The equalizer setting is not mandatory. The default equalizer setting will be used if equalizer parameter is missing. Please check #equalizer-source-configuration

Equalizer source configuration

IPAC uses a four-band equalizer. Its configuration must be embedded in the “config” parameter of the body of the call. See below example:

{
  ...
      "config": { 
            "equalizer": {
                "enable": false,
                "config": [
                {
                    "name": "LOW",
                    "f": "80",
                    "t": "q",
                    "w": "1",
                    "g": "0"
                },
                {
                    "name": "LOW-MID",
                    "f": "500",
                    "t": "q",
                    "w": "1",
                    "g": "0"
                },
                {
                    "name": "HI-MID",
                    "f": "2000",
                    "t": "q",
                    "w": "1",
                    "g": "0"
                },
                {
                    "name": "HI",
                    "f": "4000",
                    "t": "q",
                    "w": "1",
                    "g": "0"
                }
            ]
            }
        },
  ...
}

CODE

Each band of the EQ offers the following controls:

Band Parameter	Value (default)	Range	Description
`name`	`LOW`		Equalizer Band Name
`f`	`80`	20 to 400	Equalizer Central Frequency (Hz)
`t`	`q`		Q-factor band-width type
`w`	`1`	0.1 to 8	Q-factor value
`g`	`0`	-24 to 24	Gain (dB)

LOW-MID Equalizer Band Parameter	Value (default)	Range	Description
`name`	`LOW-MID`		Equalizer Band Name
`f`	`500`	80 to 1000	Equalizer Central Frequency (Hz)
`t`	`q`		Q-factor band-width type
`w`	`1`	0.1 to 8	Q-factor value
`g`	`0`	-24 to 24	Gain (dB)

HI-MID Equalizer Band Parameter	Value (default)	Range	Description
`name`	`HI-MID`		Equalizer Band Name
`f`	`2000`	800 to 12500	Equalizer Central Frequency (Hz)
`t`	`q`		Q-factor band-width type
`w`	`1`	0.1 to 8	Q-factor value
`g`	`0`	-24 to 24	Gain (dB)

HI Equalizer Band Parameter	Value (default)	Range	Description
`name`	`HI`		Equalizer Band Name
`f`	`4000`	2500 to 20000	Equalizer Central Frequency (Hz)
`t`	`q`		Q-factor band-width type
`w`	`1`	0.1 to 8	Q-factor value
`g`	`0`	-24 to 24	Gain (dB)

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.

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 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

Inputs / Outputs

Inputs and Outputs calls are only supported on hardware where inputs and outputs interfaces are present. e.g. Annuncicom MPI400

GET Input

Retrieves the current status of the dry contact digital input interface

Method	GET
Path	/api/v1/inputs
Request Headers	`X-API-Key: API_KEY Content-Type: application/json` CODE
Request Body	`$body` JSON
Response Status	200, 400, 401, 404, 500
Response Headers	`content-type: application/json` CODE
Response Body	`{ "input1": "1", "input2": "0", }` JSON

GET Relays

Retrieves the current status of the relays

Method	GET
Path	/api/v1/relays
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	`{ "relay1": "1", "relay2": "0" }` JSON

SET relay

Activate/deactivate a specific relay:

relayX key, where X is specifies the relay index number
value: “1” - activate or “0” - deactivate

Note: the user must allow API relay configuration on the web interface for the intended relay to be controlled via API

Method	PUT
Path	/api/v1/relay
Request Headers	`X-API-Key: API_KEY Content-Type: application/json` CODE
Request Body	`{ "relayX" : "1" }` 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_ALLOWED`	Relay configuration is not allowed
	`INVALID_API_KEY`	Required API Key is invalid or missing