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.

Required permissions: Application has READ on source device and WRITE on target device of Rule.

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).
scope (Optional) Rule scope. <ul><li>allApplications lists Rules accessible to all applications.</li><li>thisApplication lists Rules accessible only to this application.</li><li>allApplications,thisApplication lists Rules accessible to all applications and Rules accessible only to this application (default).</li></ul>The application must have the required permissions on the devices used in the Rule.

The below responses assume scope has not been specified.

Example response (with required permissions)

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
{
  "total": 119,
  "offset": 0,
  "count": 100,
  "data": [
    // Rule accessible to all applications
    {
      "uid":"f0a3057950384215acf8ba25c2fbfcb7",
      "id":"f0a3057950384215acf8ba25c2fbfcb7",
      "scope": "allApplications"
      "name":"Test Rule for all applications",
      "description": "This is a test Rule",
      "languageVersion": 1,
      "rule": { "if":{"and":[...]},"then":[...]},
      "enabled":true,
      "createdOn": 1234567890,
      "modifiedOn": 1234567890,
    },
    // Rule accessible to this application only
    {
      "uid":"f0a3057950384215acf8ba25c2fbfcb7",
      "id":"f0a3057950384215acf8ba25c2fbfcb8",
      "aid": "b6951bf387b84f63b38911ae35d65e28",
      "scope": "thisApplication"
      "name":"Test Rule for specific application",
      "description": ...,
      "languageVersion": 1,
      "rule": { "if":{"and":[...]},"then":[...]},
      "enabled":true,
      "createdOn": 1234567890,
      "modifiedOn": 1234567890,
    },
    // Rule accessible to a different application only
    {
      "uid":"f0a3057950384215acf8ba25c2fbfcb7",
      "id":"f0a3057950384215acf8ba25c2fbfcb9",
      "scope": "thisApplication"
    },
  ]
}

Example response (without required permissions)

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
{
  "total": 119,
  "offset": 0,
  "count": 100,
  "data": [
    // Rule accessible to all applications
    {
      "uid":"f0a3057950384215acf8ba25c2fbfcb7",
      "id":"f0a3057950384215acf8ba25c2fbfcb7",
      "scope": "allApplications"
    },
    // Rule accessible to this application only
    {
      "uid":"f0a3057950384215acf8ba25c2fbfcb7",
      "id":"f0a3057950384215acf8ba25c2fbfcb8",
      "aid": "b6951bf387b84f63b38911ae35d65e28",
      "scope": "thisApplication"
      "name":"Test Rule for specific application",
      "description": ...,
      "languageVersion": 1,
      "rule": { "if":{"and":[...]},"then":[...]},
      "enabled":false,
      "createdOn": 1234567890,
      "modifiedOn": 1234567890,
    },
    // Rule accessible to a different application only
    {
      "uid":"f0a3057950384215acf8ba25c2fbfcb7",
      "id":"f0a3057950384215acf8ba25c2fbfcb9",
      "scope": "thisApplication"
    },
  ]
}

Response parameters

Parameter Description
total Total number of items.
offset String required for pagination.
count Number of items returned on the page.
uid User ID.
id Rule ID.
aid Application ID. Returned only when a Rule has scope=thisApplication.
scope Rule scope.
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.

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
20
21
22
23
24
25
{
  "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": {
        "Issuer-DN": "/O=Samsung Electronics Inc./OU=SSIC/CN=ARTIK CLOUD",
        "Cert-UID": "FF101010101010",
        "Cert-CN": "RogerCert1",
        "Cert-SN": "FF1010101010100000",
        "Cert-FP": "36E1E0CF6D704135E1D77F3E9C6CE11E8C3E1E59"
      },
      "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.
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).
certificateInfo Information about the client certificate. Present only if the device is securely registered.

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
{
  "name":"New Office Samsung lamp 2",
  "manifestVersion":3,
  "manifestVersionPolicy":"DEVICE",
}
          

Request body parameters

Parameter Description
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
8
{
  "data": {
    "accessToken": "ac4ed92410fa4c4b86d4d5d30f21be22",
    "uid": "7b202300eb904149b36e9739574962a5",
    "did": "03fd772ae34b4b2a81db909898506146",
    "cid": "b6951bf387b84f63b38521ae35d65e28"
  }
}

Response parameters

