---
metadata:
  - name: generator
    content: Diplodoc Platform v5.66.0
alternate:
  - https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/platform-capabilities.md
  - https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/platform-capabilities.md
  - href: https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/platform-capabilities.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

# Managing device capabilities

Sends actions to the user devices.

## Request format {#input}

```
POST https://api.iot.yandex.net/v1.0/devices/actions
```

<!-- source: en/_includes/concepts/platform-capabilities/header-section.md -->
#### Request headers {#header-section}

#|
||**Header** | **Description** | **Required**||
||Authorization | The authorization token of the OAuth application. | Yes||
|#
<!-- endsource: en/_includes/concepts/platform-capabilities/header-section.md -->


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

```json translate=no
{
	"devices": [{
		"id": String,
		"actions": [{
			"type": "devices.capabilities.{capability}",
			"state": {}
		}]
	}]
}
```

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

||
devices
|
[Array](*array) of DeviceActionsObjects
|
An array of actions for devices.
|
Yes
||
|#

<br>

**`devices` array**

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

||
deviceActions1
|
DeviceActionObject
|
Set of actions for devices.
|
No
||

||
deviceActions2
|
DeviceActionObject
|
Set of actions for devices.
|
No
||
|#

<br>

**`DeviceActionsObject` type**

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

||
id
|
[String](*string)
|
Device ID
|
Yes
||

||
actions
|
[Array](*array) of CapabilityObjects
|
Array of actions for the device.
|
Yes
||
|#

<br>

**`actions` array**

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

||
capability1
|
CapabilityObject
|
Capability and command to change it.
|
No
||

||
capability2
|
CapabilityObject
|
Capability and command to change it.
|
No
||
|#

<br>

**`CapabilityObject` type**

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

