Getting information about the device status

Requesting information about the current status of the user device.

Request format

GET https://api.iot.yandex.net/v1.0/devices/{device_id}

device_id

ID of the user device.

Request headers

Header	Description	Required
Authorization	The authorization token of the OAuth application.	Yes

Response format

Response successful

Response with error

HTTP/1.1 200 OK

{
	"status": "ok",
	"request_id": String,
	"id": String,
	"name": String,
	"aliases": [String],
	"type": "devices.types.{type}",
	"state": String,
	"groups": [String],
	"room": String,
	"external_id": String,
	"skill_id": String,
	"capabilities": [{
			"retrievable": Boolean,
			"type": "devices.capabilities.{capability}",
			"parameters": {},
			"state": {},
			"last_updated": Float
		},
		{
			"retrievable": Boolean,
			"type": "devices.capabilities.{capability}",
			"parameters": {},
			"state": {},
			"last_updated": Float
		}
	],
	"properties": [{
			"retrievable": Boolean,
			"type": "devices.properties.{property}",
			"parameters": {},
			"state": {},
			"last_updated": Float
        },
        {
			"retrievable": Boolean,
			"type": "devices.properties.{property}",
			"parameters": {},
			"state": {},
			"last_updated": Float
        }
    ]
}

Parameter	Type	Description	Required
status	String	Status of processing the request. Acceptable values: `ok`.	Yes
request_id	String	Request ID. Must be logged for the purpose of incident investigation.	Yes
id	String	Device ID.	Yes
name	String	The name of the device.	Yes
aliases	Array of Strings	An array with additional device names.	Yes
room	String	The ID of the device room. The `null` value is transmitted if the device is not linked to the room.	Yes
external_id	String	The ID of the device in the manufacturer's cloud.	Yes
skill_id	String	The ID of the device manufacturer's skill	Yes
type	String	Device type.	Yes
state	String	The state of the device. Acceptable values: `online`; `offline`.	Yes
groups	Array of Strings	Array with IDs of the device's groups.	Yes
capabilities	Array of CapabilityObjects	Array with information about device capabilities.	Yes
properties	Array of PropertyObjects	Array with information about the device properties.	Yes

capabilities array

Parameter	Type	Description	Required
capability1	CapabilityObject	Description of capability.	No
capability2	CapabilityObject	Description of capability.	No

properties array

Parameter	Type	Description	Required
property1	PropertyObject	Property description.	No
property2	PropertyObject	Property description.	No

`CapabilityObject` type

Parameter	Type	Description	Required
type	String	Type of capability.	Yes
retrievable	Boolean	If it's possible to request the state of this device capability.	Yes
parameters	CapabilityParametersObject	Capability parameters. Corresponds to the value of the `parameters` field from the capability description.	Yes
state	CapabilityStateObject	Current capability state. If the value is `null`, it means that the state was never transmitted to the system. Corresponds to the value of the `state` field from the capability description.	Yes
last_updated	Float	The time of the last state update in seconds, in the Unix timestamp format.	Yes

`PropertyObject` type

Parameter	Type	Description	Required
type	String	Property type.	Yes
retrievable	Boolean	Whether the state of this device property can be requested.	Yes
parameters	PropertyParametersObject	Property parameters. Corresponds to the value of the `parameters` field from the property description.	Yes
state	PropertyStateObject	Current property state. If the value is `null`, it means that the state was never transmitted to the system. Corresponds to the value of the `state` field from the property description.	Yes
last_updated	Float	The time of the last state update in seconds, in the Unix timestamp format.	Yes

HTTP/1.1 404 Not Found

{
    "request_id": String,
    "status": "error",
    "message": String
}

Parameter	Type	Description	Required
request_id	String	Request ID. Must be logged for the purpose of incident investigation.	Yes
status	String	Status of processing the request. Acceptable values: `error`.	Yes
message	String	Error message.	No

Error codes

Example

Request

Response successful

Response with error

curl -i -X GET 'https://api.iot.yandex.net/v1.0/devices/lamp-id-1' \
-H 'Authorization: Bearer 123qwe456a...'

HTTP/1.1 200 OK

{
	"status": "ok",
	"request_id": "fd9299b8-f927-44f1-8728-8a0b35f1c72a",
	"id": "lamp-id-1",
	"name": "Лампочка 1",
	"aliases": [],
	"type": "devices.types.light",
	"state": "online",
	"groups": [
		"light-group-id-1"
	],
	"room": "room-id-1",
	"external_id": "external-lamp-id-1",
	"skill_id": "skill-id-1",
	"capabilities": [{
			"retrievable": true,
			"type": "devices.capabilities.on_off",
			"parameters": {
				"split": false
			},
			"state": {
				"instance": "on",
				"value": false
			},
			"last_updated": 1626702522.614036
		},
		{
			"retrievable": true,
			"type": "devices.capabilities.range",
			"parameters": {
				"instance": "brightness",
				"unit": "unit.percent",
				"random_access": true,
				"range": {
					"min": 1,
					"max": 100,
					"precision": 1
				}
			},
			"state": {
				"instance": "brightness",
				"value": 100
			},
			"last_updated": 1626702522.614036
		},
		{
			"retrievable": true,
			"type": "devices.capabilities.color_setting",
			"parameters": {
				"color_model": "rgb",
				"temperature_k": {
					"min": 1700,
					"max": 6500
				}
			},
			"state": {
				"instance": "temperature_k",
				"value": 3400
			},
			"last_updated": 1626702522.614036
		}
	],
	"properties": []
}

HTTP/1.1 404 Not Found

{
    "request_id": "9813e54b-021d-4203-b22a-02c6370d07b1",
    "status": "error",
    "message": "Устройство не найдено"
}

An array of elements separated by a comma. As array items, you can use standard JSON elements: a string, number, true, false, object, or array. Arrays are enclosed in square brackets []:

"cities": ["Moscow", "Tokyo", "New York"]

Was the article helpful?

Getting full information about the user's smart home

Managing device capabilities