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/v1/application (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
Request Parameters

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
Response

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
Request Parameters

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

Request Body

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
}
}
Response

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
Request Parameters

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
Response

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
Request Parameters

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

Request Body

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
}
}
Response

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
Request Parameters

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
Response

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
Request Parameters

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

Request Body

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
}
Response

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
Request Parameters

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

Response

204: Ok

404: Not found

Get Session Data

GET /applications/{applicationId}/sessions/{sessionId}/data

Returns the session's data

Request Parameters
Response
Request Parameters

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
Response

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
Request Parameters

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

Request Body

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
}
Response

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
Request Parameters

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.

Response

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
Request Parameters

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

Request Body

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

Metadata labels to classify to aid searching.

minItems: 0. maxItems: 50

label: string, maxLength: 128

properties

object

Attach specific information to media.

<*> : string. maxLength: 256

maxProperties: 50. Example: {"deviceType": "HUD"}

mediaId

string

Media's file ID. Generated if not supplied at creation

either string($uuid) or string (nullable: true, maxLength: 0)

contentType*

string

Content (mime) Type. minLength: 1, maxLength: 255

totalBytes*

integer

Media file's size in bytes. default: 1. minimum: 1

annotations

array

Media annotations

annotationId* : string($uuid). Client-supplied id for annotation. Pattern : ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

path* : string. Annotation as an svg. maxLength: 100000

Example body:

{
"filename": "theImage.jpeg",
"title": "The Image",
"description": "This is the image.",
"labels": [
"one",
"two",
"three"
],
"properties": {
"deviceType": "HUD"
},
"mediaId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"contentType": "image/jpeg",
"totalBytes": 800000,
"annotations": [
{
"annotationId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"path": "<SVG>...</SVG>"
}
]
}

Response

201: Created.

Example Response Body:

{
"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.918Z",
"modifiedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"modifiedAt": "2020-12-14T07:55:41.918Z",
"sessionId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"annotations": [
{
"annotationId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"path": "<SVG>...</SVG>"
}
]
}

Upload Media

POST /applications/{applicationId}/sessions/{sessionId}/media/{mediaID}/uploads

Upload a single session media file or initialize a multipart upload.

Request Parameters
Request Body
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID for this Application

Path

sessionId*

string($uuid)

ID for this Session

Path

mediaId*

string($uuid)

ID for this Media

Header

deviceid

string

Header

clientTimestamp

string($date-time)

Query

uploadType

string

Type of upload to perform. If 'uploadType=multipart' it will initialize a multipart upload and return a valid upload id. If 'uploadType=singlepart' it will attempt to upload the file directly to the S3 compatible store. Available values: multipart, singlepart. Default: singlepart

Query

chunkTotal

integer

How many multipart chunks the upload will require to complete. If the uploadType is multipart, this parameter is required.

Request Body

Request body only required if uploadType is singlepart.

Content-type: multipart/form-data

Name

Value Type

Value Description

file

string($binary)

A single file to upload. This is only used when the query parameter 'uploadType' equals 'singlepart'. Required file headers are Content-Type and filename.

Response

200: Ok

Multipart initial upload request processed successfully. Includes an uploadId for uploading the chunks.

Response Headers:

Name

Type

Description

ETag

string

The media file's etag value

Response Body:

{
"uploadId": "string"
}

201: Created

Singlepart file uploaded successfully (after uploading a single file or all chunks).

Response Headers:

Name

Type

Description

ETag

string

The media file's etag value.

Response Body:

{
"uploadedBytes": integer, // The cumulative bytes uploaded thus far
"totalBytes": integer // Convenient for calculating upload progress
}

The upload is complete when uploadedBytes equals totalBytes

Upload Media Multipart Chunk

PUT /applications/{applicationId}/sessions/{sessionId}/media/{mediaId}/uploads/{uploadId}

Upload a multipart chunk to a specific upload job.

Request Parameters
Request Body
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID of this Application

Path

sessionId*

string($uuid)

ID of this Session

Path

mediaId*

string($uuid)

ID of this Media

Path

uploadId*

string

ID of the upload job

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

Query

chunkTotal*

integer

How many multipart chunks the upload will require to complete

Query

chunkIndex*

integer

Which multipart chunk is being uploaded. minimum: 1. maximum: chunkTotal

Request Body

Content-type: multipart/form-data

Name

Value Type

Value Description

file

string($binary)

A single or multipart chunk of the file to upload. Required file headers are Content-Type and filename.

Response

200: Ok

Chunk successfully uploaded

Response Headers:

Name

Type

Description

ETag

string

The media file's etag value

Response Body:

{
"uploadedBytes": integer, // Cumulative bytes uploaded thus far
"totalBytes": integer, // Convenient for calculating upload progress
"done": [ boolean ] // Progress snapshot indicating whether each chunk has been uploaded
}

201: Created

All chunks uploaded successfully.

Response Headers:

Name

Type

Description

ETag

string

The media file's etag value

Response Body:

{
"uploadedBytes": integer, // Cumulative bytes uploaded thus far
"totalBytes": integer // Convenient for calculating upload progress
}

Get Media Metadata by ID

GET /applications/{applicationId}/sessions/{sessionId}/media/{mediaId}

Returns an item of session media metadata for a given session media

Request Parameters
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID for this Application

Path

sessionId*

string($uuid)

ID for this Session

Path

mediaId*

string($uuid)

ID for this Media

Response

200: Ok

Example Response Body:

{
"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:52:41.756Z",
"modifiedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"modifiedAt": "2020-12-14T07:52:41.756Z",
"sessionId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"annotations": [
{
"annotationId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"path": "<SVG>...</SVG>"
}
]
}

