Quick start
Control your first Singular graphic with the REST API
In this guide, you’ll create an overlay, see its output in a web browser, and control it with Singular's REST API.
This quick start uses a lower thirds template, but the process is the same for other templates and even overlays you create from scratch.
1. Get a template
In this step, you'll use the Singular Dashboard to get a control app template.
Open the Singular Dashboard.
Select Templates to open the template library.
In the template library, search for UNO Lowers | Momentum.
Double click on the template photo to open a preview.
Select Use this template to download it. UNO Lowers | Momentum will be listed under Apps in the Dashboard.

2. See the output in a web browser
In this step, you'll get the output URL of the UNO Lowers | Momentum control app and paste it into a web browser to see one of the control app's overlays.
Select UNO Lowers | Momentum under Apps to highlight it.
Click the i button at the top right of the page to open the Dashboard Inspector, which shows details about the app.
Under App URLs and Token, locate and copy the Output URL.

Locating the output URL Paste the Output URL into your internet browser.
The webpage should look like the image below. Keep this tab open for steps three, four, and five to see how the APIs change the overlay.

3. Send your first Singular API request and see the payload
In this step, you'll use the Singular API to return JSON data about the UNO Lowers | Momentum overlay.
Open the Singular API v2 Postman collection and press Run in Postman.
In the Singular Dashboard, open the Dashboard inspector and copy the Shared APP Token for the UNO Lowers | Momentum control app.

Getting the Shared App Token Back in Postman, navigate to Collections > Singular REST API > Singular API v2 > App Instance API (Token) > Get Control App Details > Get Control App Control.

Locating the Get Control App Control API request Replace
:appTokenin the URL with the actual app token from step 3.2.
Replacing the app token in the URL Click Save and Send to return a payload for the UNO Lowers | Momentum control app.

Saving and sending a request Locate the
Lower - Headersub-composition in the response array and copy itssubCompositionIdfor steps four and five. Its payload containsHeaderandMain Text. To match names to IDs, use the composition model guide. An example response entry is shown below; use the ID from your own response:
Open your favorite text editor and paste in the following command:
2. In the Singular Dashboard, open the Dashboard inspector and copy the Shared APP Token for the UNO Lowers | Momentum control app.

3. Back in your text editor, replace :appToken in the cURL request with the actual Shared App Token.
4. Open Terminal on macOS/Linux or PowerShell/Command Prompt on Windows. On Windows, replace curl with curl.exe to call cURL rather than a PowerShell alias. Run each command below as one line.
5. Paste the updated cURL request into the command line and press enter.
The response is a JSON array. This excerpt shows the Lower - Header entry; your IDs and current state may differ:
6. Copy your Lower - Header sub-composition's ID for steps four and five. Its payload contains Header and Main Text. Use the composition model guide to match names to IDs if needed.
4. Use the API to change an overlay's text
In this step, you'll change the text in the Lower - Header overlay and take it In so the change is visible. Both Postman and cURL send the same JSON array. Replace the sample subCompositionId below with your own ID from step three.
Navigate to Collections > Singular REST API > Singular API v2 > App Instance API (Token) > Send Data to Control App >Update Control App Content.

Finding the Update Control App Content request Update
:appTokenin the URL as you did in step 3.4.Select Body > raw > JSON and replace the body with this request. Use your own sub-composition ID:

Updating the request body In the JSON payload, change the text for
"HEADER"and"MAIN LINE OF TEXT"to something else.
Updating the sub-composition's text fields Click Save.
With the output URL window from step two visible, press Send and watch the text change in the web browser.
Create a file named
update-content.jsonin your current terminal directory. Paste in this request body, replacesubCompositionIdwith your ID from step three, and changeHeaderandMain Textto the text you want to display. Save it as UTF-8:
Replace
:appTokenin the command below with your Shared App Token. Run the command from the directory containingupdate-content.json.
macOS/Linux (Bash):
Windows (PowerShell or Command Prompt):
With the output URL window from step two visible, send the request and confirm that the overlay is In and shows your new text.
5. Use the API to trigger an overlay in and out
In this step, you'll animate the same overlay in and out.
Navigate to the Update Control App Animation State request and select the Body tab.

Finding the Update Control App Animation State request Update
:appTokenin the URL as you did in step 3.4 and 4.2.Use your sub-composition ID from step three. Set
stateto"Out"and send the request to take the overlay Out; then set it to"In"and send it again to bring the overlay back In.
Updating an overlay's animation state With the output URL window from step two visible, press Save and Send and then watch the overlay change its animation state.
Create
update-state.jsonin your current terminal directory with this body. Replace the samplesubCompositionIdwith your own ID from step three and save it as UTF-8:
Replace
:appTokenwith your Shared App Token and run the appropriate command as one line from the directory containingupdate-state.json.
macOS/Linux (Bash):
Windows (PowerShell or Command Prompt):
Confirm that the overlay animates Out in the output URL window.
Change
"state": "Out"to"state": "In"inupdate-state.json, save the file, and run the same command again. Confirm that the overlay animates back In.
Next steps
Now that you've successfully used Singular, check out Singular Basics to see how Singular works and learn some key concepts. Or jump right into the REST APIs.
Last updated
Was this helpful?