Cloud-aware devices that have been or will be manufactured for a project. Each object represents an instance of a device class defined for the project.

Endpoints

The Device object

  • idinteger

    Unique device ID.

  • projectIdinteger

    Project that this device belongs to.

  • creationTimestring| format is date-time

    Timestamp of device record creation.

  • namestring

    Display name of device.

  • tagstring

    An optional/informational tag associated with device. Can be used to store the serial number, for example.

  • deviceClassstring

    Device class ID as defined by the project.

  • homeIdinteger

    This property is present if device belongs to a home.

  • apiKeystring

    API access key assigned to device. Usually hidden except to privileged clients, but is also present during the On-Demand Device Provisiong process.

  • claimCodestring

    Claim code assigned to device. Hidden except to privileged clients.

  • claimTimestring| format is date-time

    Timestamp of device being claimed by a user.

  • claimExpirationTimestring| format is date-time

    Expiration time of device's claimable state.

  • isConnectedboolean

    Device is currently connected to MODE Cloud via a websocket or MQTT connection.

  • lastConnectTimestring| format is date-time

    The last time the device connected to the cloud.

  • lastDisconnectTimestring| format is date-time

    The last time the device disconnected from the cloud.

  • channelstring

    The name of firmware channel the device should download from.

  • bundleInstalledstring

    If present, the name of firmware bundle installed on this device.

  • bundleInstallTimestring| format is date-time

    If present, the timestmap when the firmware bundle was installed.

The Device object

{
  "id": 34346,
  "projectId": 1265,
  "deviceClass": "smart_light",
  "name": "light",
  "tag": "bedroom_light",
  "homeId": 1923,
  "claimExpirationTime": "2019-09-18T22:19:39Z",
  "claimTime": "2019-09-18T22:19:39Z",
  "isConnected": false,
  "lastConnectTime": "2019-09-18T22:31:20.678Z",
  "lastDisconnectTime": "2019-09-18T22:34:19.314Z",
  "apiKey": "v1.ZHwzNDM0Ng==.8293847182.ec7bad61175db09bb42e2a8650f1bfe0e3kiekdj998d3135e1a2ca9c5c2106f8743555bc5681f1fdaf1dabb4c59fffd6092b8bfc6685fc7417bb0b49d1bd3e9257e4547ffcf1da06e",
  "claimCode": "f5106924ce0f943d"
}

Get all devices

Endpoint
get /devices
Description

Get the list of devices of a project (by using the projectId parameter), or devices belonging to a home (by using the homeId parameter). Either project ID or home ID must be specified. To fetch the devices of a project, the request must be made using a project API key with "Admin" privileges. An optional deviceClass parameter can be used to return only devices of the specified device class.

Query Parameters
  • projectId

    integer

    Return devices of the specified project.

  • homeId

    integer

    Return devices that belong to the specified home.

  • deviceClass

    string

    Return devices of the specified Device Class ID.

  • skip

    integer

    Number of devices to skip over.

  • limit

    integer

    Maximum number of devices to return.

    Default value is 25

    Minimum value is 1

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200Successful retrieval of all devices.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

[
  {
    "id": 34256,
    "projectId": 1265,
    "deviceClass": "smart_sensor",
    "name": "happy",
    "tag": "store_one",
    "homeId": 1701,
    "claimExpirationTime": "2019-09-18T22:19:39Z",
    "claimTime": "2019-09-18T22:19:39Z",
    "isConnected": false,
    "lastConnectTime": "2019-09-18T22:31:20.678Z",
    "lastDisconnectTime": "2019-09-18T22:34:19.314Z"
  },
  {
    "id": "343d8",
    "projectId": 1265,
    "deviceClass": "smart_sensor",
    "name": "sad",
    "tag": "store_one",
    "claimExpirationTime": "2019-09-18T23:42:39.885Z",
    "isConnected": false
  }
]

Add device to a home

Endpoint
post /devices
Description