Parameter Description
accessToken Access token.
uid User ID of the device owner.
did Device ID.
cid Application ID associated with the token.

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
8
{
  "data": {
    "accessToken": "0b312ca200cc47fbab80994262eb03ad",
    "uid": "7b202300eb904149b36e9739574962a5",
    "did": "9a020ce80acb47de93255607006908cf",
    "cid": "b6951bf387b84f63b38521ae35d65e28"
  }
}

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
8
{
  "data": {
    "accessToken": "ac4ed92410fa4c4b86d4d5d30f21be22",
    "uid": "7b202300eb904149b36e9739574962a5",
    "did": "03fd772ae34b4b2a81db909898506146",
    "cid": "b6951bf387b84f63b38521ae35d65e28"
  }
}

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.

Request parameters

Parameter Description
deviceID Device ID.

Available URL query parameters

Parameter Description
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.

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

GET /devices/<deviceID>/status

Returns current status of a device.

Request parameters

Parameter Description
deviceID Device ID.

Available URL query parameters

Parameter Description
includeSnapshot (Optional) Boolean (true/false). Indicates whether to return message snapshot in response payload (default: true).
includeSnapshotTimestamp (Optional) Boolean (true/false). If includeSnapshot = true, 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
{
  "did": "4697f11336c540a69ffd6f445061215e",
  "data": {
    "lastMessageTs": 1421281794212,
    "lastActionTs": 1421463142526,
    "availability": "online",
    "lastTimeOnline": 1421463142563,
    "snapshot": {
      ...
    }
  }
}

Response parameters

Parameter Description
did Device ID.
lastMessageTs Timestamp of last message sent by the device and received by ARTIK Cloud.
lastActionTs Timestamp of last Action received by ARTIK Cloud for the device.
availability Device availability. <ul><li> online means device can send messages and receive Actions.</li><li>offline means device cannot send messages or receive Actions.</li><li> unknown means device has never connected via WebSocket, MQTT, or CoAP, or has never manually declared any status.</li></ul>
lastTimeOnline Timestamp of last time availability = online.
snapshot JSON-formatted message snapshot. See Get message snapshots for format.

Get device statuses

GET /devices/status

Returns a list of device statuses.

Available URL query parameters

Parameter Description
dids Comma-separated list of device IDs (minimum: 1).
includeSnapshot (Optional) Boolean (true/false). Indicates whether to return message snapshot in response payload (default: true).
includeSnapshotTimestamp (Optional) Boolean (true/false). If includeSnapshot = true, 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
{
  "total": 2,
  "offset": 0,
  "count": 2,
  "data": [ {
    "did": "4697f11336c540a69ffd6f445061215e",
    "data": {
      "lastMessageTs": 1421281794212,
      "lastActionTs": 1421463142526,
      "availability":"online",
      "lastTimeOnline": 1421463142563,
      "snapshot": {
      }
    }
   },
  ...
  ]
}

Update device status

PUT /devices/<deviceID>/status

Modifies current status of a device.

Request parameters

Parameter Description
deviceID Device ID.

Request body parameters

Parameter Description
availability Device availability. Can be online, offline, unknown.

Example response

1
2
3
4
5
6
7
8
9
{
  "did": "4697f11336c540a69ffd6f445061215e",
  "data": {
    "lastMessageTs": 1421281794212,
    "lastActionTs": 1421463142526,
    "availability": "online",
    "lastTimeOnline": 1421463142563,
  }
}

Get a device's certificates

GET /devices/<deviceID>/certificate

Returns fields for a device's certificates.

Request parameters

