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
  • Get control app model
  • Response definitions
  • Model content
  • logicLayer content

Was this helpful?

  1. REST API
  2. API reference
  3. Get control app details

Get a control app's model

Get control app model

GET https://app.singular.live/apiv2/controlapps/:appToken/model

Returns the model of a control app instance, including the content, type, and structure of its controllable elements. Can be used to build a user interface.

Path Parameters

Name
Type
Description

appToken*

String

[
  {
    "id": "-NC_s8grzroliz2xbx7e",
    "name": "default",
    "model": [],
    "logicLayer": null,
    "snapshot": null,
    "subcompositions": [
      {
        "id": "1695dbd7-430c-40eb-82f7-85287a965849",
        "name": "compTextArea",
        "state": "Out",
        "model": [
          {
            "defaultValue": "Multi-line Text \nfrom Google Sheet",
            "id": "text-area-control-node-id",
            "immediateUpdate": false,
            "index": 1,
            "resetValue": "Default Text",
            "title": "text-area-control-node-id",
            "type": "textarea"
          }
        ],
        "logicLayer": null,
        "snapshot": null,
        "subcompositions": []
      },
      {
        "id": "1e602003-5bfa-45f4-8049-8892220fdff2",
        "name": "compTimer",
        "state": "Out",
        "model": [
          {
            "defaultValue": {
              "UTC": 1615816679354,
              "isRunning": false,
              "value": 0
            },
            "id": "time-control-node-id",
            "immediateUpdate": true,
            "index": 0,
            "resetValue": {
              "UTC": 0,
              "isRunning": false,
              "value": 0
            },
            "title": "time-control-node-id",
            "type": "timecontrol"
          }
        ],
        "logicLayer": null,
        "snapshot": null,
        "subcompositions": []
      },
      {
        "id": "41aaf130-468c-4f11-9bca-c1ea68ba1c8b",
        "name": "compColor",
        "state": "Out",
        "model": [
          {
            "defaultValue": {
              "a": 1,
              "b": 156,
              "g": 188,
              "r": 26
            },
            "id": "color-control-node-id",
            "immediateUpdate": false,
            "index": 2,
            "resetValue": {
              "a": 1,
              "b": 255,
              "g": 255,
              "r": 255
            },
            "title": "color-control-node-id",
            "type": "color"
          },
          {
            "defaultValue": "crimson",
            "id": "cnColorText",
            "immediateUpdate": false,
            "index": 1,
            "resetValue": "Default Text",
            "title": "cnColorText",
            "type": "text"
          }
        ],
        "logicLayer": null,
        "snapshot": null,
        "subcompositions": []
      },
      {
        "id": "755bd36f-fff0-4250-b703-4cbd310f07fb",
        "name": "compVideoClip",
        "state": "Out",
        "model": [
          {
            "defaultValue": {
              "__singularButton": true,
              "ts": 0
            },
            "id": "cnVideoClipPause",
            "immediateUpdate": true,
            "index": 2,
            "resetValue": {
              "__singularButton": true,
              "ts": 0
            },
            "title": "cnVideoClipPause",
            "type": "button"
          },
          {
            "defaultValue": {
              "__singularButton": true,
              "ts": 0
            },
            "id": "cnVideoClipPlay",
            "immediateUpdate": true,
            "index": 1,
            "resetValue": {
              "__singularButton": true,
              "ts": 0
            },
            "title": "cnVideoClipPlay",
            "type": "button"
          },
          {
            "defaultValue": {
              "__singularButton": true,
              "ts": 0
            },
            "id": "cnVideoClipStart",
            "immediateUpdate": true,
            "index": 0,
            "resetValue": {
              "__singularButton": true,
              "ts": 0
            },
            "title": "cnVideoClipStart",
            "type": "button"
          }
        ],
        "logicLayer": null,
        "snapshot": null,
        "subcompositions": []
      },
      {
        "id": "7ccc118d-5333-474d-9a33-b5fb951cd765",
        "name": "compJsonTable",
        "state": "Out",
        "model": [
          {
            "defaultValue": "{\"content\": [\r\n    {\"pos\": \"1\", \"name\": \"NYG\", \"image\": \"https://image.singular.live/f12f184c9a0eb763beb40478e02a1250/images/4BhR3iwVI7oTpuMPQFSNBE.png\"},\r\n    {\"pos\": \"2\", \"name\": \"SF\", \"image\": \"https://image.singular.live/f12f184c9a0eb763beb40478e02a1250/images/1PpN2FpuAutk3zeYILkDum.png\"},\r\n    {\"pos\": \"3\", \"name\": \"DEN\", \"image\": \"https://image.singular.live/f12f184c9a0eb763beb40478e02a1250/images/7Mg4XYFRQWiwT5IKIoH1E7.png\"},\r\n    {\"pos\": \"4\", \"name\": \"PIT\", \"image\": \"https://image.singular.live/f12f184c9a0eb763beb40478e02a1250/images/5K84dUL3ACt2l4pCCfwRP4.png\"}\r\n  ]\r\n}",
            "height": "100px",
            "id": "json-control-node-id",
            "immediateUpdate": false,
            "index": 0,
            "resetValue": "{}",
            "title": "json-control-node-id",
            "type": "json"
          }
        ],
        "logicLayer": null,
        "snapshot": null,
        "subcompositions": []
      },
      {
        "id": "816df4ac-3231-49a2-b744-ccd48aa33a40",
        "name": "compText",
        "state": "Out",
        "model": [
          {
            "defaultValue": "Text from Google Sheet",
            "id": "text-control-node-id",
            "immediateUpdate": false,
            "index": 0,
            "resetValue": "Default Text",
            "title": "text-control-node-id",
            "type": "text"
          }
        ],
        "logicLayer": null,
        "snapshot": null,
        "subcompositions": []
      },
      {
        "id": "9d0ebd84-bdae-6adc-2050-d54c36448d70",
        "name": "background",
        "state": "Out",
        "model": [],
        "logicLayer": {
          "name": "Background",
          "tag": "#5e35b1"
        },
        "snapshot": null,
        "subcompositions": []
      },
      {
        "id": "ab6e39f9-5550-47c2-81be-fa07611a6666",
        "name": "compCheckbox",
        "state": "Out",
        "model": [
          {
            "defaultValue": true,
            "id": "checkbox-control-node-id",
            "immediateUpdate": false,
            "index": 0,
            "resetValue": true,
            "title": "checkbox-control-node-id",
            "type": "checkbox"
          }
        ],
        "logicLayer": null,
        "snapshot": null,
        "subcompositions": []
      },
      {
        "id": "ca6f12cf-d990-464b-948b-5d7ad9dd3d33",
        "name": "compNumber",
        "state": "Out",
        "model": [
          {
            "defaultValue": "1234.56",
            "id": "number-control-node-id",
            "immediateUpdate": false,
            "index": 0,
            "resetValue": 0,
            "step": "0.01",
            "title": "number-control-node-id",
            "type": "number"
          },
          {
            "defaultValue": "$1,234.56",
            "id": "cnNumberDisplayed",
            "immediateUpdate": false,
            "index": 1,
            "resetValue": "Default Text",
            "title": "cnNumberDisplayed",
            "type": "text"
          }
        ],
        "logicLayer": null,
        "snapshot": null,
        "subcompositions": []
      }
    ]
  }
]