Add a device to a user's home. The complete process depends on how the project was set up and is carried out in one of two possible ways.

Devices are Pre-provisioned

If the project was configured to pre-provision all its devices, adding a device to a home means claiming ownership of an existing device and registering it to the specified home. In this scenario, the device in question must first enable registration before the user calls this API method.

Devices are Provisioned on Demand

If the project was configured to allow On-Demand Device Provisioning, a user must first initiate the device provisioning process and obtain a provisioning token. The token should be passed to the device hardware which will then call this API method to complete the process. The Device object returned will contain an API key. The device hardware should store the device ID and API key, so that it can begin communicating with the MODE API directly.

Request Headers What's this?
  • Authorization

    Must contain API key of a user. Required only if device is pre-provisioned.

Request Body
  • homeId

    integer

    ID of the home to which the device will be added.

    Required if device is pre-provisioned.

  • claimCode

    string

    Unique claim code assigned to the device to be added.

    Required if device is pre-provisioned.

  • token

    string

    Device provisioning token issued for the device to be added.

    Required for On-Demand Device Provisioning.

  • deviceClass

    string

    Override the default Device Class associated with the token.

    Only used for On-Demand Device Provisioning

Response
  • 201Successfully added device to home. Return body is device added with the home ID now specified.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

homeId=1885&claimCode=b4d632e16981e66a

Response Body Sample

{
  "id": 34328,
  "projectId": 1260,
  "deviceClass": "smart_sensor",
  "name": "happy",
  "tag": "0002",
  "homeId": 1885,
  "claimExpirationTime": "2019-12-17T22:54:39Z",
  "claimTime": "2019-12-17T22:54:39Z",
  "isConnected": false,
  "lastConnectTime": "2019-12-17T22:54:03.321Z"
}

Get device info

Endpoint
get /devices/{deviceId}
Description

Return the device with the specified ID.

Path Parameters
  • deviceId

    integer

    required

    Device ID

Request Headers What's this?
  • Authorization

    required

    Must contain a project, user or device API key.

Response
  • 200Successful retrieval of device by specified ID.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested device does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": 34328,
  "projectId": 1260,
  "deviceClass": "smart_light",
  "name": "happy",
  "tag": "0002",
  "homeId": 1885,
  "claimExpirationTime": "2019-12-17T22:54:39Z",
  "claimTime": "2019-12-17T22:54:39Z",
  "isConnected": true,
  "lastConnectTime": "2019-12-17T22:54:03.321Z"
}

Update device info

Endpoint
patch /devices/{deviceId}
Description

Update the device with the specified ID. Normally, only the name field of the device instance can be changed. But if the request is made with a Project API Key with "Admin" privileges, the device instance can be moved or added to a home by specifying a homeId field in the request body.

Path Parameters
  • deviceId

    integer

    required

    Device ID

Request Headers What's this?
  • Authorization

    required

    Must contain a project or user API key.

Request Body
  • name

    string

    Display name of device.

  • tag

    string

    An optional/informational tag associated with device. Can be used to store the serial number, for example.

  • homeId

    integer

    This property is present if device belongs to a home.

  • claimCode

    string

    Claim code assigned to device. Hidden except to privileged clients.

Response
  • 204Successfully updated device properties. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested device does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "name": "new_sensor_name",
  "tag": "new_001",
  "homeId": 1885,
  "claimCode": "ba985521068488fc"
}

Delete a device

Endpoint
delete /devices/{deviceId}
Description

Delete (or "Un-provision") the device with the specified ID. The actual process depends on how the project is set up.

Devices are Pre-provisioned

If the project was configured to pre-provision all its devices, deleting a device simply means removing the device from its current home. The device can be claimed by another home in the future, and the device ID and device API key remain valid.

Devices are Provisioned on Demand

If the project was configured to allow On-Demand Device Provisioning, deleting a device means removing the device from its home and erasing the device from the system permanently. The device ID and device API key will become invalid.

Path Parameters
  • deviceId

    integer

    required

    Device ID

