Filter results by

REST API

For POST and PUT calls, pass request parameters as a JSON payload in the request body, not as URL parameters.

Endpoints

API calls (with access token)

1
https://api.artik.cloud/v1.1

Authentication (to get access token)

1
https://accounts.artik.cloud

Users

Get the current user's profile

GET /users/self

Returns the current user's profile. The user must be authenticated with a bearer access token.

Example response

1
2
3
4
5
6
7
8
9
{
  "data":{
    "id":"db2e64c653b94f519dbca8f157f73b79",
    "email":"tuser@ssi.samsung.com",
    "fullName":"Test User",
    "createdOn": 1403042304, // unix time in milliseconds
    "modifiedOn": 1403042305 // unix time in milliseconds
  }
}

Get a user's application properties

GET /users/<userID>/properties

Returns the properties of a user's application.

The call must be authenticated with a valid Authorization header. The application for which the properties are searched is the application linked to the Authorization token.

Request parameters

Parameter Description
userID User ID.

Available URL query parameters

Parameter Description
aid Application ID. String between 1 and 64 characters.

Example response

1
2
3
4
5
6
7
{
  "data":{
    "uid":"03c99e714b78420ea836724cedcebd49",
    "aid":"181a0d34621f4a4d80a43444a4658150",
    "properties":"custom"
  }
}      

Create a user's application properties

POST /users/<userID>/properties

Specifies the properties of a user's application.

The call must be authenticated with a valid Authorization header. The application for which the properties are created is the application linked to the Authorization token and MUST be the same as the aid parameter sent in the JSON Payload.

Request parameters

Parameter Description
userID User ID.

Example request

1
2
3
4
5
{
  "uid":"03c99e714b78420ea836724cedcebd49",
  "aid":"9628eef2a00d43d89b757b8d34373588",
  "properties":"{\"some\":[\"custom\",\"properties\"]}"
}   

Request body parameters

Parameter Description
uid (Optional) User ID. String representation of a User ID.
aid Application ID. String between 1 and 64 characters.
properties Custom properties for each user in the format that the application wants. String max 10000 characters.

Example response

1
2
3
4
5
6
7
{
  "data":{
    "uid":"03c99e714b78420ea836724cedcebd49",
    "aid":"9628eef2a00d43d89b757b8d34373588",
    "properties":"{\"some\":[\"custom\",\"properties\"]}"
  }
}

Update a user's application properties

PUT /users/<userID>/properties

Modifies the properties of a user's application.

The call must be authenticated with a valid Authorization header. The application for which the properties are updated is the application linked to the Authorization token and MUST be the same as the aid parameter sent in the JSON Payload.

Request parameters

Parameter Description
userID User ID.

Example request

1
2
3
4
5
{
  "uid":"03c99e714b78420ea836724cedcebd49",
  "aid":"9628eef2a00d43d89b757b8d34373588",
  "properties":"{\"some\":[\"custom\",\"properties\",3],\"more\":\"props\"}"
}

Request body parameters

Parameter Description
uid (Optional) User ID. String representation of a User ID.
aid Application ID. String between 1 and 64 characters.
properties Custom properties for each user in the format that the application wants. String max 10000 characters.

Example response

1
2
3
4
5
6
7
{
  "data":{
    "uid":"03c99e714b78420ea836724cedcebd49",
    "aid":"9628eef2a00d43d89b757b8d34373588",
    "properties":"{\"some\":[\"custom\",\"properties\",3],\"more\":\"props\"}"
  }
}

Delete a user's application properties

DELETE /users/<userID>/properties

Deletes the properties of a user's application.

The call must be authenticated with a valid Authorization header. The application for which the properties are deleted is the application linked to the Authorization token.

Request parameters

Parameter Description
userID User ID.

Available URL query parameters

Parameter Description
aid Application ID. String between 1 and 64 characters.

Example response

1
2
3
4
5
6
7
{
  "data":{
    "uid":"03c99e714b78420ea836724cedcebd49",
    "aid":"9628eef2a00d43d89b757b8d34373588",
    "properties":""
  }
}          

Get a user's devices

GET /users/<userID>/devices

Returns all devices owned by a user and/or shared devices on the user's account.

Request parameters

Parameter Description
userID User ID.

Available URL query parameters

Parameter Descrption
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).
includeProperties (Optional) Boolean (true/false). Return device properties set by ARTIK Cloud (default: false).
owner (Optional) Return all, owned, or shared devices. Can be ALL, ME, SHARED_WITH_ME (default: ALL).
includeShareInfo (Optional) Boolean (true/false). If true, response includes sharedWithOthers (default: false).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "data": {
    "devices": [
      {
        "id": "SdP8UyrNdNBm",
        "dtid": "polestar_locator_v2",
        "name": "NAME OF THE DEVICE",
        "manifestVersion":2,
        "manifestVersionPolicy":"LATEST",
        "needProviderAuth": false,
        "sharedWithOthers": true
      },
      {
        "id": "e98fsEKW5cQp",
        "dtid": "polestar_locator_coord",
        "name": "ALIAS OF THE SHARE",
        "manifestVersion":5,
        "manifestVersionPolicy":"DEVICE",
        "needProviderAuth": true,
        "sharedWithMe": shareid,
      }
    ]
  },
  "total": 2,
  "offset": 0,
  "count": 2
}

Response parameters

Parameter Description
id Device ID.
dtid Device Type ID.
name Device name.
manifestVersion Device's Manifest version that is used to parse the messages it sends to ARTIK Cloud.
manifestVersionPolicy Device's policy that will be applied to the messages sent by this device. <ul><li> LATEST means it will use the most recent manifest created.</li><li>DEVICE means it will use a specific version of the manifest regardless if newer versions are available.</li></ul>
needProviderAuth Boolean (true/false). If false the device needs authentication and is authenticated. If true the device needs authentication and is not authenticated.
total Total number of items.
offset String required for pagination.
count Number of items returned on the page.
sharedWithOthers Boolean (true/false). Indicates whether the device is shared with other users (if user is the device owner).
sharedWithMe Device share ID (if device is shared with the user).

Get a user's device types

GET /users/<userID>/devicetypes

Returns the device types owned by a user.

Request parameters

Parameter Description
userID User ID.

Available URL query parameters

Parameter Descrption
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "data": {
    "deviceTypes": [
      {
        "id": "dt73ad01f36baa4524a2f21f59a0ecef54",
        "oid": "4c4a90745ffb46628489230fffdb1e38",
        "uid": "766e28f546054d3c8d4bfe71e5bd5d53",
        "name": "cloud connector device",
        "published": false,
        "approved": false,
        "protected": true,
        "latestVersion": 0,
        "uniqueName": "cc.device.com",
        "vid": "0",
        "rsp": false,
        "issuerDn": null,
        "description": null,
        "tags": [
          {
            "name": "sensors",
            "isCategory": false
          },
          {
            "name": "smarthome",
            "isCategory": false
          }
        ],
        "hasCloudConnector": false,
        "lastUpdated": 1478025645000
    },
  "total": 1,
  "offset": 0,
  "count": 1
}  

Response parameters

Parameter Description
id Device type ID.
oid Organization ID.
uid Owner's user ID.
name Device type name.
published Device type published.
approved Device type latest Manifest approved by ARTIK Cloud team.
protected Boolean (true/false). Indicates whether scope is restricted to users of owner's applications.
latestVersion Device type latest Manifest version available.
uniqueName Device type unique name in the system (will be used for Manifest package naming). Has to be a valid JAVA package name.
vid Vendor ID.
rsp Boolean (true/false). Requires secure protocol. Defaults to false if not specified.
issuerDn Issuer of the client certificate. Used in conjunction with rsp.
description Custom description of the device type. String max 1500 characters.
tags Device type tag(s).
hasCloudConnector Boolean (true/false). Indicates whether device type uses Cloud Connector SDK.
lastUpdated Timestamp that the device type Manifest was last updated, in milliseconds since epoch.
ownedByCurrentUser Boolean (true/false). Indicates whether current user owns a device of this device type.
total Total number of items.
offset String required for pagination.
count Number of items returned on the page.
tags Device type tag(s).

Get a user's Rules

GET /users/<userID>/rules

Returns the user's Rules created by the current application.

This call accepts application and user tokens as the access token.

Request parameters

Parameter Description
userID User ID.

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
excludeDisabled (Optional) Boolean (true/false). Indicates whether to exclude disabled Rules in the result (default: false).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
{
  "total": 119,
  "offset": 0,
  "count": 100,
  "data": [
    {...},
    {...}
  ]
}

Each element in data is a Rule object (e.g., example response for Get a Rule) that contains a Rule body.

Get a user's trials

GET /users/<userID>/trials

Returns the trials of a participant or administrator.

Request parameters

Parameter Description
userID User ID.

Available URL query parameters

Parameter Descrption
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).
role Role of user. Can be administrator or participant.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "data": {
    "trials": [
      {
        "id": "924228cf373b4e6ebc343cdf1366209e",
        "ownerId": "7b202300eb904149b36e9739574962a5",
        "name": "My First Trial",
        "description": "This is my first trial",
        "startDate": 1426868135000,
        "endDate": null
      }
    ]
  },
  "total": 1,
  "offset": 0,
  "count": 1
}

Response parameters

Parameter Description
id Trial ID.
ownerId User ID of trial creator.
name Trial name.
description Trial description. String max 1500 characters.
startDate Start date of the trial (in milliseconds since epoch). Set to the current date-time when the trial is created.
endDate End date of the trial (in milliseconds since epoch). Set to the current date-time when the trial is stopped.

Devices

Get a device

GET /devices/<deviceID>

Returns a specific shared or owned device.

Required permissions: READ on the device.

Request parameters

Parameter Description
deviceID Device ID.

Available URL query parameters

Parameter Description
includeProperties (Optional) Boolean (true/false). Return device properties set by ARTIK Cloud (default: false).

Example response (user is the owner)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "data":
    {
      "id":"d3c3c521ee734226960b222728cab472",
      "uid":"237f11a303c94dd2bc953586dd2f0ac8",
      "dtid":"dta86763eadd02422b8f20660d5fe627ef",
      "name":"Mood Indicator Output",
      "manifestVersion":1,
      "manifestVersionPolicy":"LATEST",
      "needProviderAuth":false,
      "cloudAuthorization":"NO_AUTHORIZATION",
      "eid":null,
      "certificateSignature":null,
      "certificateInfo":null,
      "createdOn":1481328563000,
      "connected":true,
      "sharedWithOthers":false
  }
}

Example response (device is shared with user)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "data":
    {
      "id":"ecdae40f2288410499d92c29e25a3499",
      "uid":"237f11a303c94dd2bc953586dd2f0ac8",
      "dtid":"dtd079710fe2d14dcabb1d09c88ae179ed",
      "name":"Mood Indicator Input",
      "manifestVersion":1,
      "manifestVersionPolicy":"LATEST",
      "needProviderAuth":false,
      "cloudAuthorization":"NO_AUTHORIZATION",
      "eid":null,
      "certificateSignature":null,
      "certificateInfo":null,
      "createdOn":1481328564000,
      "connected":true,
      "sharedWithMe":e11b952de2ea4267b98050d3d823eef3,
      "sharedWithOthers": false
  }
}

Response parameters

Parameter Description
id Device ID.
uid User ID of the device owner.
dtid Device Type ID.
name Device name.
manifestVersion Device's Manifest version that is used to parse the messages it sends to ARTIK Cloud.
manifestVersionPolicy Device's policy that will be applied to the messages sent by this device. <ul><li> LATEST means it will use the most recent manifest created.</li><li>DEVICE means it will use a specific version of the manifest regardless if newer versions are available.</li></ul>
needProviderAuth Boolean (true/false). If false the device needs authentication and is authenticated. If true the device needs authentication and is not authenticated.
manifestVersionPolicy Device's policy that will be applied to the messages sent by this device. <ul><li> LATEST means it will use the most recent manifest created.</li><li>DEVICE means it will use a specific version of the Manifest regardless if newer versions are available.</li></ul>
needProviderAuth Boolean (true/false). If false the device needs authentication and is authenticated. If true the device needs authentication and is not authenticated.
sharedWithOthers Boolean (true/false). Indicates whether the device is shared with other users (if user is the device owner).
sharedWithMe Device share ID (if device is shared with the user).

Create a device

POST /devices

Adds a device.

Example request

1
2
3
4
5
6
7
{
  "uid": "240bc34cf61348e6a3255fe5d8539484",
  "dtid": "cloud.artik.example.activitytracker",
  "name": "temp activity tracker",
  "manifestVersion": -1,
  "manifestVersionPolicy": "LATEST"
}  

Request body parameters

Parameter Description
uid User ID. String representation of a User ID.
dtid Device type ID or unique name. <,>,&,'," not allowed.
name Device name. Between 1 and 64 characters. <,>,&,'," not allowed.
manifestVersion (Optional) Numeric greater than 0 (zero). Device's Manifest version that is used to parse the messages it sends to ARTIK Cloud.
manifestVersionPolicy (Optional) String. Device's policy that will be applied to the messages sent by this device. Only 2 values available. If not sent, defaults to LATEST. <ul><li>LATEST means it will use the most recent manifest created.</li> <li>DEVICE means it will use a specific version of the manifest regardless if newer versions are available. manifestVersion will stay with this version.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "data": {
    "id": "74941ee597e347ae9df62ef2cd9213aa",
    "uid": "240bc34cf61348e6a3255fe5d8539484",
    "dtid": "dt013005c9302a428990073c9d6359b354",
    "name": "temp activity tracker",
    "manifestVersion": 1,
    "manifestVersionPolicy": "LATEST",
    "needProviderAuth": false,
    "cloudAuthorization": "NO_AUTHORIZATION",
    "eid": null,
    "certificateSignature": null,
    "certificateInfo": null,
    "createdOn": 1494026364000,
    "connected": true
  }
}        

Update a device

PUT /devices/<deviceID>

Modifies a device's parameters.

Request parameters

Parameter Description
deviceID Device ID.

Example request

1
2
3
4
5
6
7
8
{
  "uid":"1111",
  "dtid":"181a0d34621f4a4d80a43444a4658150",
  "name":"New Office Samsung lamp 2",
  "manifestVersion":3,
  "manifestVersionPolicy":"DEVICE",
}
          

Request body parameters

Parameter Description
uid User ID. String representation of a User ID.
dtid Device type ID or unique name. <,>,&,'," not allowed.
name Device name. Between 1 and 64 characters. <,>,&,'," not allowed.
manifestVersion Numeric greater than 0 (zero). Device's Manifest version that is used to parse the messages it sends to ARTIK Cloud.
manifestVersionPolicy (Optional) String. Device's policy that will be applied to the messages sent by this device. Only 2 values available. If not sent, defaults to LATEST. <ul><li>LATEST means it will use the most recent manifest created.</li> <li>DEVICE means it will use a specific version of the manifest regardless if newer versions are available. manifestVersion will stay with this version.

