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
- 400
- 401
- 403
- 404
- 409
- 422
- 503
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).
Malformed request body, or the caller's resource_access claim could not be parsed.
Authentication is required, or the token is invalid.
The caller's role in the organization owning this device is below the one this command requires (Command.NotAuthorized).
Device not found or outside the organizations the caller can access (Device.NotFound), or the device publishes no DTDL model at all (Command.NotFound).
The device is not connected, so the command is rejected rather than queued (Command.OfflineDevice)
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.
The device's command catalog could not be read. Transient. The device may well support this command; retry.