Skip to content

Composition API

This section describes the endpoint /compositions with associated resources.

POST Create Composition

Create a new empty composition in your account.

Requires for authentication a Username and Password

Method URL Sample URL
POST /compositions https://app.singular.live/apiv1/compositions

REQUEST

NO PARAMETERS

REQUEST BODY

The request body are key/value pairs of properties of the app instance to create.

Parameter Description Required
name name of the new composition yes
folder folder uuid to specify the destination folder for the composition. yes

Example

1
2
3
4
{
  "folder": "4e867728-b556-4d10-8761-afecf431614b",
  "name": "composition created via REST API"
}

RESPONSE

STATUS 200 - application/json - Returns metadata of the created composition

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "user_id": 2290,
  "account_id": 56,
  "tenant_id": null,
  "name": "composition created via REST API",
  "firebaseUrl": "https://fiery-torch-2122.firebaseio.com/users/2290/channels/-LKlWtAmlkf9OsOySL4b",
  "category": "default",
  "fid": "ada41bfb-4d11-446d-a1e1-93b934ea7bf4",
  "updated_at": "2018-08-25T14:40:35.087Z",
  "created_at": "2018-08-25T14:40:35.087Z",
  "id": 89416,
  "refId": 89416,
  "type": "composition"
}

STATUS 401 Returned if authorisation failed.

PUT Update Thumbnail of Composition

Update the thumbnail of a composition and upload the image to the Singular cloud.

Requires for authentication a Username and Password

Method URL Sample URL
PUT https://app.singular.live/apiv1/compositions/{composition_id}/thumbnail https://app.singular.live/apiv1/appinstances/36766/composition

REQUEST

PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes

REQUEST BODY

The request body is defined as form data in key/value pairs.

Key Value Required
name file yes
file local thumbnail file to upload yes

RESPONSE

STATUS 200 - application/json - Returns the URL to the uploaded thumbnail.

1
"//images-singularlive.wixmp.com/356a192b7913b04c54574d18c28d46e6395428ab/images/08f7d1ebfbff4e95bee93d17d9bcfac3~mv2/v1/fit/w_150,h_150/39ae4e53c99c9b5fd29fe79fd6e6b962.png#w_116,h_102,mt_image%2Fpng"

STATUS 400 Bad Request: Returned if the request body is wrong.

STATUS 401 Returned if authorisation failed.

STATUS 500 Internal Server Error if image format is not supported.

1
2
3
4
5
6
{
  "error": {
    "message": "File upload failed: {\"error_code\":-7751,\"error_description\":\"Not allowed file extension .webp for media_type picture\",\"error_info\":{\"message\":\"Not allowed file extension {0} for media_type {1}\",\"args\":[\".webp\",\"picture\"],\"key\":\"wpm_error.unsupported_file_extension\"}}",
    "code": 500
  }
}

GET List all Compositions

Return a list of all compositions in the acount with the specified user credientials.

Requires for authentication a Username and Password.

Method URL Sample URL
GET /compositions https://app.singular.live/apiv1/compositions

REQUEST

No query parameters

RESPONSE

STATUS 200 - application/json - Returns an array with full JSON representation of composition properties

EXAMPLE

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
[
  {
    "id": 85836,
    "account_id": 56,
    "tenant_id": null,
    "user_id": 2290,
    "is_deleted": 0,
    "fid": "13285e6b-ee31-482c-b9d2-044cc80f669f",
    "uuid": null,
    "name": "Comp-for-DevDocs-Green",
    "firebaseUrl": "https://fiery-torch-2122.firebaseio.com/users/2290/channels/-LK7-3jWdfPg-iV7h1rR",
    "thumbnail": "//images-singularlive.wixmp.com/356a192b7913b04c54574d18c28d46e6395428ab/images/e295f79b37ac46ee90d79bf39b69a2ba~mv2/v1/fit/w_150,h_150/3f2a882f56eaec211724d8df68835f6f.png#w_151,h_85,mt_image%2Fpng",
    "category": "default",
    "updated_at": "2018-08-24T19:56:19.000Z",
    "created_at": "2018-08-17T13:08:24.000Z",
    "deleted_at": null,
    "is_deleted_depend": null
  },
  {
    "id": 85834,
    "account_id": 56,
    "tenant_id": null,
    "user_id": 2290,
    "is_deleted": 0,
    "fid": "b8c32a00-d3db-49c6-b462-4a27318c3348",
    "uuid": null,
    "name": "Comp-for-DevDocs-Blue",
    "firebaseUrl": "https://fiery-torch-2122.firebaseio.com/users/2290/channels/-LK6VBJKfomRmhME0p4P",
    "thumbnail": "//images-singularlive.wixmp.com/356a192b7913b04c54574d18c28d46e6395428ab/images/c6924113560345e4be15a4472b7c648c~mv2/v1/fit/w_150,h_150/7435edf778b68e42fa3b268e16967292.png#w_490,h_276,mt_image%2Fpng",
    "category": "default",
    "updated_at": "2018-08-24T19:55:31.000Z",
    "created_at": "2018-08-17T10:49:06.000Z",
    "deleted_at": null,
    "is_deleted_depend": null
  }
]

