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.

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 and four 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.

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

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 :appToken in 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
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"
        }
    }

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.

4. Use the API to change an overlay's text

In this step, you'll change the text in the one of UNO Lowers | Momentum's overlays.

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

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" } } ]'

2. Replace :appToken with the actual Shared App Token you got in step 3.2.

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.

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 :appToken in the URL as you did in step 3.4 and 4.2.
Change the value of subCompositionId to "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
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" } ]'

2. Replace :appToken with the actual Shared App Token you got in step 3.2.

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.

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.

PreviousPortal overview NextIntroduction

Last updated 1 year ago

Was this helpful?