||
type
|
[String](*string)
|
[The type of the capability](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md#types).
|
Yes
||

||
state
|
CapabilityStateObject
|
The target state of the capability. Corresponds to the value of the `state` field from the description of the command for [managing the device capability](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/on_off.md).
|
Yes
||
|#



## Response format {#output-structure}


{% list tabs %}

- Response successful


  ```json translate=no
  HTTP/1.1 200 OK

  {
     "[status](*row-status-struct-table-protocol-alerts)": "ok",
     "[request_id](*row-request-id)": String,
     "[devices](*row-devices)": [{
        "[id](*row-id)": String,
        "[capabilities](*row-capabilities)": [{
           "[type](*row-type)": "devices.capabilities.{capability}",
           "[state](*row-state)": {
              "[instance](*row-instance)": String,
              "[action_result](*row-action-result)": {
                 "[status](*row-status)": String;
              }
           }
        }]
     }]
  }
  ```

  <br>

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

  ||
  request_id
  |
  [String](*string)
  |
  Request ID. Must be logged for the purpose of incident investigation.
  |
  Yes
  ||

  ||
  status
  |
  [String](*string)
  |
  Status of processing the request. Acceptable values:
  - `ok`.

  |
  Yes
  ||

  ||
  devices
  |
  [Array](*array) of DeviceActionsResultObjects
  |
  Results of performing actions on devices.
  |
  Yes
  ||
  |#

  <br>

  **`devices` array**

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

  ||
  deviceActionsResult1
  |
  DeviceActionResultObject
  |
  The result of performing actions on the device.
  |
  No
  ||

  ||
  deviceActionsResult2
  |
  DeviceActionResultObject
  |
  The result of performing actions on the device.
  |
  No
  ||
  |#

  <br>

  **`DeviceActionsResultObject` type**

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

  ||
  id
  |
  [String](*string)
  |
  Device ID
  |
  Yes
  ||

  ||
  capabilities
  |
  CapabilityActionResultObject
  |
  Results of actions.
  |
  Yes
  ||
  |#

  <br>

  **`CapabilityActionResultObject` type**

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

  ||
  type
  |
  [String](*string)
  |
  [The type of the capability](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md#types).
  |
  Yes
  ||

  ||
  state
  |
  StateResultObject
  |
  The state of the capability.
  |
  Yes
  ||
  |#

   <br>

  **`StateResultObject` type**

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

  ||
  instance
  |
  [String](*string)
  |
  The function of the capability.
  |
  Yes
  ||

  ||
  action_result
  |
  ActionResultObject
  |
  The result of the action.
  |
  Yes
  ||
  |#

   <br>

  **`ActionResultObject` type**

  #|
  ||
  **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.

  |
  Yes
  ||

  ||
  error_code
  |
  [String](*string)
  |
  An error code from the [list of possible errors](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/response-codes.md#codes-api).
  |
  No
  ||

  ||
  error_message
  |
  [String](*string)
  |
  Extended human-readable description of a possible error.
  |
  No
  ||
  |#



- Response with error


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

  {
      "[request_id](*row-request-id)": String,
      "[status](*row-error-status-struct-table-protocol-alerts)": "error",
      "[message](*row-message)": String
  }
  ```

   <!-- source: en/_includes/concepts/platform-capabilities/id-output-structure/table-error.md -->
     #|
     ||
     **Parameter**
     |
     **Type**
     |
     **Description**
     |
     **Required**
     ||

     ||
     request_id
     |
     [String](*string)
     |
     Request ID. Must be logged for the purpose of incident investigation.
     |
     Yes
     ||

     ||
     status
     |
     [String](*string)
     |
     Status of processing the request. Acceptable values:
     - `error`.

     |
     Yes
     ||

     ||
     message
     |
     [String](*string)
     |
     Error message.
     |
     No
     ||
     |#
   <!-- endsource: en/_includes/concepts/platform-capabilities/id-output-structure/table-error.md -->



  [Error codes](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/platform-error-codes.md)

{% endlist %}


## Example {#example-JSON}

> {% list tabs %}
>
> - Request
>
>
>   ```bash translate=no
>   curl --request POST 'https://api.iot.yandex.net/v1.0/devices/actions' \
>   --header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
>   --header 'Content-Type: application/json' \
>   --data-raw '{
>       "devices": [
>           {
>               "id": "lamp-id-1",
>               "actions": [
>                   {
>                       "type": "devices.capabilities.on_off",
>                       "state": {
>                           "instance": "on",
>                           "value": true
>                       }
>                   }
>               ]
>           }
>       ]
>   }'
>   ```
>
>
> - Response successful
>
>
>   ```json translate=no
>   HTTP/1.1 200 OK
>
>   {
>      "[status](*row-status-struct-table-protocol-alerts)": "ok",
>      "[request_id](*row-request-id)": "4901aee0-85bf-4b04-9b12-de0f18d23d1e",
>      "[devices](*row-devices)": [{
>         "[id](*row-id)": "lamp-id-1",
>         "[capabilities](*row-capabilities)": [{
>            "[type](*row-type)": "devices.capabilities.on_off",
>            "[state](*row-state)": {
>               "[instance](*row-instance)": "on",
>               "[action_result](*row-action-result)": {
>                  "[status](*row-status)": "DONE"
>               }
>            }
>         }]
>      }]
>   }
>   ```
>
>
> - Response with error
>
>
>   ```json translate=no
>   HTTP/1.1 404 Not Found
>
>   {
>       "[request_id](*row-request-id)": "4901aee0-85bf-4b04-9b12-de0f18d23d1e",
>       "[status](*row-error-status-struct-table-protocol-alerts)": "error",
>       "[message](*row-message)": "Устройства не найдены"
>   }
>   ```
>
> {% endlist %}


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

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

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

[*row-id]:
   **Type**

[String](*string)

**Description**

Device ID

**Required**

Yes

[*row-status]:
   **Type**

[String](*string)

**Description**

Status of the device state change. Acceptable values:
  - `DONE`: device state changed.
  - `ERROR`: an error occurred when changing the device state.


**Required**

Yes

[*row-action-result]:
   **Type**

DeviceActionResultObject

**Description**

The result of performing actions on the device.

**Required**

No

[*row-instance]:
   **Type**

[String](*string)

**Description**

The function of the capability.

**Required**

Yes

[*row-state]:
   **Type**

StateResultObject

**Description**

The state of the capability.

**Required**

Yes

[*row-type]:
   **Type**

[String](*string)

**Description**

[The type of the capability](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md#types).

**Required**

Yes

[*row-message]:
   **Type**

[String](*string)

**Description**

Error message.

**Required**

No

[*row-devices]:
   **Type**

[Array](*array) of DeviceActionsResultObjects

**Description**

Results of performing actions on devices.

**Required**

Yes

[*row-capabilities]:
   **Type**

CapabilityActionResultObject

**Description**

Results of actions.

**Required**

Yes

[*row-status-struct-table-protocol-alerts]:
   **Type**

[String](*string)

**Description**

Status of processing the request. Acceptable values:
  - `ok`.


**Required**

Yes

[*row-error-status-struct-table-protocol-alerts]:
   **Type**

[String](*string)

**Description**

Status of processing the request. Acceptable values:
  - `error`.


**Required**

Yes

[*row-request-id]:
   **Type**

[String](https://yandex.ru/dev/dialogs/smart-home/doc/en/types.md#string)

**Description**

Request ID. Must be logged for the purpose of incident investigation.

**Required**

Yes