Integration API Reference

REST API reference for communicating with Skylight from an external app.

Using the API
The base url is https://api.skylight.upskill.io (substitute your own host for skylight.upskill.io if applicable).
Retrieving an access token
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.
Refreshing the access token
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.
Using the access token to authorize API calls
To authorize calls to Skylight API methods, every call should have the following value set for the Authorization request header
Bearer: {access_token}
where {access_token} is the access token retrieved from the login process.
Using the access token to authorize MQTT subscriptions
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.
General Errors
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.
Session
Get Sessions
GET /applications/{applicationId}/sessions
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"
  }
}
Create New Session
POST /applications/{applicationId}/sessions
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
}
Get Session by ID
GET /applications/{applicationId}/sessions/{sessionId}
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 Session
PATCH /applications/{applicationId}/sessions/{sessionId}
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
Get Participants
GET /applications/{applicationId}/sessions/{sessionId}/participants
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
  }
]
Add a Participant
POST /applications/{applicationId}/sessions/{sessionId}/participants
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)
Remove a Participant
DELETE /applications/{applicationId}/sessions/{sessionId}/participants/{participantId}
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
Get Session Data
GET /applications/{applicationId}/sessions/{sessionId}/data
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.
Update Session Data
PATCH /applications/{applicationId}/sessions/{sessionId}/data
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)
Session Media
Get Media List
GET /applications/{applicationId}/sessions/{sessionId}/media
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"
  }
}
Create Media Metadata
POST /applications/{applicationId}/sessions/{sessionId}/media
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

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.

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 }