Parameter Description
deviceID 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
34
35
36
37
38
39
40
41
{
  "data": {
    "deviceCertificateFields": {
      "version": 1,
      "serialNumber": "85a588901ce653d0",
      "signatureAlgorithm": "SHA256WITHRSA",
      "subject": "1.2.840.113549.1.9.1=#16096440746573742e6672,CN=DeviceD1,O=My device manufacture organisation,ST=Some-State,C=FR",
      "issuer": "1.2.840.113549.1.9.1=#16097440746573742e6672,CN=MyCA,OU=test,O=My CA organisation,ST=Some-State,C=FR",
      "validity": {
        "notBefore": 1492785005000,
        "notAfter": 1535985005000
      }
    },
    "issuerCertificateFields": {
      "version": 3,
      "serialNumber": "fd93df0205aad39a",
      "signatureAlgorithm": "SHA256WITHRSA",
      "subject": "1.2.840.113549.1.9.1=#16097440746573742e6672,CN=MyCA,OU=test,O=My CA organisation,ST=Some-State,C=FR",
      "issuer": "1.2.840.113549.1.9.1=#16097440746573742e6672,CN=MyCA,OU=test,O=My CA organisation,ST=Some-State,C=FR",
      "validity": {
        "notBefore": 1492784953000,
        "notAfter": 1492784953010
      }
    },
    "trustAnchorCertificateFields": {
      "version": 3,
      "serialNumber": "fd93df0205aad39a",
      "signatureAlgorithm": "SHA256WITHRSA",
      "subject": "1.2.840.113549.1.9.1=#16097440746573742e6672,CN=MyCA,OU=test,O=My CA organisation,ST=Some-State,C=FR",
      "issuer": "1.2.840.113549.1.9.1=#16097440746573742e6672,CN=MyCA,OU=test,O=My CA organisation,ST=Some-State,C=FR",
      "validity": {
        "notBefore": 1492784953000,
        "notAfter": 1492784953010
      }
    },
    "isValid": false,
    "error": {
      "reason": "Trust anchor for certification path not found."
    }
  }
}

Response parameters

Parameter Description
deviceCertificateFields Certificate fields of the client (device) certificate.
issuerCertificateFields Certificate fields of the issuer (device type) certificate.
trustAnchorCertificateFields Certificate fields of the trust anchor recovered when validating the certification path.
isValid Boolean (true/false). Indicates whether the certificate chained is valid. If false the device is unable to send data due to a problem in the certification path.
error Error returned if isValid = false.

Error cases

A 404 error will be returned for an unsecured device.

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.

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
{ "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 Share 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
  }
}

Response parameters

Parameter Description
id Shared ID.
email Email address which received the share invitation.
status Share status.
sharedOn Timestamp.

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

Response parameters

Parameter Description
id Shared ID.

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.

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 PENDING, ACCEPTED, REJECTED, EXPIRED, DELETED (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]
  }
}
          

Upload an Approved List

POST /devicetypes/<deviceTypeId>/whitelist

Uploads an Approved List as a CSV file.

Request parameters

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

Example response

1
2
3
{
   "uploadId": "uploadID1234"
}

Response parameters

Parameter Description
uploadId Upload ID.

Check Approved List upload status

GET /devicetypes/<deviceTypeId>/whitelist/<uploadId>/status

Returns the status of an uploaded CSV.

Request parameters

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

Example response

1
2
3
4
5
6
7
8
9
10
11
{
  "data": {
    "uploadId": "5842551b98aa4e44a239294dabea967d",
    "status": "Completed",
    "vdidsCount": {
      "total": 10000,
      "succeeded": 9994,
      "failed": 6
    }
  }
}

Response parameters

Parameter Description
uploadId Upload ID.
status Upload status.
vdidsCount Count of vendor device IDs.<ul><li>total: Total number of vendor device IDs uploaded.</li><li>succeeded: Number of successful uploads.</li><li>failed: Number of failed uploads.</li></ul>

Get rejected device rows

GET /devicetypes/<deviceTypeId>/whitelist/<uploadId>/rejectedRows

Returns the rows that were rejected in an uploaded CSV.

Request parameters

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

Available URL query parameters

Parameter Description
count (Optional) Number of items to return per query. Can be 1-1000 (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
{
  "data":[
    {
      "index":"0",
      "message":"Invalid vdid format"
    },
    {
      "index":"4",
      "message":"Invalid vdid format"
    }
  ],
  "total":92,
  "offset":82,
  "count":10
}

Response parameters

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

Get a device type's Approved List

GET /devicetypes/<deviceTypeId>/whitelist

Returns the Approved List 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
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "dtid": "dta8a02005a5854c11b224997e2705e3cc",
  "offset": 0,
  "count": 4,
  "total": 9994,
  "data": [
    {
      "vdid": "1b2138b1-9c45-44ac-8d2d-c965d110d44d",
      "uploadedOn": "2017-11-16T05:57:24"
    },
    {
      "vdid": "0fc18b86-42d8-405f-8135-4ccb49069047",
      "uploadedOn": "2017-11-16T05:57:24"
    },
    {
      "vdid": "0c80e060-af61-40dc-9594-764aceca7701",
      "uploadedOn": "2017-11-16T05:57:24"
    },
    {
      "vdid": "0d668f54-579f-4848-9ada-8386d1b4cded",
      "uploadedOn": "2017-11-16T05:57:24"
    }
  ]
}

