Managing device capabilities

Sends actions to the user devices.

Request format

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

Request headers

Header	Description	Required
Authorization	The authorization token of the OAuth application.	Yes

Request body format

{
	"devices": [{
		"id": String,
		"actions": [{
			"type": "devices.capabilities.{capability}",
			"state": {}
		}]
	}]
}

Parameter	Type	Description	Required
devices	Array of DeviceActionsObjects	An array of actions for devices.	Yes

devices array

Parameter	Type	Description	Required
deviceActions1	DeviceActionObject	Set of actions for devices.	No
deviceActions2	DeviceActionObject	Set of actions for devices.	No

DeviceActionsObject type

Parameter	Type	Description	Required
id	String	Device ID	Yes
actions	Array of CapabilityObjects	Array of actions for the device.	Yes

actions array

Parameter	Type	Description	Required
capability1	CapabilityObject	Capability and command to change it.	No
capability2	CapabilityObject	Capability and command to change it.	No

CapabilityObject type

Parameter	Type	Description	Required
type	String	The type of the capability.	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.	Yes

Response format

Response successful

Response with error

HTTP/1.1 200 OK

{
   "status": "ok",
   "request_id": String,
   "devices": [{
      "id": String,
      "capabilities": [{
         "type": "devices.capabilities.{capability}",
         "state": {
            "instance": String,
            "action_result": {
               "status": 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: `ok`.	Yes
devices	Array of DeviceActionsResultObjects	Results of performing actions on devices.	Yes

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

DeviceActionsResultObject type

Parameter	Type	Description	Required
id	String	Device ID	Yes
capabilities	CapabilityActionResultObject	Results of actions.	Yes

CapabilityActionResultObject type

Parameter	Type	Description	Required
type	String	The type of the capability.	Yes
state	StateResultObject	The state of the capability.	Yes

StateResultObject type

Parameter	Type	Description	Required
instance	String	The function of the capability.	Yes
action_result	ActionResultObject	The result of the action.	Yes

ActionResultObject type

Parameter	Type	Description	Required
status	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	An error code from the list of possible errors.	No
error_message	String	Extended human-readable description of a possible error.	No

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 --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
                    }
                }
            ]
        }
    ]
}'

HTTP/1.1 200 OK

{
   "status": "ok",
   "request_id": "4901aee0-85bf-4b04-9b12-de0f18d23d1e",
   "devices": [{
      "id": "lamp-id-1",
      "capabilities": [{
         "type": "devices.capabilities.on_off",
         "state": {
            "instance": "on",
            "action_result": {
               "status": "DONE"
            }
         }
      }]
   }]
}

HTTP/1.1 404 Not Found

{
    "request_id": "4901aee0-85bf-4b04-9b12-de0f18d23d1e",
    "status": "error",
    "message": "Устройства не найдены"
}

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 []:

"cities": ["Moscow", "Tokyo", "New York"]

Was the article helpful?

Getting information about the device status

Getting information about the status of a device group