Get key-value pairs (and receive updates)
GET/devices/{deviceId}/kv
Base URL: https://api.tinkermode.com
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.
Authentication
Send an Authorization header of the form ModeCloud <AUTH_CODE>.
Must contain a user key, service account token, project API key, or API key of the matching device.
Path parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
deviceId | integer | Yes | Device ID |
Query parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
keyPrefix | string | No | If specified, only items with keys containing the prefix are returned. This parameter is ignored for WebSocket requests. |
Responses
101 Successfully established a WebSocket connection.
200 An array of key-value pair objects are returned.
Content type: application/json
A key-value pair stored for a home.
An array of objects with the following shape:
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
key | string | No | read-only (server-generated); pattern: ^[a-zA-Z0-9]([a-zA-Z0-9\-_\:]*[a-zA-Z0-9])*$ | Must be unique within each home. Must 1 to 256 characters and must contain alphanumeric characters; dashes ('-'), underscores ('_') and colons (':') may be used after the first character but must be followed by 1+ alphanumeric characters. |
modificationTime | string | No | read-only (server-generated); format: date-time | Timestamp of creation or last modification. |
value | boolean | string | number | array | object | Yes | An arbitrary piece of data assigned to the given key. |
Response example
[
{
"key": "happy",
"modificationTime": "2020-01-02T23:18:16.915Z",
"value": true
},
{
"key": "neutral",
"modificationTime": "2020-01-02T23:17:39.852Z",
"value": false
},
{
"key": "clicks",
"modificationTime": "2020-01-02T23:18:21.383Z",
"value": 100
}
]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. |