Response parameters

Parameter Description
dtid Device type ID.
offset String required for pagination.
count Number of items returned on the page.
total Total number of items.
vdid Vendor device ID.
uploadedOn Timestamp upload was completed.

Remove device from Approved List

DELETE /devicetypes/<deviceTypeID>/whitelist/<vendorDeviceID>

Deletes a specified device from a device type's Approved List.

Request parameters

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

Example response

1
2
3
4
5
6
{
  "data" : {
    "dtid": "dta8a02005a5854c11b224997e2705e3cc",
    "vdid": "vdid8"
  }
}

Enable/disable Approved List for a device type

PUT /devicetypes/<deviceTypeID>/whitelist/enable

Enables or disables a device type's Approved List.

Request parameters

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

Request body parameters

Parameter Description
enableWhitelist Boolean (true/false). Enable or disable an Approved List.

Example request

1
2
3
{
  "enableWhitelist":true
}

Example response

1
2
3
4
5
6
{
  "data": {
    "dtid": "dta8a02005a5854c11b224997e2705e3cc",
    "enableWhitelist": true
  }
}

Upload Approved List certificate

POST /devicetypes/<deviceTypeID>/whitelist/certificates

Uploads a Public X.509 certificate for a device type. This is required for device types that are not securely registered. Read the documentation for details.

Request parameters

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

Request body parameters

Parameter Description
certificate Public X.509 certificate.

Example request

1
2
3
{
  "certificate":"-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIZCUXZkuugkXPZAC5A=\n-----END CERTIFICATE-----\n"
}

Remove Approved List certificate from device type

DELETE /devicetypes/<deviceTypeID>/whitelist/certificates/<certificateID>

Deletes an Approved List certificate for a device type.

Request parameters

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

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": {
    "certificateFields": {
      "version": 3,
      "serialNumber": "f9045d1ba0e6a691",
      "signatureAlgorithm": "SHA256WITHRSA",
      "subject": "O=Internet Widgits Pty Ltd,ST=Some-State,C=AU",
      "issuer": "O=Internet Widgits Pty Ltd,ST=Some-State,C=AU",
      "validity": {
        "notBefore": 1506540213000,
        "notAfter": 1549740213000
      }
    },
    "id": "cacd79d63fbc864ff8b9d25ac39f1e29be"
  }
}

Check if Approved List is enabled for device type

GET /devicetypes/<deviceTypeID>/whitelist/status

Returns the enabled/disabled status of an Approved List.

Request parameters

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

Example response

1
2
3
4
5
6
{
  "data" : {
    "dtid": "dta8a02005a5854c11b224997e2705e3cc",
    "enableWhitelist": false
  }
}

Get a device type's Approved List certificate

GET /devicetypes/<deviceTypeID>/whitelist/certificates

Returns details of an Approved List certificate.

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
{
  "data": {
    "certificateFields": {
      "version": 3,
      "serialNumber": "f9045d1ba0e6a691",
      "signatureAlgorithm": "SHA256WITHRSA",
      "subject": "O=Internet Widgits Pty Ltd,ST=Some-State,C=AU",
      "issuer": "O=Internet Widgits Pty Ltd,ST=Some-State,C=AU",
      "validity": {
        "notBefore": 1506540213000,
        "notAfter": 1549740213000
      }
    },
    "id": "cacd79d63fbc864ff8b9d25ac39f1e29be"
  }
}

Response parameters

Parameter Description
certificateFields Certificate fields.
version Certificate version.
serialNumber Certificate serial number.
signatureAlgorithm Certificate signature algorithm.
subject Certificate subject.
issuer Certificate issuer.
validity Time range of certificate validity.
notBefore Beginning timestamp of certificate validity.
notAfter Ending timestamp of certificate validity.
id Certificate ID.

Find a vendor device ID

GET /devicetypes/<deviceTypeID>/whitelist/vdid/<vendorDeviceID>

Returns a specified vendor device ID.

Request parameters

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

Example response