Example response

1
2
3
4
5
6
7
8
9
10
11
{
  "data":{
    "id":"d1d04e4cb18a4757b5481901e3665a34",
    "uid":"1111",
    "dtid":"181a0d34621f4a4d80a43444a4658150",
    "name":"New Office Samsung lamp 2",
    "manifestVersion":3,
    "manifestVersionPolicy":"DEVICE"
  }
}
          

Delete a device

DELETE /devices/<deviceID>

Deletes a device.

Request parameters

Parameter Description
deviceID Device ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
{
  "data":{
    "id":"d1d04e4cb18a4757b5481901e3665a34",
    "uid":"1111",
    "dtid":"181a0d34621f4a4d80a43444a4658150",
    "name":"New Office Samsung lamp 2",
    "manifestVersion":3,
    "manifestVersionPolicy":"DEVICE"
  }
}
          

Get a device's token

GET /devices/<deviceID>/tokens

Returns the access token of a device.

Request parameters

Parameter Description
deviceID Device ID.

Example response

1
2
3
4
5
6
7
{
  "data": {
    "accessToken": "ac4ed92410fa4c4b86d4d5d30f21be22",
    "uid": "7b202300eb904149b36e9739574962a5",
    "did": "03fd772ae34b4b2a81db909898506146",
  }
}

Create device token

PUT /devices/<deviceID>/tokens

Creates a new access token for a device.

Request parameters

Parameter Description
deviceID Device ID.

Example response

1
2
3
4
5
6
7
{
  "data": {
    "accessToken": "0b312ca200cc47fbab80994262eb03ad",
    "uid": "7b202300eb904149b36e9739574962a5",
    "did": "9a020ce80acb47de93255607006908cf",
  }
}

Delete a device's token

DELETE /devices/<deviceID>/tokens

Deletes the access token of a device.

Request parameters

Parameter Description
deviceID Device ID.

Example response

1
2
3
4
5
6
7
{
  "data": {
    "accessToken": "ac4ed92410fa4c4b86d4d5d30f21be22",
    "uid": "7b202300eb904149b36e9739574962a5",
    "did": "03fd772ae34b4b2a81db909898506146",
  }
}

Authenticate a Cloud Connector device

POST /devices/<deviceID>/providerauth

Begins an authentication flow to grant ARTIK Cloud permissions to access a device's data on a third-party cloud.

There are two ways to authenticate a Cloud Connector device. One way is to have the user provide authorization on My ARTIK Cloud. The second way is to perform the authorization within the third-party app. The app initiates the authorization by calling the API documented here.

The application calling this API must support interactive redirects. This call triggers a sequence of redirections between ARTIK Cloud, the third-party cloud, and the application.

Available URL query parameters

Parameter Description
deviceID Device ID.
mobile (Optional) Boolean (true/false). Specifies whether this is a mobile client.

Specify Referer in the HTTP header to redirect the browser to this referer after all redirections are done. This is the best way to verify authentication success.

This call accepts device, application, and user tokens as the access token. The token can either be specified in the HTTP Authorization header or in the request body:

Request body parameters

Parameter Description
token Access token.

Revoke Cloud Connector device's authentication

DELETE /devices/<deviceID>/providerauth

Removes the stored third-party credentials and revokes all subscriptions for the device on ARTIK Cloud.

After performing this call, ARTIK Cloud may no longer communicate with the third-party cloud to receive data for this device.

Available URL query parameters

Parameter Description
deviceID Device ID.

This call accepts device, application, and user tokens as the access token.

If the call succeeds, it returns HTTP status 200. If the device is not found, the HTTP status code is 404.

Get device presence

GET /devices/<deviceID>/presence

Returns the active connection status of a device and the timestamp it was last seen. Active connections are indicated for Websocket, MQTT, or CoAP.

Presence is not reported in some special cases, such as SmartThings and Cloud Connector devices.

Available URL query parameters

Parameter Description
deviceID Device ID.

Example response

1
2
3
4
5
6
7
{
  "sdid": "4697f11336c540a69ffd6f445061215e",
  "data": {
    "connected": true,
    "lastSeenOn": 1466714037000
  }
}

Response parameters

Parameter Description
sdid Source device ID.
connected Boolean (true/false). Indicates whether the device is actively connected. Does NOT apply for SmartThings and Cloud Connector devices.
lastSeenOn Timestamp indicating when the device was last actively connected (in milliseconds since epoch). If connected is true the present time will be returned.

Get device shares

GET /devices/<deviceID>/shares

Returns all device shares for a device ID.

Required permissions: READ on user (device owner) and READ on device.

Request parameters

Parameter Description
deviceID Device ID.

Request body parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{ "total": 2,
  "offset": 0,
  "count": 2,
  "data" : {
    "shares": [ {
        "id": "aaa",
        "email": "xxx",
        "status": "PENDING",
        "sharedOn": 123456
      }, {
        "id": "bbb",
        "email": "yyy",
        "status": "ACCEPTED",
        "sharedOn": 123456
    } ]
  } 
}

Response parameters

Parameter Description
total Total number of items.
count Number of items returned on the page.
offset String required for pagination.
id User ID of device share recipient.
email Email address of device share recipient.
status Device share status.
sharedOn Timestamp the device share was created, in milliseconds since epoch.

Get a device share

GET /devices/<deviceID>/shares/<shareID>

Returns a device share.

Required permissions: READ on user (device owner) and READ on device.

Request parameters

Parameter Description
deviceID Device ID.
shareID Device share ID.

Example response

1
2
3
4
5
6
7
8
{ 
  "data" {
    "id": "aaa",
    "email": "xxx",
    "status": "ACCEPTED",
    "sharedOn": 123456
  }
}

Create a device share

POST /devices/<deviceID>/shares

Shares a device with a recipient.

Required permissions: WRITE on user (device owner) and WRITE on device.

Request parameters

Parameter Description
deviceID Device ID.

Request body parameters

Parameter Description
email Email address of device share recipient.

Example response

1
2
3
4
5
{ 
  "data": { 
    "id": "aaa"
  } 
}

Delete a device share

DELETE /devices/<deviceID>/shares/<shareID>

Deletes a device share.

Required permissions: WRITE on user (device owner) and WRITE on device.

Request parameters

Parameter Description
deviceID Device ID.
shareID Device share ID.

Request body parameters

Parameter Description
email Email address of device share recipient.

Example response

1
2
3
4
5
{ 
  "data": { 
    "id": "aaa"
  } 
}

Get a user's device shares

GET /users/<userID>/shares

List all devices shared with a user.

Required permissions: READ on user (device share recipient) or READ on devices owned by user (device share recipient).

Request parameters

Parameter Description
userID User ID.

Request body parameters

Parameter Description
filter Filter devices by share status. Can be ALL, WAITING, ACCEPTED, REJECTED (defaults to ALL).
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "data": {
    "shares": [
      {
        "id": "abc1235",
        "ownerId": "userid1",
        "did": "d8UyrNdNBm",
        "alias": "john's door lock",
        "status": "ACCEPTED",
        "sharedOn": 123456
      },
      {
        "id": "def6789",
        "ownerId": "userid2",
        "did": "dqwerty123",
        "alias": "bob's tracker",
        "status": "PENDING",
        "sharedOn": 789012
      },
      {
        "id": "12345678",
        "ownerId": "userid3",
        "did": "dazerty123",
        "alias": "eve's light",
        "status": "REJECTED",
        "sharedOn": 3456789
      }
    ]
  },
  "total": 3,
  "offset": 0,
  "count": 3
}

Device Types

Get a device type

GET /devicetypes/<deviceTypeID>

Returns the device type of a device.

Request parameters

Parameter Description
deviceTypeID Device type ID or unique name. <,>,&,'," not allowed.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "data": {
    "id": "dte5f9851dca3b4063a6440a3aa1142bac",
    "oid": "b019a9261d0940c3b84993139744ca1e",
    "uid": "11026",
    "name": "SIMBAND",
    "published": true,
    "approved": true,
    "protected": true,
    "latestVersion": 62,
    "uniqueName": "simband",
    "vid": "0",
    "rsp": false,
    "issuerDn": null,
    "description": "Samsung Simband device",
    "tags": [
      {
        "name": "fitness",
        "isCategory": true
      },
      {
        "name": "sensors",
        "isCategory": false
      }
    ],
    "hasCloudConnector": false,
    "lastUpdated": 1461766428000,
    "ownedByCurrentUser": false
  }
}

Response parameters

Parameter Description
id Device type ID.
oid Organization ID.
uid Owner's user ID.
name Device type name.
published Device type published.
approved Device type latest Manifest approved by ARTIK Cloud team.
protected Boolean (true/false). Indicates whether scope is restricted to users of owner's applications.
latestVersion Device type latest Manifest version available.
uniqueName Device type unique name in the system (will be used for Manifest package naming). Has to be a valid JAVA package name.
vid Vendor ID.
rsp Boolean (true/false). Requires secure protocol. Defaults to false if not specified.
issuerDn Issuer of the client certificate. Used in conjunction with rsp.
description Custom description of the device type. String max 1500 characters.
tags Device type tag(s).
hasCloudConnector Boolean (true/false). Indicates whether device type uses Cloud Connector SDK.
lastUpdated Timestamp that the device type Manifest was last updated, in milliseconds since epoch.
ownedByCurrentUser Boolean (true/false). Indicates whether current user owns a device of this device type.

Get device types

GET /devicetypes/

Returns a list of device types.

Available URL query parameters

Parameter Description
name Name of the device type.
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "data": {
    "deviceTypes": [
      {
        "id": "dt9881bbb5918a494888154d98b5121eed",
        "oid": "5200bc54f0084a34a85470d602a640e0",
        "uid": "637f11a303c94dd2bc953586dd2f0ac8",
        "name": "AKC_test_device",
        "published": false,
        "approved": true,
        "protected": true,
        "latestVersion": 1,
        "uniqueName": "test.device.com",
        "vid": "0",
        "rsp": false,
        "issuerDn": null,
        "description": "This is a test device",
        "tags": [
          {
            "name": "agriculture",
            "isCategory": true
          },
          {
            "name": "industrial",
            "isCategory": false
          },
          {
            "name": "automation",
            "isCategory": false
          }
        ],
        "hasCloudConnector": false,
        "lastUpdated": 1490747247000,
        "ownedByCurrentUser": false
      }
    ]
  },
  "total": 1,
  "offset": 0,
  "count": 1
}

Get latest Manifest properties

GET /devicetypes/<deviceTypeID>/manifests/latest/properties

Returns the properties for the latest Manifest version. This will return metadata about the Manifest, such as the fields and the units they are expressed in.

Request parameters

Parameter Description
deviceTypeID Device type ID or unique name. <,>,&,'," not allowed.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "data":{
    "version": 1,
    "properties" : {
      "fields": {
        "calories": {
          "type": "Double",
          "unit": "J*4.184",
          "isCollection": false,
          "description": "calories"
        },
        "heartRate": {
          "type": "Integer",
          "unit": "b/min",
          "isCollection": false,
          "description": "heartRate"
        },
        ...
      }
    },
    "actions": {}
  }
}

Get Manifest properties

GET /devicetypes/<deviceTypeID>/manifests/<version>/properties

Returns the properties for a specific Manifest version. This will return metadata about the Manifest, such as the fields and the units they are expressed in.

Request parameters

Parameter Description
deviceTypeID Device type ID or unique name. <,>,&,'," not allowed.
version Manifest version number.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "data":{
    "version": 1,
    "properties" : {
      "fields": {
        "calories": {
          "type": "Double",
          "unit": "J*4.184",
          "isCollection": false,
          "description": "calories"
        },
        "heartRate": {
          "type": "Integer",
          "unit": "b/min",
          "isCollection": false,
          "description": "heartRate"
        },
        ...
      }
    },
    "actions": {}
  }
}

Get available Manifest version numbers

GET /devicetypes/<deviceTypeID>/availablemanifestversions

Returns the available Manifest versions for a device type.

Request parameters

Parameter Description
deviceTypeID Device type ID or unique name. <,>,&,'," not allowed.

Example response

1
2
3
4
5
6
{
  "data":{
    "versions":[1,2,3,4]
  }
}
          

Messages

Post a message or Action

POST /messages

Sends a message or Action, using one of the following parameter combinations. If sending Actions, only "actions" should be contained in the payload.

Combination Required Parameters
Send message sdid, type = message
Send action ddid, type = action
Common parameters data, ts

Example request (message)

1
2
3
4
5
6
7
{
  "sdid": "4697f11336c540a69ffd6f445061215e",
  "ddid": "9f06411ad3174a4f98444a374447fe10",
  "ts": 1388179812427,
  "type": "message",
  "data": [payload]
}         

Example request (Action)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "ddid": "9f06411ad3174a4f98444a374447fe10",
  "ts": 1388179812427,
  "type": "action",
  "data": {
    "actions": [
      {
        "name": "setOn",
        "parameters": {}
      },
      {
        "name": "setColorRGB",
        "parameters": {
          "colorRGB": {
              "r": 192,
              "g": 180,
              "b": 45
          },
          "intensity": 55
        }
      }
    ]
  }
}

Request body parameters

Parameter Description
sdid (Optional) Source device ID.
data Data. Can be a simple text field, or a JSON document.
ddid (Optional) Destination device ID. Can be used when sending a message to another device.
ts (Optional) Message timestamp. Must be a valid time: past time, present or future up to the current server timestamp grace period. Current time if omitted.
type Type of message: message or action (default: message).
token (Optional) Device token.

Example response

1
2
3
4
5
{
  "data": {
    "mid": "7fb20d3809b54075af6bdfc22591c521"
  }
}           

Response parameters

Parameter Description
mid Message ID.

Error cases

ARTIK Cloud returns mid to acknowledge receipt of data-only messages (where type = message). The Developer Dashboard indicates whether a data-only message is invalid. An invalid message produces a Manifest normalization error. For example, a normalization error will be thrown if the value of the data field has a different type from the specified type in the Manifest. If there is a typo in the data field name but no other errors, the message is still considered as a valid message but that data field is ignored (the message is stored by ARTIK Cloud without that field).

ARTIK Cloud returns an error instead of mid upon receiving an invalid Action (e.g. wrong Action names or wrong parameters).

Get normalized messages

GET /messages

Returns normalized messages, according to one of the following parameter combinations:

Combination Required Parameters
Get by device sdid, endDate, startDate
Get by message ID mid, uid (required for applications only)
Get by device and field presence sdid, fieldPresence
Get by device, filter and date range sdid, filter, endDate, startDate
Common parameters order, count, offset

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
endDate (Optional) Time of latest (newest) item to return, in milliseconds since epoch.
fieldPresence (Optional) String representing a field from the specified device ID.
filter (Optional) Filter messages by fields (attributes) as defined in the Manifest. Fields and values are separated by colon (e.g., ecg:80, ecg:>=80).
mid (Optional) The ARTIK Cloud message ID being searched.
offset (Optional) Offset for cursor-based pagination. Takes value of next or prev returned from a previous request.
order (Optional) Desired sort order: asc or desc (default: asc). Sorts by ts (timestamp from source).
sdid (Optional) Source device ID of the messages being searched.
startDate (Optional) Time of earliest (oldest) item to return, in milliseconds since epoch.
uid (Optional) The owner's user ID of the messages being searched. If not specified, assume that of the current authenticated user. If specified, it must be that of a user for which the current authenticated user has read access to.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "uid": "7b202300eb904149b36e9739574962a5",
  "sdid": "4697f11336c540a69ffd6f445061215e",
  "startDate": 1421281794212,
  "endDate": 1421281794230,
  "count": 100,
  "order": "asc",
  "size": 1,
  "prev": "eyJtaWQiOiIzYWExMDY0OGMzNjM0OGZiYmNhOTczODZmYjZhYjZjNCIsInRzIjoxNDc0MDU4ODk4ODU5LCJkdCI6IjIwMTYtMDktMTZUMTM6NDg6MTguODU5LTA3OjAwIiwiaXNGb3J3YXJkIjpmYWxzZSwib2Zmc2V0IjoxMH0=",
  "next": "eyJtaWQiOiI5NDk5MmNhYWQ1YjE0ZGIyOTE4NDFjNDMxMjkzMTBlNSIsInRzIjoxNDc0MjcxNDcyMjYyLCJkdCI6IjIwMTYtMDktMTlUMDA6NTE6MTIuMjYyLTA3OjAwIiwiZXhpc3RzTW9yZURhdGEiOnRydWUsImlzRm9yd2FyZCI6dHJ1ZSwib2Zmc2V0IjoyMH0=",
  "data": [
    {
      "mid": "057a407d4f814cbc874f3f7a0485af3b",
      "data": {
        "dateMicro": 1421281794211000,
        "ecg": -73
      },
      "ts": 1421281794212,
      "sdtid": "vitalconnect_module",
      "cts": 1421281794212,
      "uid": "7b202300eb904149b36e9739574962a5",
      "mv": 1,
      "sdid": "4697f11336c540a69ffd6f445061215e"
    }
  ]
}

Response parameters

Parameter Description
uid User ID.
sdid Source device ID.
startDate Time of earliest message requested.
endDate Time of latest message requested.
count Number of items requested.
order Sort order.
size Number of items received.
prev String used for cursor-based pagination.
next String used for cursor-based pagination.
mid Message ID.
ts Timestamp from source.
sdtid Source device type ID.
cts Timestamp from ARTIK Cloud.
mv Manifest version.

Get normalized Actions

GET /actions

Returns normalized Actions, according to one of the following parameter combinations:

Combination Required Parameters
Get by device and date range ddid, endDate, startDate
Get by message ID mid, uid (required for applications only)
Get by Action and date range action, ddid, endDate, startDate
Common parameters order, count, offset

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
endDate (Optional) Time of latest (newest) item to return, in milliseconds since epoch.
mid (Optional) The ARTIK Cloud message ID being searched.
offset (Optional) Offset for cursor-based pagination. Takes value of next or prev returned from a previous request.
order (Optional) Desired sort order: asc or desc (default: asc). Sorts by ts (timestamp from source).
ddid (Optional) Destination device ID receiving the Actions being searched.
startDate (Optional) Time of earliest (oldest) item to return, in milliseconds since epoch.
uid (Optional) The owner's user ID of the Actions being searched. If not specified, assume that of the current authenticated user. If specified, it must be that of a user for which the current authenticated user has read access to.
action (Optional) Name of the Action sent to the destination device.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "mid": "m2",
  "uid": "11000",
  "startDate": 1421281794212,
  "endDate": 1421281794230,
  "count": 100,
  "order": "asc",
  "size": 1,
  "prev": "eyJtaWQiOiIzYWExMDY0OGMzNjM0OGZiYmNhOTczODZmYjZhYjZjNCIsInRzIjoxNDc0MDU4ODk4ODU5LCJkdCI6IjIwMTYtMDktMTZUMTM6NDg6MTguODU5LTA3OjAwIiwiaXNGb3J3YXJkIjpmYWxzZSwib2Zmc2V0IjoxMH0=",
  "next": "eyJtaWQiOiI5NDk5MmNhYWQ1YjE0ZGIyOTE4NDFjNDMxMjkzMTBlNSIsInRzIjoxNDc0MjcxNDcyMjYyLCJkdCI6IjIwMTYtMDktMTlUMDA6NTE6MTIuMjYyLTA3OjAwIiwiZXhpc3RzTW9yZURhdGEiOnRydWUsImlzRm9yd2FyZCI6dHJ1ZSwib2Zmc2V0IjoyMH0=",
  "data": [
    {
      "type": "action",
      "mid": "m2",
      "ts": 1442524539568,
      "cts": 1442524539568,
      "ddid": "905775af311d479584f4ef8692e2e6e3",
      "ddtid": "dt18dcaca3f2e245af94feeb90627f7e6a",
      "uid": "11000",
      "data": {
        "actions": [
          { "name": "setColorAsRGB", "parameters": { "colorRGB": { "r": 1,  "g": 2, "b": 4 } } },
          { "name": "setOn" },
          { "name": "setIntensity", "parameters": { "intensity": 1 } }
        ]}
    }]
}

Response parameters

Parameter Description
uid User ID.
sdid Source device ID.
startDate Time of earliest message requested.
endDate Time of latest message requested.
count Number of items requested.
order Sort order.
size Number of items received.
prev String used for cursor-based pagination.
next String used for cursor-based pagination.
type Type of message.
mid Message ID.
ts Timestamp from source.
ddid Destination device ID.
ddtid Destination device type ID.
cts Timestamp from ARTIK Cloud.

Get last normalized messages

GET /messages/last

Returns the most recent normalized messages from a device or devices.

Available URL query parameters

Parameter Description
sdids Comma-separated list of source device IDs (minimum: 1).
count Number of items to return per query. Can be 1-100 (default: 100).
fieldPresence (Optional) String representing a field from the specified device ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "sdids": "4697f11336c540a69ffd6f445061215e",
  "count": 2,
  "size": 2,
  "data": [
    {
      "mid": "fc344af3869d40ffb856824bbb6ee92a",
      "data": {
        "dateMicro": 1414692018449000,
        "ecg": -127
      },
      "ts": 1414692018448,
      "sdtid": "vitalconnect_module",
      "cts": 1414692018448,
      "uid": "7b202300eb904149b36e9739574962a5",
      "mv": 1,
      "sdid": "4697f11336c540a69ffd6f445061215e"
    },
    {
      "mid": "f70c58dd5d134d3095c6c796bc517d4e",
      "data": {
        "dateMicro": 1414692018439000,
        "ecg": -98
      },
      "ts": 1414692018438,
      "sdtid": "vitalconnect_module",
      "cts": 1414692018438,
      "uid": "7b202300eb904149b36e9739574962a5",
      "mv": 1,
      "sdid": "4697f11336c540a69ffd6f445061215e"
    }
  ]
}

Get normalized message aggregates

GET /messages/analytics/aggregates

Returns the sum, minimum, maximum, mean and count of message fields that are numerical. This call generates results on messages that are at least 1 minute old. Values for startDate and endDate are rounded to start of minute, and the date range between startDate and endDate is restricted to 31 days max.

Available URL query parameters

Parameter Description
endDate Time of latest (newest) item to return, in milliseconds since epoch.
field Message field being queried for analytics.
sdid Source device ID of the messages being queried.
startDate Time of earliest (oldest) item to return, in milliseconds since epoch.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "sdid": "deea2ca077b94d2db337722e28b41287",
  "startDate": "1426441570303",
  "endDate": "1427049970303",
  "field": "stepcount",
  "size": 1,
  "data": [
    {
      "count": 83,
      "min": 23,
      "max": 17095,
      "mean": 5649.989,
      "sum": 468949.06,
      "variance": 28158896
    }
  ]
}

Response parameters

Parameter Description
sdid Source device ID.
startDate Time of earliest message requested.
endDate Time of latest message requested.
field Message field.
size Number of items received.
count Number of items requested.
min Lowest-value item.
max Highest-value item.
mean Mean value of items.
sum Sum of items.
variance Variance of items.

Get normalized message histogram

GET /messages/analytics/histogram

Returns message aggregates over equal intervals, which can be used to draw a histogram. This call generates results on messages that are at least 1 minute old. For each interval, the sum, minimum, maximum, mean, count and variance of message fields are returned.

Available URL query parameters

Parameter Description
endDate End time of histogram in milliseconds. Should be beginning of the time interval.
field Message field being queried for histogram aggregation (histogram Y-axis).
sdid Source device ID of the messages being queried.
interval Interval on histogram X-axis. Can be: minute (1-hour limit), hour (1-day limit), day (31-day limit), month (1-year limit) or year (1-year limit).
startDate Start time of histogram in milliseconds. Should be beginning of the time interval.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "sdid": "1c1e46b708ff4cb5994e6332786adbc9",
  "startDate": "1429315200000",
  "endDate": "1429747200000",
  "field": "datemicro",
  "interval": "day",
  "size": 2,
  "data": [
    {
      "count": 12,
      "min": 1429471890000,
      "max": 1429471890000,
      "mean": 1429471890000,
      "sum": 17153663200000,
      "variance": 0,
      "ts": 1429401600000
    },
    {
      "count": 2,
      "min": 1429471890000,
      "max": 1429471890000,
      "mean": 1429471890000,
      "sum": 2858943770000,
      "variance": 0,
      "ts": 1429574400000
    }
  ]
}

Response parameters

Parameter Description
sdid Source device ID.
startDate Time of earliest message requested.
endDate Time of latest message requested.
field Message field.
interval Interval of histogram X-axis.
size Number of histogram segments.
count Number of items.
min Lowest-value item.
max Highest-value item.
mean Mean value of items.
sum Sum of items.
variance Variance of items.
ts Timestamp of the histogram segment.

Get normalized messages presence

GET /messages/presence

Returns presence of normalized messages.

Available URL query parameters

Parameter Description
sdid (Optional) Source device ID of the messages being searched.
interval String representing grouping interval. One of: minute (1-hour limit), hour (1-day limit), day (31-day limit), month (1-year limit) or year (10-year limit).
fieldPresence (Optional) String representing a field from the specified device ID.
startDate Time of earliest (oldest) item to return, in milliseconds since epoch.
endDate Time of latest (newest) item to return, in milliseconds since epoch.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "sdid": "4697f11336c540a69ffd6f445061215e",
  "fieldPresence": "ecg",
  "interval": "MINUTE",
  "startDate": 1414691892883,
  "endDate": 1414691893809,
  "size": 1,
  "data": [
    {
      "startDate": 1414691880000
    }
  ]
}

Get message snapshots

GET /messages/snapshots

Returns last received value for all Manifest fields (aka device "state") of a device or devices.

Available URL query parameters

Parameter Description
sdids Comma-separated list of source device IDs (1-100).
includeTimestamp (Optional) Boolean (true/false). Indicates whether to return timestamp (ts) of the last modification for each field. (default: true).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "sdids": "53e6d4c9777146369997835951adc572,otherId",
  "size": 2,
  "data": [
    {
      "sdid": "53e6d4c9777146369997835951adc572",
      "data": {
        "coachName": {
          "ts": 1466378866013,
          "value": "coach basic"
        },
        "objectives": {
          "total": {
            "steps": {
              "ts": 1466378866013,
              "value": 3300
            }
          }
        },
        "day": {
          "ts": 1466378866013,
          "value": "2016-06-20T01:27:46.013+02:00[Europe/Paris]"
        }
      }
    },
    {
      "sdid": "otherId",
      "data" : {}
    }
  ]
}

Export

Create an export request

POST /messages/export

Exports normalized messages from up to 30 days, according to one of the following parameter combinations. The maximum duration between startDate and endDate is 31 days. A confirmation message is emailed when the export request has been processed.

Data can be exported in JSON or "simple" CSV. CSV exports sort the message metadata into separate columns and the data payload into a unique column.

Combination Required Parameters
Get by users uids
Get by devices sdids
Get by device types uids, sdtids
Get by trial trialID
Get by combination of parameters uids, sdids, sdtids
Common parameters startDate, endDate, order, format, url, csvHeaders

Request body parameters

Parameter Description
csvHeaders (Optional) Adds a header to a CSV export. Accepted values are true, false, 1, 0. Defaults to true if format = csv1.
endDate Time of latest (newest) item to return, in milliseconds since epoch.
format (Optional) Format the export will be returned as: json (JSON) or csv1 (simple CSV). Defaults to json if not specified.
order (Optional) Desired sort order: asc or desc (default: asc). Sorts by ts (timestamp from source).
sdids (Optional) Comma-separated list of source device IDs. Max 30 device IDs. For example, "egabbb,ffbcd87" for two device IDs.
startDate Time of earliest (oldest) item to return, in milliseconds since epoch.
sdtids (Optional) Comma-separated list of source device type IDs. Max 30 device type IDs. For example, "dtegabbb,dtffbcd87" for two device type IDs.
trialID (Optional) Trial ID being searched for messages.
uids (Optional) Comma-separated list of user IDs. The current authenticated user must have read access to each user in the list. Max 30 user IDs. For example, "egabbb,ffbcd87" for two user IDs.
url (Optional) URL to include in email confirmation message.

Example response

1
2
3
4
5
6
7
8
9
10
{
  "data":{
    "exportId": "f2fcf3e0-4425-11e4-be99-0002a5d5c51b",
    "uids": "7b202300eb904149b36e9739574962a5",
    "startDate": 1378425600000,
    "endDate": 2378425600000,
    "order": "asc",
    "format": "json"
  }
}

Check export status

GET /messages/export/<exportID>/status

Returns the status of the messages export.

Request parameters

Parameter Description
exportID The Export ID of the export query.

Example response

1
2
3
4
5
6
7
8
{
  "exportId": "52f921fac0f841e384de8bef438adf07",
  "status": "Served",
  "md5": "f73f0a2a69d0f2ca3f986f8b31f60b00",
  "expirationDate": 1426367261000,
  "fileSize": 189,
  "totalMessages": 0
}

Response parameters

Parameter Description
exportId Export ID.
status Status of the export query. Values include Received, InProgress, Success, Failure, Served, Expired.
md5 Checksum of the file returned.
expirationDate Expiration date.
fileSize File size in bytes.
totalMessages Number of messages in the export.

Get export result

GET /messages/export/<exportID>/result

Returns the result of the export query. The result call returns the response in tgz format.

Request parameters

Parameter Description
exportID The Export ID of the export query.

Example response header

