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

Response body example

[
  {
    "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

401 Unauthorized
500 Internal server error

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

Response body example

[
  {
    "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

401 Unauthorized
404 File not found
500 Internal server error

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

Response body example

{
  "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: `"physicalZone"`: A group of devices and/or other physical zones. Physical zones can be created in a hierarchy. A device can only be a member of one physical zone in the hierarchy. `"site"`: The entire audio installation controlled by the server. `"device"`: An individual speaker or system device connected to the server. `"destination"`: An object created in the AXIS Audio Manager Pro user interface. It defines a target set of physical zones and devices, a schedule for planned playbacks and paging configurations for live communication.
`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. Physical zones: A zone one level deeper in the hierarchy of physical zones. Destinations: A physical zone set as the target for the destination.

Error responses

401 Unauthorized
404 File not found
500 Internal server error

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.

Request body example

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

401 Unauthorized
404 File not found
500 Internal server error

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

Response body example

{
  "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: `"physicalZone"`: A group of devices and/or other physical zones. Physical zones can be created in a hierarchy. A device can only be a member of one physical zone in the hierarchy. `"site"`: The entire audio installation controlled by the server. `"device"`: An individual speaker or system device connected to the server. `"destination"`: An object created in the AXIS Audio Manager Pro user interface. It defines a target set of physical zones and devices, a schedule for planned playbacks and paging configurations for live communication.
`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. Physical zones: A zone one level deeper in the hierarchy of physical zones. Destinations: A physical zone set as the target for the destination.

Error responses

401 Unauthorized
500 Internal server error

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

Response body example

[
  {
    "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: `"HIGH"` `"MEDIUM"` `"LOW"` 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

401 Unauthorized
500 Internal server error

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

Request body example

{
  "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: `"HIGH"` `"MEDIUM"` `"LOW"` 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

Response body example

[
  {
    "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: `"HIGH"` `"MEDIUM"` `"LOW"` 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

400 Invalid parameters
401 Unauthorized
404 File not found
500 Internal server error

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

401 Unauthorized
404 File not found
500 Internal server error

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.

Request body example

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

400 Invalid parameters
401 Unauthorized
404 File not found
500 Internal server error

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

Request body example

{
  "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: `"HIGH"` `"MEDIUM"` `"LOW"` 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

Response body example

[
  {
    "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: `"HIGH"` `"MEDIUM"` `"LOW"` 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>`	Unique audio session ID.
`type=<string>`	The type of the audio session.

Error responses

400 Invalid parameters
401 Unauthorized
404 File not found
500 Internal server error

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

Response body example

[
  {
    "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: `"HIGH"` `"MEDIUM"` `"LOW"` 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>`	Unique audio session ID.
`type=<string>` Optional	The type of the audio session.

Error responses

401 Unauthorized
404 File not found
500 Internal server error

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

401 Unauthorized
404 File not found
500 Internal server error

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

Response body example

{
  "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>` `reason=<string>`: Unique identifier for this error. `message=<string>`: A human readable text providing more details about the error. `location=<string>`: The location of the error (interpretation of its value depends on `locationType`). `locationType=<string>`: `"DATA_FIELD"`, `"HEADER"`, `"PARAMETER"`	An array of objects.
`id=<string>`	A unique identifier for the request.

401 Unauthorized

HTTP Code: 401 Unauthorized
Content-Type: application/json

Response body example

{
  "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>` `reason=<string>`: Unique identifier for this error. `message=<string>`: A human readable text providing more details about the error. `location=<string>`: The location of the error (interpretation of its value depends on `locationType`). `locationType=<string>`: `"DATA_FIELD"`, `"HEADER"`, `"PARAMETER"`	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

Response body example

{
  "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>` `reason=<string>`: Unique identifier for this error. `message=<string>`: A human readable text providing more details about the error. `location=<string>`: The location of the error (interpretation of its value depends on `locationType`). `locationType=<string>`: `"DATA_FIELD"`, `"HEADER"`, `"PARAMETER"`	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

Response body example

{
  "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>` `reason=<string>`: Unique identifier for this error. `message=<string>`: A human readable text providing more details about the error. `location=<string>`: The location of the error (interpretation of its value depends on `locationType`). `locationType=<string>`: `"DATA_FIELD"`, `"HEADER"`, `"PARAMETER"`	An array of objects.
`id=<string>`	A unique identifier for the request.