1
2
3
4
5
6
7
8
{
  "data": {
    "dtid": "dta8a02005a5854c11b224997e2705e3cc",
    "vdid": "ahjsdjhasgd",
    "uploadedOn": "2017-11-13T05:48:09",
    "did": "4697f11336c540a69ffd6f445061215e"
  }
}

Response parameters

Parameter Description
dtid Device type ID.
vdid Vendor device ID.
uploadedOn Timestamp upload was completed.
did Device ID.

Messages

Post a message

POST /messages

Sends a message.

Example request (message)

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

Request body parameters

Parameter Description
sdid 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) Timestamp (past, present or future). If not sent, defaults to current time.
type (Optional) Type of message. Defaults to message. Must be message if specified.

Example response

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

Response parameters

Parameter Description
mid Message ID.

Error cases

The API 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 services without that field).

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.

Post an Action

POST /actions

Sends an Action to the specified device.

Request body parameters

Parameter Description
data Data. Must be a JSON payload containing only the actions to send.
ddid Destination device ID.
sdid (Optional) Source device ID.
ts (Optional) Timestamp (past, present or future). If not sent, defaults to current time.
type (Optional) Type of message. Defaults to action. Must be action if specified.

Example request

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
{
  "ddid": "9f06411ad3174a4f98444a374447fe09",
  "ddid": "9f06411ad3174a4f98444a374447fe10",
  "ts": 1388179812427,
  "type": "action",
  "data": {
    "actions": [
      {
        "name": "setOn",
        "parameters": {}
      },
      {
        "name": "setColorRGB",
        "parameters": {
          "colorRGB": {
            "r": 192,
            "g": 180,
            "b": 45
          },
        "intensity": 55
        }
      }
    ]
  }
}

Example response

1
2
3
4
5
{
  "data": {
    "mid": "f32e94839a8f4644bb852dd112ac30cc"
  }
}           

Response parameters

Parameter Description
mid Message ID.

Error cases

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

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" : {}
    }
  ]
}

Monetization

Get upgrade URL

GET /pricing/devices/<deviceID>/revenueshare/upgradepath

If a user's device is using a Monetization plan that can be upgraded, returns a URL to be called by an application working with the device. The URL opens a UI to one of three phases of the upgrade flow.

This endpoint accepts a user token as the access token.

Available URL query parameters

Parameter Description
action Phase of the upgrade flow (defaults to upgrade). <ul><li>upgrade presents option to upgrade Monetization plan.</li><li>select prompts user to select a credit card on file.</li><li>edit prompts user to enter credit card information.</li></ul>

Example response

1
2
3
4
5
{
  "data" :{
    "url":"www.xyz.artik.cloud/payment/upgrade/<one-time-use-token>"
  }
}

Response parameters

Parameter Description
url Upgrade URL. Contains one-time token that maps to the access token, user ID, and device ID of the request.

Get device type Monetization Tiers

GET /pricing/devicetypes/<deviceTypeID>/pricingtiers

Returns Monetization Tiers (if any) of a device type.

This endpoint accepts a user token as the access token.

Available URL query parameters

Parameter Description
latest (Optional) Boolean (true/false). If true, return only the latest version of a Monetization Tier (default: false).
status (Optional) Status of Monetization Tier. Can be NEW, PENDING, APPROVED, or REJECTED. If not specified, returns all statuses.

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
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
{ 
   "data":{ 
      "pricingTiers":[ 
         { 
            "type":"count",
            "tiers":[ 
               { 
                  "ptid":"uniqueTierId",
                  "name":"basic",
                  "type":"free",
                  "description":"Free tier",
                  "messageLimit":80,
                  "interval":"DAILY"
               },
               { 
                  "ptid":"uniqueTierId",
                  "name":"premium",
                  "description":"Paid tier",
                  "type":"paid",
                  "cost":"4.0,
                  "messageLimit":-1,
                  "interval":"DAILY",
                  "billingInterval":"ONCE"
               }
            ],
            "contactInfo":{ 
               "email":"abc@gmail.com",
               "phone":"986-876-9876"
            },
            "version":2,
            "status":"NEW"
         },
         { 
            "type":"count",
            "tiers":[ 
               { 
                  "ptid":"uniqueTierId",                  
                  "type":"free",
                  "messageLimit":100,
                  "interval":"DAILY"
               },
               { 
                  "ptid":"uniqueTierId",                  
                  "type":"paid",
                  "cost":"2.0",
                  "messageLimit":-1,
                  "interval":"DAILY",
                  "billingInterval":"ONCE"
               }
            ],
            "contactInfo":{ 
               "email":"abc@gmail.com",
               "phone":"986-876-9876"
            },
            "version":1,
            "status":"APPROVED",
            "comments" : "This is Approved."
            "revenueSharePercent":70
         }
      ],
      "total":2
   }
}

