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:
curl --request GET \
--url https://environment.lvis.io/api/v2/projects/b16eaab4-f611-47e4-8a54-54fa20064cc5/events \
--header 'Authorization: Bearer JmsmU5gZb6xNVUgQGoKcQLvQjRhKAUSb' \
--header 'Content-Type: application/vnd.api+json'
This responds with:
{
"data": [
{
"id": "97a3bc87-3cc1-4ad9-842d-d67035badcc0",
"type": "events",
"attributes": {
"name": "Event name",
"duration": 3600,
"original_duration": 3600,
"start_mode": "manual",
"repeat": false,
"repeat_in": null,
"feed_uuid": "95212462-fbf9-4acf-ab45-1078433fe75b",
"live_stats_uuid": null,
"extra_time": 60,
"start_at": 1493218159,
"start_at_iso": "2017-04-26T14:49:19Z",
"end_at": 1493221759,
"end_at_iso": "2017-04-26T15:49:19Z",
"settings": [
{
"key": "tab_active",
"values": {
"all": null
}
},
...
Authentication is done via a bearer token. Each request must include a header with a valid token like in the example below. Technical details about authentication can be found in The OAuth 2.0 Bearer token usage specification.
Authorization: Bearer mF_9.B5f-4.1JqM
To generate a token login to Monterosa / Interaction Cloud™. Hover your mouse over your username in the top right corner. From the dropdown menu choose Profile info. In the tab API Credentials you will see options to generate and revoke your token.
Every token has the same permissions as the user who generated this token, i.e. if the user has access to 3 Projects then the token will have access only to the same 3 Projects. In order to obtain a token with different permissions from your user, for example a token for read-only access, then a new user with desired access level needs to be created and then a token for this user can be generated.
A rate limit is applied to every API request. It is scoped to the authentication token, which means that every API client has an independent request count calculation.
The platform allocates a bucket of 15 requests for each authentication token. These requests can all be made within the same second or spread over time. Every second when there is no request made, 2 requests are added to the bucket, up to a maximum of 15.
Please note, current configuration values of the rate limit are provided only for a reference, and can change over time.
Proper error handling and backoff strategies should be implemented on the consumer side instead of relying on these values.
If the rate limit level is exceeded, HTTP code 429 Too Many Requests is returned. This response should be handled by implementing API requests throttling and backoff strategies.
HTTP/1.1 429
{
"error": "Rate limit exceeded"
}
Default value: 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 Events. Note that Events can still be created manually via Studio.
HTTP/1.1 422 Unprocessable Entity
{
"error": "current and future events count limit is reached"
}
Default value: 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.
HTTP/1.1 422 Unprocessable Entity
{
"error": "elements count limit is reached"
}
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 | ✘ |
The Control API supports pagination for
GET events requests.The response body for such request contains
links object with next and previous pages URLs."links": {
"prev": "https://environment.lvis.io/api/v2/projects/55aecc98-87d4-4c42-b9c9-c8d76e924452/events?filter[state]=future&page[count]=20&page[cursor]=eyJmcm9tIjoxNTU0MzkyMTAyMDAwLCJvcmRlciI6InN0YXJ0X3RpbWUiLCJpZCI6Ijg1NyIsImZvcndhcmQiOmZhbHNlfQ",
"next": "https://environment.lvis.io/api/v2/projects/55aecc98-87d4-4c42-b9c9-c8d76e924452/events?filter[state]=future&page[count]=20&page[cursor]=eyJmcm9tIjoxNTU0MzkyMTAyMDAwLCJvcmRlciI6InN0YXJ0X3RpbWUiLCJpZCI6Ijg1NyIsImZvcndhcmQiOnRydWV9"
}
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 value is 20.The Control API validates the format of provided URLs and returns a validation error for invalid URLs.
HTTP/1.1 422 Unprocessable Entity
{
"errors": [
{
"detail": "invalid URL",
"source": {
"pointer":"/data/attributes/settings/image1/all"
}
]
}
Example of valid urls:
https://bucket.io/image.pnghttp://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.
The Control API supports pixel size, aspect ratio and file size validation of images.
During the validation, Studio fetches the image's properties by the provided image URL and validates them according to the app spec.
In the cases where Studio is not able to fetch an image's properties by the provided URL, the API returns the following error:
HTTP/1.1 422 Unprocessable Entity
{
"errors": [
{
"detail": "unable to get image properties",
"source": {
"pointer":"/data/attributes/settings/image1/all"
}
]
}
All possible errors in cases when an uploaded image does not meet the app spec:
HTTP/1.1 422 Unprocessable Entity
{
"errors": [
{
"detail": "image height must be between 20px and 1000px",
"source": {
"pointer":"/data/attributes/settings/image1/all"
}
},
{
"detail": "image width must be between 50px and 2000px",
"source": {
"pointer":"/data/attributes/settings/image1/all"
}
},
{
"detail": "image aspect ratio must be 7 to 5",
"source": {
"pointer":"/data/attributes/settings/image1/all"
}
},
{
"detail": "image file size must be less than or equal to 750KB",
"source": {
"pointer":"/data/attributes/settings/image1/all"
}
}
]
}
Last modified 21d ago