Skip to main content

Device Commands

The Commands API provides an HTTP API for the end user to run commands on their devices.

Execute Command CloudGateway​

POST /v3/devices/{device_id}/execute_command

Executes the specified command on the device. The device's blueprint must contain the command.

Request​

$ curl -X POST \
    http://api.enapter.com/v3/devices/fecbbba0-79f2-4e9e-a6f0-69a310ab110b/execute_command \
    -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}' \
    -d '{
            "name": "change_color_temperature",
            "arguments": {
                "temp_kelvins": 1850
            }
        }'

Query Parameters​

expandarray of strings#

Comma-separated list of additional command execution information to display. By default, no additional parameters are included.

Supported values:

  • log — includes all command responses, which are sorted by received_at in the descending order.

Body Parameters​

namestring#

Command name.

argumentsobject#

Command arguments are key-value pairs.

ephemeralbooleandefault: false#

ephemeral means that the command execution is not listed by default and will be deleted in 24 hours.

Response​

Command execution with the request and the latest response.

{
    "execution": {
        "id": "7ba65010-f64e-4ba8-bfe4-963dd0c67009",
        "state": "SUCCESS",
        "created_at": "2025-07-11T00:00:01Z",
        "request": {
            "name": "change_color_temperature",
            "arguments": {
                "temp_kelvins": 1850
            },
            "manifest_name": "change_lux"
        },
        "response": {
            "state": "SUCCEEDED",
            "received_at": "2025-07-11T00:00:02Z"
        }
    }
}
executionobject#

Object containing command execution information.

execution.idstring#

Command execution ID.

execution.statestring#

Command execution state. Possible values:

  • NEW
  • IN_PROGRESS
  • SUCCESS
  • ERROR
  • TIMEOUT
execution.created_atstring#

The datetime when the execution was created, in RFC 3339 format.

execution.requestobject#

CommandRequest object contains execution request information.

CommandRequest.namestring#

A command name as it is or an alias.

CommandRequest.argumentsobject#

The command arguments are specified in the device blueprint manifest.

This is an object whose keys are the names of the arguments and whose values are the corresponding argument values.

CommandRequest.manifest_namestring#

A command name specified in the device manifest.

execution.responseobject#

CommandResponse object with response information.

CommandResponse.statestring#

Command response state. Possible values:

  • STARTED
  • IN_PROGRESS
  • SUCCEEDED
  • ERROR
CommandResponse.payloadobject#

The payload depends on the response state.

CommandResponse.received_atstring#

The datetime when the response was received, in RFC 3339 format.

execution.logarray of objects#

The log contains a list of CommandResponse objects.

CommandResponse.statestring#

Command response state. Possible values:

  • STARTED
  • IN_PROGRESS
  • SUCCEEDED
  • ERROR
CommandResponse.payloadobject#

The payload depends on the response state.

CommandResponse.received_atstring#

The datetime when the response was received, in RFC 3339 format.

execution.ephemeralboolean#

Shows whether the command has a limited TTL (time-to-live).

Create Command Execution CloudGateway​

POST /v3/devices/{device_id}/command_executions

Creates an execution for the specified command on the device. The device's blueprint must contain the command. You can check the execution's state with Get Command Execution.

Request​

$ curl -X POST \
    http://api.enapter.com/v3/devices/fecbbba0-79f2-4e9e-a6f0-69a310ab110b/command_executions \
    -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}' \
    -d '{
          "name": "change_color_temperature",
          "arguments": {
              "temp_kelvins": 15000
          },
          "ephemeral": true
        }'

Body Parameters​

namestring#

Command name.

argumentsobject#

Command arguments are key-value pairs.

ephemeralbooleandefault: false#

ephemeral means that the command execution is not listed by default and will be deleted in 24 hours.

Response​

{
  "execution_id": "7ba65010-f64e-4ba8-bfe4-963dd0c67009"
}

Get Command Execution CloudGateway​

GET /v3/devices/{device_id}/command_executions/{execution_id}

Returns a specified command execution.

Request​

$ curl http://api.enapter.com/v3/devices/fecbbba0-79f2-4e9e-a6f0-69a310ab110b/command_executions/7ba65010-f64e-4ba8-bfe4-963dd0c67009 \
    -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}'