Get Media by ID

GET /applications/{applicationId}/sessions/{sessionId}/media/{mediaId}/content

Return the media file content

Request Parameters
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID for this Application

Path

sessionId*

string($uuid)

ID for this Session

Path

mediaId*

string($uuid)

ID for this Media

Response

200: Ok

Response Headers:

Name

Type

Description

ETag

string

The file's etag value

Content-Type

string

the file's content-type

Content-Disposition

string

Attachment formatted Content-Disposition for friendly browser filename downloading.

Content-Length

integer

The file's content length in bytes

Response Body:

string($binary)

Get Media Thumbnail

GET /applications/{applicationId}/sessions/{sessionId}/media/{mediaId}/thumbnail

Download a session media file's thumbnail

Request Parameters
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID for this Application

Path

sessionId*

string($uuid)

ID for this Session

Path

mediaId*

string($uuid)

ID for this Media

Query

type

string

type of thumbnail. If the type is 'image' then the thumbnail is a static .jpg file. If the type is 'preview' then the thumbnail is an animated .gif file. Available values: image, preview. Default: image

Response

200: Ok

Response Headers:

Name

Type

Description

Content-Type

string

The file's content type

Content-Disposition

string

Attachment formatted Content-Disposition for friendly browser filename downloading

Response Body:

string($binary)

Update Media Metadata

PATCH /applications/{applicationId}/sessions/{sessionId}/media/{mediaId}

Update an item of session media metadata

Request Parameters
Request Body
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID for this Application

Path

sessionId*

string($uuid)

ID for this Session

Path

mediaId*

string($uiid)

ID for this Media

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

Request Body

Name

Value Type

Value Description

filename

string

Filename. minLength: 1. maxLength: 255. Example: theImage.jpg

title

string

Title of the file. maxLength: 255

description

string

Description of the file. maxLength: 255

labels

array

Metadata labels to classify to aid searching.

minItems: 0. maxItems: 50

label: string, maxLength: 128

properties

array

Attach specific information to media

<*> : string, maxLength: 256

maxProperties: 50. Example: {"deviceType": "HUD"}

uploadedBytes

integer

Cumulative bytes uploaded thus far. Upload is complete when uploadedBytes equals totalBytes. minimum: 0

totalBytes

integer

Media file's size in bytes. minimum: 1

Example body:

{
"filename": "theImage.jpeg",
"title": "The Image",
"description": "This is the image.",
"labels": [
"one",
"two",
"three"
],
"properties": {
"deviceType": "HUD"
},
"uploadedBytes": 100000,
"totalBytes": 800000
}

Response

200: Ok.

Example Response Body:

{
"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:41:46.459Z",
"modifiedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"modifiedAt": "2020-12-14T07:41:46.459Z",
"sessionId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"annotations": [
{
"annotationId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"path": "<SVG>...</SVG>"
}
]
}

Archive Media by ID

DELETE /applications/{applicationId}/sessions/{sessionsId}/media/{mediaId}

Archives an item of session media metadata

Request Parameters
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID for this Application

Path

sessionId*

string($uuid)

ID for this Session

Path

mediaId*

string($uuid)

ID for this Media

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

Response

200: Ok

Example Response Body:

{
"applicationId": "string",
"mediaId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"etag": "string",
"sessionId": "e78fa929-627a-459d-bb57-0a96b98cb11f"
}

409: Conflict. Media already archived.

Unarchive Media by ID

POST /applications/{applicationId}/sessions/{sessionId}/media/{mediaId}/unarchive

Unarchives an item of session media

Request Parameters
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID for this Application

Path

sessionId*

string($uuid)

ID for this Session

Path

mediaId*

string($uuid)

ID for this Media

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

Response

200: Ok

Example Response Body:

{
"applicationId": "string",
"mediaId": "e78fa929-627a-459d-bb57-0a96b98cb11f",
"etag": "string",
"sessionId": "e78fa929-627a-459d-bb57-0a96b98cb11f"
}

Add Annotation to Media

POST /applications/{applicationId}/sessions/{sessionId}/media/{mediaId}/annotations

Add an annotation to an item of session media

Request Parameters
Request Body
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID for this Application

Path

sessionId*

string($uuid)

ID for this Session

Path

mediaId*

string($uuid)

ID for the Media

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

Request Body

Name

ValueType

Value Description

annotationId*

string($uuid)

Client-supplied ID for annotation. Example: e78fa929-627a-459d-bb57-0a96b98cb11f . Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

path*

string

Annotation as SVG. Example: <svg> ... </svg>. maxLength: 100000

Response

201: Created.

Example Response Body:

{
"annotationId": "e78fa929-627a-459d-bb57-0a96b98cb11f"
}

404: Not found. No media found or annotation already exists.

Delete Annotation from Media

DELETE /applications/{applicationId}/sessions/{sessionId}/media/{mediaId}/annotations/{annotationId}

Remove an annotation from an item of session media

Request Parameters
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID for this Application

Path

sessionId*

string

ID for this Session

Path

mediaId*

string

ID for this Media

Path

annotationId*

string

ID for the media annotation

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

Response

200: Ok

Example Response Body:

{
"annotationId": "e78fa929-627a-459d-bb57-0a96b98cb11f"
}

Get Media Labels

GET /applications/{applicationId}/sessions/{sessionId}/mediaLabels

Returns unique labels across all media for a given session

Request Parameters
Response
Request Parameters

Parameter Type

Name

Type

Description

Path

applicationId*

string

ID for this Application

Path

sessionId*

string

ID for this Session

Response

200: Ok

Example Response Body:

[
"string"
]