Information about the states of user devices

Requests information about the state of user devices.

Example case where this request is sent: the user opens the Home with Alice app and wants to change the state of their devices.

In response to the request, the provider must return the states of the requested user devices.

Note

The capabilities for which the state request is not available (with retrievable=false). Can be omitted in the response because their state is ignored.

Smart home platform request format

Yandex Smart Home sends a request to the provider's Endpoint URL (https://example.com/).

POST https://example.com/v1.0/user/devices/query

Request headers

Header

Description

Required

Authorization

Authorization token of the skill owner.

Yes

Content-Type

The format of sent/submitted data. Possible values: application/json.

Yes, in operations with HTTP POST

X-Request-Id

Request ID. Must be logged on the provider's side for investigating incidents and problems.

Yes

Request body format

{
    "devices": [
      {
        "id": String,
        "custom_data": Object
      },
      ...
    ]
}

Parameter

Type

Description

Required

devices

Array of objects

Array of the user's devices.

Yes


devices object

Parameter

Type

Description

Required

id

String

Device ID. It must be unique among all the manufacturer's devices.

Yes

custom_data

Object

An object passed by the provider for the device in response to the request Information about user devices.

No

Provider response format

The provider must use the correct format to respond to the request received from the smart home platform.

HTTP/1.1 200 OK

{
  "request_id": String,
  "payload": {
    "devices":[
      {
        "id": String,
        "capabilities": [
          "<capability1>": Object,
          "<capability2>": Object,
          ...
        ],
        "properties": [
          "<property1>": Object,
          "<property2>": Object,
          ...
        ],
        "error_code": String,
        "error_message": String
      },
      ...
    ]
  }
}

Parameter

Type

Description

Required

request_id

String

Request ID.

Yes

payload

Object

Object with devices.

Yes


payload object

Parameter

Type

Description

Required

devices

Array of objects

Array of the user's devices.

Yes


devices object

Parameter

Type

Description

Required

id

String

Device ID. It must be unique among all the manufacturer's devices.

Yes

capabilities

Array of objects

Array with information about device capabilities.

No

properties

Array of objects

Array with information about the device properties.

No

error_code

String

An error code from the list. If the field is filled in, the capabilities and properties parameters are ignored.

No

error_message

String

Extended human-readable description of a possible error. Available only on the Testing tab of the developer console.

No


capabilities object

Parameter

Type

Description

Required

<capability1>

Object

Capability and its status. For more information about the list of available capabilities and their parameters, see About capabilities.

No

<capability2>

Object

Capability and its status. For more information about the list of available capabilities and their parameters, see About capabilities.

No


properties object

Parameter

Type

Description

Required

<property1>

Object

Property and its status. For more information about the list of available properties and their parameters, see About properties.

No

<property2>

Object

Property and its status. For more information about the list of available properties and their parameters, see About properties.

No

Codes associated with the request

HTTP/1.1 404 Not Found

Global codes

Example

This example describes the properties of a lamp featuring color and outlet control.

curl -i -X POST 'https://example.com/v1.0/user/devices/query' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json'

Request body

{
    "devices": [
        {
            "id": "abc-123",
            "custom_data": {
              "foo": 1,
              "bar": "two",
              "baz": false,
              "qux": [1, "two", false],
              "quux": {
                "quuz": {
                  "corge": []
                }
              }
            }
        },
        {
            "id": "sock-56GF-3"
        }
    ]
}
{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [{
            "id": "abc-123",
            "capabilities": [{
                "type": "devices.capabilities.color_setting",
                "state": {
                    "instance": "hsv",
                    "value": {
                        "h": 255,
                        "s": 50,
                        "v": 100
                    }
                }
            }, {
                "type": "devices.capabilities.on_off",
                "state": {
                    "instance": "on",
                    "value": true
                }
            }]
        },
        {
            "id": "abc-123",
            "error_code": "DEVICE_NOT_FOUND",
            "error_message": "the human readable error message"
        },
        {
            "id": "sock-56GF-3",
            "capabilities": [{
                "type": "devices.capabilities.on_off",
                "state": {
                    "instance": "on",
                    "value": true
                }
            }]
        }]
    }
}
HTTP/1.1 404 Not Found