Run a device command

POST 
/api/v1/devices/{deviceId}/commands:invoke

Run a command declared by the target device. Read its command definitions first with GET capabilities/schema?type=commands. Use the Command's name with each underscore replaced by a dot (for example, set_di becomes set.di) as deviceCommand, and build parameters from the Command's request schema. A command the device does not declare is rejected with 422. Keep the returned reqSeqId and match it in the device's command history (GET commands/results) to follow the outcome. The set.di command in the request example is only an example. It works only on devices that declare it.

Request

Responses

202

Accepted. Returns the initial command-result envelope (reqSeqId, phase, status, message). Track it via GET commands/results until it reaches result, or fails / times out (data.status = 1, data.error.code timedOut).

400

Malformed request body, or the caller's resource_access claim could not be parsed.

401

Authentication is required, or the token is invalid.

403

The caller's role in the organization owning this device is below the one this command requires (Command.NotAuthorized).

404

Device not found or outside the organizations the caller can access (Device.NotFound), or the device publishes no DTDL model at all (Command.NotFound).

409

The device is not connected, so the command is rejected rather than queued (Command.OfflineDevice)

422

Either the target device's agent provides no capability model, or deviceCommand is not declared in the device's catalog (Device.CapabilityNotSupported), or timeoutSeconds is out of range (15..86400, and 1800..86400 for report.historical) (Command.InvalidParameters). The example below shows the first.

503

The device's command catalog could not be read. Transient. The device may well support this command; retry.