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

The Device Command object

  • actionstring

    Action to be taken by device.

  • parametersobject

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

The Event object

  • eventTypestring

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

  • eventDataobject

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

  • timestampstring| format is date-time

    Moment when event was triggered. MODE adds this at event delivery to listeners. Devices don't need to add this.

  • homeIdinteger

    ID of the home associated with this event. MODE adds this at event delivery to listeners. Devices don't need to add this.

  • originDeviceIdinteger

    MODE adds this at event delivery to listeners. This property is present if the event originates from a device.

  • originDeviceClassstring

    If the event originates from a device, this property is the device's class ID. MODE adds this at event delivery to listener.

  • originDeviceIpstring

    IP address of device. This property is present if the event originates from a device. MODE adds this at event delivery to listeners.

  • originProjectKeyIdstring

    If the event originates from a project API key, this property is the unique key ID. MODE adds this at event delivery to listener.

  • originProjectKeyNamestring

    If the event originates from a project API key, this property is its display name. MODE adds this at event delivery to listener.

The Event object

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

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.

Authorization Headers What's this?

Must contain a user or project API key.

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

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.

Authorization Headers What's this?

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

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.

Authorization Headers What's this?

Must contain a project, user or device API key.

URI Parameters
  • deviceId

    integer

    required

    Device ID

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.

Authorization Headers What's this?

Must contain a project or user API key.

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.

URI Parameters
  • deviceId

    integer

    required

    Device ID

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.

Authorization Headers What's this?

Must contain a project or device API key.

URI Parameters
  • deviceId

    integer

    required

    Device ID

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.

Authorization Headers What's this?

Must contain an API key of the matching device.

Query Parameters
  • authToken

    string

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

URI Parameters
  • deviceId

    integer

    required

    Device ID

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.

Authorization Headers What's this?

Must contain a user or project API key.

Body
  • action

    string

    required

    Action to be taken by device.

  • parameters

    object

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

URI Parameters
  • deviceId

    integer

    required

    Device ID

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.

Authorization Headers What's this?

Must contain API key of the matching device.

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.

URI Parameters
  • deviceId

    integer

    required

    Device ID

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.

Authorization Headers What's this?

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

Query Parameters
  • keyPrefix

    string

    required

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

URI Parameters
  • deviceId

    integer

    required

    Device ID

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.

Authorization Headers What's this?

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

URI Parameters
  • deviceId

    integer

    required

    Device ID

  • key

    string

    required

    A unique key for a key-value pair stored for a 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.

Authorization Headers What's this?

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

Body
  • value

    required

    An arbitrary piece of data assigned to the given key.

URI Parameters
  • deviceId

    integer

    required

    Device ID

  • key

    string

    required

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

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 requested <<resourcePathName|!singularize>> does not exist or is not accessible.
  • 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.

Authorization Headers What's this?

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

URI Parameters
  • deviceId

    integer

    required

    Device ID

  • key

    string

    required

    A unique key for a key-value pair stored for a 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.

Authorization Headers What's this?

Must contain device API key of the matching device.

Body
  • bundleId

    string

    required

    Unique ID that represents the installed bundle.

URI Parameters
  • deviceId

    integer

    required

    Device ID

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 requested <<resourcePathName|!singularize>> does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "bundleId": "5e0e93edf8379d390de5417d"
}