What is the Automator API?
An API, or application programming interface, is a type of (intermediary) software with certain standards and protocols that allows different software components to talk to each other. APIs are omnipresent on the web, usually living in the background, but sometimes they can come to the foreground as well, as is the case for our Automator API.
When using the Automator to automate (live) shows by connecting your Cuez Episode with the hardware and software that is used in the studio, the Automator API performs its tasks mainly in the background, such as when you click a trigger, a Step button, a CuezDeck button, or even load an Episode and more.
As you program the Automator to perform certain automation functions on your connected devices, in most cases API commands are sent behind the scenes. However, we can bring some of these more to the foreground to make automations even more powerful or easy to use.
The functions/calls available in the Automator API are a combination of functions that are available in the Automator itself, as well as additional functions.
The Automator API can be updated with new functions as needed, so depending on your needs, make sure to regularly check the documentation for updates.
To make use of the Automator API, make sure you are on Automator Stable Build 2024.10.28-0 or newer, or a Next Build that was released after that point.
Note: The Automator API is not to be confused with the (non-public) Cuez API.
Where can I find the Automator API and its documentation?
The Automator API and available functions are described here.
The column on the left shows all available API functions/calls.
When selecting one of the functions/calls, the middle of the page shows the exact 'link' to use for the function/call, usually in the form of a GET command. It also explains what the equivalent function would be in Automator itself.
The column on the right shows additional information for the selected API function/call.
How can I use the Automator API?
As you can see in the Automator API documentation, there are quite a few functions/calls available, allowing you to expand your automation setup.
On the one hand, you could build your own 'interface' that triggers certain API functions towards the Automator, in order to run your show from that interface.
On the other hand, the Automator API is often used in combination with something like Bitfocus Companion or with a Stream Deck (whether it being the stream Deck Mini, +, XL, Studio, Mobile,...).
Some of the most used/useful API functions
Next: http://localhost:7070/api/trigger/next
Next Trigger: http://localhost:7070/api/trigger/nextTrigger
Step by index: e.g. http://localhost:7070/api/trigger/step/2
Which reflects the available Step buttons for a trigger
Triggering CuezDeck buttons: http://localhost:7070/api/trigger/button/{buttonID}
Firing Macros: http://localhost:7070/api/macro/{macroID}
and more
Getting available buttons, macros,...
Some of the Automator API functions require you to first get a list of the available CuezDeck buttons, Macros, and more.
Get all cuez deck buttons
One example would be to get all available CuezDeck buttons from your configuration. This is done by running http://localhost:7070/api/trigger/button/ in your browser or favorite tool to work with API's (Postman, Paw/RapidAPI,...).
In browser
Running http://localhost:7070/api/trigger/button/ in the browser, initially gives a compact/messy result, but checking the 'Pretty print' box at the top puts the result in a more readable JSON format.
In an API tool
Running the same command in one of your favorite API tools, usually gives a readable JSON format by default.
Putting the function/call to action using the 'id'
The result of the above allows you to identify by 'id' which is the CuezDeck button that you need or want to trigger via the API. Using that 'id', the function can now be constructed, depending on which type of CuezDeck button you want to trigger.
Normal 'button' type: http://localhost:7070/api/trigger/button/{buttonID}
A 'switch' or toggle button:
On: http://localhost:7070/api/trigger/button/{buttonID}/on
Off: http://localhost:7070/api/trigger/button/{buttonID}/off
Get all macros
Another example would be to get all available macros from your configuration. This is done by running http://localhost:7070/api/macro/.
In browser
Running http://localhost:7070/api/macro/ in the browser, initially gives a compact/messy result, but checking the 'Pretty print' box at the top puts the result in a more readable JSON format.
In an API tool
Running the same command in one of your favorite API tools, usually gives a readable JSON format by default.
Putting the function/call to action using the 'id'
The result of the above allows you to identify by 'id' which is the Macro that you need or want to trigger via the API. Using that 'id', the function can now be constructed:
http://localhost:7070/api/macro/{macroID}
Other functions
Following the same methods, you can also list and identify keyboard shortcuts, timers, and more.
Automator API and Stream Deck
In this Help Center Article, we will further explain by using Stream Deck (Mini, +, XL, Studio, Mobile,...) as an example to use the Automator API to expand your workflow.
In your Stream Deck configuration software, first make sure you have a way of adding buttons that can handle API functions/calls - there are multiple available.
In many cases, you can achieve the same result by using the default 'Website' type button, but the less desirable effect is that a webpage would also be opened.
Next, start adding the buttons you would like to use to trigger API functions towards the Automator.
In our example, we have the following (not in order of appearance):
Navigational triggers
Next:
http://localhost:7070/api/trigger/nextIf Step buttons are present on the element you have currently triggered, then the 'Next' function would go through the Step buttons first.
In the example screenshot, this is represented by the arrow right saying 'Step'.
Next Trigger:
http://localhost:7070/api/trigger/nextTriggerWhether Step buttons are present or not , then the 'Next Trigger' function would skip the Step buttons and go straight to the next element in the rundown.
In the example screenshot, this is represented by the arrow down saying 'Trigger'.
Previous:
http://localhost:7070/api/trigger/previousIf Step buttons are present on the element you have currently triggered, then the 'Previous' function would go backwards through the Step buttons first.
In the example screenshot, this is represented by the arrow left saying 'Step'.
Previous Trigger:
http://localhost:7070/api/trigger/previousTriggerWhether Step buttons are present or not , then the 'Previous Trigger' function would skip the Step buttons and go right back to the previous element in the rundown.
In the example screenshot, this is represented by the arrow up saying 'Trigger'.
Re-Trigger the current trigger:
http://localhost:7070/api/trigger/step/0Given the fact that the main trigger itself is technically a Step, being Step 0 (zero), this means that we can use the function to trigger Step 0 in order to re-trigger the current element.
In the example screenshot, this is represented by the circular arrow saying 'Redo'.
Going back to the top (beginning of the Episode):
This can be achieved in a couple ways, the easiest being by using 'First Trigger'.
http://localhost:7070/api/trigger/firstTriggerNo matter where in the Episode/rundown you are currently triggering, this command will bring you back to the beginning and (re)trigger the very first element.
In the example screenshot represented by the circled arrow up saying 'First'.
The other option (being more convoluted) would be by triggering a Block by ID, or by triggering a corresponding CuezDeck button (with the use of Variables and Webhooks). This option gives us a CuezDeck button that can also be triggered in the Automator itself, and shows how different parts of the Automator can be tied together.
We'll explain this option by working through it backwards - unfold this section of the article to find out more.
We'll explain this option by working through it backwards - unfold this section of the article to find out more.
The Stream Deck button itself would have the following command:
http://localhost:7070/api/trigger/button/{buttonID}, with {buttonID} being the ID of the corresponding CuezDeck button, as that is what Stream Deck would be triggering.
As shown in the screenshot above, our CuezDeck button uses a Webhook device which we called 'OPEN'. The Webhook is configured as a Webhook device with the following 'GET' request, which we called 'OPEN Block':
As shown above, our Cuez Deck button runs the Webhook's 'OPEN Block' request. In that request, we need to add the Block ID, which we will do by using a Variable. In the Variables menu (under the gear icon top right), we created a new Variable called 'OPEN Block', so we know that it goes together with our Webhoook.
At this point, we have:
Our CuezDeck button, with its ID, which we trigger from the Stream Deck
Our Webhook device that will actually trigger the required Automator API function, including the Block ID of the Block we will be triggering.
Our Variable where the Block ID will be stored, so that the Webhook can make use of it.
What is missing, is getting the correct Block ID into our Variable, then our circle is complete.
In our example Episode configuration, we have an 'OPEN' Cue Block that we use to execute all sorts of setup functions
Setting Variables
Playing Opening titles
Opening/closing microphones
And more
One of the Variables we set in this 'OPEN' Block, is to set the Block ID into our 'OPEN Block' Variable
With that last piece of the puzzle, we now have everything we need to trigger our CuezDeck button from the Stream Deck, via the Automator API. This is represented in our example screenshot by the key with the arrow pointing up towards a horizontal line, saying 'TO TOP'.
Camera triggers
As shown in our example screenshot, we also have a couple Stream Deck buttons to easily trigger different cameras. This is achieved by triggering the corresponding CuezDeck buttons via their API call.
See section about getting the CuezDeck buttons via the Automator API and how to then trigger those buttons.
In the end, for our example, we have 3 buttons on our Stream Deck, each allowing us to trigger a different camera. The configuration of the CuezDeck buttons themselves would look something like this, but depends on the device you use for your camera switching of course:
And more
We hope this article shows you some of the things you can achieve using the Automator and the Automator API. This is of course just a glimpse of what is possible, other examples will always depend on your exact situation and what you are trying to achieve.