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.

ephemeralboolean#

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,
    }
}
execution.idstring#

Command execution's ID.

execution.statestring#

Command execution state. Possible values:

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

The timestamp when the execution was first created.

execution.request.namestring#

A command name is specified in a device manifest. You can also use a command alias.

execution.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.

execution.request.manifest_namestring#

A command name is specified in a device manifest.

execution.response.statestring#

Command response state. Possible values:

  • UNDEFINED
  • STARTED
  • IN_PROGRESS
  • SUCCEEDED
  • ERROR
execution.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.

ephemeralboolean#

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}'

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,
    }
}
execution.idstring#

Command execution's ID.

execution.statestring#

Command execution state. Possible values:

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

The timestamp when the execution was first created.

execution.request.namestring#

A command name is specified in a device manifest. You can also use a command alias.

execution.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.

execution.request.manifest_namestring#

A command name is specified in a device manifest.

execution.response.statestring#

Command response state. Possible values:

  • UNDEFINED
  • STARTED
  • IN_PROGRESS
  • SUCCEEDED
  • ERROR
execution.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).

Request (expanded)​

$ 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}'

Response (expanded)​

log includes all commands responses for a requested execution.

{
    "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,
    }
}

List Command Executions​

GET devices/{device_id}/command_executions

Returns all command executions of the specified device.

Request​

$ curl http://api.enapter.com/v3/devices/fecbbba0-79f2-4e9e-a6f0-69a310ab110b/command_executions \
    -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​

{
  "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.

Request (show all)​

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

Response (show all)​

{
  "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
}

Request (show all, from the newest to the oldest)​

$ 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}'

Response (show all, 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