Getting information about the status of a device group

Request format
Response format
Example

Request information about the current status of the user device group.

Request format

GET https://api.iot.yandex.net/v1.0/groups/{group_id}

group_id

The ID of the user's device group.

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": "online",
	"capabilities": [{
			"retrievable": Boolean,
			"type": "devices.capabilities.{capability}",
			"parameters": {},
			"state": {}
		},
		{
			"retrievable": Boolean,
			"type": "devices.capabilities.{capability}",
			"parameters": {},
			"state": {}
		}
	],
	"devices": [{
			"id": String,
			"name": String,
			"type": "devices.types.{type}"
		},
		{
			"id": String,
			"name": String,
			"type": "devices.types.{type}"
		}
	]
}

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	The ID of the device group.	Yes
name	String	The name of the device group.	Yes
aliases	Array of Strings	An array with additional device names.	Yes
type	String	The type of the device group. It's the same as the device type for the group.	Yes
state	String	The state of the device group. Acceptable values: `online`; `offline`; `split`: The devices in the group are in different states.	Yes
capabilities	Array of CapabilityObjects	An array with information about the capabilities of the device group.	Yes
devices	Array of GroupDeviceInfoObjects	An array with information about the devices in the group.	Yes

capabilities array

Parameter	Type	Description	Required
capability1	CapabilityObject	Description of capability. For more information about the list of available capabilities and their parameters, see Capabilities.	No
capability2	CapabilityObject	Description of capability. For more information about the list of available capabilities and their parameters, see Capabilities.	No

`CapabilityObject` type

Parameter	Type	Description	Required
type	String	The type of the capability.	Yes
retrievable	Boolean	If it's possible to request the state of this 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 this capability has different states for the devices in the group. Corresponds to the value of the `state` field from the capability description.	Yes

devices array

Parameter	Type	Description	Required
device1	GroupDeviceInfoObject	Description of the device in the group.	No
device2	GroupDeviceInfoObject	Description of the device in the group.	No

`GroupDeviceInfoObject` type

Parameter	Type	Description	Required
id	String	Device ID.	Yes
name	String	The name of the device.	Yes
type	String	Device type.	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/groups/lamp-group-id-1' \
-H 'Authorization: Bearer 123qwe456a...'

HTTP/1.1 200 OK

{
	"status": "ok",
	"request_id": "4ea5619b-c4c5-41af-930b-4b317f7bdad6",
	"id": "light-group-id-1",
	"name": "Люстра",
	"aliases": ["Верхний свет"],
	"type": "devices.types.light",
	"state": "online",
	"capabilities": [{
			"retrievable": true,
			"type": "devices.capabilities.on_off",
			"parameters": {
				"split": false
			},
			"state": {
				"instance": "on",
				"value": false
			}
		},
		{
			"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
			}
		},
		{
			"retrievable": true,
			"type": "devices.capabilities.color_setting",
			"parameters": {
				"color_model": "hsv",
				"temperature_k": {
					"min": 1700,
					"max": 6500
				}
			},
			"state": {
				"instance": "temperature_k",
				"value": 3400
			}
		}
	],
	"devices": [{
			"id": "lamp-id-1",
			"name": "Лампочка 1",
			"type": "devices.types.light"
		},
		{
			"id": "lamp-id-2",
			"name": "Лампочка 2",
			"type": "devices.types.light"
		},
		{
			"id": "lamp-id-3",
			"name": "Лампочка 3",
			"type": "devices.types.light"
		}
	]
}

HTTP/1.1 404 Not Found

{
    "request_id": "667b3e0f-47a8-4136-9211-b4ff59062315",
    "status": "error",
    "message": "Группа устройств не найдена"
}

Getting information about the status of a device group

Request formatRequest format

Request headersRequest headers

Response formatResponse format

typeCapabilityObject type

typeGroupDeviceInfoObject type

ExampleExample