REST API (system)
REST API (system) will be reduced in its feature set, as it would introduce duplicate functions as the new control API. Use Control API instead for new integrations of the following calls instead.
The following calls are deprecated within firmware version 10.2 and will be removed soon:
- Load Mixer Snapshot
- Save Mixer Snapshot
- Load Channel Snapshot
- Save Mixer Snapshot
- Upload Mixer Snapshot
- Download Mixer Snapshot
- Upload Channel Snapshot
- Download Channel Snapshot
The DHD REST API (system) comes with Firmware Version 9.1 and higher. It is meant to provide easy access to useful functionalities of the console and is designed primarily to write. Reading values is only possible for global labels. This is to prevent polling.
DHD REST API is restricted to an average of one request per second, but can handle bursts of up to 10 requests per second. After such a burst of e.g. 10 requests, you will have to wait 10 seconds before the server accepts any new calls. If you have a Burst of e.g. 5 requests, you will have to wait 5 seconds. During this 'grace period', the server will respond with code '423 (Locked)'.
All examples can vary on different platforms and shell / terminal environments. Please check for the correct syntax on your environment.
REST API must be enabled in Toolbox, [Device Node] > 'Web Apps' Tab, REST API checkbox.
Labels
Set Global Label
Set a single global label
| Action path | /action/setgloballabel |
|---|---|
| Types possible | Get, Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 1 | Global label ID |
| Name | String | test | New global label value |
| Token | String | XXX-XXX-XXX | User authentication (optional) |
Example Request
curl -L -X GET 'http://1.2.3.4/action/setgloballabel?ObjectID=1&Name=test'
Get Global Label
Get a single global label
| Action path | /action/getgloballabel |
|---|---|
| Types possible | Get, Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | _ | Global label ID |
| Token | String | XXX-XXX-XXX | User authentication (optional) |
Response
The response is the label value in plain text.
Example Request
curl -L -X GET 'http://1.2.3.4/action/getgloballabel?ObjectID=1'
Reset Global Label
Reset a single global label to Toolbox default.
| Action path | /action/setgloballabel |
|---|---|
| Types possible | Get, Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 1 | Global label ID |
| Name | String | _ | Has to be empty |
| Token | String | XXX-XXX-XXX | User authentication (optional) |
Example Request
curl -L -X GET 'http://1.2.3.4/action/setgloballabel?ObjectID=1&Name='
Set Channel Label
Set a single channel label
| Action path | /action/setchannellabel |
|---|---|
| Types possible | Get, Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 1 | Fader Channel ID |
| Name | String | test | New channel label value |
| Token | String | XXX-XXX-XXX | User authentication (optional) |
Example Request
curl -L -X GET 'http://1.2.3.4/action/setchannellabel?ObjectID=1&Name=test'
Reset Channel Label
Reset a single channel label to Toolbox default.
| Action path | /action/setchannellabel |
|---|---|
| Types possible | Get, Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 1 | Fader Channel ID |
| Name | String | _ | Has to be empty |
| Token | String | XXX-XXX-XXX | User authentication (optional) |
Example Request
curl -L -X GET 'http://1.2.3.4/action/setchannellabel?ObjectID=1&Name='
Pictures
Upload Picture
Upload a picture of file type .png. This function replaces an existing Resource File and can be used for picture elements within TFT views.
Other file types such as JPG are not supported.
We're using form-data for transmission of the required parameters and file.
| Action path | /action/updatepic |
|---|---|
| Types possible | Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 1 | Resource File ID |
| file | File | image.png | Provide valid PNG here |
| Token | String | XXX-XXX-XXX | User authentication (optional) |
Example Request
curl -L -X POST 'http://1.2.3.4/action/updatepic' -F 'ObjectID=1' -F 'file=@image.png'
User
Login User
Login a specific user on a virtual mixer.
| Action path | /action/login |
|---|---|
| Types possible | Get, Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 0 | Virtual Mixer ID |
| Token | String | XXX-XXX-XXX | User authentication |
Example Request
curl -L -X GET 'http://1.2.3.4/action/login?Token=XXX-XXX-XXX&ObjectID=0'
User
Logout User
Logout any user on a virtual mixer with a valid user token.
| Action path | /action/logout |
|---|---|
| Types possible | Get, Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 0 | Virtual Mixer ID |
| Token | String | XXX-XXX-XXX | User authentication |
Example Request
curl -L -X GET 'http://1.2.3.4/action/logout?Token=XXX-XXX-XXX&ObjectID=0'
Snapshots
Load Mixer Snapshot
Load a mixer snapshot on the console.
| Action path | /action/loadmx |
|---|---|
| Types possible | Get, Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 0 | Virtual Mixer ID |
| SnapshotID | Int | 1 | Snapshot ID to load |
| Token | String | XXX-XXX-XXX | User authentication (optional) |
Example Request
curl -L -X GET 'http://1.2.3.4/action/loadmx?ObjectID=0&SnapshotID=1'
Snapshots
Load Channel Snapshot
Load a channel snapshot on the console.
| Action path | /action/loadch |
|---|---|
| Types possible | Get, Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 0 | Fader Channel ID |
| SnapshotID | Int | 1 | Snapshot ID to load |
| Token | String | XXX-XXX-XXX | User authentication (optional) |
Example Request
curl -L -X GET 'http://1.2.3.4/action/loadch?ObjectID=0&SnapshotID=1'
Snapshots
Upload Channel Snapshot
Upload a channel snapshot on the console. The channel snapshot can be downloaded using Snapshots App.
| Action path | /action/uploadchsnap |
|---|---|
| Types possible | Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| SnapshotID | Int | 1 | Snapshot ID to load |
| file | file | ChannelSnap_1.sfp | Local fader shapshot file |
| Token | String | XXX-XXX-XXX | User authentication (optional) |
Example Request
curl -L -X POST 'http://1.2.3.4/action/uploadchsnap' -F 'file=@ChannelSnap_1.sfp' -F 'SnapshotID=1'
Backup / Restore | Version >10.1
This feature comes with minimum firmware version 10.1.0
To choose what to backup or restore, we use tags. The following tags are allowed:
| Tag | Meaning | Applies to |
|---|---|---|
| ALL | Creates/restores the full backup (no other tags allowed) | All devices |
| FWCONFIG | Contains the device configuration (from Toolbox) | XC3 / XD3 Cores |
| NETWORK | Contains the network config, such as IP addresses, device name, subnet masks, etc. | All devices |
| TIMEZONE | Contains timezone and DST settings | All devices |
| TLS | Contains the TLS certificate of the device | All devices |
| SERVICES | Contains the settings done on Manage Services Page | All devices |
| LOG | Contains syslog settings | All devices |
| SNMP | Contains SNMP settings | All devices |
| USERS | Contains the encrypted user database of the device | XC3 / XD3 Cores |
| MXSNAPS | Contains all mixer snapshots of the device | XC3 / XD3 Cores |
| CHSNAPS | Contains all channel and processing snapshots of the device | XC3 / XD3 Cores |
| SNAPZERO | Contains snapshot zero of each virtual mixer | XC3 / XD3 Cores |
| AES67CONFIG | Contains the AES67 configuration of the device | AES67 Interfaces and XC3 Cores with license 52-8546 |
This API feature can also be used to automatically renew TLS certificates.
Download Backup
Download a backup of all or selected parameters of the device.
A file of type ''.bin'' will be downloaded. This has the same contents as the manually downloaded ''.tgz'' file from System App.
| Action path | /action/backup |
|---|---|
| Types possible | Post, Get |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| Token | String | XXX-XXX-XXX | User authentication (required) |
| Tags | String | ALL | Define what to backup (see list above) |
Example Request
Creating a full backup:
curl -L -X GET 'http://1.2.3.4/action/backup?Token=XXX-XXX-XXX&Tags=ALL'
** Creating a selective backup of SNMP and Network Config: **
curl -L -X GET 'http://1.2.3.4/action/backup?Token=XXX-XXX-XXX&Tags=NETWORK,SNMP'
Restore (Upload and Apply Backup File)
Upload and restore a previously downloaded backup of all or selected parameters of the device.
We're using form-data for transmission of the required parameters and file.
Selected data of the device will be overwritten, the device may restart to apply the backup, and audio will be interrupted.
File types ''.bin'' and ''.tgz'' are supported.
| Action path | /action/restore |
|---|---|
| Types possible | Post |
Params
| Key | Value Type | Example | Description |
|---|---|---|---|
| Token | String | XXX-XXX-XXX | User authentication (required) |
| Tags | String | ALL | Define what to backup (see list above) |
Example Request
Restore all Backup Data:
curl -L -X POST 'http://1.2.3.4/action/restore' -F 'file=@Backup.bin' -F 'Tags=ALL' -F 'Token=XXX-XXX-XXX'
Restore only Network and AES67 Configuration
curl -L -X POST 'http://1.2.3.4/action/restore' -F 'file=@Backup.bin' -F 'Tags=NETWORK,AES67CONFIG' -F 'Token=XXX-XXX-XXX'
Responses
The server will respond with a status 200 and a JSON object. The JSON object contains the received values such as some data required by DHD audio for debugging. If something on your request goes wrong, the JSON object will contain an Error entry.
If the server doesn't respond with status code 200:
- Status code
423 (Locked): the REST API is locked because of too many requests (more than 10 per minute) - Status code
405 (Method Not Allowed):- Check if your license 52-8577 DHD REST API is valid
- Check if REST API checkbox is enabled within Toolbox [Device Node] >
Web AppsTab