1
2
3
4
5
6
7
8
9
10
{
  "access-control-allow-origin": "*",
  "x-rate-limit-limit": "100/1000",
  "x-sami-total-messages": "133744",
  "x-rate-limit-remaining": "96/984",
  "content-length": "4508385",
  "x-rate-limit-reset": "1426905929/1426982400",
  "content-type": "application/x-compressed",
  "content-disposition": "attachment; filename=\"84efe4d9030e490c9788ede466965011.tgz\""
}
Field Description
x-sami-total-messages Total number of messages fetched from the database.
content-length Size of the .tgz file in bytes.
content-disposition Suggested filename to save. (Does not work on curl or older browsers.)

The tar file may contain one or more files in the following format:

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "size": 1,
  "data": [
    {
      "mid": "b557fbb551f04987883e5b52fd589882",
      "data": 
        {
          "dateMicro": 1415753126779000, 
          "posture": 2, 
          "ecg": -80
        },
      "ts":1423880755000,
      "sdtid":"vitalconnect_module",
      "cts":1423881187801,
      "uid":"5533a9c7d2f84792a133328d1ddf713f",
      "mv":1,
      "sdid":"920937d451ec495e9aa869684d526e49"
    }
  ]
}

Each file in the tar file has the following format: id-date.json or id-date.csv where id is either a uid or sdid, and date is a timestamp in milliseconds (the ts date of the first message in the file). If the result of a uid or sdid search is empty, the result will be a single file with the filename id-0.json or id-0.csv (id is either a uid or sdid).

Get export history

GET /messages/export/history

Returns a list of export queries that have been performed.

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).
trialId (Optional) Trial ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "count": 1,
  "offset": 0,
  "total": 1,
  "data": {
    "exports": [
      {
        "exportId": "52f921fac0f841e384de8bef438adf07",
        "request": {
          "requestDate": 1426280834731,
          "startDate": 1426273692267,
          "endDate": 1426277292267,
          "order": "asc",
          "format": "json"
        },
        "status": "Success",
        "md5": "f73f0a2a69d0f2ca3f986f8b31f60b00",
        "expirationDate": 1426367261000,
        "fileSize": 189,
        "totalMessages": 0
      }
    ]
  }
}

Subscriptions

Create a subscription

POST /subscriptions

Subscribes a client to receive notifications of messages for a user's devices. The devices are specified according to one of the following parameter combinations.

Combination Required Parameters Message Type
All user devices uid message
All user devices of a device type uid, sdtid message
Specific user device uid, sdid message
Destination device uid, ddid action

This call accepts application and user tokens as the access token.

Example request

1
2
3
4
5
6
7
{ 
   "messageType":"message",
   "uid":"5beb4e30be9145cb89742d0b315d391",
   "description":"This is a subscription to a user's devices",
   "subscriptionType": "httpCallback",
   "callbackUrl":"https://api.example.com/messages?user=earl1234"
}

Request body parameters

Parameter Description
subscriptionType Subscription type. Can be httpCallback or awsKinesis (default: httpCallback).
messageType Message type to subscribe to. Can be message or action.
uid User ID to subscribe to. Client will be notified for devices owned by this user.
sdtid (Optional) Source device type ID to subscribe to. Client will be notified for all user-owned devices of this device type. Applicable when messageType = message.
sdid (Optional) Source device ID to subscribe to. Applicable when messageType = message.
ddid Destination device ID to subscribe to. Required when messageType = action.
description (Optional) Description of the subscription. String max 256 characters.
callbackUrl Callback URL to be used (must be HTTPS). Can include query parameters. Must use a valid X.509 certificate from a well-known certificate authority (may not use a self-signed certificate). For httpCallback type only.
awsKey Key of the AWS user/role with (write) access to the Amazon Kinesis stream. For awsKinesis type only.
awsSecret Secret of the AWS user/role with (write) access to the Amazon Kinesis stream. For awsKinesis type only.
awsRegion Region of the AWS user/role with (write) access to the Amazon Kinesis stream. For awsKinesis type only.
awsKinesisStreamName Stream name of the Amazon Kinesis stream. For awsKinesis type only.
includeSharedDevices (Optional) Boolean (true/false). Include shared devices (default: false). Only applies when subscribing per user (with uid, without specifying device or device type).

Example response (callback URL)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "data":{ 
    "id":"1673d8888883acfcc50c9d",
    "aid":"f9c82b97b788888b7e2",
    "messageType":"message",
    "uid":"2455g888888",
    "description":"This is a subscription to a user's devices",
    "subscriptionType":"httpCallback",    
    "callbackUrl":"https://callback.example.com:443/messages?user=earl1234",
    "status":"ACTIVE",
    "createdOn":1435191843948,
    "modifiedOn":1439489593485
  }
}

Example response (Amazon Kinesis Stream)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "data":{
    "id":"1673d7394737480d847023acfcc50c9d",
    "aid":"f9c81f2eb69343efb336ba2b97b7b7e2",
    "messageType":"message",
    "uid":"5beb4e30",
    "description":"This is a subscription to a user's devices",
    "subscriptionType":"awsKinesis",
    "awsKey":"ABC",
    "awsSecret":"XYZ",
    "awsRegion":"us-west-1",
    "awsKinesisStreamName":"stream1",
    "status":"ACTIVE",
    "createdOn":1435191843948,
    "modifiedOn":1439489593485
  }
}

Response parameters

Parameter Description
id Subscription ID.
aid Application ID associated with the subscription. Derived from the access token.
messageType Message type. Can be message or action.
uid User ID.
sdtid Source device type ID.
sdid Source device ID.
ddid Destination device ID.
description Description of the subscription.
subscriptionType Subscription type.
callbackUrl Callback URL.
awsKey Key of the AWS user/role.
awsSecret Secret of the AWS user/role.
awsRegion Region of the AWS user/role.
awsKinesisStreamName Stream name of the Amazon Kinesis stream.
createdOn Timestamp that the subscription was created, in milliseconds since epoch.
modifiedOn Timestamp that the subscription was last modified, in milliseconds since epoch.

The subscription fields are further explained here.

Delete a subscription

DELETE /subscriptions/<subscriptionID>

Removes a subscription.

This call accepts application and user tokens as the access token.

Request parameters

Parameter Description
subscriptionID Subscription ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "data":{ 
    "id":"1673d8888883acfcc50c9d",
    "aid":"f9c82b97b788888b7e2",
    "messageType":"message",
    "uid":"2455g888888",
    "description":"This is a subscription to a user's devices",
    "subscriptionType":"httpCallback",    
    "callbackUrl":"https://callback.example.com:443/messages?user=earl1234",
    "status":"ACTIVE",
    "createdOn":1435191843948,
    "modifiedOn":1439489593485
  }
}

The call returns the subscription object, which is explained here.

Get subscriptions

GET /subscriptions

Returns all subscriptions for the current application.

This call accepts application tokens as the access token.

Available URL query parameters

Parameter Description
uid (Optional) User ID.
offset (Optional) Offset of results to start with. Used for pagination (default: 0).
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
   "data":[
      {
         "id":"1673d7394737480d847023acfc50c9d",
         ...
      },
      {
         "id":"7dfb1e6290e848d9b798079651df11d",
         ...
      }
   ],
   "total":2,
   "offset":0,
   "count":2
}

Get a subscription

GET /subscriptions/<subscriptionID>

Returns a subscription.

This call accepts application and user tokens as the access token.

Request parameters

Parameter Description
subscriptionID Subscription ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "data":{ 
    "id":"1673d8888883acfcc50c9d",
    "aid":"f9c82b97b788888b7e2",
    "messageType":"message",
    "uid":"2455g888888",
    "description":"This is a subscription to a user's devices",
    "subscriptionType":"httpCallback",    
    "callbackUrl":"https://callback.example.com:443/messages?user=earl1234",
    "status":"ACTIVE",
    "createdOn":1435191843948,
    "modifiedOn":1439489593485
  }
}

The call returns the subscription object, which is explained here.

Confirm a subscription

POST /subscriptions/<subscriptionID>/validate

Validates a subscription with ARTIK Cloud. If successful, subscription will be set to active status.

This call does not require an access token.

Request parameters

Parameter Description
subscriptionID Subscription ID.

Example request

1
2
3
4
{
   "aid": "f9c82b97b78888b7e2",
   "nonce": "<nonce>"
}

Request body parameters

Parameter Description
aid Application ID associated with the subscription.
nonce Nonce for authentication.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "data":{ 
    "id":"1673d8888883acfcc50c9d",
    "aid":"f9c82b97b788888b7e2",
    "messageType":"message",
    "uid":"2455g888888",
    "description":"This is a subscription to a user's devices",
    "subscriptionType":"httpCallback",    
    "callbackUrl":"https://callback.example.com:443/messages?user=earl1234",
    "status":"ACTIVE",
    "createdOn":1435191843948,
    "modifiedOn":1439489593485
  }
}

The call returns the subscription object, which is explained here.

Notifications

Get messages in notification

GET /notifications/<notificationID>/messages

Returns messages associated with a notification.

The notification ID is obtained from the notification payload sent to the client's callback URL.

This call accepts application and user tokens as the access token.

Request parameters

Parameter Description
notificationID Notification ID.

Request body parameters

Parameter Description
order (Optional) Desired sort order: asc or desc (default: asc). Sorts by ts (timestamp from source).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{ 
  "order":"asc",
  "total":1,
  "offset":0,
  "count":1,
  "data":[ 
    { 
       "mid":"057a407d4f814cbc87f3f7a0485af3b",
       "data":{ 
         "dateMicro":1421281794211000,
         "ecg":-73
       },
       "ts":1421281794212,
       "sdtid":"dtaeaf898b4db948ba",
       "cts":1421281794212,
       "uid":"7b202300eb90414936e9739574962a5",
       "mv":1,
       "sdid":"4697f11336c54069ffd6f445061215e"
    }
  ] 
}

Response parameters

Parameter Description
order Sort order.
total Total number of items.
offset String required for pagination.
count Number of items requested.
mid Message ID.
ts Timestamp from source.
sdtid Source device type ID.
cts Timestamp from ARTIK Cloud.
uid User ID.
mv Manifest version.
sdid Source device ID.

Rules

Develop Rules for devices provides a description of the JSON Rule body.

A Rule created by an application is not visible to another application.

Get a Rule

GET /rules/<ruleID>

Returns a Rule.

This call accepts application and user tokens as the access token.

Request parameters

Parameter Description
ruleID Rule ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "data": {
    "uid":"f0a3057950384215acf8ba25c2fbfcb7",
    "id":"f0a3057950384215acf8ba25c2fbfcb7",
    "aid": "b6951bf387b84f63b38911ae35d65e28",
    "name":"Test Rule",
    "description": "This is a test Rule",
    "languageVersion": 1,
    "rule": {"if":{"and":[{"sdid":"<BASIS_WATCH_ID>","field":"heartRate","operator":">=","operand":{"value":180}}]},"then":[{"ddid":"<SMART_THINGS_ON_OFF_CONTROL_ID>","action":"setState","parameters":{"state":{"value":"on"}}}]},
    "enabled":true,
    "createdOn": 1234567890,
    "modifiedOn": 1234567890
  }
}

Response parameters

Parameter Description
uid User ID.
id Rule ID.
aid Application ID. Rule is associated with only this application.
name Rule name. String max 64 characters.
description Rule description. String max 1400 characters.
languageVersion Version of the Rule body specification.
rule JSON-formatted Rule.
enabled Boolean (true/false). Indicates whether Rule is enabled.
createdOn Date Rule was created.
modifiedOn Date Rule was last modified.

Create a Rule

POST /rules

Adds a Rule.

This call accepts application and user tokens as the access token.

Example request

1
2
3
4
5
6
{
  "name":"Test Rule",
  "description": "This is a test Rule",
  "rule": {"if":{"and":[{"sdid":"<BASIS_WATCH_ID>","field":"heartRate","operator":">=","operand":{"value":180}}]},"then":[{"ddid":"<SMART_THINGS_ON_OFF_CONTROL_ID>","action":"setState","parameters":{"state":{"value":"on"}}}]},
  "enabled":true
}

Request body parameters

Parameter Description
name Rule name. String max 64 characters.
uid (Optional) User ID. Must provide if using an application token as an access token.
description (Optional) Rule description. String max 1400 characters.
rule JSON-formatted Rule.
enabled (Optional) Boolean (true/false). Indicates whether Rule is enabled. If not specified, defaults to enabled.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "data": {
    "uid":"f0a3057950384215acf8ba25c2fbfcb7",
    "id":"f0a3057950384215acf8ba25c2fbfcb7",
    "aid": "b6951bf387b84f63b38911ae35d65e28",
    "name":"Test Rule",
    "description": "This is a test Rule",
    "languageVersion": 1,
    "rule": {"if":{"and":[{"sdid":"<BASIS_WATCH_ID>","field":"heartRate","operator":">=","operand":{"value":180}}]},"then":[{"ddid":"<SMART_THINGS_ON_OFF_CONTROL_ID>","action":"setState","parameters":{"state":{"value":"on"}}}]},
    "enabled":true,
    "createdOn": 1234567890,
    "modifiedOn": 1234567890
  }
}

Update a Rule

PUT /rules/<ruleID>

Modifies parameters of a Rule.

This call accepts application and user tokens as the access token.

Request parameters

Parameter Description
ruleID Rule ID.

Example request

1
2
3
4
5
6
{
  "name":"Test Rule",
  "description": "This is a test Rule",
  "rule": {"if":{"and":[{"sdid":"<BASIS_WATCH_ID>","field":"heartRate","operator":">=","operand":{"value":180}}]},"then":[{"ddid":"<SMART_THINGS_ON_OFF_CONTROL_ID>","action":"setState","parameters":{"state":{"value":"on"}}}]},
  "enabled":true
}

Request body parameters

Parameter Description
name (Optional) Rule name. String max 64 characters.
description (Optional) Rule description. String max 1400 characters.
rule (Optional) JSON-formatted Rule.
enabled (Optional) Boolean (true/false). Indicates whether Rule is enabled.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "data": {
    "uid":"f0a3057950384215acf8ba25c2fbfcb7",
    "id":"f0a3057950384215acf8ba25c2fbfcb7",
    "aid": "b6951bf387b84f63b38911ae35d65e28",
    "name":"Test Rule",
    "description": This is a test Rule",
    "languageVersion": 1,
    "rule": {"if":{"and":[{"sdid":"<BASIS_WATCH_ID>","field":"heartRate","operator":">=","operand":{"value":180}}]},"then":[{"ddid":"<SMART_THINGS_ON_OFF_CONTROL_ID>","action":"setState","parameters":{"state":{"value":"on"}}}]},
    "enabled":true,
    "createdOn": 1234567890,
    "modifiedOn": 1234567890
  }
}

Delete a Rule

DELETE /rules/<ruleID>

Deletes a Rule.

This call accepts application and user tokens as the access token.

Request parameters

