Skip to main content

REST API Usage

note

REST API requests are hard limited to one request per second.

note

Encrypted connections require a valid HTTPS certificate for the device.

HTTP/GET​

All nodes and values of the API can be queried directly.

Requests​

Requests are designed to directly access a node or value. To query the full API tree, use:

  • https://[device]/api/rest/?token=XYZ for encrypted requests
  • http://[device]/api/rest/?token=XYZ for unencrypted requests
note

Encrypted connections require a valid HTTPS certificate for the device.

This will return a huge JSON object. Therefore, querying the API root on a regular basis is not recommended to keep traffic and load to a save level.

To authenticate, use GET argument token.

Rate limiting​

REST requests are limited to one per second per client, to reduce overall system load. If the limit is exceeded, the device will answer with error 503 Service Temporarily Unavailable. If more connectivity is required, consider using the WebSocket based connection instead.

Query Objects / Nodes​

For example, to query automix group 1 status of mixer 0, use:

tip

For a full list and description of available paths, see OpenAPI documentation.

//Query
https://[device]/api/rest/audio/mixers/0/automix/1?token=XYZ

//Answer
{
 "_active": true,
 "attmax": 12,
 "attpassive": 15,
 "hold": 260,
 "ratio": 1.5,
 "release": 8.5
}

Query single value​

For example, to query automix group 1 hold time of mixer 0, use:

//Query
https://[device]/api/rest/audio/mixers/0/automix/1/hold?token=XYZ

//Answer
260

Set values​

To set a specific value, use GET argument set

For example, to change the automix group 1 hold time of mixer 0, use:

//Query
https://[device]/api/rest/audio/mixers/0/automix/1/hold?token=XYZ&set=42

//Answer
42

If you query the value again, it will have the new value.

warning

If the value you provided doesn't match the accepted range, it will be set to it's nearest possible value (minimum or maximum)

If you provide the wrong type (e.g. string instead of integer), it will result in an error message.

Flat option​

To navigate the API tree, GET requests support the option flat=true. This will only print an array containing the next tree nodes / levels without any values.

For example, querying a mixer:

//Query
https://device/api/rest/audio/mixers/0/?flat=true

//Answer
[
 "automix",
 "cleanfeeds",
 "faders",
 "mutegroups",
 "options",
 "sourcelist"
]

HTTP/POST​

HTTP/POST requests can always be sent to the same endpoints:

  • https://[device]/api/rest/
  • http://[device]/api/rest/
note

Encrypted connections require a valid HTTPS certificate for the device.

Control api expects a message body that is formatted the following way:

{"method":"get", "path":"/audio/mixers/0/automix/1/hold", "token":"XYZ"}
  • method: get to query values, set to set values
  • path: path within control api, see OpenAPI documentation
  • token: DHD API token.

Get values​

To get a specific value, use "method":"get".

For example, to query automix group 1 hold time of mixer 0, use:

// Query
{"method":"get", "path":"/audio/mixers/0/automix/1/hold", "token":"XYZ"}

// Answer
{"method":"get","path":"/audio/mixers/0/automix/1/hold","payload":42,"success":true}

If you query the whole automix group 1 of mixer 0, you can address the node directly. It will return the json object accordingly:

// Query
{"method":"get", "path":"/audio/mixers/0/automix/1/", "token":"XYZ"}

// Answer
{"method":"get","path":"/audio/mixers/0/automix/1/","payload":{"_active":true,"attmax":12,"attpassive":15,"hold":0,"ratio":1.5,"release":8.5},"success":true}

Set values​

To set a specific value, use "method":"set".

For example, to change the automix group 1 hold time of mixer 0, use:

// Query
{"method":"set", "path":"/audio/mixers/0/automix/1/hold", "payload":42, "token":"XYZ"}

// Answer
{"method":"set","path":"/audio/mixers/0/automix/1/hold","payload":42,"success":true}