type=count is fixed and indicates that the Monetization plan is based on a daily message count.

Response parameters

Parameter Description
ptid Tier ID.
name Tier name.
type Tier type (free or paid).
description Tier description.
cost Upgrade price.
messageLimit Message quota limit (no limit if -1).
interval Quota counter interval.
billingInterval Billing interval.
active Tier active status.
contactInfo Device type owner contact information.
version Version of Monetization Tier.
status Status of Monetization Tier.
revenueSharePercent Device type owner's percentage share of Monetization revenue.
total Total number of items.

Get a device's Monetization Tiers

GET /pricing/devices/<deviceID>/pricingtiers

Returns Monetization Tiers (if any) of a device.

This endpoint accepts a user token as the access token.

Available URL query parameters

Parameter Description
active (Optional) Boolean (true/false). If true, return only the current active Monetization Tier (if any). If not specified, returns both active and inactive tiers (if any).

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" : { 
    "did":"<device_id>",
    "pricingTiers":[ 
       { 
         "ptid":"uniqueTierId",
         "name":"premium",
         "description":"Paid tier",
         "type": "paid",
         "messageLimit":-1,
         "cost":"9.99",
         "interval":"DAILY",
         "billingInterval":"ONCE",
         "active":true
       }
       { 
         "ptid":"uniqueTierId",
         "name":"basic",
         "description":"Free tier",
         "type":"free",
         "messageLimit":80,
         "interval":"DAILY",
         "active":false
       }
    ]
  }
}

Response parameters

Parameter Description
ptid Tier ID.
name Tier name.
type Tier type (free or paid).
description Tier description.
messageLimit Message quota limit (no limit if -1).
cost Upgrade price.
interval Quota counter interval.
billingInterval Billing interval.
active Tier active status.

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). Applies when subscribing per user (with uid).

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.

Get a Rule

GET /rules/<ruleID>

Returns a Rule.

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

Required permissions: Application has READ on source device and WRITE on target device of Rule.

Request parameters

Parameter Description
ruleID Rule ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "data": {
    "uid":"f0a3057950384215acf8ba25c2fbfcb7",
    "id":"f0a3057950384215acf8ba25c2fbfcb7",
    "aid": "b6951bf387b84f63b38911ae35d65e28",
    "scope": "thisApplication"
    "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
  }
}

See Get a user's Rules for examples of other possible responses.

Response parameters

Parameter Description
uid User ID.
id Rule ID.
aid Application ID. Returned only when a Rule has scope=thisApplication.
scope Rule scope.
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.

Please note that Actions triggered by a Rule are subject to special rate limits.

Required permissions: Application has READ on source device and WRITE on target device of Rule.

Example request

