Skip to main content

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.
Hardware diversity is welcome. Integrate any device into a unified energy network.
© 2022 Enapter
Developer toolkit
DocumentationReference