Commands API

Commands API provides HTTP API for the end user to run commands.

Execute Command

POST /commands/v1/execute

Cause execution of a specified command.

Request

Sample request via cURL

$ curl 'http://enapter-gateway.local/api/commands/v1/execute?show_progress=true' -X POST \
  -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}' \
  -d '{
    "device_id": "123e4567-e89b-12d3-a456-426614174000", 
    "command_name": "ping", 
    "arguments": {"count": 5}
  }'

Path Parameters

show_progressboolean

Enable command in-progress responses streaming.

Body Parameters

device_idstringrequired

Device ID.

command_namestringrequired

Command name, same as specified in the blueprint manifest for this device.

argumentsobject

Command arguments according to arguments specified in the blueprint manifest for this device. This is an object whose keys and values are arguments' names and values respectively.

Request body must be a valid JSON object.

Response

If streaming is disabled, response is a single valid JSON object with a terminal state or array of errors:

statestring

Command execution state (see below). Included only if command was executed or is currently being executed.

payloadobject

Payload depends on state (see below). Included only if command is taken for execution.

errorsarray

If error occurred before running the command, response contains an array of errors. See common error format for more details.

Sample response (200 OK)

{
  "state": "succeeded",
  "payload": {
    "value": 112.3
  }
}

Sample response (400 Bad Request)

{
  "errors": [...]
}

If streaming is enabled, successful response will set Transfer-Encoding header to chunked and return a stream of individual JSON payloads:

{"state": "started"}
{"state": "device_in_progress", "payload": {"state": "downloading"}}
{"state": "succeeded", "payload": {"value": 112.3}}

Terminal states:

• succeeded: device replied with successful completion state.
• error: device replied with an error state, payload contains unchanged fields from payload reported by device.
• platform_error: internal error happened during command execution, payload contains code, message and any additional code-specific fields.

Transitional states:

• started: command request is processed and taken for execution.
• device_in_progress: device replied with any non-terminal state, payload contains unchanged state and payload reported by device.