1
2
3
4
5
6
7
{
  "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,
  "scope":"thisApplication"
}

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.
scope (Optional) Rule scope. <ul><li>allApplications sets Rule accessible to all applications.</li><li>thisApplication sets Rule accessible to this application only (default).</li></ul>The application must have the required permissions on the devices used in the Rule.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "data": {
    "uid":"f0a3057950384215acf8ba25c2fbfcb7",
    "id":"f0a3057950384215acf8ba25c2fbfcb7",
    "aid": "b6951bf387b84f63b38911ae35d65e28",
    "scope": "thisApplication"
    "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.

Required permissions: Application has READ on source device and WRITE on target device of Rule.

Request parameters

Parameter Description
ruleID Rule ID.

Example request

1
2
3
4
5
6
7
{
  "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,
  "scope":"thisApplication"
}

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.
scope (Optional) Rule scope. <ul><li>allApplications sets Rule accessible to all applications.</li><li>thisApplication sets Rule accessible to this application only (default).</li></ul>The application must have the required permissions on the devices used in the Rule.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "data": {
    "uid":"f0a3057950384215acf8ba25c2fbfcb7",
    "id":"f0a3057950384215acf8ba25c2fbfcb7",
    "aid": "b6951bf387b84f63b38911ae35d65e28",
    "scope": "thisApplication"
    "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.

Required permissions: Application has READ on source device and WRITE on target device of Rule.

Request parameters

Parameter Description
ruleID Rule ID.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "data": {
    "uid":"f0a3057950384215acf8ba25c2fbfcb7",
    "id":"f0a3057950384215acf8ba25c2fbfcb7",
    "aid": "b6951bf387b84f63b38911ae35d65e28",
    "scope": "thisApplication"
    "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
  }
}

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.

Required permissions: Application has READ on source device and WRITE on target device of Rule.

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.

Required permissions: Application has WRITE on target device of Rule.

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.

Machine Learning

The Machine Learning APIs are used to create one of two model types with their own data input and output.

  • The input of a prediction model is data from a device field. When trained, the model outputs a predicted data value for a specified timestamp.
  • The input of an anomaly detection model is data from a device field and a sensitivity threshold. When trained, the model outputs a boolean that determines whether or not a new data value at a specified timestamp is an anomaly.

These APIs are also integrated with the Rules API. A Rule can include a prediction or anomaly detection condition and an operator to match the result of the prediction or anomaly detection. This can also be done on the Developer Dashboard.

Create and train a model

POST /ml/models

Creates a prediction or anomaly detection model that learns a device's data usage.

Required permissions: Application has READ on source device specified in the model.

Request body parameters

Parameter Description
sources Data source to use in model.
did Source device ID.
field Source data field.
type Type of model. Can be prediction or anomalyDetectionUsingPrediction.
parameters Parameters used in model. Some parameters are specific to the model type.<ul><li>sourceToPredict: did (device) and field (data field) to predict.</li><li>anomalyDetectionSensitivity: (Optional) Used only for anomaly detection model. Sensitivity of anomaly detection. Can be 0 (very few anomalies) to 100 (receive many anomalies). Defaults to 50.</li><li>predictIn: Used only for prediction model. Time in seconds from last received data to predict output. Must be a positive value (greater than 0).</li></ul>
uid User ID. Required if using an application token as the access token.

We do not currently support prediction or anomaly detection on a device's field based on another device's field. This capability is forthcoming.

Prediction model

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "data": {
    "sources": [
      {
        "did": "8020d467d0e9438782b77ef5eebcade2",
        "field": "state"
      }
    ]
  },
  "type": "prediction",
  "parameters": {
    "sourceToPredict": {
        "did": "8020d467d0e9438782b77ef5eebcade2",
        "field": "state"  
    },
    "predictIn": 3600
  }
} 

The above request creates a model that predicts door lock state.

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
{
  "data": {
    "id": "54acae38ac464032b2028c8aa6fa478c",
    "uid": "d8713ebafc5741c1aa6b801295c087d2",
    "aid": "d18f11efb5244c8f99f1ac7aa4fb9bbc",
    "inputs": [
      {
        "name": "ts",
          "type": "number"
      }
    ],
    "outputs": [
      {
        "name": "8020d467d0e9438782b77ef5eebcade2.state",
          "type": "string"
      }
    ],
    "data": {
      "from": "fields",
      "sources": [
        {
          "did": "8020d467d0e9438782b77ef5eebcade2",
          "field": "state"
        }
      ]
    },
    "trainingCron": "45 18 15 * * *",
    "type": "Prediction",
    "parameters": {
      "sourceToPredict": {
      "did": "8020d467d0e9438782b77ef5eebcade2",
      "field": "state"
      },
      "predictIn": 3600
    },
    "status": "training",
    "origin": "artikcloud",
    "version": 1
  }
}

Anomaly detection model

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "data": {
    "sources": [
      {
        "did": "8020d467d0e9438782b77ef5eebcade2",
        "field": "state"
      }
    ]
  },
  "type": "anomalyDetectionUsingPrediction",
  "parameters": {
    "sourceToPredict": {
        "did": "8020d467d0e9438782b77ef5eebcade2",
        "field": "state"  
    },
    "anomalyDetectionSensitivity": 70
  }
} 

