Integration API Reference
REST API reference for communicating with Skylight from an external app.
The base url is https://api.skylight.upskill.io (substitute your own host for skylight.upskill.io if applicable).
All of the API methods require an access token. To retrieve an access token, call the POST endpoint:
/v1/authentication/login/realms/{realm}
where
{realm}
is replaced with the name of your realm. This request should have the following body parameters:{
username: <string>,
password: <string>,
realm: <string> // This realm should match the realm in the URL
}
For a successful login, the API will return the access token as part of the response JSON :
{
access_token: <string>,
expires_in: <number>, // How long the access token is valid, in seconds
refresh_token: <string>,
refresh_expires_in: <number> // How long the refresh toaken is valid, in seconds
}
Though any account's credentials can be used to retrieve a token, the ability to use certain API methods may be limited by the user's roles for the application of interest.
If the access token expires, the refresh token can be used to refresh the access token by calling the following POST endpoint:
/v1/authentication/token/refresh
This request takes a single body parameter:
{
refreshToken: <string> // The refresh token from the login response
}
The response JSON data will contain the same fields as a successful login.
To authorize calls to Skylight API methods, every call should have the following value set for the
Authorization
request headerBearer: {access_token}
where
{access_token}
is the access token retrieved from the login process.The access token is also used to authorize MQTT subscriptions. Skylight's MQTT broker is accessible at the following:
URL: ssl://mqtt.skylight.upskill.io
Port: 8883
​
(substitute your own host for skylight.upskill.io if applicable)
To set up the connection, the following MQTT client options should be used:
- Client ID:
{realm}-{accessToken.sub}-{8 random digits}
{realm}
should be replaced with your realm{accessToken.sub}
is the subject of the access token. To retrieve the subject, the access token from the login step should be processed by the JWT library.- The random digits at the end of the ID distinguish this client from other clients. Using the same sequence of digits when reconnecting with the same access token will retrieve any messages in the broker's queue that were received while this client was unavailable.
- Username:
{realm}/{accessToken.sub}
- See the section on the Client ID for information about the
{realm}
and{accessToken.sub}
parameters
- Password:
{accessToken.rawData}
{accessToken.rawData}
is the raw value of the access token that was in the login response. This is the same value that is used as the authorization header's bearer token for API calls.
- Use TLS 1.2 as the SSL protocol when connecting to Skylight's MQTT broker.
Subscribe to the following MQTT topic to receive session events:
v1/realms/{realm}/users/{accessToken.sub}/session/#
{realm}
should be replaced with your realm and {accessToken.sub}
is the access token's subject, which can be retrieved by using a JWT library to process the access token in the login response.400: Bad Request.
401: Unauthorized.
This is a response common to all API calls to indicate that the caller has not provided the required authentication tokens or the token is invalid.
Example:
{
"error": "No authorization token found"
}
403: Forbidden.
User is not authorized to perform the requested action on the specified resource.
404: Not found.
The requested item was not found having the specified parameters.
Returns a list of application sessions
Request Parameters
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Query | {prop.*} | string | Properties are useful for doing dynamic filtering on arbitrary properties for all items. All values for each key must be in comma separated list format. The resulting items are determined through at least one valid key/value pair match. If you want to filter for multiple values for a specific key, pass multiple values as a comma-delimited list. Example: prop.department=A,B You can do more advanced filtering with multiple key/value pair combinations. Different desired keys filters will be combined with an AND. Multiple property filters for prop1 and prop2 would look like this -- ?prop.department=A,B&prop.deviceType=HUD |
Query | status | string | Session status; valid values: open, closed |
Query | participants | string | Filter by comma-separated list of participant IDs |
Query | name | string | Filter by session name |
Query | limit | integer | Max number of items per page. Valid range: 1-200. Default: 50 |
Query | sort | string | Name of the paginated field to sort by. Ascending by default. Prefix with '-' to indicate descending. Default: creation order. Available values: name, createdAt, modifiedAt |
Query | nextCursor | string | Enables the service to return the next page of items. Supply this or prevCursor. If both are supplied, prevCursor is ignored. If neither are supplied, pagination is reset, and the first page will be returned. |
Query | prevCursor | string | Enables the service to return the previous page of items. Supply this or nextCursor. If both are supplied, prevCursor is ignored. If neither are supplied, pagination is reset, and the first page will be returned. |
Query | createdBy | string | Comma-separated list of user ids to filter by createdBy field. |
Query | modifiedBy | string | Comma-separated list of user ids to filter by modifiedBy field. |
Query | createdFrom | string($date-time) | The oldest created date/time when entity has been created. |
Query | createdTo | string($date-time} | The latest created date/time when entity has been created. |
Query | modifiedFrom | string($date-time) | The oldest date/time when entity has been modified. |
Query | modifiedTo | string($date-time) | The latest date/time when entity has been modified. |
Example Request URL:
https://api.skylight.upskill.io/v1/application/applications/5fbd8ebfcee428353b0dc8de/sessions?%7Bprop.%2A%7D=prop.department%3DA%2CB&limit=50&sort=_id
200: Ok
Example Response Body:
{
"data": [
{
"sessionId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"applicationId": "string",
"version": 1,
"name": "string",
"description": "string",
"participants": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "user",
"isGuest": true
}
],
"status": "open",
"properties": {
"productId": "ABC-123",
"orderId": 123456
},
"createdBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"createdAt": "2020-12-11T16:53:14.081Z",
"modifiedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"modifiedAt": "2020-12-11T16:53:14.081Z",
"isDraft": true
}
],
"page": {
"count": 0,
"limit": 0,
"total": 0,
"prevCursor": "string",
"nextCursor": "string"
}
}
Creates an application session
Request Parameters
Request Body
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Header | deviceid | string | used for looking up against the device database for specifics of the users device this event was generated from |
Header | devicetimestamp | string($date-time) | The RFC 3339 client device timestamp |
Header | content-type | string | set to application/json |
​
Name | Value Type | Value Description |
version* | integer | Application Version number; Minimum : 1 |
name | string | User-friendly session name; maxLength 255 |
description | string | Description of session; maxLength 1000 |
participants* | array | Session participant(s). |
​ | ​ | type* : string; valid values: user, group |
​ | ​ | id*: string; the id of the user or group |
​ | ​ | isGuest: boolean; default is false |
status | string | Session status; valid values: open or closed; default : open |
properties | object | Object used for classification and item specific information. Properties values are searchable and indexed. nullable: true; maxProperties: 50; example: { "productID": "ABC-123", "orderId": 123456 } |
Example
{
"version": 1,
"name": "string",
"description": "string",
"participants": [
{
"type": "user",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
"isGuest": true
}
],
"status": "open",
"properties": {
"productId": "ABC-123",
"orderId": 123456
}
}
201: Created
{
"sessionId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"applicationId": "string",
"version": 1,
"name": "string",
"description": "string",
"participants": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "user",
"isGuest": true
}
],
"status": "open",
"properties": {
"productId": "ABC-123",
"orderId": 123456
},
"createdBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"createdAt": "2020-12-11T15:26:00.482Z",
"modifiedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"modifiedAt": "2020-12-11T15:26:00.482Z",
"isDraft": true
}
Returns a session by Id
Request Parameters
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Path | sessionId* | string($uuid) | ID for the requested session |
Example Request URL:
https://api.skylight.upskill.io/v1/application/applications/5fbd8ebfcee428353b0dc8de/sessions/e78fa929-627a-459d-bb57-0a96b98cb11f
200: Ok
Example Response Body:
{
"sessionId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"applicationId": "string",
"version": 1,
"name": "string",
"description": "string",
"participants": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "user",
"isGuest": true
}
],
"status": "open",
"properties": {
"productId": "ABC-123",
"orderId": 123456
},
"createdBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"createdAt": "2020-12-11T19:05:43.826Z",
"modifiedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"modifiedAt": "2020-12-11T19:05:43.826Z",
"isDraft": true
}
Update part of the session
Request Parameters
Request Body
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Path | sessionId* | string($uuid) | ID for this session |
Header | deviceid | string | used for looking up against the device database for specifics of the users device this event was generated from |
Header | devicetimestamp | string($date-time) | The RFC3339 client deviceTimestamp |
​
Name | Value Type | Value Description |
version | integer | Application Version Number. Minimum: 1. |
name | string | User-friendly session name. maxLength: 255 |
description | string | Description of the session. maxLength: 1000 |
participants | array | Session participant(s). |
​ | ​ | type* : string ; valid values: user, group |
​ | ​ | id*: string ; the id of the user or group |
​ | ​ | isGuest: boolean ; default : false. |
status | string | Session status; valid values: open, closed |
properties | object | Object used for classification and item specific information. Properties values are searchable and indexed. nullable: true; maxProperties: 50; example: { "productID": "ABC-123", "orderId": 123456 } |
Example
{
"version": 1,
"name": "string",
"description": "string",
"participants": [
{
"type": "user",
"id": "string",
"isGuest": true
}
],
"status": "open",
"properties": {
"productId": "ABC-123",
"orderId": 123456
}
}
200: Ok
Example Response Body:
{
"sessionId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"applicationId": "string",
"version": 1,
"name": "string",
"description": "string",
"participants": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "user",
"isGuest": true
}
],
"status": "open",
"properties": {
"productId": "ABC-123",
"orderId": 123456
},
"createdBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"createdAt": "2020-12-11T19:16:29.110Z",
"modifiedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"modifiedAt": "2020-12-11T19:16:29.110Z",
"isDraft": true
}
409: Conflict
Session is closed
Returns session's participants
Request Parameters
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Path | sessionId* | string($uuid) | ID for this session |
Example Request URL:
https://api.skylight.upskill.io/v1/application/applications/5fbd8ebfcee428353b0dc8de/sessions/df93da6b-d8e7-49c3-8827-75c519522ab8/participants
200: Ok
Example Response Body
[
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "user",
"isGuest": true
}
]
Adds a participant to the session
Request Parameters
Request Body
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Path | sessionId* | string($uuid) | ID for this session |
Header | deviceid | string | used for looking up against the device database for specifics of the users device this event was generated from |
Header | devicetimestamp | string | The RFC3339 client deviceTimestamp |
Name | Value Type | Value Description |
type* | string | Type of identity; Valid values: user, group |
id* | string($uuid) | ID of the user or group |
isGuest | boolean | Determines if the user is a guest; default: false |
Example
{
"type": "user",
"id": "string",
"isGuest": true
}
204: Ok
409: Conflict (Unable to modify session)
Removes a user or group from the session
Request Parameters
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Path | sessionId* | string($uuid) | ID for this session |
Path | participantId* | string($uuid) | ID of the user or group to remove |
Header | deviceid | string | used for looking up against the device database for specifics of the users device this event was generated from |
Header | devicetimestamp | string($date-time) | The RFC3339 client deviceTimestamp |
​
204: Ok
404: Not found
Returns the session's data
Request Parameters
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Path | sessionId* | string($uuid) | ID for this session |
Example Request URL:
https://api.skylight.upskill.io/v1/application/applications/5fbd8ebfcee428353b0dc8de/sessions/e78fa929-627a-459d-bb57-0a96b98cb11f/data
200: Ok
Response Body (json):
Data object keys can contain only word and digit characters and "-"" or "_". Key length is limited to 64 symbols. |
Updates the session's data new chunk of data
Request Parameters
Request Body
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Path | sessionId* | string | ID for this session |
Header | deviceid | string | used for looking up against the device database for specifics of the users device this event was generated from |
Header | devicetimestamp | string($date-time) | The RFC3339 client deviceTimestamp |
​
Name | Value Type | Value Description |
data* | object | Data object keys can contain only word and digit characters and "-"" or "_". Key length is limited to 64 symbols. |
version* | integer | Application version number. Minimum: 1. |
Example
{
"data": {},
"version": 1
}
200: Ok
Example Response Body:
{
"eventId": "string"
}
409: Conflict (Session is closed)
Returns all session media metadata for a given application session
Request Parameters
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Path | sessionId* | string($uuid) | ID for this Session |
Query | {prop.*} | string | Properties are useful for doing dynamic filtering on arbitrary properties for all items. All values for each key must be in comma separated list format. The resulting items are determined through at least one valid key/value pair match. If you want to filter for multiple values for a specific key, pass multiple values as a comma-delimited list. Example: prop.department=A,B You can do more advanced filtering with multiple key/value pair combinations. Different desired keys filters will be combined with an AND. Multiple property filters for prop1 and prop2 would look like this -- ?prop.department=A,B&prop.deviceType=HUD |
Query | archived | string | Include, exclude, or only archived. Available values: include, exclude, only. Default: exclude |
Query | limit | integer | Max number of items per page. Range 1-200. Default: 50 |
Query | sort | string | Name of the paginated field to sort by. Ascending by default. Prefix with '-' to indicate descending. If omitted, default is creation order. Available values : filename, -filename, createdAt, -createdAt, modifiedAt, -modifiedAt Default value : _id (internal id) |
Query | nextCursor | string | Enables the service to return the next page of items. Supply this or prevCursor. If both are supplied, prevCursor is ignored. If neither are supplied, pagination is reset, and the first page will be returned. |
Query | prevCursor | string | Enables the service to return the previous page of items. Supply this or nextCursor. If both are supplied, prevCursor is ignored. If neither are supplied, pagination is reset, and the first page will be returned. |
Query | contentType | string | Include media metadata of these content (mime) types. All types by default. Comma-separated list. |
Query | labels | string | Include media metadata with these labels. Comma-separated list. |
Query | excludeLabels | string | Exclude media metadata with these labels. Comma-separated list. |
Query | createdBy | string | Comma-separated list of user ids to filter by createdBy field. |
Query | modifiedBy | string | Comma-separated list of user ids to filter by modifiedBy field. |
Query | createdFrom | string($date-time) | The oldest created date/time when entity has been created. |
Query | createdTo | string($date-time) | The latest created date/time when entity has been created. |
Query | modifiedFrom | string($date-time) | The oldest date/time when entity has been modified. |
Query | modifiedTo | string($date-time) | The latest date/time when entity has been modified. |
200: Ok
Example Response Body:
{
"data": [
{
"filename": "theImage.jpeg",
"title": "The Image",
"description": "This is the image.",
"etag": "string",
"labels": [
"one",
"two",
"three"
],
"properties": {
"deviceType": "HUD"
},
"applicationId": "string",
"mediaId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"contentType": "image/jpeg",
"totalBytes": 800000,
"uploadedBytes": 100000,
"createdBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"createdAt": "2020-12-14T07:55:41.905Z",
"modifiedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"modifiedAt": "2020-12-14T07:55:41.905Z",
"sessionId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"annotations": [
{
"annotationId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"path": "<SVG>...</SVG>"
}
]
}
],
"page": {
"count": 0,
"limit": 0,
"total": 0,
"prevCursor": "string",
"nextCursor": "string"
}
}
Creates session media metadata for a given application session
Request Parameters
Request Body
Response
Parameter Type | Name | Type | Description |
Path | applicationId* | string | ID for this Application |
Path | sessionId* | string($uuid) | ID for this Session |
Header | deviceid | string | used for looking up against the device database for specifics of the users device this event was generated from |
Header | devicetimestamp | string($date-time) | The RFC3339 client deviceTimestamp |
Name | Value Type | Value Description |
filename* | string | Filename. minLength: 1. maxLength: 255 |
title | string | Title of file. maxLength: 255 |
description | string | Description of file. maxLength: 255 |
labels | array |