Parameter Description
ruleID Rule ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
 {
  "data": {
    "uid": "eee2fb1e88f245458520ed23661dead4",
    "id": "096ba7b27db54f73bbbe724d6c0bca22",
    "aid": "d18f11efb5244c8f99f1ac7aa4fb9bbc",
    "name": "Example rule",
    "languageVersion": 1,
    "rule": {"if":{"and":[{"sdid":"<BASIS_WATCH_ID>","field":"heartRate","operator":">=","operand":{"value":180}}]},"then":[{"ddid":"<SMART_THINGS_ON_OFF_CONTROL_ID>","action":"setState","parameters":{"state":{"value":"on"}}}]},
    "enabled": true,
    "createdOn": 1445440561132,
    "modifiedOn": 1445440561132,
    "description": "IF Basis Watch heartRate is more than or equal to 180\nTHEN send to SmartThingsOnOffControl the action setState with state=\"on\"‌"
  }
}

Get a Rule's execution statistics

GET /rules/<ruleID>/executions

Returns statistics for executions of a Rule.

This call accepts application and user tokens as the access token.

Request parameters

Parameter Description
ruleID Rule ID.

Example response

1
2
3
4
5
6
{
  "data": {
    "countApply": 3,
    "lastApply": 123456789,
  }
}

Response parameters

Parameter Description
countApply Number of times Rule was triggered and sent Actions.
lastApply Last time Rule was triggered, in milliseconds since epoch. Does not appear if Rule was not triggered.

Test Actions

POST /rules/<ruleID>/actions

Runs an Action in a Rule.

This call accepts application and user tokens as the access token.

Any testable Actions will actually be sent to your device, so be prepared!

An Action is testable if the definition of the Action is static. See this article for more information.

In case any Action is not testable, the POST request returns a 400 error and no Action will be executed (including those which are testable).

Request parameters

Parameter Description
ruleID Rule ID.

Test Actions available

GET /rules/<ruleID>/actions

Checks whether at least one Action can be run for test.

This call accepts application and user tokens as the access token.

Request parameters

Parameter Description
ruleID Rule ID.

Example response

1
2
3
4
5
{ 
  "data": { 
    "testable": true 
  }
}

Response parameters

Parameter Description
testable Boolean (true/false). Indicates whether it is possible to run an Action for the test.

Device Management

Write Server Properties

POST /devicemgmt/devices/<deviceID>/serverproperties

Writes Server Properties for a device.

Server Properties must have been defined in the Device Management Manifest. Fields not in the Manifest will not be stored in the payload.

This call accepts the following as the access token:

  • The device token.
  • The user token belonging to the device owner, or to an administrator of the device type's organization (in applications created by the device type's organization).
  • An application token created by the device type's organization.

Request parameters

Parameter Description
deviceID Device ID.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
{
  "firmwareVersion": "1.23a",
  "location": {
    "latitude": -43.5723,
    "longitude": 153.21760,
    "altitude": 103
  },
  "proximitySensor": {
    "isEnabled": true,
    "detectionsInPast24Hours": [1458581509231, 1458619488095, 1458667909598]
  }
}

Example response

1
2
3
4
5
{
  "data": {
    "did": "12c013d19fd649e6a4b8495ce1ce9cc3"
  }
}

Response parameters

Parameter Description
did Device ID.

Read properties on a device

GET /devicemgmt/devices/<deviceID>/properties

Reads properties for a device.

This call accepts the following as the access token:

  • The device token.
  • The user token belonging to the device owner, or to an administrator of the device type's organization (in applications created by the device type's organization).
  • An application token created by the device type's organization.

Request parameters

Parameter Description
deviceID Device ID.
includeTimestamp (Optional) Whether to include last-updated timestamp for Device and Server Properties. Defaults to false.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
  "data": {
    "serverProperties":{
      "firmwareVersion": "1.23a",
      "location": {
        "latitude": -43.5723,
        "longitude": 153.21760,
        "altitude": 103
      },
      "proximitySensor": {
        "isEnabled": true,
        "detectionsInPast24Hours": [1458581509231, 1458619488095, 1458667909598]
      }
    },
    "systemProperties": {
      "did": "12c013d19fd649e6a4b8495ce1ce9cc3",
      "createdOn": 1459383758458,
      "connection": {
        "connected":true,
        "protocol":"websocket",
        "lastSeenOn":1464292930124
      }
    },
    "deviceProperties": {
      "device": {
        "timezone":"America/Argentina/Cordoba",
        "utcOffset":"-03",
        "currentTime":1466522723000,
        "errorCode":[
          0
        ],
        "memoryFree":140,
        "batteryLevel":10,
        "firmwareVersion":"1.0.0",
        "serialNumber":"LT-500-000-0001",
        "modelNumber":"Model 500",
        "supportedBindingAndModes":"U",
        "manufacturer":"Leshan Demo Device"
      }
    }
  }
}

Example response with includeTimestamp=true

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "data":{
    "serverProperties":{
      "firmware":{
        "firmwareVersion":{
          "value":"1.0 alpha",
          "ts":1467052155996
        }
      }
    },
    "systemProperties":{
      "did":"a56d653313b5424394366b03ed0c4bbc",
      "createdOn":1461322123000,
      "connection":{
        "connected":true,
        "protocol":"websocket",
        "lastSeenOn":1464292930000
      }
    },
    "deviceProperties":{
      "device":{
        "timezone":{
          "value":"America/Argentina/Cordoba",
          "ts":1467052155996
        },
        "utcOffset":{
          "value":"-03",
          "ts":1467052155996
        }
      }
    }
  }
}

Response parameters

Parameter Description
serverProperties Server Properties defined by device type owner.
systemProperties System Properties provided by ARTIK Cloud.
deviceProperties Device properties supported by ARTIK Cloud for LWM2M devices.

Device Presence explains the connection property.

Query properties on devices

GET /devicemgmt/devices/properties

Queries and returns properties across devices.

This call accepts the following as the access token:

  • The user token belonging to an administrator of the device type's organization (in applications created by the device type's organization).
  • An application token created by the device type's organization.

Available URL query parameters

Parameter Description
dtid Device type ID.
count (Optional) Number of results to return. Used for pagination. Defaults to 100.
offset (Optional) Number of results to skip. Used for pagination. Defaults to 0.
filter (Optional) Comma-separated list of key=value pairs. Details below.

Follow the following rules to create a filter.

  • Filter values can be alphanumeric characters (A-z, 0-9), underscore, hyphen, and spaces. Nested JSON objects are separated with dot notation.
  • Values for System Properties must be an exact match. Values for Server Properties and Device Properties must be an exact match, with the exception of string values, for which the system applies a wildcard on both sides of the search term.

Example filter parameters (should be URL-encoded):

Filter type Example Syntax
Filter by System Property Search for device with did "a1b2c3" systemProperties.did=a1b2c3
Filter by Server Property Search for devices whose firmwarefirmwareVersion property matches *alpha* serverProperties.firmware.firmwareVersion=alpha
Filter by multiple properties Search for devices matching exact weight and height serverProperties.weight=12.34,serverProperties.height=45.5454
Filter by System and Server Properties Search for devices matching exact creation date and weight systemProperties.createdOn=1460981497000,serverProperties.weight=12.34
Filter by Device Properties Search LWM2M devices whose device/modelNumber resource matches *Model 500* deviceProperties.device.modelNumber=Model+500

The below filter searches properties of devices with device id "a56d653313b5424394366b03ed0c4bbc" in connected status, where the firmware version contains "alpha", and device/modelNumber LWM2M resource matches *Model 500*:

1
systemProperties.connection.connected=true,systemProperties.did=a56d653313b5424394366b03ed0c4bbc,serverProperties.firmware.firmwareVersion=alpha,deviceProperties.device.modelNumber=Model+500

The encoded URL looks like this:

Example request

1
2
/devicemgmt/devices/properties?dtid=dt6172aca4919f40a4a96afbd27cee09c8
&filter=systemProperties.connection.connected%3Dtrue%2CsystemProperties.did%3Da56d653313b5424394366b03ed0c4bbc%2C%0D%0AserverProperties.firmware.firmwareVersion%3Dalpha%2CdeviceProperties.device.modelNumber%3DModel%2B500%0D%0A

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "data": {
    "properties": [{
      "serverProperties": {
        "firmware": {
            "firmwareVersion": "1.0 alpha"
        }
      },
      "systemProperties": {
          "did": "a56d653313b5424394366b03ed0c4bbc",
          "createdOn": 1461322123000,
          "connection": {
              "connected": true,
              "protocol": "websocket",
              "lastSeenOn": 1464292930000
          }
      },
      "deviceProperties": {
          "device": {
              "timezone": "America/Argentina/Cordoba",
              "utcOffset": "-03",
              "currentTime": 1466522723000,
              "errorCode": [0],
              "memoryFree": 140,
              "batteryLevel": 10,
              "firmwareVersion": "1.0.0",
              "serialNumber": "LT-500-000-0001",
              "modelNumber": "Model 500",
              "supportedBindingAndModes": "U",
              "manufacturer": "Leshan Demo Device"
          }
      }
    }],
    "total": 1,
    "offset": 0,
    "count": 100
  }
}

Response parameters

Parameter Description
total Total number of items.
offset String required for pagination.
count Number of items returned on the page.

Delete Server Properties

DELETE /devicemgmt/devices/<deviceID>/serverproperties

Deletes all Server Properties associated with the device. The System Properties will remain.

This call accepts the following as the access token:

  • The device token.
  • The user token belonging to the device owner, or to an administrator of the device type's organization (in applications created by the device type's organization).
  • An application token created by the device type's organization.

Request parameters

Parameter Description
deviceID Device ID.

Example response

1
2
3
4
5
{
  "data": {
    "did": "12c013d19fd649e6a4b8495ce1ce9cc3"
  }
}

Response parameters

Parameter Description
did Device ID.

Get Device Management Manifest properties

GET /devicemgmt/devicetypes/<devicetypeID>/manifest/properties

Returns the properties of a Device Management Manifest for a device type. The response includes the Server Properties defined by the device type owner. If Device Properties are enabled, they will also be included in the response payload.

Request parameters

Parameter Description
devicetypeID Device type ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{ 
  "data":{
    "properties":{ 
      "fields":{ 
        "Location":{ 
          "type":"Double",
          "isCollection":false,
          "description":"Location",
          "metadata": {}
        },
        "firmware":{ 
          "firmwareVersion":{ 
            "type":"String",
            "isCollection":false,
            "description":"firmwareVersion",
            "metadata": {}
          }
        }
      }
    }
  }
}

Get device type configuration

GET /devicemgmt/devicetypes/<devicetypeID>

Returns the device management configuration of a device type.

Request parameters

Parameter Description
devicetypeID Device type ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
{
  "data": {
    "dtid": "dt00451159ee684e4498ebb3f2f737dba2",
    "devicePropertiesEnabled": true,
    "pmin": 300,
    "pmax": 700,
    "taskExpiresAfter": 3600,
    "createdOn": 1467049786779,
    "modifiedOn": 1472592289863
  }
}

Response parameters

Parameter Description
dtid Device type ID.
devicePropertiesEnabled Boolean (true/false). Indicates whether Device Properties are enabled for the device type.
pmin Minimum time in seconds the LWM2M client must wait between notifications.
pmax Maximum time in seconds the LWM2M client may wait between notifications.
taskExpiresAfter Custom expiration time for tasks on device type, in seconds.
createdOn Date device type was created.
modifiedOn Date device type was last modified.

Update device type configuration

PUT /devicemgmt/devicetypes/<devicetypeID>

Modifies the device management configuration of a device type.

Request parameters

Parameter Description
devicetypeID Device type ID.

Request body parameters

Parameter Description
devicePropertiesEnabled Boolean (true/false). Indicates whether Device Properties are enabled for the device type. Defaults to false.
pmin (Optional) Minimum time in seconds the LWM2M client must wait between notifications. Defaults to 300 (5 minutes).

Min 60 (1 minute), max 3600 (1 hour).
pmax (Optional) Maximum time in seconds the LWM2M client may wait between notifications. Must not be smaller than pmin. Defaults to 21600 (6 hours).

Min 3600 (1 hour), max 86400 (24 hours).
taskExpiresAfter (Optional) Custom expiration time in seconds for the device type's tasks. If not specified, default expiration time is 7 days.

Min 60 (1 minute), max 604800 (7 days).

Example request

1
2
3
4
5
6
{
  "devicePropertiesEnabled": true,
  "pmin": 300,
  "pmax": 700,
  "taskExpiresAfter": 3600
}

Example response

1
2
3
4
5
6
7
8
9
10
11
{
  "data": {
    "dtid": "dt00451159ee684e4498ebb3f2f737dba2",
    "devicePropertiesEnabled": true,
    "pmin": 300,
    "pmax": 700,
    "taskExpiresAfter": 3600,
    "createdOn": 1467049786779,
    "modifiedOn": 1472592289863
  }
}

Create a task

POST /devicemgmt/tasks

Creates a new task for one or more devices of a single device type.

Each task operates on a single property. An exception is that when reading Device Properties, you can issue a read on a group of Device Properties.

Request body parameters

Parameter Description
dtid Device type ID to operate on.
dids (Optional) Comma-separated list of device IDs to operate on. If not specified, task operates on all devices matching dtid. Cannot be passed with filter.
filter (Optional) Filter for device IDs to operate on. Uses the same syntax as query properties on device API. Cannot be passed with dids.
taskType Operation to perform (Read, Write, or Execute).
property Property to operate on, using dot notation.
taskParameters (Optional) JSON object containing additional parameters for the task.
taskParameters.value (Optional) Value to use in Write or Execute tasks (e.g., for a Write task, the value to write).
taskParameters.expiresAfter (Optional) Custom expiration time in seconds for the task. If not specified, task uses value of taskExpiresAfter. Otherwise, default expiration time is 7 days.
taskParameters.update.updateId Update ID of the firmware update image (only used with akc.update property).

Example request

1
2
3
4
5
6
7
8
9
10
{
  "dtid": "device type id",
  "dids": ["list of device ids", "1234"],
  "filter": "filter string",
  "taskType":"R",
  "property":"deviceProperties.device.manufacturer",
  "taskParameters":{
    "value": "1234",
  }
}

Example request (firmware update)

1
2
3
4
5
6
7
8
9
10
11
{
  "dtid":"dt0ccc6be7a0b24c9f80e7803ad1fdf834",
  "taskType":"E",
  "property":"deviceProperties.akc.update",
  "taskParameters":{
      "update": {
        "updateId": "14e7cf72efe24cd3bd083277ca793c03"
      }
   },
  "dids":["86f7cca4e77647cc83794d072c51007d"]
}

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": {
    "id": "task id",
    "dtid": "device type id",
    "dids": ["list of devices ids", "1234"],
    "filter": "filter string",
    "taskType":"R",
    "property":"deviceProperties.device.manufacturer",
    "taskParameters": {
      "value":"1234"
    },
    "status": "REQUESTED",
    "createdOn": 1470780879910,
    "modifiedOn": 1470780879910
  }
}

Get a task

GET /devicemgmt/tasks/<taskID>

