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.
In this step, you'll use the Singular Dashboard to get a control app template.
- 1.
- 2.Select Templates to open the template library.
- 3.In the template library, search for UNO Lowers | Momentum.
- 4.Double click on the template photo to open a preview.
- 5.Select Use this template to download it. UNO Lowers | Momentum will be listed under Apps in the Dashboard.
Opening the UNO Lowers | Momentum template
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.
Locating the output URL - 4.Paste the Output URL into your internet browser.
- 5.Add
&bgcolor=greento the end of the URL and press enter. This will set the background color of the webpage to green, which makes it easier to see.
The webpage should look like the image below. Keep this tab open for steps three and four to see how the APIs change the overlay.
UNO Lowers | Momentum overlay output
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.
Postman
cURL
- 1.
- 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
:appTokenin 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.Inspect the payload and notice that this control app is set up so the API can access its color, text, and In/Out state. In particular, we'll use this snippet from in the next step:
{
"subCompositionId": "57d57254-f15b-42ca-b68e-75b69875f5ea",
"subCompositionName": "Lower - Header",
"mainComposition": false,
"state": "In",
"payload": {
"Header": "HEADER",
"Main Text": "MAIN LINE OF TEXT"
}
}
- 1.Open your favorite text editor and paste in the following command:
curl --location --request GET 'https://app.singular.live/apiv2/controlapps/:appToken/control'
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 the Command Prompt in Windows or Terminal in Mac.
5. Paste the updated cURL request into the command line and press enter.
The payload (in JSON) should look like this:
[{
"compositionId": "-MwbugjuLzQ1fYlGAczq",
"compositionName": null,
"mainComposition": true,
"animation": {
"state": "Out1"
},
"controlNode": {
"payload": {
"Accent Text Color": {
"a": 1,
"b": 255,
"g": 255,
"r": 255
},
"Dropline Color": {
"a": 1,
"b": 66,
"g": 66,
"r": 66
},
"Primary Color": {
"a": 1,
"b": 255,
"g": 255,
"r": 255
},
"Primary Text Color": {
"a": 1,
"b": 51,
"g": 51,
"r": 51
},
"Secondary Color": {
"a": 1,
"b": 0,
"g": 0,
"r": 180
}
}
}
}, {
"compositionId": "57d57254-f15b-42ca-b68e-75b69875f5ea",
"compositionName": "Lower - Header",
"animation": {
"state": "Out2"
},
"controlNode": {
"payload": {
"Header": "HEADER",
"Main Text": "MAIN LINE OF TEXT"
}
}
}, {
"compositionId": "6cb2b49c-03e1-499b-89b1-93664560e92b",
"compositionName": "Lower - Header + Dropline",
"animation": {
"state": "Out2"
},
"controlNode": {
"payload": {
"Dropline": "DROPLINE MESSAGE",
"Header": "HEADER",
"Main Text": "MAIN LINE OF TEXT"
}
}
}, {
"compositionId": "f771e339-dde9-45ef-a8a4-5545f0bde56c",
"compositionName": "Lower - Breaking News",
"animation": {
"state": "In"
},
"controlNode": {
"payload": {
"Header": "HEADER",
"Text 1": "BREAKING NEWS",
"Text 2": "MAIN LINE OF TEXT"
}
}
}]
6. Inspect the payload and notice that this control app is set up so the API can access its color, text, and In/Out state.
In this step, you'll change the text in the one of UNO Lowers | Momentum's overlays.
Postman
cURL
- 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.
- 3.Select the Body tab and replace the JSON date with the code snippet from step 3.6 between the square brackets.
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.
In the payload from the
GETControl App Control request in step three, this is the sub-composition that you'll update:{
"subCompositionId": "57d57254-f15b-42ca-b68e-75b69875f5ea",
"state": "In",
"payload": {
"Header": "HEADER",
"Main Text": "MAIN LINE OF TEXT"
}
}
1. Paste the following cURL request into your text editor:
curl --location --request PATCH 'https://app.singular.live/apiv2/controlapps/:appToken/control'
--header 'Content-Type: application/json'
--data-raw '[ { "subCompositionId": "57d57254-f15b-42ca-b68e-75b69875f5ea", "mainComposition": false, "state": "In", "payload": { "Header": "HEADER", "Main Text": "MAIN LINE OF TEXT" } } ]'
3. Find the key-value pairs
"Header":"HEADER" and "Text 2":"MAIN LINE OF TEXT" and change the current values ("HEADER", "MAIN LINE OF TEXT") to the text of your choice.4. With the output URL window from step two visible, copy your updated
PATCH request and past it into the command line and press enter. Then, watch the text update in the web browser.In this step, you'll animate the same overlay in and out.
Postman
cURL
- 1.Navigate to the Update Control App Animation State request and select the Body tab.
Finding the Update Control App Animation State request - 2.
- 3.Change the value of
subCompositionIdto"57d57254-f15b-42ca-b68e-75b69875f5ea", from the previous request, and value of"state"to"In"or"Out"to animate this overlay in or out respectively.
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.
In the payload from the
GETControl App Control request in step three, this is the sub-composition that you'll update to trigger an overlay in and out.{
"subCompositionId": "57d57254-f15b-42ca-b68e-75b69875f5ea",
"state": "In",
"payload": {
"Header": "HEADER",
"Main Text": "MAIN LINE OF TEXT"
}
}
1. Paste the following cURL request into your text editor:
curl --location --request PATCH 'https://app.singular.live/apiv2/controlapps/:appToken/control'
--header 'Content-Type: application/json'
--data-raw '[ { "subCompositionId": "57d57254-f15b-42ca-b68e-75b69875f5ea", "state": "In" } ]'
3. Find the key-value pair
"state": "In" and change the value to "Out".4. With the output URL window from step two visible, copy your updated
PATCH request, paste it into the command line, and press enter. Then, watch the overlay go to its Out state.5. Using the same API request, change the
"state" value to "Out".6. With the output URL window from step two visible, copy your updated
PATCH request, paste it into the command line, and press enter. Then, watch the overlay go to its Out state.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 modified 8mo ago