STATUS 401 Returned if authorisation failed.

EXAMPLE

1
2
3
4
5
6
{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}

GET List Properties of a Composition

Return the properties of one specific composition.

Requires for authentication a Username and Password.

Method URL Sample URL
GET /compositions/{composition_id} https://app.singular.live/apiv1/compositions/85836

REQUEST

QUERY PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes

RESPONSE

STATUS 200 - application/json - Returns full JSON representation of the composition properties

EXAMPLE

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "id": 85836,
  "account_id": 56,
  "tenant_id": null,
  "user_id": 2290,
  "is_deleted": 0,
  "fid": "13285e6b-ee31-482c-b9d2-044cc80f669f",
  "uuid": null,
  "name": "Comp-for-DevDocs-Green",
  "firebaseUrl": "https://fiery-torch-2122.firebaseio.com/users/2290/channels/-LK7-3jWdfPg-iV7h1rR",
  "thumbnail": "//images-singularlive.wixmp.com/356a192b7913b04c54574d18c28d46e6395428ab/images/e295f79b37ac46ee90d79bf39b69a2ba~mv2/v1/fit/w_150,h_150/3f2a882f56eaec211724d8df68835f6f.png#w_151,h_85,mt_image%2Fpng",
  "category": "default",
  "updated_at": "2018-08-24T19:56:19.000Z",
  "created_at": "2018-08-17T13:08:24.000Z",
  "deleted_at": null,
  "is_deleted_depend": null
}

STATUS 401 Returned if authorisation failed.

STATUS 404 Returned if composition id undefined or not found.

GET List full JSON Representation of a Composition

Return the full JSON representation of one specific composition.

Requires for authentication a Username and Password.

Method URL Sample URL
GET /compositions/{composition_id}/content https://app.singular.live/apiv1/compositions/85836/content

REQUEST

QUERY PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes

RESPONSE

STATUS 200 - application/json - Returns full JSON representation of the composition properties