To receive all command responses:

$ curl http://api.enapter.com/v3/devices/fecbbba0-79f2-4e9e-a6f0-69a310ab110b/command_executions/7ba65010-f64e-4ba8-bfe4-963dd0c67009?expand=log \
    -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}'

Query Parameters​

expandarray of strings#

Comma-separated list of additional command execution information to display. By default, no additional parameters are included.

Supported values:

  • log — includes all command responses, which are sorted by received_at in the descending order.

Response​

Running execution
{
    "execution": {
        "id": "7ba65010-f64e-4ba8-bfe4-963dd0c67009",
        "state": "IN_PROGRESS",
        "created_at": "2025-09-11T00:00:00Z",
        "request": {
            "name": "change_color_temperature",
            "arguments": {
                "temp_kelvins": 15000
            },
            "manifest_name": "change_lux"
        }
    }
}
Finished execution
{
    "execution": {
        "id": "7ba65010-f64e-4ba8-bfe4-963dd0c67009",
        "state": "ERROR",
        "created_at": "2025-09-11T00:00:00Z",
        "request": {
            "name": "change_color_temperature",
            "arguments": {
                "temp_kelvins": 15000
            },
            "manifest_name": "change_lux"
        },
        "response": {
            "state": "ERROR",
            "payload": {"message": "Temperature value is out of range"},
            "received_at": "2025-09-11T00:00:01Z"
        }
    }
}
Expanded with log
{
    "execution": {
        "id": "7ba65010-f64e-4ba8-bfe4-963dd0c67009",
        "state": "ERROR",
        "created_at": "2025-09-11T00:00:00Z",
        "request": {
            "name": "change_color_temperature",
            "arguments": {
                "temp_kelvins": 15000
            },
            "manifest_name": "change_lux"
        },
        "response": {
            "state": "ERROR",
            "payload": {"message": "Temperature value is out of range"},
            "received_at": "2025-09-11T00:00:01Z"
        },
        "log": [
          {
            "state": "ERROR",
            "received_at": "2025-09-11T00:00:01Z",
            "payload": {"message":"Temperature value is out of range"}
          },
          {
            "state": "IN_PROGRESS",
            "received_at": "2025-09-11T00:00:00Z",
            "payload": {"message": "received"}
          },
          {
            "received_at": "2025-09-11T00:00:00Z",
            "state": "STARTED"
          }
        ],
        "ephemeral": true
    }
}
executionobject#

Object containing command execution information.

execution.idstring#

Command execution ID.

execution.statestring#

Command execution state. Possible values:

  • NEW
  • IN_PROGRESS
  • SUCCESS
  • ERROR
  • TIMEOUT
execution.created_atstring#

The datetime when the execution was created, in RFC 3339 format.

execution.requestobject#

CommandRequest object contains execution request information.

CommandRequest.namestring#

A command name as it is or an alias.

CommandRequest.argumentsobject#

The command arguments are specified in the device blueprint manifest.

This is an object whose keys are the names of the arguments and whose values are the corresponding argument values.

CommandRequest.manifest_namestring#

A command name specified in the device manifest.

execution.responseobject#

CommandResponse object with response information.

CommandResponse.statestring#

Command response state. Possible values:

  • STARTED
  • IN_PROGRESS
  • SUCCEEDED
  • ERROR
CommandResponse.payloadobject#

The payload depends on the response state.

CommandResponse.received_atstring#

The datetime when the response was received, in RFC 3339 format.

execution.logarray of objects#

The log contains a list of CommandResponse objects.

CommandResponse.statestring#

Command response state. Possible values:

  • STARTED
  • IN_PROGRESS
  • SUCCEEDED
  • ERROR
CommandResponse.payloadobject#

The payload depends on the response state.

CommandResponse.received_atstring#

The datetime when the response was received, in RFC 3339 format.

execution.ephemeralboolean#

Shows whether the command has a limited TTL (time-to-live).

List Command Executions CloudGateway​

GET /v3/devices/{device_id}/command_executions

Returns all command executions of the specified device.

Request​