Returns a task, its task status, and device task status counts.

Request parameters

Parameter Description
taskID Task ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "data": {
    "id": "task id",
    "dtid": "device type id",
    "dids": ["list of devices ids", "1234"],
    "filter": "filter string",
    "taskType":"R",
    "property":"deviceProperties.device.manufacturer",
    "taskParameters": {
      "value":"1234"
    },
    "status": "REQUESTED",
    "createdOn": 1470780879910,
    "modifiedOn": 1470780879910
  },
    "statusCounts": {
      "totalDevices": 1000,
      "numCompleted": 400,
      "numSucceeded": 399,
      "numFailed": 1,
      "numCancelled": 0
    }
  }
}

Response parameters

Parameter Description
status Current task status.
statusCounts Grouping for device task status counts.
statusCounts.numCancelled Number of devices that have been successfully cancelled.
statusCounts.numCompleted Number of devices that have this task completed. Complete can either indicate SUCCEEDED, FAILED, or CANCELLED status.
statusCounts.numFailed Number of devices that have this task failed.
statusCounts.numSucceeded Number of devices that have this task succeeded.
statusCounts.totalDevices Total number of devices in this task.

Possible task statuses

Status Description
REQUESTED Task has been created.
QUEUING Device tasks are being created for the task.
PROCESSING Task is processing.
COMPLETE All device tasks are in their end state (FAILED/SUCCEEDED/CANCELLED).
CANCELLED A task cancel is requested through the API.

See also possible device task statuses.

Get tasks

GET /devicemgmt/tasks

Returns all tasks for a device type.

Available URL query parameters

Parameter Description
dtid Device type ID.
offset (Optional) Offset of results to start with. Used for pagination (default: 0).
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
status (Optional) Task status.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
   "data":{
      "tasks":[
         {
            "id": "task id",
            "dtid": "device type id",
            ...
            "statusCounts": {
               "totalDevices": 1000,
               "numCompleted": 400,
               "numSucceeded": 399,
               "numFailed": 1,
               "numCancelled": 0
            }
         },
         ...
      ]
   },
   statusCounts: {
      "REQUESTED": 30,
      "PROCESSING": 40,
      "COMPLETE": 50,
      "CANCELLED": 60
   },
   "total": 180,
   "offset": 0,
   "count": 100
}

Note: The outer statusCounts groups the task status counts for the device type ID.

Get task detailed status

GET /devicemgmt/tasks/<taskID>/statuses

Returns a task, its task status, device task status counts, and individual device task statuses.

Request parameters

Parameter Description
taskID Task ID.

Available URL query parameters

Parameter Description
offset (Optional) Offset of results to start with. Used for pagination (default: 0).
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
status (Optional) Task status.
dids (Optional) Comma-separated list of device IDs.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
   "data":{
      "id": "task id",
      "dtid": "device type id",
      ...
      "statusCounts": {
         "totalDevices": 1000,
         "numCompleted": 400,
         "numSucceeded": 399,
         "numFailed": 1,
         "numCancelled": 0
      },
      "statuses": [
        { "did": "1234", "status": "QUEUED", "ts": 1466809058 },
        { "did": "5678", "status": "SUCCEEDED", "ts": 1466809060 },
        { "did": "abcd", "status": "FAILED", "ts": 1466801058,
               "errorCode": "error code",
               "errorMessage": "Device error information",
               "numAttempts": 8 },
        ...
      ]
   },
   "total": 1000,
   "offset": 0,
   "count": 100
}

Possible device task statuses

Status Description
REQUESTED Status of device task upon creation.
QUEUED Device task queued. If the device is not registered, set instead to FAILED.
PROCESSING Device task is processing.
FAILED Device task has failed for any reason (e.g., can't connect to device; device returns error; task expires before device connects).
SUCCEEDED Device task returns success.
CANCEL_REQUESTED Cancel has been requested while task is in QUEUED state.
CANCELLED Task is successfully cancelled.

See also possible task statuses.

Get task status history

GET /devicemgmt/tasks/<taskID>/statuses/history

Returns the history of status changes for a task, or for a specific device ID in that task.

Request parameters

Parameter Description
taskID Task ID.

Available URL query parameters

Parameter Description
did (Optional) Device ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
   "data":{
      "id":"task id",
      "history":[
         {
            "ts":1466801058,
            "status":"REQUESTED"
         },
         {
            "ts":1466801158,
            "status":"QUEUED"
         },
         {
            "ts":1466801158,
            "status":"FAILED",
            "errorCode": "error code",
            "errorMessage": "Device error information",
            "numAttempts": 9
         }
      ]
   }
}

Get tasks by device

GET /devicemgmt/devices/<deviceID>/tasks

Returns tasks for a device ID.

Request parameters

Parameter Description
deviceID Device ID.

Available URL query parameters

Parameter Description
offset (Optional) Offset of results to start with. Used for pagination (default: 0).
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
status (Optional) Device task status.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
   "data":{
      "tasks":[
         {
            "dids":[
               "361ad953a1a14b9296d54a85926546ba",
               "835cbd01b1654caa8bef9b45ab11b912"
            ],
            "status":"PROCESSING",
            "id":"7a75352daa9a4b7690981ee1977879bf",
            "taskType":"R",
            "property":"deviceProperties.device.manufacturer",
            "taskParameters":{
               "value":"value"
            },
            "statuses":[
               {
                  "did":"361ad953a1a14b9296d54a85926546ba",
                  "status":"REQUESTED",
                  "ts":1470689967620,
                  "numAttempts": 0
               }
            ],
            "createdOn":1470689967618,
            "modifiedOn":1470689967622,
            "dtid":"29663009b4b04e85b5253c41b30aecba",
            "statusCounts":{
               "totalDevices":1,
               "numCompleted":1,
               "numSucceeded":1,
               "numFailed":0,
               "numCancelled": 0
            }
         },
         ...
      ]
   },
   "count":2,
   "offset":0,
   "total":2
}

Cancel a task

PUT /devicemgmt/tasks/<taskID>

Cancels a task. Only affects devices that have not completed the task.

Request parameters

Parameter Description
taskID Task ID.

Example request

1
2
3
{
  "status": "CANCELLED"
}

Example response

1
2
3
4
5
6
7
8
9
10
11
{
   "data": {
      "id": "task id",
      "dtid": "device type id",
      ...
      },
      "status": "CANCELLED",
      "createdOn": 1470780879910,
      "modifiedOn": 1470780879910
   }
}

Cancel device in task

PUT /devicemgmt/tasks/<taskID>/devices/<deviceID>

Cancels a single device in a task. Only affects devices that have not completed the task.

Request parameters

Parameter Description
taskID Task ID.
deviceID Device ID.

Example request

1
2
3
{
  "status": "CANCELLED"
}

Example response

1
2
3
4
5
6
{
   "did": "device id",
   "status": "CANCELLED" | "CANCEL_REQUESTED",
   "ts": 1466809058,
   "numAttempts":0
}

Trials

Create a trial

POST /trials

Adds a trial.

Device types and invitations may be included in the call. See Add a trial device type and Create a trial invitation for the request formats.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "name": "test trial",
  "description": "this is a test trial",
  "deviceTypes": [
    {
      "dtid": "181a0d34621f4a4d80a43444a4658150"
    },
    {
      "dtid": "vitalconnect_module"
    }
  ],
  "invitations": [
    {
      "email": "john@email.com",
      "invitationType": "participant"
    }
 ]
}

Request body parameters

Parameter Description
description Description of the trial. String max 1500 characters.
name Name of the trial.
deviceTypes (Optional) Device types to add to the trial.
invitations (Optional) Invitations to be sent for the trial.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
{
  "data":{
    "id": "b5f1fd9954b348a3a6999fbd698a4928",
    "ownerId": "7b202300eb904149b36e9739574962a5",
    "name": "test trial",
    "description": "this is a test trial",
    "aid": "62bb65ceaa304f7989922fefb6a45814",
    "clientSecret": "e02a63d400b44d798b1f9962d7a8b09b",
    "startDate": 1396224000000,
    "endDate": null
  }
} 

Response parameters

Parameter Description
id Trial ID.
ownerId User ID of trial creator.
name Trial name.
description Trial description. String max 1500 characters.
aid Application ID of the associated application.
clientSecret Client secret.
startDate Start date of the trial (in milliseconds since epoch). Set to the current date-time when the trial is created.
endDate End date of the trial (in milliseconds since epoch). Set to the current date-time when the trial is stopped.

Delete a trial

DELETE /trials/<trialID>

Deletes a trial and its invitations, administrators, participants and connected devices.

Can be called by a trial administrator only.

Request parameters

Parameter Description
trialID Trial ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
{
  "data":{
    "id": "b5f1fd9954b348a3a6999fbd698a4928",
    "ownerId": "7b202300eb904149b36e9739574962a5",
    "name": "test trial",
    "description": "this is a test trial",
    "aid": "62bb65ceaa304f7989922fefb6a45814",
    "clientSecret": "e02a63d400b44d798b1f9962d7a8b09b",
    "startDate": 1396224000000,
    "endDate": null
  }
}

Find a trial

GET /trials/<trialID>

Returns a trial.

Can be called by trial administrators and participants. Only administrators will see aid and clientSecret.

Request parameters

Parameter Description
trialID Trial ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
{
  "data":{
    "id": "b5f1fd9954b348a3a6999fbd698a4928",
    "ownerId": "7b202300eb904149b36e9739574962a5",
    "name": "test trial",
    "description": "this is a test trial",
    "aid": "62bb65ceaa304f7989922fefb6a45814",
    "clientSecret": "e02a63d400b44d798b1f9962d7a8b09b",
    "startDate": 1396224000000,
    "endDate": null
  }
}

Update a trial

PUT /trials/<trialID>

Modifies the parameters of a trial.

Can be called by a trial administrator only.

Request parameters

Parameter Description
trialID Trial ID.

Example request

1
2
3
4
{
  "name": "new trial name",
  "description": "this is a new trial description"
}

Request body parameters

Parameter Description
description Description of the trial. String max 1500 characters.
name Name of the trial.

The status field can be updated to stop. This sets the end date of the trial. Pending invitations for the trial will be deleted, and updates to the stopped trial are disallowed.

Example request

1
2
3
{
  "status": "stop"
}

Request body parameters

Parameter Description
status Trial invitation status. Must be stop.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
{
  "data":{
    "id": "b5f1fd9954b348a3a6999fbd698a4928",
    "ownerId": "7b202300eb904149b36e9739574962a5",
    "name": "new trial name",
    "description": "this is a new trial description",
    "aid": "62bb65ceaa304f7989922fefb6a45814",
    "clientSecret": "e02a63d400b44d798b1f9962d7a8b09b",
    "startDate": 1396224000000,
    "endDate": 1426874500000
  }
}

Update trial application

PUT /trials/<trialID>/application

Updates the trial with a new application. This can be used if the client secret of the existing application is exposed. A new aid and clientSecret will be generated.

Can be called by a trial administrator only.

Request parameters

Parameter Description
trialID Trial ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
{
  "data":{
    "id": "b5f1fd9954b348a3a6999fbd698a4928",
    "ownerId": "7b202300eb904149b36e9739574962a5",
    "name": "test trial",
    "description": "this is a test trial",
    "aid": "c619c96c78b14c6289ee4644be0625c4",
    "clientSecret": "a95f631146b14c589de82db47d8496ab",
    "startDate": 1396224000000,
    "endDate": null
  }
}

Trials - Devices

Add a trial device type

POST /trials/<trialID>/devicetypes

Add a device type to the trial device types list.

Can be called by a trial administrator only.

Request parameters

Parameter Description
trialID Trial ID.

Example request

1
2
3
{
  "dtid": "dta38d91dfd9164e96a5dc74ef2305af43" 
}

Request body parameters

Parameter Description
dtid Device type ID or unique name. <,>,&,'," not allowed.

Example response

1
2
3
4
5
6
{
  "data": {
    "tid": "unique_trial_id",
    "dtid": "dta38d91dfd9164e96a5dc74ef2305af43"
  }
}

Connect a user device

POST /trials/<trialID>/participants/<userID>/devices

Connects a participant device to the trial.

Can be called by a trial participant only.

Request parameters

Parameter Description
trialID Trial ID.
userID User ID.

Example request

1
2
3
{
  "did": "4697f11336c540a69ffd6f445061215e"
}

Request body parameters

Parameter Description
did Participant device ID.

Example response

1
2
3
4
5
6
7
{
  "data":{
    "tid": "unique_trial_id",
    "uid": "7b202300eb904149b36e9739574962a5"
    "did": "4697f11336c540a69ffd6f445061215e"
  }
}

Disconnect a user device

DELETE /trials/<trialID>/participants/<userID>/devices/<deviceID>

Disconnects a participant device from the trial.

Can be called by a trial participant only.

Request parameters

Parameter Description
deviceID Participant device ID.
trialID Trial ID.
userID User ID.

Example response

1
2
3
4
5
6
7
{
  "data":{
    "tid": "unique_trial_id",
    "uid": "7b202300eb904149b36e9739574962a5"
    "did": "4697f11336c540a69ffd6f445061215e"
  }
}

Get trial connected devices

GET /trials/<trialID>/devices

Returns all devices connected to a trial.

Can be called by a trial administrator only.

Request parameters

Parameter Description
trialID Trial ID.

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ 
  "data":{ 
    "devices":[ 
      { 
        "id":"65ee0eae038b4f538d93faf97d044e12",
        "uid":"90cb4ef84c7d41d3b691241c392b2e42",
        "dtid":"dt11cfee3a5d294019b5e9afda11a93668",
        "name":"Device d8cb1e09b6b04fb",
        "manifestVersion":1,
        "manifestVersionPolicy":"LATEST",
        "connected_on":1411447202000
      }
   ]
 },
 "total":1,
 "offset":0,
 "count":1
}

Response parameters

Parameter Description
id Device ID.
uid User ID.
dtid Device type ID.
name Device name.
manifestVersion Device's Manifest version that is used to parse the messages it sends to ARTIK Cloud.
manifestVersionPolicy Device's policy that will be applied to the messages sent by this device. <ul><li> LATEST means it will use the most recent Manifest created.</li><li>DEVICE means it will use a specific version of the manifest regardless if newer versions are available.</li></ul>
connected_on Date the device was connected to the trial (in milliseconds since epoch).
total Total number of items.
offset String required for pagination.
count Number of items returned on the page. Default and max is "100".

Get trial device types

GET /trials/<trialID>/devicetypes

Returns all device types in a trial.

Can be called by trial administrators and participants.

Request parameters

Parameter Description
trialID Trial ID.

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "data": {
    "deviceTypes": [
      {
        "id":"dta38d91dfd9164e96a5dc74ef2305af43",
        "uid": "12345",
        "name":"Samsung Web Camera XYZ",
        "published":true,
        "latestVersion":5,
        "uniqueName":"com.samsung.web.camera"
      },
      ...
    ]
  },
  "total": 1,
  "offset": 0,
  "count": 1  
}            