EXAMPLE: The JSON below is a subset only of the full JSON representation of a composition

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
{
    "command": {
        "commands": [
            {
                "name": "play2",
                "target": "d247fb90-22a0-4250-8a3a-2dedaef1fba0",
                "to": "In"
            }
        ],
        "id": 0.4242396286082777
    },
    "compositionProps": {
        "logicLayers": {
            "6437a497-27c5-9246-b06d-1ae353844fc2": {
                "name": "Background",
                "tag": "#e53935"

            }
        },
        "timeline2Active": {
            "-Kn25RyfewL29LigHvV1": false,
            "-KnWhELPgM8j-suGHRjs": true,
            "-KnXXbHZpD6sKVP4iHCD": true,
            "6437a497-27c5-9246-b06d-1ae353844fc2": false,
            "68c3003e-e569-5caf-cb41-201d53ecf634": true,
            "d247fb90-22a0-4250-8a3a-2dedaef1fba0": false
        }
    },
    "compositionStates": {
        "-Kn25RyfewL29LigHvV1": "Out1",
        "-KnXXbHZpD6sKVP4iHCD": "Out1",
        "6437a497-27c5-9246-b06d-1ae353844fc2": "In",
        "c053332b-bf54-48f4-ab40-0da1cf980384": "Out2",
        "d247fb90-22a0-4250-8a3a-2dedaef1fba0": "In"
    },
    "compositions": {
        "-LK7-3jWdfPg-iV7h1rR": {
            "dataSources": {
                "composition": {
                    "controlNode": {
                        "id": "controlNode",
                        "name": "Control Node",
                        "thumbnail": "/images/noimage.png"
                    }
                }
            },
            "groups": {
                "-Kn25RyjJKPpZOxmIez1": {
                    "effects": {
                        "In": {
                            "easing": {
                                "easing": "power1",


>>> ...more details ... <<<


                }
            }
        }
    },
    "editingIds": {
        "00f36f4f-e2e3-4612-8012-7c37332b0c8e": true
    },
    "mainComposition": "-LK7-3jWdfPg-iV7h1rR",
    "revision": "4",
    "uiSettings": {
        "disableTimelineUpdate": true,
        "editorResolution": 0,
        "editorResolutionHeight": 1080,
        "editorResolutionWidth": 1920,
        "showBoundingBox": true,
        "timelineSnap": "grid",
        "timelineZoom": 2
    }
}

STATUS 401 Returned if authorisation failed.

STATUS 404 Returned if composition id undefined or not found.

GET List Subcompositions of a Composition

Return all subcompositions of one specific composition.

Requires for authentication a Username and Password.

Method URL Sample URL
GET /compositions/{composition_id}/subcompositions https://app.singular.live/apiv1/compositions/85836/subcompositions

REQUEST

QUERY PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes

RESPONSE

STATUS 200 - application/json - Returns an array with full JSON representation of all subcompositions in a composition

EXAMPLE:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "data": [
    {
      "id": "6437a497-27c5-9246-b06d-1ae353844fc2",
      "name": "Background Image",
      "state": "In"
    },
    {
      "id": "68c3003e-e569-5caf-cb41-201d53ecf634",
      "name": "Panel Left",
      "state": "In"
    },
    {
      "id": "7e07a5d6-b50f-47b2-b036-d39033d109f7",
      "name": "Lower Topic",
      "state": "In"
    },
    {
      "id": "ba8b75bc-e122-973f-04a7-8ff799ae41aa",
      "name": "Fullscreen Title",
      "state": "Out"
    },
    {
      "id": "c053332b-bf54-48f4-ab40-0da1cf980384",
      "name": "Lower Line",
      "state": "Out"
    },
    {
      "id": "d247fb90-22a0-4250-8a3a-2dedaef1fba0",
      "name": "Baseline Crawl",
      "state": "In"
    }
  ]
}

STATUS 401 Returned if authorisation failed.

STATUS 404 Returned if composition id undefined or not found.

POST Create a Copy of Composition

Create a copy of a composition.

Requires for authentication a Username and Password

Method URL Sample URL
POST /compositions/{composition_id}/duplicate https://app.singular.live/apiv1/compositions/85836/duplicate

REQUEST

QUERY PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes

REQUEST BODY

The request body are key/value pairs of properties of the app instance to create.

Parameter Description Required
folder folder uuid to specify the destination folder for the composition. yes

Example

1
2
3
{
  "folder": "4e867728-b556-4d10-8761-afecf431614b"
}

RESPONSE

STATUS 200 - application/json - Returns metadata of the duplicated composition

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "user_id": 2290,
  "account_id": 56,
  "tenant_id": null,
  "name": "Copy of Comp-for-DevDocs-Green",
  "firebaseUrl": "https://fiery-torch-2122.firebaseio.com/users/2290/channels/-LKlYR_uMlMq4v8kqkYo",
  "category": "default",
  "thumbnail": "//images-singularlive.wixmp.com/356a192b7913b04c54574d18c28d46e6395428ab/images/e295f79b37ac46ee90d79bf39b69a2ba~mv2/v1/fit/w_150,h_150/3f2a882f56eaec211724d8df68835f6f.png#w_151,h_85,mt_image%2Fpng",
  "fid": "6c37baa6-6380-466d-82ae-3bd0aa0379b6",
  "updated_at": "2018-08-25T14:47:22.299Z",
  "created_at": "2018-08-25T14:47:22.299Z",
  "id": 89418,
  "refId": 89418,
  "type": "composition"
}

STATUS 401 Returned if authorisation failed.

POST Send a Copy of Composition to another User

Create a copy of a composition and send it to another user.

Requires for authentication a Username and Password

Method URL Sample URL
POST /compositions/duplicateto https://app.singular.live/apiv1/compositions/duplicateto

REQUEST

No query parameters

REQUEST BODY

The request body are key/value pairs of properties of the app instance to create.

Parameter Description Required
compId id of the composition to send yes
targetEmail id of the composition to send yes

Example

1
2
3
4
{
  "compId": 85836,
  "targetEmail": "user@domain.live"
}

RESPONSE

STATUS 200 - application/json - Returns metadata of the sent composition

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "account_id": 1,
  "tenant_id": null,
  "user_id": 152,
  "is_deleted": 0,
  "fid": "97b383fa-f86c-4e08-8b3b-adb1c3d8c5cf",
  "name": "Comp-for-DevDocs-Green",
  "firebaseUrl": "https://fiery-torch-2122.firebaseio.com/users/152/channels/-LKm_lZiY4Zhtu9vawtU",
  "thumbnail": "//images-singularlive.wixmp.com/356a192b7913b04c54574d18c28d46e6395428ab/images/e295f79b37ac46ee90d79bf39b69a2ba~mv2/v1/fit/w_150,h_150/3f2a882f56eaec211724d8df68835f6f.png#w_151,h_85,mt_image%2Fpng",
  "category": "default",
  "updated_at": "2018-08-25T19:37:09.704Z",
  "created_at": "2018-08-25T19:37:09.704Z",
  "deleted_at": null,
  "is_deleted_depend": null,
  "id": 89606
}