Request Headers What's this?
  • Authorization

    required

    Must contain a project or device API key.

Response
  • 204Successfully deleted a single user. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required device does not exist or is not accessible.
  • 409The device cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Receive commands

Endpoint
get /devices/{deviceId}/command
Description

Establish a WebSocket connection and listen for commands. Only the corresponding device itself can make this call. Any non-WebSocket requests will be rejected. Once the connection is established, the client can expect incoming messages in the form of Device Command JSON objects as used in the PUT method. Since not all WebSocket client implementations allow you to set the Authorization HTTP header, you can pass the device API key as the authToken query parameter.

Path Parameters
  • deviceId

    integer

    required

    Device ID

Query Parameters
  • authToken

    string

    API key assigned to device. Needed only if the Authorization header cannot be set.

Request Headers What's this?
  • Authorization

    required

    Must contain an API key of the matching device.

Response
  • 101Successfully established a WebSocket connection.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested resource does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Send command to device

Endpoint
put /devices/{deviceId}/command
Description

Issue a command to the specified device.

Path Parameters
  • deviceId

    integer

    required

    Device ID

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Request Body
  • action

    string

    required

    Action to be taken by device.

  • parameters

    object

    Action-specific parameters. This is opaque to the cloud service.

Response
  • 204Successfully sent a command to device. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested command does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
    "action": "sprinkler-on",
    "parameters": {
        "zone": 2,
        "duration": 120
    }
}

Send device event to cloud

Endpoint
put /devices/{deviceId}/event
Description

Send a device event to the cloud, which propagates the event to the other relevant listeners. Only the corresponding device itself can make this call.

Path Parameters
  • deviceId

    integer

    required

    Device ID

Request Headers What's this?
  • Authorization

    required

    Must contain API key of the matching device.

Request Body
  • eventType

    string

    required

    Event type ID. Project Developers can define any event IDs.

  • eventData

    object

    required

    Event-specific data as a JSON hash. Opaque to the cloud service.

Response
  • 204Successfully sent device event to the cloud. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested event does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
    "eventType": "sprinkler-status",
    "eventData": {
        "zones": [0,0,0,0,0,0,0,1],
        "serial": 12,
        "timestamp": 1402313424,
        "appSerial": 14,
        "appTimestamp": 14243423423
    }
}

Get key-value pairs (and receive updates)

Endpoint
get /devices/{deviceId}/kv
Description

Get all key-value pairs stored for the specified device, if request is a regular REST call. However, if the caller is the device itself, it can upgrade the request into a WebSocket connection. In that scenario, the device will automatically receive a full dump of all key-value pairs right after the WebSocket upgrade, and will receive real-time key-value updates thereafter.

This is part of the Device Data Proxy feature.

Path Parameters
  • deviceId

    integer

    required

    Device ID

Query Parameters
  • keyPrefix

    string

    required

    If specified, only items with keys containing the prefix are returned. This parameter is ignored for WebSocket requests.

Request Headers What's this?
  • Authorization

    required

    Must contain a user key, project API key, or API key of the matching device.

Response
  • 101Successfully established a WebSocket connection.
  • 200An array of key-value pair objects are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

[
    {
        "key": "happy",
        "value": true,
        "modificationTime": "2020-01-02T23:18:16.915Z"
    },
    {
        "key": "neutral",
        "value": false,
        "modificationTime": "2020-01-02T23:17:39.852Z"
    },
    {
        "key": "clicks",
        "value": 100,
        "modificationTime": "2020-01-02T23:18:21.383Z"
    }
]

Look up a key-value pair

Endpoint
get /devices/{deviceId}/kv/{key}
Description

Get the key-value pair for the specified key.

Path Parameters
  • deviceId

    integer

    required

    Device ID

  • key

    string

    required

    A unique key for a key-value pair stored for a device.

Request Headers What's this?
  • Authorization

    required

    Must contain a user key, project API key, or API key of the matching device.