Response parameters

Parameter Description
id Device type ID.
uid Owner's user ID.
name Device type name.
published Device type published.
latestVersion Device type latest Manifest version available.
uniqueName Device type unique name in the system (used for Manifest package naming). Has to be a valid JAVA package name.
total Total number of items.
offset String required for pagination.
count Number of items returned on the page.

Get user connected devices

GET /trials/<trialID>/participants/<userID>/devices

Returns all devices connected by a participant to a trial.

Can be called by trial administrators and participants.

Request parameters

Parameter Description
trialID Trial ID.
userID User ID.

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ 
  "data":{ 
    "devices":[ 
      { 
        "id":"65ee0eae038b4f538d93faf97d044e12",
        "uid":"90cb4ef84c7d41d3b691241c392b2e42",
        "dtid":"dt11cfee3a5d294019b5e9afda11a93668",
        "name":"Device d8cb1e09b6b04fb",
        "manifestVersion":1,
        "manifestVersionPolicy":"LATEST",
        "connected_on":1411447202000
      }
   ]
 },
 "total":1,
 "offset":0,
 "count":1
}

Trials - Members

Create a trial invitation

POST /trials/<trialID>/invitations

Sends a new trial invitation. The invitation will be active for 24 hours.

Can be called by a trial administrator only.

Request parameters

Parameter Description
trialID Trial ID.

Example request

1
2
3
4
{
  "email": "john@email.com",
  "invitationType": "participant"
}

Request body parameters

Parameter Description
email User's email address.
invitationType User role. Can be participant or administrator.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "data":{
    "id": "f252c2e77a68419eb6322a8fbae37bc9",
    "tid": "f5fc7af5fa6d4480b597e340bfff4450",
    "email": "john@email.com",
    "invitationType": "participant",
    "sentDate": "1395705600000",
    "acceptedDate": null,
    "expirationDate": "1395878400000",
    "revokedDate": null,
    "status": "sent"
  }
} 

Response parameters

Parameter Description
id Invitation ID.
tid Trial ID.
email User's email address.
invitationType User role. Can be participant or administrator.
sentDate Date the invitation was sent (in milliseconds since epoch).
acceptedDate Date the invitation was accepted (in milliseconds since epoch).
expirationDate Date the invitation expires (in milliseconds since epoch).
revokedDate Date the invitation was revoked (in milliseconds since epoch).
status Invitation status. Can be accepted, expired or sent.

Delete a trial administrator

DELETE /trials/<trialID>/administrators/<userID>

Removes an administrator from a trial.

Can be called by a trial administrator only.

Request parameters

Parameter Description
trialID Trial ID.
userID User ID.

Example response

1
2
3
4
5
6
{
  "data":{
    "tid":"unique_trial_id",
    "uid":"03c99e714b78420ea836724cedcebd49"
  }
}

Delete a trial invitation

DELETE /trials/<trialID>/invitations/<invitationID>

Removes an invitation from a trial. This only applies to invitations with a status of sent.

Can be called by a trial administrator only.

Request parameters

Parameter Description
invitationID Invitation ID.
trialID Trial ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "data":{
    "id": "f252c2e77a68419eb6322a8fbae37bc9",
    "tid": "f5fc7af5fa6d4480b597e340bfff4450",
    "email": "john@email.com",
    "invitationType": "participant",
    "sentDate": "1395705600000",
    "acceptedDate": null,
    "expirationDate": "1395878400000",
    "revokedDate": null,
    "status": "sent"
  }
} 

Delete a trial participant

DELETE /trials/<trialID>/participants/<userID>

Removes a participant from a trial and disconnects their devices. Participant's data can no longer be accessed by trial administrators.

Can be called by a trial administrator only.

Request parameters

Parameter Description
trialID Trial ID.
userID User ID.

Example response

1
2
3
4
5
6
{
  "data":{
    "tid":"unique_trial_id",
    "uid":"03c99e714b78420ea836724cedcebd49"
  }
}

Get trial administrators

GET /trials/<trialID>/administrators

Returns all the administrators of a trial.

Can be called by a trial administrator only.

Request parameters

Parameter Description
trialID Trial ID.

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "data":{
    "id":"db2e64c653b94f519dbca8f157f73b79",
    "name":"tuser",
    "email":"tuser@ssi.samsung.com",
    "fullName":"Test User",
    "createdOn":1403042304,
    "modifiedOn":1403042305
  }
},
"total":1,
"offset":0,
"count":1

Response parameters

Parameter Description
id User ID.
name User name.
email Administrator's email address.
fullName Administrator's name.
createdOn Date user was created.
modifiedOn Date user was last modified.

Find trial invitations

GET /trials/<trialID>/invitations

Returns invitations for a trial that match a status.

Can be called by a trial administrator only.

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).
status Trial invitation status. Can be sent, accepted, revoked or expired.
trialID Trial ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "data":{
    "invitations": [
      {
        "id": "f252c2e77a68419eb6322a8fbae37bc9",
        "tid": "f5fc7af5fa6d4480b597e340bfff4450",
        "email": "john@email.com",
        "invitationType": "participant",
        "sentDate": "1395705600000",
        "acceptedDate": "1395792000000",
        "expirationDate": "1395878400000",
        "revokedDate": null,
        "status": "accepted"
      }
    ]
  },
  "total": 1,
  "offset": 0,
  "count": 1
}

Get trial participants

GET /trials/<trialID>/participants

Returns all the participants of a trial.

Can be called by a trial administrator only.

Request parameters

Parameter Description
trialID Trial ID.

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "data":{
    "id":"db2e64c653b94f519dbca8f157f73b79",
    "name":"tuser",
    "email":"tuser@ssi.samsung.com",
    "fullName":"Test User",
    "createdOn":1403042304,
    "modifiedOn":1403042305
  }
},
"total":1,
"offset":0,
"count":1

Response parameters

Parameter Description
id User ID.
name User name.
email Participant's email address.
fullName Participant's name.
createdOn Date user was created.
modifiedOn Date user was last modified.

Update a trial invitation

PUT /trials/<trialID>/invitations/<invitationID>

Modifies an invitation status.

Can be called by trial administrators and participants. Only administrators may revoke; only invitees may accept.

Request parameters

Parameter Description
invitationID Invitation ID.
trialID Trial ID.

Example request

1
2
3
{
  "status": "accepted"
}

Request body parameters

Parameter Description
status Trial invitation status. Can be accepted or revoked.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "data":{
    "id": "f252c2e77a68419eb6322a8fbae37bc9",
    "tid": "f5fc7af5fa6d4480b597e340bfff4450",
    "email": "john@email.com",
    "invitationType": "participant",
    "sentDate": "1395705600000",
    "acceptedDate": null,
    "expirationDate": "1395878400000",
    "revokedDate": 1424802260000,
    "status": "revoked"
  }
} 

Sessions

Add session to trial

POST /trials/sessions

Adds a session to a trial.

Example request

1
2
3
4
5
{
  "trialId": "b936c867117a4ae9a40bfb482682c1a8",
  "participantId": "b379322f43e641bd9ad6ee7787043fad",
  "devices": "a5c1cb6a35dc4387b722487982bcd6bc"
}

Request body parameters

Parameter Description
trialId Trial ID to associate with the session.
participantId Trial participant user ID to associate with the session.
devices Comma-separated list of device IDs to associate with the session.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "data": {
    "uuid": "03bb0612-4e10-4e20-b70a-c7d9b5f23489",
    "id": "03bb06124e104e20b70ac7d9b5f23489",
    "trialId": "b936c867117a4ae9a40bfb482682c1a8",
    "participantId": "b379322f43e641bd9ad6ee7787043fad",
    "devices": [
      {
        "uuid": "a8eeaeb5-7d2a-4cb1-b8ee-0327b8a9d52d",
        "id": "a8eeaeb57d2a4cb1b8ee0327b8a9d52d",
        "deviceId": "a5c1cb6a35dc4387b722487982bcd6bc"
      }
    ],
    "start": null,
    "end": null,
    "metadatas": [
      
    ],
    "exports": [
      
    ],
    "status": 200
  }
}

Response parameters

Parameter Description
uuid Universally unique identifier.
id String representation of uuid.
trialId Trial ID.
participantId Participant user ID.
devices List of session devices.
start Start date of the session (in milliseconds since epoch).
end End date of the session (in milliseconds since epoch).
metadatas List of session metadata.
exports List of ARTIK Cloud exports created for session.

Delete session

DELETE /trials/sessions/<sessionID>

Deletes a session.

Request parameters

Parameter Description
sessionID Session ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "uuid": null,
  "id": null,
  "trialId": "",
  "participantId": "",
  "devices": [
    
  ],
  "start": null,
  "end": null,
  "metadatas": [
    null
  ],
  "exports": [
    
  ],
  "status": null
}

Get session

GET /trials/sessions/<sessionID>

Returns a trial session.

Request parameters

Parameter Description
sessionID Session ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "data": {
    "uuid": "323952e7-e62b-4b55-970f-223ab85dc08d",
    "id": "323952e7e62b4b55970f223ab85dc08d",
    "trialId": "bea520d4c211447c8d1cc043429e380f",
    "participantId": "23b4853a78ba4490aabe709955834d4f",
    "devices": [
      {
        "uuid": "a2bea1b9-1f75-496e-a6b8-dc73e8092734",
        "id": "a2bea1b91f75496ea6b8dc73e8092734",
        "deviceId": "fdeeb6dc808045cbac7fe28b9d23a64b"
      }
    ],
    "start": null,
    "end": null,
    "metadatas": [
      
    ],
    "exports": [
      
    ],
    "status": null
  }
}

Update session

PUT /trials/sessions/<sessionID>

Updates an existing session.

Request parameters

Parameter Description
sessionID Session ID.

Example request

1
2
3
4
{
  "start": 1438581333000,
  "end": 1444833634387
}

Request body parameters

Parameter Description
start (Optional) Start date of the session (in milliseconds since epoch).
end (Optional) End date of the session (in milliseconds since epoch).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "data": {
    "uuid": "ecb987af-a140-491b-b1df-c0f5c4821b47",
    "id": "ecb987afa140491bb1dfc0f5c4821b47",
    "trialId": "b936c867117a4ae9a40bfb482682c1a8",
    "participantId": "b379322f43e641bd9ad6ee7787043fad",
    "devices": [
      {
        "uuid": "f31e7967-6f3d-4121-8baa-cf4fbb3fa9b5",
        "id": "f31e79676f3d41218baacf4fbb3fa9b5",
        "deviceId": "a5c1cb6a35dc4387b722487982bcd6bc"
      }
    ],
    "start": 1438581333000,
    "end": 1444833634387,
    "metadatas": [
      {
        "uuid": "3a315261-2a24-4411-b7eb-1ca5c1a938cc",
        "id": "3a3152612a244411b7eb1ca5c1a938cc",
        "key": "subject",
        "value": "b"
      },
      {
        "uuid": "a33b0348-48b2-4c43-bddd-8dad15791ba5",
        "id": "a33b034848b24c43bddd8dad15791ba5",
        "key": "age",
        "value": "45"
      }
    ],
    "exports": [
      
    ],
    "status": null
  }
}

Find all ongoing sessions for this trial

GET /trials/<trialID>/sessions/ongoing

Returns ongoing sessions for the trial.

Request parameters

Parameter Description
trialID Trial ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "data": {
    "sessions": [
      {
        "uuid": "ceb6c5e3-6cd7-47b5-a386-e3d318c1ac2e",
        "id": "ceb6c5e36cd747b5a386e3d318c1ac2e",
        "trialId": "b936c867117a4ae9a40bfb482682c1a8",
        "participantId": "b379322f43e641bd9ad6ee7787043fad",
        "devices": [
          {
            "uuid": "9400ebd8-666e-4692-b42d-79567c6505f8",
            "id": "9400ebd8666e4692b42d79567c6505f8",
            "deviceId": "a5c1cb6a35dc4387b722487982bcd6bc"
          }
        ],
        "start": 1447875816000,
        "end": null,
        "metadatas": [
          {
            "uuid": "8590276c-3e5d-4b86-ab4e-27d31a6b7fa3",
            "id": "8590276c3e5d4b86ab4e27d31a6b7fa3",
            "key": "subject",
            "value": "a"
          }
        ],
        "exports": [
          
        ],
        "status": null
      }
    ]
  },
  "total": 1,
  "offset": 0,
  "count": 1
}

Find all trial's sessions

GET /trials/<trialID>/sessions

Returns all sessions for the trial.

Request parameters

Parameter Description
trialID Trial ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "data": {
    "sessions": [
      {
        "uuid": "ceb6c5e3-6cd7-47b5-a386-e3d318c1ac2e",
        "id": "ceb6c5e36cd747b5a386e3d318c1ac2e",
        "trialId": "b936c867117a4ae9a40bfb482682c1a8",
        "participantId": "b379322f43e641bd9ad6ee7787043fad",
        "devices": [
          {
            "uuid": "9400ebd8-666e-4692-b42d-79567c6505f8",
            "id": "9400ebd8666e4692b42d79567c6505f8",
            "deviceId": "a5c1cb6a35dc4387b722487982bcd6bc"
          }
        ],
        "start": 1447875816000,
        "end": null,
        "metadatas": [
          {
            "uuid": "8590276c-3e5d-4b86-ab4e-27d31a6b7fa3",
            "id": "8590276c3e5d4b86ab4e27d31a6b7fa3",
            "key": "subject",
            "value": "a"
          }
        ],
        "exports": [
          
        ],
        "status": null
      }
    ]
  },
  "total": 1,
  "offset": 0,
  "count": 1
}

Sessions - Metadata

Get metadata key's values

GET /trials/<trialID>/sessions/metadata/key/<key>

Returns all values given to the metadata key.

Request parameters

Parameter Description
trialID Trial ID.
key Metadata key.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "data": {
    "metadata": [
      {
        "uuid": "21a243b9-aa5f-43d1-8287-dee4eda42907",
        "id": "21a243b9aa5f43d18287dee4eda42907",
        "key": "subject",
        "value": "1"
      }
    ]
  },
  "total": 1,
  "offset": 0,
  "count": 1
}

Response parameters

Parameter Description
uuid Universally unique identifier.
id String representation of uuid.
key Metadata's key.
value Metadata's value.

Create metadata

POST /trials/<trialID>/sessions/metadata

Creates metadata for a trial session.

Request parameters

Parameter Description
trialID Trial ID.

Example request

1
2
3
4
5
6
7
{
  "trialSession": {
    "id": "4be6caec17e948dc9b2e02506422ea96"
  },
  "key": "age",
  "value": "50"
}

Example response

1
2
3
4
5
{
  "trialSession": "4be6caec17e948dc9b2e02506422ea96",
  "key": "age",
  "value": "50"
}

Get metadata

GET /trials/<trialID>/sessions/metadata

Returns all metadata for the trial session.

