AXIS Audio Manager Pro API
The VAPIX® AXIS Audio Manager Pro API can be used together with the AXIS Audio Manager Pro software to manage larger and more advanced audio installations. Supported features includes central control, zone management, scheduling, system health monitoring and real time configuration. Using this API makes it possible to make programmatic interactions with an existing Audio Manager Pro installation, including:
Start/Stop the playback of an audio file.
Silence either the whole or parts of a site.
Access to the API is enabled in the System settings in the Audio Manager Pro interface. Clients are then able to authenticate using the Digest Authentication method and the username and password specified in the System settings.
Further information on how to use the API is available in the document How To AXIS Audio Manager Pro API, available from AXIS Audio Manager Pro.
Overview
The API is divided into the following sections containing their own operations and methods:
Audio files — Announcements or music available on the AXIS Audio Manager Pro server. These endpoints can be used to retrieve and list information about them.
Targets — Endpoints used to interact with available targets such as physical zones and destinations. Targets can be enabled/disabled or be used to define where audio sessions should be played.
Audio sessions — Plays a live or pre-recorded announcement to either the entire or parts of a site. The session contains a list of designated targets and a priority setting. An audio session can be used one time or saved for future use.
Audio files
List audio files
This method should be used when you want to list all audio files available on the site. These files are found in the announcement and music library.
Request
- Method
GET
- Content-Type
application/json
https://<servername>/api/v1.0/audioFiles
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
[
{
"id": 156,
"length": 35,
"library": "Announcement",
"name": "Closing announcement.mp3",
"path": "/Closing/"
}
]
Parameter | Description |
id=<string> | A unique audio file ID. |
length=<number> | The length of the audio file (in seconds). |
library=<string> | The library containing the audio file. |
name=<string> | A file name or nicename of the audio file. |
path=<string> Optional | Folder information of the audio file. |
Error responses
Retrieve a specific audio file
This method should be used when you want to retrieve a specific audio file available on the site.
Request
- Method
GET
- Content-Type
application/json
https://<servername>/api/v1.0/audioFiles/{audioFileId}
Parameter | Description |
audioFileId | The ID of the audio file that will be retrieved. |
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
[
{
"id": 156,
"length": 35,
"library": "Announcement",
"name": "Closing announcement.mp3",
"path": "/Closing/"
}
]
Parameter | Description |
id=<string> | A unique audio file ID. |
length=<number> | The length of the audio file (in seconds). |
library=<string> | The library containing the audio file. |
name=<string> | A file name or nicename of the audio file. |
path=<string> Optional | Folder information of the audio file. |
Error responses
Targets
Retrieve a specific target
This method should be used when you want to retrieve a specific target.
Request
- Method
GET
- Content-Type
application/json
https://<servername>/api/v1.0/targets/{targetId}
Parameter | Description |
targetId | A unique target ID. |
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
{
"id": "zon_1256",
"type": "physicalZone",
"niceName": "Zone for first floor",
"enabled": true,
"children": [
"zon_1256",
"zon_1257"
]
}
Parameter | Description |
id=<string> | A unique target ID. |
type=<string> | Type of targets:
|
niceName=<string> | The nicename of the target. |
enabled=<boolean> | Indicates if a target should play audio. All mapped sources will be stopped for a destination, but other audio can still play in the destination’s targets. |
children=<array> | An array of strings for the immediate children of this target.
|
Error responses
Modify a specific target
This method should be used when you want to modify the settings or property of a specific target.
Request
- Method
PATCH
- Content-Type
application/json
https://<servername>/api/v1.0/targets/{targetId}
Parameter | Description |
targetId | A unique target ID. |
{
"enabled": true
}
Parameter | Description |
enabled=<boolean> | Indicates if the target should play audio. All mapped sources will be stopped for a destination, but other audio clips can still be played in the destination’s target. |
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
Error responses
List targets
This method should be used when you want to list all available targets. Targets can be enabled/disabled or be used to define where the audio session should be played.
Request
- Method
GET
- Content-Type
application/json
https://<servername>/api/v1.0/targets
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
{
"id": "zon_1256",
"type": "physicalZone",
"niceName": "Zone for first floor",
"enabled": true,
"children": [
"zon_1256",
"zon_1257"
]
}
Parameter | Description |
id=<string> | A unique target ID. |
type=<string> | Type of targets:
|
niceName=<string> | The nicename of the target. |
enabled=<boolean> | Indicates if a target should play audio. All mapped sources will be stopped for a destination, but other audio can still play in the destination’s targets. |
children=<array> | An array of strings for the immediate children of this target.
|
Error responses
Audio sessions
List audio sessions
This method should be used when you want to retrieve a list of available audio sessions.
Request
- Method
GET
- Content-Type
application/json
https://<servername>/api/v1.0/audioSessions
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
[
{
"targets": [
"zon_1",
"dev_15"
],
"prio": "HIGH",
"id": "156",
"type": "HTTP"
}
]
Parameter | Description |
targets=<array> | An array of strings containing the targets of the audio session. Accepted types are "physicalZone" and "device" . |
prio=<string> Optional | Enum:
The priority parameter indicates the relative priority of an audio session compared to other playing audio. Sessions with a higher priority will automatically silence audio sessions with a lower priority in the same targets. The first audio session will have higher priority if multiple API audio sessions with the same priority and to the same targets are simultaneously active. The audio session priority levels (high, medium, low) correspond to the paging priority groups in the web interface in Scheduling & Destinations > Content Priorities > Paging. New audio sessions will be placed at the lowest priority in the priority group. |
id=<string> | A unique audio session ID. |
type=<string> | The type of the audio session. |
Error responses
Create an audio session
This method should be used when you want to create a new audio session.
Request
- Method
POST
- Content-Type
application/json
https://<servername>/api/v1.0/audioSessions
{
"targets": [
"zon_1",
"dev_15"
],
"prio": "HIGH",
"type": "HTTP"
}
Parameter | Description |
targets=<array> | An array of strings containing the targets of the audio session. Accepted types are "physicalZone" and "device" . |
prio=<string> Optional | Enum:
The priority parameter indicates the relative priority of an audio session compared to other playing audio. Sessions with a higher priority will automatically silence audio sessions with a lower priority in the same targets. The first audio session will have higher priority if multiple API audio sessions with the same priority and to the same targets are simultaneously active. The audio session priority levels (high, medium, low) correspond to the paging priority groups in the web interface in Scheduling & Destinations > Content Priorities > Paging. New audio sessions will be placed at the lowest priority in the priority group. |
type=<string> | The type of the audio session. |
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
[
{
"targets": [
"zon_1",
"dev_15"
],
"prio": "HIGH",
"id": "156",
"type": "HTTP"
}
]
Parameter | Description |
targets=<array> | An array of strings containing the targets of the audio session. Accepted types are "physicalZone" and "device" . |
prio=<string> Optional | Enum:
The priority parameter indicates the relative priority of an audio session compared to other playing audio. Sessions with a higher priority will automatically silence audio sessions with a lower priority in the same targets. The first audio session will have higher priority if multiple API audio sessions with the same priority and to the same targets are simultaneously active. The audio session priority levels (high, medium, low) correspond to the paging priority groups in the web interface in Scheduling & Destinations > Content Priorities > Paging. New audio sessions will be placed at the lowest priority in the priority group. |
id=<string> | A unique audio session ID. |
type=<string> | The type of the audio session. |
Error responses
Stop audio files
This method should be used when you want to stop playing audio files in the session.
Request
- Method
POST
- Content-Type
application/json
https://<servername>/api/v1.0/audioSessions/{audioSessionId}/stopAudioFiles
Parameter | Description |
audioSessionId=<string> | The ID of the HTTP audio session. |
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
Error responses
Play audio files
This method should be used when you want to trigger a playback for an array of audio files from the content library. Files listed in the audio session will be played in succession. The current playback will be replaced if this method is used while an audio file is played in the audio session.
Request
- Method
POST
- Content-Type
application/json
https://<servername>/api/v1.0/audioSessions/{audioSessionId}/playAudioFiles
Parameter | Description |
audioSessionId=<string> | The ID of the HTTP audio session. |
{
"fileIds": [
"15",
"19"
],
"repeat": 1
}
Parameter | Description |
fileIds=<array> | An array of strings containing the IDs of the audio files that should be played. |
repeat=<integer> Optional | Default value: 1 Indicates the number of times the audio files will be played. A negative number indicates an infinite number of repetitions that can only be stopped by calling stopAudioFiles or deleting the audio session. |
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
Error responses
Play one shot audio files
This method should be used when you want to create a temporary audio session and trigger playback for an array of audio files. The audio session is deleted after playback, but can be also be stopped by deleting the audio session returned by the request.
Request
- Method
POST
- Content-Type
application/json
https://<servername>/api/v1.0/audioSessions/oneshotPlayAudioFiles
{
"targets": [
"zon_1",
"dev_15"
],
"prio": "HIGH",
"fileIds": [
"15",
"19"
],
"repeat": 1
}
Parameter | Description |
targets=<array> | An array of strings containing the targets of the audio session. Accepted types are "physicalZone" and "device" . |
prio=<string> Optional | Enum:
The priority parameter indicates the relative priority of an audio session compared to other playing audio. Sessions with a higher priority will automatically silence audio sessions with a lower priority in the same targets. The first audio session will have higher priority if multiple API audio sessions with the same priority and to the same targets are simultaneously active. The audio session priority levels (high, medium, low) correspond to the paging priority groups in the web interface in Scheduling & Destinations > Content Priorities > Paging. New audio sessions will be placed at the lowest priority in the priority group. |
fileIds=<array> | An array of strings containing the IDs of the audio files that will be played. |
repeat=<integer> Optional | Default: 1 Indicates the number of times the audio files will be played. A negative number indicates an infinite number of repetitions that can only be stopped by calling stopAudioFiles or deleting the audio session. |
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
[
{
"targets": [
"zon_1",
"dev_15"
],
"prio": "HIGH",
"id": "156",
"type": "HTTP"
}
]
Parameter | Description |
targets=<array> | An array of strings containing the targets of the audio session. Accepted types are "physicalZone" and "device" . |
prio=<string> | Enum:
|
id=<string> | Unique audio session ID. |
type=<string> | The type of the audio session. |
Error responses
Retrieve a specific audio session
This method should be used when you want to retrieve an existing audio session.
Request
- Method
GET
- Content-Type
application/json
https://<servername>/api/v1.0/audioSessions/{audioSessionId}
Parameter | Description |
audioSessionId | The ID of the audio session. |
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
[
{
"targets": [
"zon_1",
"dev_15"
],
"prio": "HIGH",
"id": "156",
"type": "HTTP"
}
]
Parameter | Description |
targets=<array> | An array of strings containing the targets of the audio session. Accepted types are "physicalZone" and "device" . |
prio=<string> Optional | Enum:
|
id=<string> | Unique audio session ID. |
type=<string> Optional | The type of the audio session. |
Error responses
Delete a specific audio session
This method should be used when you want to delete an existing audio session. Deleting the audio session will also cancel any ongoing audio playback.
Request
- Method
DELETE
- Content-Type
application/json
https://<servername>/api/v1.0/audioSessions/{audioSessionId}
Parameter | Description |
audioSessionId | The ID of the audio session. |
Successful response
- HTTP Code
200 Operation successful
- Content-Type
application/json
Error responses
General error responses
The following error responses can occur for any request independent of their type.
400 Invalid parameters
- HTTP Code
400 Invalid parameters
- Content-Type
application/json
{
"error": {
"message": "Unknown priority 'HIGHER'",
"code": 400,
"errors": [
{
"reason": "string",
"message": "string",
"location": "string",
"locationType": "DATA_FIELD"
}
],
"id": "f1a02d76-9b83-437e-8cb4-21016465ea43"
}
}
Parameter | Description |
error=<object> | Container for the error data. |
message=<string> | The error message for the corresponding error code. |
code=<integer> | The error code. |
errors=<array>
| An array of objects. |
id=<string> | A unique identifier for the request. |
401 Unauthorized
- HTTP Code
401 Unauthorized
- Content-Type
application/json
{
"error": {
"message": "Unauthorized",
"code": 401,
"errors": [
{
"reason": "string",
"message": "string",
"location": "string",
"locationType": "DATA_FIELD"
}
],
"id": "a3abbd16-010e-e456-200f-03022665eaa1"
}
}
Parameter | Description |
error=<object> | Container for the error data. |
message=<string> | The error message for the corresponding error code. |
code=<integer> | The error code. |
errors=<array>
| An array of objects. |
id=<string> | A unique identifier for the request. |
404 File not found
- HTTP Code
404 File not found
- Content-Type
application/json
{
"error": {
"message": "Target with id:1 not found",
"code": 404,
"errors": [
{
"reason": "string",
"message": "string",
"location": "string",
"locationType": "DATA_FIELD"
}
],
"id": "d98e31c9-ca61-4bd1-952f-a81935b2b349"
}
}
Parameter | Description |
error=<object> | Container for the error data. |
message=<string> | The error message for the corresponding error code. |
code=<integer> | The error code. |
errors=<array>
| An array of objects. |
id=<string> | A unique identifier for the request. |
500 Internal server error
- HTTP Code
500 Internal server error
- Content-Type
application/json
{
"error": {
"message": "Internal server error",
"code": 500,
"errors": [
{
"reason": "string",
"message": "string",
"location": "string",
"locationType": "DATA_FIELD"
}
],
"id": "93639374-ae23-010e-952f-aefd39001e22"
}
}
Parameter | Description |
error=<object> | Container for the error data. |
message=<string> | The error message for the corresponding error code. |
code=<integer> | The error code. |
errors=<array>
| An array of objects. |
id=<string> | A unique identifier for the request. |