Data API - Audio File Names
The Audio Files API lets an external system list the audio configured on a CCaaS tenant: queue and hold music, IVR announcements, and queue announcements. It is read-only. Use it to check that a music or announcement name exists before sending it in a skill setting or an IVR configuration. This page is the endpoint reference.
Requires Version 5.67.5 or HigherThe Audio Files API is available on CCaaS version 5.67.5 and later. On an earlier version, the endpoint does not exist and requests fail.
Overview
| Base URL | https://<hostname>.xima.cloud/rest/api |
| Authentication | Bearer token from an API Service User |
| Request and response format | JSON |
| Minimum version | 5.67.5 |
| Access | Read-only. The API never changes the tenant's audio |
Authentication
Every request requires a Service User bearer token in the Authorization header:
Authorization: Bearer <api_bearer_token>Service Users are created under API Enablement > API Service Users. See API Service Users. Any valid Service User token can read the audio list.
Identifying Audio
Music and announcements are identified by name, not by an id. Wherever audio is configured, such as a skill's queue music or a queue announcement, it is referenced by its name, so the name this API returns is the value to send. Names are matched exactly as returned.
Endpoints
| Method | Path | Summary |
|---|---|---|
GET | /v1/audio-files | List every configured audio file |
List Audio Files
GET /v1/audio-files
Lists the tenant's music, IVR announcements, and queue announcements: the same audio an administrator can choose from in the admin pages. Each list is sorted by name, ignoring case.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Authorization | header | string | Yes | Bearer <api_bearer_token> |
Responses
| Code | Description |
|---|---|
200 OK | An AudioFileList |
401 Unauthorized | Missing or invalid token |
Example Request
curl -L -X GET 'https://<hostname>.xima.cloud/rest/api/v1/audio-files' \
-H 'Authorization: Bearer <api_bearer_token>'Example Response — 200 OK
200 OK{
"music": [
{ "name": "Energy by Bensound", "standard": true },
{ "name": "Happiness by Bensound", "standard": true },
{ "name": "Hey by Bensound", "standard": true },
{ "name": "Holiday Hold Loop", "standard": false },
{ "name": "Memories by Bensound", "standard": true },
{ "name": "Smile by Bensound", "standard": true },
{ "name": "Smooth Jazz", "standard": true },
{ "name": "Snap Clap Whistle", "standard": true },
{ "name": "Sunny by Bensound", "standard": true },
{ "name": "The Jazz Piano by Bensound", "standard": true },
{ "name": "Ukulele by Bensound", "standard": true },
{ "name": "Vivaldi", "standard": true }
],
"ivrAnnouncements": [
{ "name": "After Hours Message" },
{ "name": "Main Greeting" }
],
"queueAnnouncements": [
{ "name": "Estimated Wait Reminder" },
{ "name": "Please Hold" }
]
}On a tenant with no uploaded audio, ivrAnnouncements and queueAnnouncements are empty arrays, and music still lists the standard tracks.
Models
AudioFileList
| Field | Type | Description |
|---|---|---|
music | array of AudioFile | Standard music tracks that ship with CCaaS, plus music uploaded in Manage Music Files. Use for queue and hold music |
ivrAnnouncements | array of AudioFile | Announcements uploaded as IVR announcements. Use in IVR call flows |
queueAnnouncements | array of AudioFile | Announcements uploaded as in-queue announcements. Use for a skill's queue announcements |
Every uploaded file appears in exactly one list: the same one it appears in on the admin pages. If an administrator moves an upload between announcements and music, it moves between lists here too.
AudioFile
| Field | Type | Description |
|---|---|---|
name | string | The audio's name, as shown in the admin pages. This is the value to send wherever the audio is referenced |
standard | boolean | Music only. true for a track that ships with CCaaS, false for one the tenant uploaded. Omitted on announcements |
What This API Does Not Include
- Voicemail greetings. Skill and agent voicemail greetings are not listed.
- The audio itself. The API returns names only; it does not download or stream audio.
- System prompts. Language-pack audio and built-in system messages are not listed.
- Silence. The built-in Silence option is not listed as a music track, matching Manage Music Files.
Using the Names
The names this API returns are the values the Skill Management APIs expect for audio settings:
| Skill setting | List to use |
|---|---|
voiceSettings.queueMusic | music |
voiceSettings.queueAnnouncements.announcements[].announcementName | queueAnnouncements |
Read the list first, then send a name exactly as returned. A name that does not exist on the tenant is not applied; see Skill Management APIs for how a skill write reports a value it could not resolve.
Audio Names Can ChangeAdministrators can delete or re-upload audio at any time, and an upload can be moved between announcements and music. Read the list shortly before you use a name, rather than storing names long-term.
Limits
| Limit | Description |
|---|---|
| Version | 5.67.5 or higher |
| Access | Read-only. Audio cannot be uploaded, renamed, or deleted through this API |
| Paging | None. Every list is returned in full |
See API Limits & Statuses for statuses shared by every CCaaS API.
Related Pages
Updated 1 day ago
