DHD REST API

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).

Note
To use it, the license 52-8577 DHD REST API is required.

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 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='

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.

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

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'

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'

Logout User

Logout a 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'

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'

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'

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 Virtual Mixer ID
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'

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 Apps Tab