STATUS 401 Returned if authorisation failed.

POST Create a new Revision of a Composition

Create a new revision of the current state of a specific composition.

Requires for authentication a Username and Password.

Method URL Sample URL
POST /compositions/{composition_id}/revisions https://app.singular.live/apiv1/compositions/85836/revisions

REQUEST

QUERY PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes

The request body are key/value pairs of properties for the revision to create.

Parameter Description Required
scene_id composition_id of the composition yes
revision_id id of the revision to create or to update yes
description description for the revision yes

Example

1
2
3
4
5
{
  "scene_id": 85836,
  "revision_id": 2,
  "description": "2018-08-20: Backup 2 (DevDocs-Green)"
}

RESPONSE

STATUS 200 - application/json - Returns JSON with status information.

EXAMPLE

1
2
3
{
  "status": "success"
}

STATUS 401 Returned if authorisation failed.

STATUS 404 Returned if composition id undefined or not found.

GET List Revisions of a Composition

Return a list of all revisions of one specific composition.

Requires for authentication a Username and Password.

Method URL Sample URL
GET /compositions/{composition_id}/revisions https://app.singular.live/apiv1/compositions/85836/revisions

REQUEST

QUERY PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes

RESPONSE

STATUS 200 - application/json - Returns a JSON representation of revisions of the composition

EXAMPLE

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
[
  {
    "id": 5274,
    "account_id": 56,
    "scene_id": 85836,
    "revision_id": 1,
    "user_id": 2290,
    "description": "2018-08-20: Backup 1 (DevDocs-Green)",
    "firebaseUrl": "",
    "storageUrl": "https://static-singularlive.wixmp.com/356a192b7913b04c54574d18c28d46e6395428ab/static/430d4d67d43644b794545273813f62cf/file.json",
    "comp_extract_json": null,
    "subcomposition_names": null,
    "updated_at": "2018-08-25T14:56:15.000Z",
    "created_at": "2018-08-25T14:56:15.000Z",
    "user_email": "apisdk@singular.live"
  }
]

STATUS 401 Returned if authorisation failed.

STATUS 404 Returned if composition id undefined or not found.

GET List Content of a Revisions of a Composition

Return the full JSON representation of a specific revisions of a composition.

Requires for authentication a Username and Password.

Method URL Sample URL
GET /compositions/{composition_id}/revisions/{revision_id}/content https://app.singular.live/apiv1/compositions/85836/revisions/5274/content

REQUEST

QUERY PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes
{revision_id} The Id of the revision yes

RESPONSE

STATUS 200 - application/json - Returns the full JSON representation of a revisions of a composition

