---
metadata:
  - name: generator
    content: Diplodoc Platform v5.66.0
alternate:
  - https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-devices-query-jrpc.md
  - https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query-jrpc.md
  - href: https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-devices-query-jrpc.md
    type: text/markdown
    title: Markdown version
  - href: https://yandex.ru/dev/dialogs/smart-home/doc/en/llms.txt?revision=r21995741
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/dialogs/smart-home/doc/en/llms.txt?revision=r21995741

# Information about the states of user devices

Requests information about the state of user devices.

<!-- source: en/_includes/reference/post-action/situation-example.md -->
Example case where this request is sent: the user opens the [![](../_images/smart-home-app.svg) Home with Alice](https://alice.yandex.ru/smart-home) app and wants to change the state of their devices.
<!-- endsource: en/_includes/reference/post-action/situation-example.md -->


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


{% note info %}

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

{% endnote %}


## Smart home platform request format {#input}

The smart home platform sends a request to the provider's Endpoint URL (https://example.com/).

```bash translate=no
POST https://functions.yandexcloud.net/<function_id>?integration=raw
```

#### Request body format {#structure-in}

```json translate=no
{
  "headers": {
    "request_id": String,
    "authorization": String
  },
  "request_type": String,
  "payload": {
    "devices": [
      {
        "id": String,
        "custom_data": Object
      },
      ...
    ]
  },
  "api_version": Float
}
```

<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/post-devices-query-jrpc-input.md -->
<!-- Post devices query -->
<!-- Query -->


#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||

||
headers
|
[Object](*object)
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/headers-ph.md -->
Object with additional request fields.
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/headers-ph.md -->
|
Yes
||

||
request_type
|
[String](*string)
|
Request type. Acceptable values:
- query: Information about the states of user devices.
|
Yes
||

||
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-1.md -->
payload
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-1.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-2.md -->
[Object](*object)
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-2.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-3.md -->
Object with devices.
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-3.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-4.md -->
Yes
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-4.md -->
||

||
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/api_version-row-col-1.md -->
api_version
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/api_version-row-col-1.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/api_version-row-col-2.md -->
[Float](*float)
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/api_version-row-col-2.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/api_version-row-col-3.md -->
The protocol version of Yandex Smart Home.
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/api_version-row-col-3.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/api_version-row-col-4.md -->
Yes
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/api_version-row-col-4.md -->
||
|#

<br>

<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/headers-tgroup.md -->
**`headers` object**

#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||

||
request_id
|
[String](*string)
|
Request ID. Should be logged on the provider's side for investigating incidents and problems.
|
Yes
||

||
authorization
|
[String](*string)
|
User's authorization token.
|
Yes
||
|#
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/headers-tgroup.md -->

<br>


**`payload` object**

#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||

||
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-1.md -->
devices
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-1.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-2.md -->
[Array](*array) of [objects](*object)
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-2.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-3.md -->
Array of the user's devices.
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-3.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-4.md -->
Yes
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-4.md -->
||
|#

<br>


**`devices` object**

#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||

||
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-1.md -->
id
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-1.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-2.md -->
[String](*string)
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-2.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-3.md -->
Device ID. It must be unique among all the manufacturer's devices.
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-3.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-4.md -->
Yes
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-4.md -->
||

||
custom_data
|
[Object](*object)
|
An object passed by the provider for the device in response to the request.
 [Information about user devices](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/get-devices-jrpc.md).
|
No
||
|#
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/post-devices-query-jrpc-input.md -->



## Provider response format {#output-structure}

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


{% list tabs %}

- Response successful


  ```json translate=no
  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
        },
        ...
      ]
    }
  }
  ```

  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/post-devices-response.md -->
  <!-- Response -->


  #|
  ||
  **Parameter**
  |
  **Type**
  |
  **Description**
  |
  **Required**
  ||

  ||
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/request_id-col-1.md -->
  request_id
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/request_id-col-1.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/request_id-col-2.md -->
  [String](*string)
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/request_id-col-2.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/request_id-col-3.md -->
  Request ID.
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/request_id-col-3.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/request_id-col-4.md -->
  Yes
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/request_id-col-4.md -->
  ||

  ||
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-1.md -->
  payload
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-1.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-2.md -->
  [Object](*object)
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-2.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-3.md -->
  Object with devices.
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-3.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-4.md -->
  Yes
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-4.md -->
  ||
  |#

  <br>

  **`payload` object**

  #|
  ||
  **Parameter**
  |
  **Type**
  |
  **Description**
  |
  **Required**
  ||

  ||
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-1.md -->
  devices
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-1.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-2.md -->
  [Array](*array) of [objects](*object)
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-2.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-3.md -->
  Array of the user's devices.
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-3.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-4.md -->
  Yes
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/devices-row-col-4.md -->
  ||
  |#

  <br>


  **`devices` object**

  #|
  ||
  **Parameter**
  |
  **Type**
  |
  **Description**
  |
  **Required**
  ||

  ||
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-1.md -->
  id
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-1.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-2.md -->
  [String](*string)
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-2.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-3.md -->
  Device ID. It must be unique among all the manufacturer's devices.
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-3.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-4.md -->
  Yes
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-4.md -->
  ||

  ||
  capabilities
  |
  [Array](*array) of [objects](*object)
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/capabilities-description-ph.md -->
  Array with information about device [capabilities](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md).
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/capabilities-description-ph.md -->
  |
  No
  ||

  ||
  properties
  |
  [Array](*array) of [objects](*object)
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/properties-description-ph.md -->
  Array with information about the device [properties](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/properties-types.md).
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/properties-description-ph.md -->
  |
  No
  ||

  ||
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_code-row-col-1.md -->
  error_code
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_code-row-col-1.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_code-row-col-2.md -->
  [String](*string)
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_code-row-col-2.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_code-row-col-3.md -->
  An error code from the [list](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/response-codes.md#codes-api). If the field is filled in, the `capabilities` and `properties` parameters are ignored.
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_code-row-col-3.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_code-row-col-4.md -->
  No
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_code-row-col-4.md -->
  ||

  ||
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_message-row-col-1.md -->
  error_message
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_message-row-col-1.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_message-row-col-2.md -->
  [String](*string)
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_message-row-col-2.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_message-row-col-3.md -->
  Extended human-readable description of a possible error. Available only on the [Testing](https://yandex.ru/dev/dialogs/smart-home/doc/en/testing.md) tab of the developer console.
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_message-row-col-3.md -->
  |
  <!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_message-row-col-4.md -->
  No
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/error_message-row-col-4.md -->
  ||
  |#

  <br>


  **`capabilities` object**

  #|
  ||
  **Parameter**
  |
  **Type**
  |
  **Description**
  |
  **Required**
  ||

  ||
  \<capability1>
  |
  [Object](*object)
  |
  Capability and its status. For more information about the list of available capabilities and their parameters, see [About capabilities](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md).
  |
  No
  ||

  ||
  \<capability2>
  |
  [Object](*object)
  |
  Capability and its status. For more information about the list of available capabilities and their parameters, see [About capabilities](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md).
  |
  No
  ||
  |#

  <br>


  **`properties` object**

  #|
  ||
  **Parameter**
  |
  **Type**
  |
  **Description**
  |
  **Required**
  ||

  ||
  \<property1>
  |
  [Object](*object)
  |
  Property and its status. For more information about the list of available properties and their parameters, see [About properties](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/properties-types.md).
  |
  No
  ||

  ||
  \<property2>
  |
  [Object](*object)
  |
  Property and its status. For more information about the list of available properties and their parameters, see [About properties](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/properties-types.md).
  |
  No
  ||
  |#
  <!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/post-devices-response.md -->


  [Codes associated with the request](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/response-codes.md#codes-api)


- Response with error


  <!-- source: en/_includes/reference/check-jrpc/id-output-structure/cloud.md -->
  For more information about returning status codes other than `200 OK`, see the [documentation](https://yandex.cloud/en/docs/functions/concepts/function-invoke#response).
  <!-- endsource: en/_includes/reference/check-jrpc/id-output-structure/cloud.md -->


  ```json translate=no
  HTTP/1.1 404 Not Found
  ```

  [ Global codes](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/response-codes.md#enq-with-error-codes)

{% endlist %}


## Example {#example-JSON}

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

> {% list tabs %}
>
> - Request
>
>
>   ```bash translate=no
>   curl -i POST https://functions.yandexcloud.net/<function_id>?integration=raw \
>   -H 'Content-Type: application/json' \
>   -d '{
>         "headers": {
>           "request_id": "1111-aaaa-2222-bbbb",
>           "authorization": "Bearer 123qwe456a..."
>         },
>         "request_type": "query",
>         "payload": {
>           "devices": [{
>             "id": "abc-123",
>             "custom_data": {
>               "foo": 1,
>               "bar": "two",
>               "baz": false,
>               "qux": [1, "two", false],
>               "quux": {
>                 "quuz": {
>                   "corge": []
>                 }
>               }
>             }
>           },
>           {
>             "id": "sock-56GF-3"
>           }
>         ]},
>         "api_version": 1.0
>   }'
>   ```
>
>
> - Response successful
>
>
>   ```json translate=no
>   {
>       "request_id": "1111-aaaa-2222-bbbb",
>       "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
>                   }
>               }]
>           }]
>       }
>   }
>   ```
>
>
> - Response with error
>
>
>   ```json translate=no
>   HTTP/1.1 404 Not Found
>   ```
>
> {% endlist %}


<!-- {% include [support-support-button](../_includes/about/id-support/support-button.md) %}-->

[*object]:
  List of `"key": value` pairs separated by commas. The list is enclosed in curly brackets `{}`.

```json translate=no
{
  "name": "John",
  "surname": "Smith"
}
```

[*string]:
  String enclosed in quotation marks, for example: `"Hello, world"`.

[*float]:
  Floating-point number with a precision of 6-9 decimal digits.

[*array]:
  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 `[]`:

```json translate=no
"cities": ["Moscow", "Tokyo", "New York"]
```