The above request creates a model that detects anomalies in door lock state.

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
{
  "data": {
    "id": "b4ae30e34c544a6a900e004dc3164956",
    "uid": "d8713ebafc5741c1aa6b801295c087d2",
    "aid": "d18f11efb5244c8f99f1ac7aa4fb9bbc",
    "inputs": [
      {
        "name": "ts",
        "type": "number"
      },
      {
        "name": "8020d467d0e9438782b77ef5eebcade2.state",
        "type": "string"
      }
    ],
    "outputs": [
      {
          "name": "isAnomaly",
          "type": "boolean"
      }
    ],
    "data": {
      "from": "fields",
      "sources": [
          {
            "did": "8020d467d0e9438782b77ef5eebcade2",
            "field": "state"
          }
      ]
    },
    "trainingCron": "46 27 15 * * *",
    "type": "anomalyDetectionUsingPrediction",
    "parameters": {
      "sourceToPredict": {
        "did": "8020d467d0e9438782b77ef5eebcade2",
        "field": "state"
      },
      "anomalyDetectionSensitivity": 70,
    },
    "status": "training",
    "origin": "artikcloud",
    "version": 1
  }
}

Response parameters

Parameter Description
id Model ID.
aid Application ID.
uid User ID.
inputs Data input for model.
outputs Data output for model.
name Input/output data name. Output name will be isAnomaly for anomaly detection model and Manifest field name for prediction model.
type Input/output data type. Output type will be boolean for anomaly detection model and Manifest field type for prediction model.
sources Data source.
did Source device ID.
field Source data field.
type Model type.
parameters Model parameters.
sourceToPredict Data source to predict.
anomalyDetectionSensitivity Anomaly detection sensitivity. Only returned for anomaly detection model.
predictIn Prediction lag. Only returned for prediction model.
trainingCron Datetime for model training.
version Model version.
origin Model origin.
status Model status. Can be training, ready, or error.

Error cases

A validation error or training error returns a 200 or 400 error as follows.

1
2
3
4
5
6
7
8
9
10
{ 
  "data": {
  ...
    "error": {
      "errorType": "Validation Error",
      "errorMessage": "The manifest path "temperature" referenced in this model is not valid anymore for the device did"
    }
  }
...
}

Predict outputs

POST /ml/models/<modelID>/predict

Returns the predicted output for the specified input.

Request parameters

Parameter Description
modelID Model ID.

Request body parameters

Parameter Description
inputs Data input to use in prediction, returned when creating a model.
name Input data name.
type Input data type.

Prediction model

Example request

1
2
3
4
5
6
7
8
{
  "inputs": [ 
    {
      "name": "ts",
      "value": 1511450342868
    }
  ]
}

Example response

1
2
3
4
5
6
7
8
9
10
{
  "data": {
    "outputs": [
      {
        "name": "8020d467d0e9438782b77ef5eebcade2.state",
        "value": "unlocked"
      }
    ]
  }
}

Anomaly detection model

Example request

1
2
3
4
5
6
7
8
9
10
11
12
{
  "inputs": [ 
    {
      "name": "ts",
      "value": 1511450342868
    }, 
    {
      "name": "8020d467d0e9438782b77ef5eebcade2.state",
      "value": "unlocked"
    }
  ]
}

Example response

1
2
3
4
5
6
7
8
9
10
{
  "data": {
    "outputs": [
      {
        "name": "isAnomaly",
        "value": false
      }
    ]
  }
}

Response parameters

Parameter Description
name Output name.
value Output value.
value Output confidence

Error cases

A 400 error is returned if the model is not trained yet.

Get a model

GET /ml/models/<modelID>

Returns a model.

Request parameters

Parameter Description
modelID Model ID.

Example response

1
2
3
4
5
6
7
8
{
  "data": { 
    "id": "...",
    "aid": "...",
    "uid": "...",
    ...
  }
}

Delete a model

DELETE /ml/models/<modelID>

Deletes a model.

Request parameters

Parameter Description
modelID Model ID.

Example response

1
2
3
4
5
6
7
8
{
  "data": { 
    "id": "...",
    "aid": "...",
    "uid": "...",
    ...
  }
}

Get models

GET /ml/models

Returns all models of an application.

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).
uid User ID. Required if using an application token as the access token.

Example response

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

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.

The connection property indicates whether the device is actively connected. Active connections are indicated for WebSocket, MQTT, or CoAP. Does NOT apply for SmartThings and Cloud Connector devices.

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 /trials/sessions/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.
429 6313 Following actions can't be send because rate limiting exceeded: [list of affected Actions] User has reached the rate limit for HTTP Actions.
413 430 Payload size exceeded. Plan quota exceeded for organization <organizationID>. Reason: Max payload size limit.