Control API v2 Overview

Monterosa / Interaction Cloud™ was previously known as LViS. As such, you will find API documentation using the term.
Note that Control API V1 is no longer supported.
The Control API V2 is a server-side REST API which provides programmatic interface to the platform content management functions. Using this API a server-side script can interact with the the platform in order to manage content. For example one can write a script which monitors content creation in an external CMS and automatically re-publishes articles via the platform.
Here is an example of Control API request which returns a list of events:
1
curl --request GET \
2
  --url https://environment.lvis.io/api/v2/projects/b16eaab4-f611-47e4-8a54-54fa20064cc5/events \
3
  --header 'Authorization: Bearer JmsmU5gZb6xNVUgQGoKcQLvQjRhKAUSb' \
4
  --header 'Content-Type: application/vnd.api+json'
Copied!
This responds with:
1
{
2
  "data": [
3
    {
4
      "id": "97a3bc87-3cc1-4ad9-842d-d67035badcc0",
5
      "type": "events",
6
      "attributes": {
7
        "name": "Event name",
8
        "duration": 3600,
9
        "original_duration": 3600,
10
        "start_mode": "manual",
11
        "repeat": false,
12
        "repeat_in": null,
13
        "feed_uuid": "95212462-fbf9-4acf-ab45-1078433fe75b",
14
        "live_stats_uuid": null,
15
        "extra_time": 60,
16
        "start_at": 1493218159,
17
        "start_at_iso": "2017-04-26T14:49:19Z",
18
        "end_at": 1493221759,
19
        "end_at_iso": "2017-04-26T15:49:19Z",
20
        "settings": [
21
          {
22
            "key": "tab_active",
23
            "values": {
24
              "all": null
25
            }
26
          },
27
...
Copied!
Data format
Control API adheres to JSONAPI specification.
Authentication
User needs to obtain a bearer token from top right menu / Profile Info page within Studio, and use it to authenticate each request according to The OAuth 2.0 Bearer token usage specification. Access level a script can obtain via the Control API is defined by access level of the user who owns the bearer token, i.e. if the user has access to 3 projects then the script will have access only to the same 3 projects. If you want to separate script access level from your user access level, for example you want the script to have read-only access, then you can create a new user with desired access level and user that user's access token.
Request header example
1
Authorization: Bearer mF_9.B5f-4.1JqM
Copied!
Rate limit
Only a certain number of requests can be performed to the Control API within a rate limit window.
There are two levels of rate limit:
​
​
Account-level
10 requests in 10 seconds
Global
50 requests in 10 seconds
Account-level
There is a limit on requests to the resources of the specific account.
For example, consider the following request sequence:
get projects of the account X
create an event in one of the received projects
create a manual element in that event
publish element
It will be counted as 4 requests for account X, and 6 more requests left in the current time window, no matter who produce the requests. Account Y still have 10 requests to handle.
Global
Additionally, a total number of Control API requests to the  is limited.
For example, if API calls are performed for 6 accounts simultaneously with an account-level rate limit of 10 requests in 10 seconds, the total number of the requests can reach the limit on a global level.
Response
If the rate limit is exceeded on any level, HTTP code 429 Too Many Requests is returned. Control API consumer should handle this response by implementing API requests throttling and backoff strategies.
Error response
1
HTTP/1.1 429
2
​
3
{
4
    "error": "Rate limit exceeded"
5
}
Copied!
Resource limits
Events creation limit
Default: 7. Can be increased by request.
When this number of current and future scheduled events is created within the project the Control API cannot be used to create new such events. Note that such events can still be created manually via Studio.
Error response
1
HTTP/1.1 422 Unprocessable Entity
2
​
3
{
4
    "error": "current and future events count limit is reached"
5
}
Copied!
Elements creation limit
Default: 100. Can be increased by request.
When this number of elements is created within an event the Control API cannot be used to create more elements within the event. Note that elements can still be created manually via Studio.
Error response
1
HTTP/1.1 422 Unprocessable Entity
2
​
3
{
4
    "error": "elements count limit is reached"
5
}
Copied!
Capabilities
Below is the list of functions supported by the Control API:
​
​
​
Project
View
✔
​
Create, Update and Delete
✔
Event
View
✔
​
Update
✔
​
Create
✔
​
Start
✔
​
Stop
✔
​
Delete
✘
​
Create from a template
✘
​
Clone
✘
Element
View
✔
​
Create
✔
​
Update
✔
​
Stop
✔
​
Reveal results
✔
​
Publish
✔
​
Revoke
✔
​
Reveal answer
✔
​
Delete
✘
Pagination
The Control API supports pagination for GET events requests.
The response body for such request contains links object with next and previous pages URLs.
1
"links": {
2
    "prev": "https://environment.lvis.io/api/v2/projects/55aecc98-87d4-4c42-b9c9-c8d76e924452/events?filter[state]=future&page[count]=20&page[cursor]=eyJmcm9tIjoxNTU0MzkyMTAyMDAwLCJvcmRlciI6InN0YXJ0X3RpbWUiLCJpZCI6Ijg1NyIsImZvcndhcmQiOmZhbHNlfQ",
3
    "next": "https://environment.lvis.io/api/v2/projects/55aecc98-87d4-4c42-b9c9-c8d76e924452/events?filter[state]=future&page[count]=20&page[cursor]=eyJmcm9tIjoxNTU0MzkyMTAyMDAwLCJvcmRlciI6InN0YXJ0X3RpbWUiLCJpZCI6Ijg1NyIsImZvcndhcmQiOnRydWV9"
4
}
Copied!
The response without the next or prev means that the last page in corresponding direction is reached.
To get the first page the request URL must omit page[cursor] parameter.
To change the maximum records count on page use page[count] parameter. Values between 1 and 20 are allowed. Default is 20.
File and image URLs validation
The Control API validates the format of provided URLs and returns a validation error for invalid URLs.
1
HTTP/1.1 422 Unprocessable Entity
2
​
3
{
4
  "errors": [
5
    {
6
      "detail": "invalid URL",
7
      "source": {
8
        "pointer":"/data/attributes/settings/image1/all"
9
      }
10
  ]
11
}
Copied!
Example of valid urls:
https://bucket.io/image.png
http://images.com/images/123
//d3mss.cloudfront.net/assets/1c/logo.jpeg
The Control API allows URLs with leading and trailing whitespace. Whitespace is ignored during validation and removed before saving.
Validation of images
The Control API supports pixel size, aspect ratio and file size validation of images.
Parameters and limits for validation must be defined in the app spec.
During the validation, Studio fetches the image's properties by the provided image URL and validates them according to the app spec.
In the case of Studio is not able to fetch an image's properties by the provided URL, the API returns the following error:
Error response
1
HTTP/1.1 422 Unprocessable Entity
2
​
3
{
4
  "errors": [
5
    {
6
      "detail": "unable to get image properties",
7
      "source": {
8
        "pointer":"/data/attributes/settings/image1/all"
9
      }
10
  ]
11
}
Copied!
All possible errors in the case when an uploaded image does not meet the app spec:
Error response
1
HTTP/1.1 422 Unprocessable Entity
2
​
3
{
4
  "errors": [
5
    {
6
      "detail": "image height must be between 20px and 1000px",
7
      "source": {
8
        "pointer":"/data/attributes/settings/image1/all"
9
      }
10
    },
11
    {
12
      "detail": "image width must be between 50px and 2000px",
13
      "source": {
14
        "pointer":"/data/attributes/settings/image1/all"
15
      }
16
    },
17
    {
18
      "detail": "image aspect ratio must be 7 to 5",
19
      "source": {
20
        "pointer":"/data/attributes/settings/image1/all"
21
      }
22
    },
23
    {
24
      "detail": "image file size must be less than or equal to 750KB",
25
      "source": {
26
        "pointer":"/data/attributes/settings/image1/all"
27
      }
28
    }
29
  ]
30
}
Copied!