The DHD REST API comes with Firmware Version 9.1 & Web Apps version 2.0. 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).
REST API (system) will be reduced in its feature set, as it would introduce duplicate functions as the new control API.
The following calls are deprecated within firmware version 10.2 and will be removed soon:
Note
All examples can vary on different platforms and shell / terminal environtments. Please check for the correct syntax on your environment.
REST API must be enabled in Toolbox, [Device Node] > Web Apps Tab, REST API checkbox.
Set a single global label
| Action path | /action/setgloballabel |
|---|---|
| Types possible | Get, Post |
| 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) |
curl -L -X GET 'http://1.2.3.4/action/setgloballabel?ObjectID=1&Name=test'
Get a single global label
| Action path | /action/getgloballabel |
|---|---|
| Types possible | Get, Post |
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | | Global label ID |
| Token | String | XXX-XXX-XXX | User authentication (optional) |
The response is the label value in plain text.
curl -L -X GET 'http://1.2.3.4/action/getgloballabel?ObjectID=1'
Reset a single global label to Toolbox default.
| Action path | /action/setgloballabel |
|---|---|
| Types possible | Get, Post |
| 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) |
curl -L -X GET 'http://1.2.3.4/action/setgloballabel?ObjectID=1&Name='
Set a single channel label
| Action path | /action/setchannellabel |
|---|---|
| Types possible | Get, Post |
| 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) |
curl -L -X GET 'http://1.2.3.4/action/setchannellabel?ObjectID=1&Name=test'
Reset a single channel label to Toolbox default.
| Action path | /action/setchannellabel |
|---|---|
| Types possible | Get, Post |
| 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) |
curl -L -X GET 'http://1.2.3.4/action/setchannellabel?ObjectID=1&Name='
Upload a picture of file type .png. This function replaces an existing Resource File and can be used for picture elements within TFT views.
Note
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 |
| 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) |
curl -L -X POST 'http://1.2.3.4/action/updatepic' -F 'ObjectID=1' -F 'file=@image.png'
Login a specific user on a virtual mixer.
| Action path | /action/login |
|---|---|
| Types possible | Get, Post |
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 0 | Virtual Mixer ID |
| Token | String | XXX-XXX-XXX | User authentication |
curl -L -X GET 'http://1.2.3.4/action/login?Token=XXX-XXX-XXX&ObjectID=0'
Logout a any user on a virtual mixer with a valid user token.
| Action path | /action/logout |
|---|---|
| Types possible | Get, Post |
| Key | Value Type | Example | Description |
|---|---|---|---|
| ObjectID | Int | 0 | Virtual Mixer ID |
| Token | String | XXX-XXX-XXX | User authentication |
curl -L -X GET 'http://1.2.3.4/action/logout?Token=XXX-XXX-XXX&ObjectID=0'
Load a mixer snapshot on the console.
| Action path | /action/loadmx |
|---|---|
| Types possible | Get, Post |
| 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) |
curl -L -X GET 'http://1.2.3.4/action/loadmx?ObjectID=0&SnapshotID=1'
Load a channel snapshot on the console.
| Action path | /action/loadch |
|---|---|
| Types possible | Get, Post |
| 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) |
curl -L -X GET 'http://1.2.3.4/action/loadch?ObjectID=0&SnapshotID=1'
Upload a channel snapshot on the console. The channel snapshot can be downloaded using Snapshots App.
| Action path | /action/uploadchsnap |
|---|---|
| Types possible | Post |
| 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) |
curl -L -X POST 'http://1.2.3.4/action/uploadchsnap' -F 'file=@ChannelSnap_1.sfp' -F 'SnapshotID=1'
Note
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 deivce | AES67 Interfaces and XC3 Cores with license 52-8546 |
Tip
This API feature can also be used to automatically renew TLS certificates.
Download a backup of all or selected parameters of the device.
Note
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 |
| Key | Value Type | Example | Description |
|---|---|---|---|
| Token | String | XXX-XXX-XXX | User authentication (required) |
| Tags | String | ALL | Define what to backup (see list above) |
curl -L -X GET 'http://1.2.3.4/action/backup?Token=XXX-XXX-XXX&Tags=ALL'
curl -L -X GET 'http://1.2.3.4/action/backup?Token=XXX-XXX-XXX&Tags=NETWORK,SNMP'
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.
Important
Selected data of the device will be overwritten, device may restart in order to apply the backpu, audio will be interrupted.
Note
File types .bin and .tgz are supported.
| Action path | /action/restore |
|---|---|
| Types possible | Post |
| Key | Value Type | Example | Description |
|---|---|---|---|
| Token | String | XXX-XXX-XXX | User authentication (required) |
| Tags | String | ALL | Define what to backup (see list above) |
curl -L -X POST 'http://1.2.3.4/action/restore' -F 'file=@Backup.bin' -F 'Tags=ALL' -F 'Token=XXX-XXX-XXX'
curl -L -X POST 'http://1.2.3.4/action/restore' -F 'file=@Backup.bin' -F 'Tags=NETWORK,AES67CONFIG' -F 'Token=XXX-XXX-XXX'
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:
423 (Locked): the REST API is locked because of too many requests (more than 10 per minute)405 (Method Not Allowed): Web Apps Tab