Skip to main content

Commands Execution

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

Execute Command​

POST devices/{device_id}/execute_command

Executes 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 has a limited TTL (time-to-live).

Response​

Command execution with request and the latest response.

{
    "execution": {
        "id": "execcea0-45f2-4e9e-a6f0-69a310ab110b",
        "state": "SUCCESS",
        "created_at": 1735693800,
        "request": {
            "name": "change_color_temperature",
            "arguments": {
                "temp_kelvins": 1850
            },
            "manifest_name": "change_lux"
        },
        "response": {
            "state": "SUCCEEDED",
            "payload": {},
            "received_at": 1735693803
        },
        "ephemeral": false,
    }
}
executionobject#

Object containing command execution information.

execution.idstring#

Command execution's ID.

execution.statestring#

Command execution state. Possible values:

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

The timestamp when the execution was first created.

execution.requestobject#

A command request information.

request.namestring#

A command name as it is or an alias.

request.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 values of the arguments.

request.manifest_namestring#

A command name specified in a device manifest.

execution.responseobject#

A command response information.

response.statestring#

Command response state. Possible values:

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

The payload depends on the response state.

execution.logarray#

The log contains all command responses.

execution.ephemeralboolean#

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

Create Command Execution​

POST devices/{device_id}/command_executions

Creates an execution for 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 has a limited TTL (time-to-live).

Response​

{
  "execution_id": "execceb11-67f2-4e9e-a6f0-69a310ab110b"
}

Get Command Execution​

GET 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/execceb11-67f2-4e9e-a6f0-69a310ab110b \
    -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/execceb11-67f2-4e9e-a6f0-69a310ab110b?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​

It can be a running execution:

{
    "execution": {
        "id": "execceb11-67f2-4e9e-a6f0-69a310ab110b",
        "state": "IN_PROGRESS",
        "created_at": 1735751400,
        "request": {
            "name": "change_color_temperature",
            "arguments": {
                "temp_kelvins": 15000
            },
            "manifest_name": "change_lux"
        },
        "ephemeral": true,
    }
}

Or a finished one:

{
    "execution": {
        "id": "execceb11-67f2-4e9e-a6f0-69a310ab110b",
        "state": "ERROR",
        "created_at": 1735751400,
        "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": 1735751410
        },
        "ephemeral": true,
    }
}

Expanded response:

{
    "execution": {
        "id": "execceb11-67f2-4e9e-a6f0-69a310ab110b",
        "state": "ERROR",
        "created_at": 1735751400,
        "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": 1735751410
        },
        "log": [
          {
            "state": "ERROR",
            "received_at": 1735751410,
            "payload": {"message":"Temperature value is out of range"}
          },
          {
            "state": "IN_PROGRESS",
            "received_at": 1735751408,
            "payload": {"message": "received"}
          },
          {
            "received_at": 1735751405,
            "state": "STARTED"
          }
        ]
        "ephemeral": true,
    }
}
executionobject#

Object containing command execution information.

execution.idstring#

Command execution's ID.

execution.statestring#

Command execution state. Possible values:

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

The timestamp when the execution was first created.

execution.requestobject#

A command request information.

request.namestring#

A command name as it is or an alias.

request.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 values of the arguments.

request.manifest_namestring#

A command name specified in a device manifest.

execution.responseobject#

A command response information.

response.statestring#

Command response state. Possible values:

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

The payload depends on the response state.

execution.logarray#

The log contains all command responses.

execution.ephemeralboolean#

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

List Command Executions​

GET devices/{device_id}/command_executions

Returns all command executions of the specified device.

Request​

Return only 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 all 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 devices to skip. Devices are ordered by ID.

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.

orderstring#

You can receive the list:

  • CREATED_AT_ASC - sorted by created_at in ascending order. This is the default order.
  • CREATED_AT_DESC - sorted by created_at in descending order.

Response​

Only ephemeral-executions:

{
  "executions": [
    {
      "id": "execcea0-45f2-4e9e-a6f0-69a310ab110b",
      "state": "SUCCESS",
      "created_at": 1735693800,
      "request": {
          "name": "change_color_temperature",
          "arguments": {
              "temp_kelvins": 1850
          },
          "manifest_name": "change_lux"
      },
      "response": {
          "state": "SUCCEEDED",
          "received_at": 1735693803
      },
      "ephemeral": false
    }
  ],
  "total_count": 2
}
executionsarray#

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.
total_countinteger#

The total number of device command executions.

All executions:

{
  "executions": [
    {
      "id": "execcea0-45f2-4e9e-a6f0-69a310ab110b",
      "state": "SUCCESS",
      "created_at": 1735693800,
      "request": {
          "name": "change_color_temperature",
          "arguments": {
              "temp_kelvins": 1850
          },
          "manifest_name": "change_lux"
      },
      "response": {
          "state": "SUCCEEDED",
          "received_at": 1735693803
      },
      "ephemeral": false
    },
    {
        "id": "execcea1-45f2-4e9e-a6f0-69a310ab110b",
        "state": "ERROR",
        "created_at": 1735751400,
        "request": {
            "name": "change_color_temperature",
            "arguments": {
                "temp_kelvins": 15000
            },
            "manifest_name": "change_lux"
        },
        "response": {
          "state": "ERROR",
          "received_at": 1735751404
        },
        "ephemeral": true
    }
  ],
  "total_count": 2
}

All executions sorted from the newest to the oldest:

{
  "executions": [
    {
        "id": "execcea1-45f2-4e9e-a6f0-69a310ab110b",
        "state": "ERROR",
        "created_at": 1735751400,
        "request": {
            "name": "change_color_temperature",
            "arguments": {
                "temp_kelvins": 15000
            },
            "manifest_name": "change_lux"
        },
        "response": {
          "state": "ERROR",
          "received_at": 1735751404
        },
        "ephemeral": true
    },
    {
      "id": "execcea0-45f2-4e9e-a6f0-69a310ab110b",
      "state": "SUCCESS",
      "created_at": 1735693800,
      "request": {
          "name": "change_color_temperature",
          "arguments": {
              "temp_kelvins": 1850
          },
          "manifest_name": "change_lux"
      },
      "response": {
          "state": "SUCCEEDED",
          "received_at": 1735693803
      },
      "ephemeral": false
    }
  ],
  "total_count": 2
}

All Rights Reserved © 2025 Enapter AG.

Privacy Policy|Cookies Policy