Developer Portal
Quick StartsComposition scriptingAPIs and SDKsSupport
  • Portal overview
  • Quick start
  • REST API
    • Introduction
    • Rate limits
    • Authorization
    • How-to guides
      • Get a control app's API token
      • Get a composition's sub-composition IDs and names and their payload structures
      • Get a control app's model
      • Get a control app's metadata
      • Update a sub-composition's content
      • Update a sub-composition's animation state
      • Update a sub-composition's content and animation state in one call
      • Update multiple sub-compositions in one call
    • API reference
      • Get control app details
        • Get a control app's metadata
        • Get a control app's model
        • Get a control app's control data
      • Send data to a control app
        • Update a control app's content
        • Update a control app's animation state
      • Take out all of an app's output
  • Data stream API
    • Introduction
    • Rate limits
    • Authorization
    • How-to guides
      • Create a data stream
      • Link a data stream to a composition
      • Send data to an app using the data stream API
    • API reference
  • Composition scripting
    • Introduction
    • Overview
    • Quick start
      • Find sub-compositions and widgets
      • Read and update control nodes
      • Set text widget text properties
      • Read and update widget properties
      • Read control nodes and update widget properties
      • Set image widget URL property
      • Set table widget content property
    • Cheat sheets
      • Fundamentals
      • Interactive overlays
      • Best practices
    • Use cases
      • Read control nodes and generate HTML text
      • Read control nodes, generate HTML text with background
      • Text Ticker - Start ticker on "In" animation
    • Composition script editor reference
  • Software development kits
    • Graphics SDK
      • Getting started
      • Reference
        • SDK functions
        • Composition object
        • Sequencer object
      • Guides and examples
        • Load a composition with its token
        • Load a composition with its URL
        • Get the composition URL of an app instance
        • Sequencer VOD example
        • Control local preview of app
        • Load app instance output
    • Overlay SDK
      • Getting started
      • SDK functions
      • Use case examples
    • Widget SDK
      • Preparing your environment
      • Getting started
      • Reference
        • Widget UI definition
        • Widget callback functions
        • Time control object
        • Composition instance
      • Guides and examples
        • Widget example: CSS patterns
    • App SDK
  • Singular Basics
    • Overview of Singular
    • Managing overlays in the Dashboard
      • How to create a new composition
      • How to open a new app template
      • How to create an app for a composition
      • How to extract a composition from an app
      • How to find an app's shared app token and shared API URL
      • Dashboard reference
    • Building overlays in Composer
      • How to build a composition
      • How to set up layer logic to automate overlay transitions
      • How to set up control nodes to make widget properties available to a control app
      • Animating overlays
        • How to create timeline animations
        • How to create behavior animations
        • How to create update animations
      • How to make overlays interactive
      • How to adapt overlays to various screen sizes
      • Composer reference
    • Controlling overlays in Studio and UNO
      • How to use Studio
      • Studio reference
      • UNO reference
  • Support
    • Singular status
    • Support resources
    • Singular terminology
    • Performance Testing
Powered by GitBook
On this page
  • 1. Get a template
  • 2. See the output in a web browser
  • 3. Send your first Singular API request and see the payload
  • 4. Use the API to change an overlay's text
  • 5. Use the API to trigger an overlay in and out
  • Next steps

Was this helpful?

Quick start

Control your first Singular graphic with the REST API

PreviousPortal overviewNextIntroduction

Last updated 1 year ago

Was this helpful?

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

1. Get a template

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

  1. Open the.

  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.

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

  1. In the Singular Dashboard, open the Dashboard inspector and copy the Shared APP Token for the UNO Lowers | Momentum control app.

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

  3. Replace :appToken in the URL with the actual app token from step 3.2.

  4. Click Save and Send to return a payload for the UNO Lowers | Momentum control app.

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

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.

  1. Navigate to Collections > Singular REST API > Singular API v2 > App Instance API (Token) > Send Data to Control App >Update Control App Content.

  2. Select the Body tab and replace the JSON date with the code snippet from step 3.6 between the square brackets.

  3. In the JSON payload, change the text for "HEADER" and "MAIN LINE OF TEXT" to something else.

  4. Click Save.

{
    "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.

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.

  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.

{
    "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".

5. Using the same API request, change the"state" value to "Out".

Next steps

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

Under App URLs and Token, locate and copy the .

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

Open the and press Run in Postman.

Update :appToken in the URL as you did in .

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

In the payload from the GETControl App Control request in , this is the sub-composition that you'll update:

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

4. With the output URL window from 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.

Update :appToken in the URL as you did in and 4.2.

With the output URL window from visible, press Save and Send and then watch the overlay change its animation state.

In the payload from the GETControl App Control request in , this is the sub-composition that you'll update to trigger an overlay in and out.

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

4. With the output URL window from visible, copy your updated PATCH request, paste it into the command line, and press enter. Then, watch the overlay go to its Out state.

6. With the output URL window from 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 to see how Singular works and learn some key concepts. Or jump right into the .

Postman
Singular API v2 Postman collection
Singular Basics
REST APIs
step 3.4
step two
step three
step 3.2
step two
step 3.4
step two
step three
step 3.2
step two
step two
here
Singular Dashboard
Dashboard Inspector
Output URL
lower thirds
Opening the UNO Lowers | Momentum template
Locating the output URL
UNO Lowers | Momentum overlay output
Getting the Shared App Token
Locating the Get Control App Control API request
Replacing the app token in the URL
Saving and sending a request
Finding the Update Control App Content request
Updating the request body
Updating the sub-composition's text fields
Finding the Update Control App Animation State request
Updating an overlay's animation state