Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

You’ll need a Singular account to follow this quick start. Get your free account here.

1. Get a template

In this step, you'll use the Singular Dashboard to get a control app template.

  1. Select Templates to open the template library.

  2. In the template library, search for UNO Lowers | Momentum.

  3. Double click on the template photo to open a preview.

  4. Select Use this template to download it. UNO Lowers | Momentum will be listed under Apps in the Dashboard.

Opening the UNO Lowers | Momentum template

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.

  1. Select UNO Lowers | Momentum under Apps to highlight it.

  2. Click the i button at the top right of the page to open the Dashboard Inspector, which shows details about the app.

  3. Under App URLs and Token, locate and copy the Output URL.

    Locating the output URL
  4. 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.

UNO Lowers | Momentum overlay output

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.

This quick start makes API calls using Postman and cURL, but you can also use other languages and API platforms.

  1. Open the Singular API v2 Postman collection and press Run in Postman.

  2. 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
  3. 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
  4. Replace :appToken in the URL with the actual app token from step 3.2.

    Replacing the app token in the URL
  5. Click Save and Send to return a payload for the UNO Lowers | Momentum control app.

    Saving and sending a request
  6. Locate the Lower - Header sub-composition in the response array and copy its subCompositionId for steps four and five. Its payload contains Header and Main 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:

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

The examples use the response shape in Get a control app's control data. If your GET response instead uses compositionId, controlNode.payload, and animation.state, map those to subCompositionId, payload, and state in the PATCH request. Do not send the entire GET response as a PATCH body.

  1. 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
  2. Update :appToken in the URL as you did in step 3.4.

  3. Select Body > raw > JSON and replace the body with this request. Use your own sub-composition ID:

    Updating the request body
  4. In the JSON payload, change the text for "HEADER" and "MAIN LINE OF TEXT" to something else.

    Updating the sub-composition's text fields
  5. Click Save.

  6. With the output URL window from step two visible, press Send and watch the text change in the web browser.

  1. Create a file named update-content.json in your current terminal directory. Paste in this request body, replace subCompositionId with your ID from step three, and change Header and Main Text to the text you want to display. Save it as UTF-8:

  1. Replace :appToken in the command below with your Shared App Token. Run the command from the directory containing update-content.json.

macOS/Linux (Bash):

Windows (PowerShell or Command Prompt):

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

  1. Navigate to the Update Control App Animation State request and select the Body tab.

    Finding the Update Control App Animation State request
  2. Update :appToken in the URL as you did in step 3.4 and 4.2.

  3. Use your sub-composition ID from step three. Set state to "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
  4. With the output URL window from step two visible, press Save and Send and then watch the overlay change its animation state.

  1. Create update-state.json in your current terminal directory with this body. Replace the sample subCompositionId with your own ID from step three and save it as UTF-8:

  1. Replace :appToken with your Shared App Token and run the appropriate command as one line from the directory containing update-state.json.

macOS/Linux (Bash):

Windows (PowerShell or Command Prompt):

  1. Confirm that the overlay animates Out in the output URL window.

  2. Change "state": "Out" to "state": "In" in update-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?