Response definitions

The following table describes the top level key-value pairs for a sub-composition in the Get control app model request.

Response item
Description
Data type

id

Composition ID or sub-composition ID, depending where it is in the hierarchy.

String

name

Composition name or sub-composition name, depending where it is in the hierarchy.

String

state

The in/out state of a sub-composition. Supported values: In, Out, Out1, Out2. In and Out are default. When there are multiple timelines, Out1 plays in reverse of the In animation. Out2 defines a separate Out animation.

String

model

Array

logicLayer

Object

snapshot

The URL of the snapshot shown when hovering over a sub-composition in the composition tree in Composer. Generate and invoke them from camera icon in Composer's preview toolbar.

URL

subcompositions

An array of sub-compositions (if any) nested within a composition or sub-composition.

Array

Model content

The key-value pairs within the model array.

defaultValue

The sub-composition's default value. Defined in the overlay's composition.

String, Integer, Object

id

The Model ID.

String

immediateUpdate

A flag used by control applications to immediately send data.

Boolean

index

Defines the control node field's position in the hierarchy of control nodes fields. 0 is the top position.

Number

resetValue

The sub-composition's reset value. Defined in the overlay's composition.

String, Integer, Object

title

The title of the control node field in Composer.

String

type

Field type. Supported values: text, textarea, number, image, color, checkbox, audio, json, timecontrol, button.

String

Field types

Type
Description
Data type

text

The field type for a single of text.

String

textarea

The field type for multi-line text.

String

number

The field type for a number.

Integer

image

The field type for an image.

URL

color

The field type for a color.

Object, String

checkbox

The field type for a checkbox.

Boolean

audio

The field type for an audio file.

URL

json

The field type for JSON data.

Object

timecontrol

The field type for a timer.

Object

button

The field type for a button.

Object

logicLayer content

The content within the logicLayer object.

Response item
Description
Data type

name

The logic layer's name.

String

delay

The logic later's delay type as defined in the composition. Supported values: none, auto, custom.

String

tag

The hex color value assigned to the logic layer. Example: #e53935

String

PreviousGet a control app's metadataNextGet a control app's control data

Last updated 2 years ago

Was this helpful?

The shared app token for the app. This is a unique token for this app instance. .

The sub-composition's model. It contains a defaultValue, id, immediateUpdate, index, resetValue, title, and type. See the below for descriptions.

The sub-compositions assigned logic layer, if any; default is null. See the below for a description of its content.

How to find the shared app token
model content table
logicLayer content table