Return non-ephemeral executions:

$ curl http://api.enapter.com/v3/devices/fecbbba0-79f2-4e9e-a6f0-69a310ab110b/command_executions \
    -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}'

Return both ephemeral and non-ephemeral executions:

$ curl http://api.enapter.com/v3/devices/fecbbba0-79f2-4e9e-a6f0-69a310ab110b/command_executions?show=ALL \
    -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}'
Return executions sorted by created_at in descending order
$ curl http://api.enapter.com/v3/devices/fecbbba0-79f2-4e9e-a6f0-69a310ab110b/command_executions?show=ALL&order=CREATED_AT_DESC \
    -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}'

Query Parameters​

limitnumber#

The maximum number of command executions to return.

offsetnumber#

The number of command executions to skip.

showstring#

Indicates which executions should be present in the result:

  • NON_EPHEMERAL - return only executions with unlimited TTL (time-to-live).
  • ALL

By default, only non-ephemeral executions are returned.

orderstringdefault: CREATED_AT_ASC#

You can receive the list:

  • CREATED_AT_ASC - sorted by created_at in ascending order.
  • CREATED_AT_DESC - sorted by created_at in descending order.

Response​

{
  "executions": [
    {
      "id": "7ba65010-f64e-4ba8-bfe4-963dd0c67009",
      "state": "SUCCESS",
      "created_at": "2025-07-11T00:00:01Z",
      "request": {
          "name": "change_color_temperature",
          "arguments": {
              "temp_kelvins": 1850
          },
          "manifest_name": "change_lux"
      },
      "response": {
          "state": "SUCCEEDED",
          "received_at": "2025-07-11T00:00:02Z"
      },
      "ephemeral": false
    },
    {
        "id": "d8fbb364-bae2-4d29-b76e-23e23a321448",
        "state": "ERROR",
        "created_at": "2025-09-11T00:00:00Z",
        "request": {
            "name": "change_color_temperature",
            "arguments": {
                "temp_kelvins": 15000
            },
            "manifest_name": "change_lux"
        },
        "response": {
          "state": "ERROR",
          "received_at": "2025-09-11T00:00:01Z"
        },
        "ephemeral": true
    }
  ],
  "total_count": 2
}
total_countinteger#

The total number of device command executions.

executionsarray of objects#

A list of command executions of a specified device. If query parameters limit and/or offset are present:

  • the length of the list is less or equal to limit;
  • offset executions will be skipped before returning results. If offset is greater than total_count, an empty list is returned.
CommandExecutionobject#

Object containing command execution information.

CommandExecution.idstring#

Command execution ID.

CommandExecution.statestring#

Command execution state. Possible values:

  • NEW
  • IN_PROGRESS
  • SUCCESS
  • ERROR
  • TIMEOUT
CommandExecution.created_atstring#

The datetime when the execution was created, in RFC 3339 format.

CommandExecution.requestobject#

CommandRequest object contains execution request information.

CommandRequest.namestring#

A command name as it is or an alias.

CommandRequest.argumentsobject#

The command arguments are specified in the device blueprint manifest.

This is an object whose keys are the names of the arguments and whose values are the corresponding argument values.

CommandRequest.manifest_namestring#

A command name specified in the device manifest.

CommandExecution.responseobject#

CommandResponse object with response information.

CommandResponse.statestring#

Command response state. Possible values:

  • STARTED
  • IN_PROGRESS
  • SUCCEEDED
  • ERROR
CommandResponse.payloadobject#

The payload depends on the response state.

CommandResponse.received_atstring#

The datetime when the response was received, in RFC 3339 format.

execution.logarray of objects#

The log contains a list of CommandResponse objects.

CommandResponse.statestring#

Command response state. Possible values:

  • STARTED
  • IN_PROGRESS
  • SUCCEEDED
  • ERROR
CommandResponse.payloadobject#

The payload depends on the response state.

CommandResponse.received_atstring#

The datetime when the response was received, in RFC 3339 format.

CommandExecution.ephemeralboolean#

Shows whether the command has a limited TTL (time-to-live).

All Rights Reserved © 2025 Enapter AG.

Privacy Policy|Cookies Policy