Response
  • 200The matching key-value pair is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested kv does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "key": "happy",
  "value": true,
  "modificationTime": "2020-01-02T23:18:16.915Z"
}

Create or update a key-value pair

Endpoint
put /devices/{deviceId}/kv/{key}
Description

Set the value for the specified key. If the key-value pair does not already exist, it is created.

Path Parameters
  • deviceId

    integer

    required

    Device ID

  • key

    string

    required

    A unique key for a key-value pair stored for a device.

Request Headers What's this?
  • Authorization

    required

    Must contain a user key, project API key, or API key of the matching device.

Request Body
  • value

    required

    An arbitrary piece of data assigned to the given key.

Response
  • 204Key-value pair has been successfully stored. There is no response body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The specified device does not exist.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Delete a key-value pair

Endpoint
delete /devices/{deviceId}/kv/{key}
Description

Delete the key-value pair for the specified key.

Path Parameters
  • deviceId

    integer

    required

    Device ID

  • key

    string

    required

    A unique key for a key-value pair stored for a device.

Request Headers What's this?
  • Authorization

    required

    Must contain a user key, project API key, or API key of the matching device.

Response
  • 204The key-value pair has been successfully deleted. There is no response body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required kv does not exist or is not accessible.
  • 409The kv cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Record firmware installation

Endpoint
put /devices/{deviceId}/firmwareInfo
Description

This API records the information about the firmware installed on a device. When the device downloads and installs a firmware bundle, it should record the bundle ID with this endpoint.

Path Parameters
  • deviceId

    integer

    required

    Device ID

Request Headers What's this?
  • Authorization

    required

    Must contain device API key of the matching device.

Request Body
  • bundleId

    string

    required

    Unique ID that represents the installed bundle.

Response
  • 204Information has been successfully stored. There is no response body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The specified device does not exist.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "bundleId": "5e0e93edf8379d390de5417d"
}

Proxy GET request to app server

Endpoint
get /devices/{deviceId}/appProxy/{srcPath}
Description

Proxy a GET request to the a target app service if there is a matching App Proxy route for the specified source path. The response depends on the behavior of the target app service.

Path Parameters
  • deviceId

    integer

    required

    Device ID

  • srcPath

    string

    required

    A path that matches one of the source paths in the project's App Proxy configuration for devices.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Proxy POST request to app server

Endpoint
post /devices/{deviceId}/appProxy/{srcPath}
Description

Proxy a POST request to the a target app service if there is a matching App Proxy route for the specified source path. The request body and response depend on the behavior of the target app service.

Path Parameters
  • deviceId

    integer

    required

    Device ID

  • srcPath

    string

    required

    A path that matches one of the source paths in the project's App Proxy configuration for devices.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Proxy PUT request to app server

Endpoint
put /devices/{deviceId}/appProxy/{srcPath}
Description

Proxy a PUT request to the a target app service if there is a matching App Proxy route for the specified source path. The request body and response depend on the behavior of the target app service.

Path Parameters
  • deviceId

    integer

    required

    Device ID

  • srcPath

    string

    required

    A path that matches one of the source paths in the project's App Proxy configuration for devices.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Proxy PATCH request to app server

Endpoint
patch /devices/{deviceId}/appProxy/{srcPath}
Description

Proxy a PATCH request to the a target app service if there is a matching App Proxy route for the specified source path. The request body and response depend on the behavior of the target app service.

Path Parameters
  • deviceId

    integer

    required

    Device ID

  • srcPath

    string

    required

    A path that matches one of the source paths in the project's App Proxy configuration for devices.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Proxy DELETE request to app server

Endpoint
delete /devices/{deviceId}/appProxy/{srcPath}
Description

Proxy a DELETE request to the a target app service if there is a matching App Proxy route for the specified source path. The response depends on the behavior of the target app service.

Path Parameters
  • deviceId

    integer

    required

    Device ID

  • srcPath

    string

    required

    A path that matches one of the source paths in the project's App Proxy configuration for devices.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.