EXAMPLE: The JSON below is a subset only of the full JSON representation of the revision of a composition

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
{
    "command": {
        "commands": [
            {
                "name": "play2",
                "target": "d247fb90-22a0-4250-8a3a-2dedaef1fba0",
                "to": "In"
            }
        ],
        "id": 0.4242396286082777
    },
    "compositionProps": {
        "logicLayers": {
            "6437a497-27c5-9246-b06d-1ae353844fc2": {
                "name": "Background",
                "tag": "#e53935"

            }
        },
        "timeline2Active": {
            "-Kn25RyfewL29LigHvV1": false,
            "-KnWhELPgM8j-suGHRjs": true,
            "-KnXXbHZpD6sKVP4iHCD": true,
            "6437a497-27c5-9246-b06d-1ae353844fc2": false,
            "68c3003e-e569-5caf-cb41-201d53ecf634": true,
            "d247fb90-22a0-4250-8a3a-2dedaef1fba0": false
        }
    },
    "compositionStates": {
        "-Kn25RyfewL29LigHvV1": "Out1",
        "-KnXXbHZpD6sKVP4iHCD": "Out1",
        "6437a497-27c5-9246-b06d-1ae353844fc2": "In",
        "c053332b-bf54-48f4-ab40-0da1cf980384": "Out2",
        "d247fb90-22a0-4250-8a3a-2dedaef1fba0": "In"
    },
    "compositions": {
        "-LK7-3jWdfPg-iV7h1rR": {
            "dataSources": {
                "composition": {
                    "controlNode": {
                        "id": "controlNode",
                        "name": "Control Node",
                        "thumbnail": "/images/noimage.png"
                    }
                }
            },
            "groups": {
                "-Kn25RyjJKPpZOxmIez1": {
                    "effects": {
                        "In": {
                            "easing": {
                                "easing": "power1",


>>> ...more details ... <<<


                }
            }
        }
    },
    "editingIds": {
        "00f36f4f-e2e3-4612-8012-7c37332b0c8e": true
    },
    "mainComposition": "-LK7-3jWdfPg-iV7h1rR",
    "revision": "4",
    "uiSettings": {
        "disableTimelineUpdate": true,
        "editorResolution": 0,
        "editorResolutionHeight": 1080,
        "editorResolutionWidth": 1920,
        "showBoundingBox": true,
        "timelineSnap": "grid",
        "timelineZoom": 2
    }
}

STATUS 401 Returned if authorisation failed.

STATUS 404 Returned if the revision id or the composition id is undefined or not found.

POST Create Access Token for a Composition

Create a new access token for a specified composition.

Requires for authentication a Username and Password.

Method URL Sample URL
POST /compositions/{composition_id}/revisions https://app.singular.live/apiv1/compositions/85836/token

REQUEST

QUERY PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes

RESPONSE

STATUS 200 - application/json - Returns a JSON with composition id and access token.

EXAMPLE

1
2
3
4
{
  "id": 85836,
  "uuid": "1XcjscQLzO9przEaT2JU9s"
}

STATUS 401 Returned if authorisation failed.

STATUS 404 Returned if composition id undefined or not found.

GET Show Access Token of a Composition

Return a list of all revisions of one specific composition.

Requires for authentication a Username and Password.

Method URL Sample URL
GET /compositions/{composition_id}/revisions https://app.singular.live/apiv1/compositions/85836/token

REQUEST

QUERY PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes

RESPONSE

STATUS 200 - application/json - Returns a JSON with composition id and access token

EXAMPLE

1
2
3
4
{
  "id": 85836,
  "uuid": "1XcjscQLzO9przEaT2JU9s"
}

STATUS 401 Returned if authorisation failed.

STATUS 404 Returned if composition id undefined or not found.

DELETE Delete a Revision of a Composition

Delete a fevision of a composition in your account.

Requires for authentication a Username and Password

Method URL Sample URL
DELETE /compositions/{composition_id}/revisions/{revision_id}] https://app.singular.live/apiv1/compositions/85836/revisions/12345

REQUEST

QUERY PARAMETERS

Parameter Description Required
{composition_id} The Id of the composition yes
{revision_id} The Id of the revision yes

RESPONSE

STATUS 200 - application/json - Returns Ok

1
"success"

STATUS 401 Returned if authorisation failed.

STATUS 404 Returned if the revision id or the composition id is undefined or not found.