Request parameters

Parameter Description
trialID Trial ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "data": {
    "metadata": [
      {
        "uuid": "075ca963-5eb8-4f0f-8abe-be0bfc8cb600",
        "id": "075ca9635eb84f0f8abebe0bfc8cb600",
        "key": "age",
        "value": "50"
      },
      {
        "uuid": "0c71ff37-84ea-439b-8c35-cd945ba4746a",
        "id": "0c71ff3784ea439b8c35cd945ba4746a",
        "key": "test",
        "value": "1"
      },
      {
        "uuid": "21a243b9-aa5f-43d1-8287-dee4eda42907",
        "id": "21a243b9aa5f43d18287dee4eda42907",
        "key": "subject",
        "value": "1"
      },
      {
        "uuid": "7934c4c0-794d-4397-8202-e274ef82e034",
        "id": "7934c4c0794d43978202e274ef82e034",
        "key": "12",
        "value": "12"
      }
    ]
  },
  "total": 4,
  "offset": 0,
  "count": 4
}

Update metadata

PUT /trials/<trialID>/sessions/metadata/<metadataID>

Updates a session's metadata.

Request parameters

Parameter Description
trialID Trial ID.
metadataID Metadata ID.

Example request

1
2
3
4
5
{
 "key": "a", 
 "value": "c", 
 "trialSession": "b936c867117a4ae9a40bfb482682c1a8" 
}

Example response

1
2
3
4
5
6
7
8
{
  "data": {
    "uuid": "075ca963-5eb8-4f0f-8abe-be0bfc8cb600",
    "id": "075ca9635eb84f0f8abebe0bfc8cb600",
    "key": "a",
    "value": "c"
  }
}

Remove metadata

DELETE /trials/<trialID>/sessions/metadata/<metadataID>

Removes a session's metadata.

Request parameters

Parameter Description
trialID Trial ID.
metadataID Metadata ID.

Example response

1
2
3
4
5
6
{
  "uuid": null,
  "id": null,
  "key": "",
  "value": ""
}

Sessions - Rules

Add session rules to trial

POST /rules

Adds session rules to the trial.

Session rules define restrictions for metadata. They are different from the Rules created in My ARTIK Cloud for sending commands to devices.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "trialId": "96f710575e01405fb67a8f1c7a4f8d61",
  "metadatas": [
    {
      "key": "subject",
      "type": "STRING",
      "choices": [
        
      ],
      "numericRangeStart": null,
      "numericRangeEnd": null,
      "required": true
    }
  ]
}

Request body parameters

Parameter Description
trialId Trial ID.
metadatas List of rule metadata.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "data": {
    "uuid": "c7cefd7f-7383-49b3-9391-1007bfd8e72f",
    "id": "c7cefd7f738349b393911007bfd8e72f",
    "trialId": "96f710575e01405fb67a8f1c7a4f8d61",
    "metadatas": [
      {
        "uuid": "63c05c43-4a32-4d22-9b18-0420c6de6d5f",
        "id": "63c05c434a324d229b180420c6de6d5f",
        "key": "subject",
        "value": null,
        "type": "STRING",
        "numericRangeStart": null,
        "numericRangeEnd": null,
        "required": true,
        "choices": [
          
        ],
        "created": 1444851017086
      }
    ],
    "primeKey": null
  }
}

Response parameters

Parameter Description
uuid Universally unique identifier.
id String representation of uuid.
trialId Trial ID.
metadatas List of metadata (see below).
metadata.uuid Metadata universally unique identifier.
metadata.id String representation of uuid.
metadata.key Metadata's key.
metadata.value Metadata's value.
metadata.type Metadata's type. Can be STRING, NUMERIC or CHOICES.
metadata.numericRangeStart Represents the minimum allowed value (if metadata.type is NUMERIC).
metadata.numericRangeEnd Represents the maximum allowed value (if metadata.type is NUMERIC).
required Boolean (true/false). Indicates whether this metadata must be added to a session.
choices List of values that can be given for this metadata (if empty, any value can be given).
primeKey "true" indicates this rule metadata is the prime key for all metadata that belong to the rule.

Find session rules for trial

GET /trials/<trialID>/sessions/rules

Returns session rules for the trial.

Request parameters

Parameter Description
trialID Trial ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "data": {
    "uuid": "5f46754e-aeeb-49aa-837b-2d7270258d9c",
    "id": "5f46754eaeeb49aa837b2d7270258d9c",
    "trialId": "b936c867117a4ae9a40bfb482682c1a8",
    "metadatas": [
      {
        "uuid": "ae3f1afa-7fe1-4217-911b-70809af4f57f",
        "id": "ae3f1afa7fe14217911b70809af4f57f",
        "key": "test",
        "value": null,
        "type": "STRING",
        "numericRangeStart": null,
        "numericRangeEnd": null,
        "required": false,
        "choices": [
          
        ],
        "created": 1441377414000
      },
      {
        "uuid": "aed1eb41-7e01-4a65-ba79-60791cea7260",
        "id": "aed1eb417e014a65ba7960791cea7260",
        "key": "subject",
        "value": null,
        "type": "STRING",
        "numericRangeStart": null,
        "numericRangeEnd": null,
        "required": true,
        "choices": [
          
        ],
        "created": 1444851000000
      }
    ],
    "primeKey": null
  }
}

Export session rules

GET /trials/<trialID>/sessions/rules/<ruleID>/sharing

Exports the session rules as a simplified JSON object (that can be imported to another trial).

Request parameters

Parameter Description
trialID Trial ID.
ruleID Rule ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": {
    "trialId": "",
    "metadatas": [
      {
        "key": "subject",
        "value": null,
        "type": "STRING",
        "numericRangeStart": null,
        "numericRangeEnd": null,
        "required": false,
        "choices": null
      }
    ]
  }
}

Import session rules

POST /trials/<trialID>/sessions/rules/<ruleID>/sharing

Replaces the session rules with the given imported rules JSON.

Request parameters

Parameter Description
trialID Trial ID.
ruleID Rule ID.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": {
    "trialId": "",
    "metadatas": [
      {
        "key": "subject",
        "value": null,
        "type": "STRING",
        "numericRangeStart": null,
        "numericRangeEnd": null,
        "required": false,
        "choices": null
      }
    ]
  }
}

Retrieve session rules

GET /trials/sessions/rules/<ruleID>

Returns session rules by ID.

Request parameters

Parameter Description
ruleID Rule ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "data": {
    "uuid": "5f46754e-aeeb-49aa-837b-2d7270258d9c",
    "id": "5f46754eaeeb49aa837b2d7270258d9c",
    "trialId": "b936c867117a4ae9a40bfb482682c1a8",
    "metadatas": [
      {
        "uuid": "ae3f1afa-7fe1-4217-911b-70809af4f57f",
        "id": "ae3f1afa7fe14217911b70809af4f57f",
        "key": "test",
        "value": null,
        "type": "STRING",
        "numericRangeStart": null,
        "numericRangeEnd": null,
        "required": false,
        "choices": [
          
        ],
        "created": 1441377414000
      },
      {
        "uuid": "aed1eb41-7e01-4a65-ba79-60791cea7260",
        "id": "aed1eb417e014a65ba7960791cea7260",
        "key": "subject",
        "value": null,
        "type": "STRING",
        "numericRangeStart": null,
        "numericRangeEnd": null,
        "required": true,
        "choices": [
          
        ],
        "created": 1444851000000
      }
    ],
    "primeKey": null
  }
}

Add session rule metadata

POST /trials/sessions/rules/metadata

Adds metadata to rule.

Example request

1
2
3
4
5
6
7
8
9
{
  "key": "age",
  "type": "NUMERIC",
  "choices": "1,2,3",
  "numericRangeStart": null,
  "numericRangeEnd": null,
  "required": true,
  "trialSessionRules": "c7cefd7f738349b393911007bfd8e72f"
}

Request body parameters

Parameter Description
key Metadata's key.
type Metadata's type. Can be STRING, NUMERIC or CHOICES.
choices Comma-separated string of allowed values (required if type is CHOICES).
numericRangeStart Minimum number allowed for value (optionally needed if type is NUMERIC).
numericRangeEnd Maximum number allowed for value (optionally needed if type is NUMERIC).
required Boolean (true/false). Specifies whether metadata rule must be given a value.
trialSessionRules Session rule ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "data": {
    "uuid": "f66ec9fe-2792-4657-a389-aaf1a3dd4418",
    "id": "f66ec9fe27924657a389aaf1a3dd4418",
    "key": "age",
    "value": null,
    "type": "NUMERIC",
    "numericRangeStart": null,
    "numericRangeEnd": null,
    "required": false,
    "choices": [
      {
        "uuid": "6e0a034e-125c-4b5f-b177-a7df861224bd",
        "id": "6e0a034e125c4b5fb177a7df861224bd",
        "order": 0,
        "value": "1",
        "created": 1450453104471
      },
      {
        "uuid": "44b3da41-aba0-46a2-a82b-d591a82701e7",
        "id": "44b3da41aba046a2a82bd591a82701e7",
        "order": 1,
        "value": "2",
        "created": 1450453104472
      },
      {
        "uuid": "35570f55-77ff-4a0d-888d-1551dd888f82",
        "id": "35570f5577ff4a0d888d1551dd888f82",
        "order": 2,
        "value": "3",
        "created": 1450453104474
      }
    ],
    "created": 1450453104470
  }
}

Remove session rule metadata

DELETE /trials/sessions/rules/metadata/<metadataID>

Deletes the specified rule metadata.

Request parameters

Parameter Description
metadataID Metadata ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": {
    "uuid": null,
    "id": null,
    "key": null,
    "value": null,
    "type": "STRING",
    "numericRangeStart": 0,
    "numericRangeEnd": 1,
    "required": false,
    "choices": [
      
    ],
    "created": null
  }
}

Update session rule metadata

PUT /trials/sessions/rules/metadata/<metadataID>

Updates the specified rule metadata.

Request parameters

Parameter Description
metadataID Metadata ID.

Example request

1
2
3
4
5
6
7
8
9
10
{
  "key": "subject",
  "value": null,
  "type": "NUMERIC",
  "numericRangeStart": null,
  "numericRangeEnd": null,
  "required": true,
  "choices": "",
  "trialSessionRules": "c7cefd7f738349b393911007bfd8e72f"
}

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": {
    "uuid": "b10b4a6a-a7dc-40a9-8fa5-f2d5e39007d0",
    "id": "b10b4a6aa7dc40a98fa5f2d5e39007d0",
    "key": "age",
    "value": null,
    "type": "NUMERIC",
    "numericRangeStart": null,
    "numericRangeEnd": null,
    "required": true,
    "choices": [
      
    ],
    "created": 1444851955211
  }
}

Search sessions

GET /trials/sessions/search

Returns sessions according to the specified parameters.

Example request

1
/trials/sessions/search?trialIds=b936c867117a4ae9a40bfb482682c1a8&participantIds=&start=1436681060043&end=1439186660043&deviceIds=&metadata=%22%22&count=10&offset=0

Request parameters

Parameter Description
trialId (Optional) Comma-separated string of trial IDs.
participantIds (Optional) Comma-separated string of participant user IDs.
start (Optional) Start date of the session (in milliseconds since epoch).
end (Optional) End date of the session (in milliseconds since epoch).
deviceIds (Optional) Comma-separated string of device IDs.
metadata (Optional) JSON string of metadata (e.g., [{"key":"test key","value":"test value"}].
count (Optional) Number of items to return per query. Can be 1-100 (default: 100).
offset (Optional) Offset of results to start with. Used for pagination (default: 0).

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
  "data": {
    "sessions": [
      {
        "uuid": "b9be25a0-764a-49ef-890f-5cb0a0e10d0c",
        "id": "b9be25a0764a49ef890f5cb0a0e10d0c",
        "trialId": "b936c867117a4ae9a40bfb482682c1a8",
        "participantId": "b379322f43e641bd9ad6ee7787043fad",
        "devices": [
          {
            "uuid": "f941157d-eca1-4230-bf5e-5a394b15607d",
            "id": "f941157deca14230bf5e5a394b15607d",
            "deviceId": "a5c1cb6a35dc4387b722487982bcd6bc"
          }
        ],
        "start": 1447875729000,
        "end": 1447875740000,
        "metadatas": [
          {
            "uuid": "cfee16c4-4942-4345-888e-af034acacb12",
            "id": "cfee16c449424345888eaf034acacb12",
            "key": "age",
            "value": "33"
          },
          {
            "uuid": "f23290f9-41e1-41ef-9755-289df2f875e6",
            "id": "f23290f941e141ef9755289df2f875e6",
            "key": "subject",
            "value": "1"
          }
        ],
        "exports": [
          {
            "uuid": "e8738377-b486-40b7-acb2-e843e4175aa8",
            "id": "e8738377b48640b7acb2e843e4175aa8",
            "exportId": "2636607af8de46a492a6a2764b4dcce2",
            "created": 1447875749000
          }
        ],
        "status": null
      }
    ]
  },
  "total": 1,
  "offset": 0,
  "count": 1
}

REST errors

Http Status Code Error message Condition
200 - Request successful.  
400 4001 Possible messages:<ul><li>Invalid email</li><li>Minimum length {0}</li><li>Maximum length {0}</li><li>Numeric field only</li><li>Text field only</li><li>Boolean field only</li><li>Invalid user name (characters allowed: alphanumeric, ".", "-" and "_" - must start with a letter)</li><li>Required parameter</li><li>The manifest content is invalid</li><li>The manifest content is invalid - Details: {0}</li><li>The manifest content cannot be empty<li>Invalid rule</li><li>Minimum value {0}</li><li>Maximum value {0}</li><li>The rule identifier "{1}" does not match with the URL parameter "{0}"</li><li>Message subscriptions cannot specify ddid</li><li>Message subscriptions can specify either sdtid or sdid, but not both</li><li>Callback url protocol must be HTTPS</li><li>The callback URL host does not match the application redirect URI host</li><li>The Device Type is not enabled for subscriptions</li><li>Quota validation error for organization <organizationID></li></ul> Validation error.
401 401 Please provide a valid authorization header You need to obtain an access token and provide an authorization header on the call.
403 403 Insufficient permissions: [message will differ depending on the permission issue] You don't have the required permissions to perform the requested action.
403 403 A client credentials token is required. You don't have the required permissions to perform the requested action.
404 404 Not Found The requested object was not found.
404 1101 Device type does not exist. The requested object was not found.
404 1201 User does not exist. The requested object was not found.
409 1202 Email already registered. You need to pass a different email address.
409 1203 Username already registered. You need to request a different username.
409 1203 Subscription already exists with id <subscription ID> You need to pass a different subscription ID.
429 431 Monthly quota exceeded. Plan quota exceeded for organization <organizationID>. Reason: Monthly message limit.
413 430 Payload size exceeded. Plan quota exceeded for organization <organizationID>. Reason: Max payload size limit.