---
metadata:
- name: generator
content: Diplodoc Platform v5.48.2
alternate:
- https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-action.md
- https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-action.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/dialogs/smart-home/doc/en/llms.txt
# Change device state
Changes the current state of user devices.
Example case where this request is sent: the user opens the [ Home with Alice](https://alice.yandex.ru/smart-home) app and wants to change the state of their devices.
In response to this request, the provider changes the state of the requested user devices.
## Smart home platform request format {#input}
The smart home platform sends a request to the provider's Endpoint URL (https://example.com/).
```
POST https://example.com/v1.0/user/devices/action
```
#### Request headers {#headers}
#|
||
**Header**
|
**Description**
|
**Required**
||
||
Authorization
|
User's authorization token.
|
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 {#structure-in}
```json translate=no
{
"payload": {
"devices":[
{
"id": String,
"custom_data": Object,
"capabilities": [
"": Object,
"": Object,
...
]
}
]
}
}
```
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
payload
|
[Object](*object)
|
Object with devices.
|
Yes
||
|#
**`payload` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
devices
|
[Array](*array) of [objects](*object)
|
Array of the user's devices.
|
Yes
||
|#
**`devices` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
id
|
[String](*string)
|
Device ID. It must be unique among all the manufacturer's devices.
|
Yes
||
||
custom_data
|
[Object](*object)
|
An object with the device that the provider sent in response to the [Information about user devices](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/get-devices.md) request. Consists of a set of `"key":"value"` pairs with any nesting level, providing additional information about the device. Object content size must not exceed 1024 bytes.
|
No
||
||
capabilities
|
[Array](*array) of [objects](*object)
|
Array with information about device [capabilities](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md).
|
Yes
||
|#
**`capabilities` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
\
|
[Object](*object)
|
Capability and command to change it. 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).
|
Yes
||
||
\
|
[Object](*object)
|
Capability and command to change it. 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).
|
Yes
||
|#
## 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": [
"": Object,
"": Object,
...
],
"action_result": {
"status": String,
"error_code": String,
"error_message": String
}
},
...
]
}
}
```
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
request_id
|
[String](*string)
|
Request ID.
|
Yes
||
||
payload
|
[Object](*object)
|
Object with devices.
|
Yes
||
|#
**`payload` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
devices
|
[Array](*array) of [objects](*object)
|
Array of the user's devices.
|
Yes
||
|#
**`devices` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
id
|
[String](*string)
|
Device ID. It must be unique among all the manufacturer's devices.
|
Yes
||
||
capabilities
|
[Array](*array) of [objects](*object)
|
Array with information about device [capabilities](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md).
|
Yes, if the `action_result` parameter is omitted
||
||
action_result
|
[Object](*object)
|
Result of device state change. This parameter is required if `capabilities` is missing.
{% note info %}
We recommend that you return a parameter for each capability separately. If this is not possible, return the result for the entire device.
The response to the request is considered successful (`status:"DONE"`) if at least one state of the device has changed.
{% endnote %}
|
Yes, if the `capabilities` parameter is omitted
||
|#
**`capabilities` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
\
|
[Object](*object)
|
Command result. 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
||
||
\
|
[Object](*object)
|
Command result. 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
||
|#
**`action_result` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
status
|
[String](*string)
|
Status of the device state change. Acceptable values:
- `DONE`: device state changed.
- `ERROR`: an error occurred when changing the device state.
|
No
||
||
error_code
|
[String](*string)
|
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.
|
No
||
||
error_message
|
[String](*string)
|
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.
|
No
||
|#
[Codes associated with the request](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/response-codes.md#codes-api)
- Response with error
```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}
> {% list tabs %}
>
> - Request
>
>
> ```bash translate=no
> curl -i -X POST 'https://example.com/v1.0/user/devices/action' \
> -H 'Authorization: Bearer 123qwe456a...' \
> -H 'X-Request-Id: ff36a3cc-ec...' \
> -H 'Content-Type: application/json'
> ```
>
> Request body
>
> ```json translate=no
> {
> "payload": {
> "devices": [{
> "id": "abc-123",
> "custom_data": {
> "foo": 1,
> "bar": "two",
> "baz": false,
> "qux": [1, "two", false],
> "quux": {
> "quuz": {
> "corge": []
> }
> }
> },
> "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": false
> }
> }]
> }, {
> "id": "sock-56GF-3",
> "capabilities": [{
> "type": "devices.capabilities.on_off",
> "state": {
> "instance": "on",
> "value": false
> }
> }]
> }]
> }
> }
> ```
>
>
> - Response successful
>
>
> ```json translate=no
> HTTP/1.1 200 OK
>
> {
> "request_id": "EE109B31-FF6C-48BD-80DB-4D07A9AFEBB3",
> "payload": {
> "devices": [{
> "id": "abc-123",
> "capabilities": [{
> "type": "devices.capabilities.color_setting",
> "state": {
> "instance": "hsv",
> "action_result": {
> "status": "ERROR",
> "error_code": "INVALID_ACTION",
> "error_message": "the human readable error message"
> }
> }
> },
> {
> "type": "devices.capabilities.on_off",
> "state": {
> "instance": "on",
> "action_result": {
> "status": "DONE"
> }
> }
> }]
> },
> {
> "id": "sock-56GF-3",
> "action_result": {
> "status": "ERROR",
> "error_code": "DEVICE_UNREACHABLE"
> }
> }]
> }
> }
> ```
>
>
> - Response with error
>
>
> ```json translate=no
> HTTP/1.1 404 Not Found
> ```
>
> {% endlist %}
[*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"`.
[*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"]
```