Get all devices
GET/devices
Base URL: https://api.tinkermode.com
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 the API the key of a user with
permission to read all devices, or a project API key.
An optional deviceClass parameter can be used to return only devices of the specified device class.
An optional tag parameter can be used to return only devices with the specified tag.
An optional hasHome parameter can be used to filter devices based on whether they belong to a home or not.
Authentication
Send an Authorization header of the form ModeCloud <AUTH_CODE>.
Must contain the key of a user or service account who has access to devices or project API key.
Query parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
deviceClass | string | No | Return devices of the specified Device Class ID. | |
hasHome | boolean | No | Filter devices based on home assignment. If true, return only devices that belong to a home. If false, return only devices that do not belong to a home. | |
homeId | integer | No | Return devices that belong to the specified home. | |
limit | integer | No | default: 25; min: 1 | Maximum number of devices to return. |
projectId | integer | No | Return devices of the specified project. | |
search | string | No | Search for devices by keywords. | |
skip | integer | No | default: 0; min: 0 | Number of devices to skip over. |
tag | string | No | Return devices with the specified tag. Case-insensitive substring match is performed. If tag and search are both specified, devices that match tag OR search are returned. |
Responses
200 Successful retrieval of all devices.
Content type: application/json
Represents a device instance created by a project.
An array of objects with the following shape:
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
apiKey | string | No | read-only (server-generated) | API access key assigned to device. Usually hidden except to privileged clients, but is also present during the On-Demand Device Provisioning process. |
bundleInstallTime | string | No | read-only (server-generated); format: date-time | If present, the timestamp when the firmware bundle was installed. |
bundleInstalled | string | No | read-only (server-generated) | If present, the name of firmware bundle installed on this device. |
channel | string | No | read-only (server-generated) | The name of firmware channel the device should download from. |
claimCode | string | No | Claim code assigned to device. Hidden except to privileged clients. | |
claimExpirationTime | string | No | read-only (server-generated); format: date-time | Expiration time of device's claimable state. |
claimTime | string | No | read-only (server-generated); format: date-time | Timestamp of device being claimed by a user. |
creationTime | string | No | read-only (server-generated); format: date-time | Timestamp of device record creation. |
description | string | No | Description of device. | |
deviceClass | string | Yes | read-only (server-generated) | Device Class ID as defined by the project. |
homeId | integer | No | This property is present if device belongs to a home. | |
id | integer | Yes | read-only (server-generated) | Unique device ID. |
isConnected | boolean | No | read-only (server-generated) | Device is currently connected to MODE Cloud via a websocket or MQTT connection. |
lastConnectTime | string | No | read-only (server-generated); format: date-time | The last time the device connected to the cloud. |
lastDisconnectTime | string | No | read-only (server-generated); format: date-time | The last time the device disconnected from the cloud. |
name | string | No | Display name of device. | |
projectId | integer | Yes | read-only (server-generated) | Project that this device belongs to. |
tag | string | No | An optional/informational tag associated with device. Can be used to store the serial number, for example. |
Response example
[
{
"claimExpirationTime": "2019-09-18T22:19:39Z",
"claimTime": "2019-09-18T22:19:39Z",
"deviceClass": "smart_sensor",
"homeId": 1701,
"id": 34256,
"isConnected": false,
"lastConnectTime": "2019-09-18T22:31:20.678Z",
"lastDisconnectTime": "2019-09-18T22:34:19.314Z",
"name": "happy",
"projectId": 1265,
"tag": "store_one"
},
{
"claimExpirationTime": "2019-09-18T23:42:39.885Z",
"deviceClass": "smart_sensor",
"id": "343d8",
"isConnected": false,
"name": "sad",
"projectId": 1265,
"tag": "store_one"
}
]401 Authorization is required to access this resource.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
403 Request failed because of denied permission.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
429 Request failed because of rate limit.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
500 An unexpected error has occurred.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
503 The service is temporarily unavailable.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |