Update Command Status

Use this endpoint to acknowledge commands. If it was properly received set device_status to OK, otherwise set it to FAILED.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

string

required

Body Params application/json

device_status

enum<string>

required

Allowed values:

FAILEDOK

device_status_reason

string

optional

Example

{
  "device_status": "FAILED",
  "device_status_reason": "string"
}

Responses

🟢200Success

application/json

Body

string <uuid>

read-onlyrequired

event_id

string <uuid> | null

read-onlyrequired

device_id

string

required

starts_at

string <date-time>

read-onlyrequired

Time at which the action should start. Note that this may be before the event itself has started. For instance, in order to pre-charge a battery prior to a discharge event.

ends_at

string <date-time> | null

read-onlyrequired

Time at which the action should stop. If null, the action should continue until replaced by another one.

duration_s

number | null

read-onlyrequired

Duration of the action, in seconds. If null, the action should continue until replaced by another one.

is_preparatory_action

boolean

read-onlyrequired

Whether the command is not part of the event itself but in preparation for the event. For instance, charging a battery before a discharging event.

battery_commands

object (BatteryCommand)

read-onlyrequired

mode

enum<string>

required

The mode the battery should go into during this period.

Allowed values:

BACKUPCHARGEDISCHARGESAVINGSSELF_CONSUMPTIONSTANDBY

power_mode

enum<string> | enum<null>

read-onlyoptional

Specifies details for the action. Present if the state is CHARGE or DISCHARGE only

Allowed values:

FOLLOW_LOADSETPOINT

setpoint_w

integer | null

read-onlyoptional

Defines specific wattage level, only used if power_mode is SETPOINT. In Watts, always a non-zero positive integer.

enable_grid_import

boolean | null

read-onlyoptional

Allow importing from the grid if charging.

enable_grid_export

boolean | null

read-onlyoptional

Allow exporting to the grid if discharging (battery only).

backup_reserve_percentage

integer | null

optional

The minimum state of charge the battery will keep when discharging.

>= 0<= 100

maximum_charge_percentage

integer | null

optional

The maximum state of charge the battery will charge to, only when charging from the grid.

>= 0<= 100

status

enum<string>

read-onlyrequired

The status of the command itself. Only OK means that the command is happening.

Allowed values:

CANCELEDOKOPT_OUT

device_status

enum<string>

required

The acknowledgment of the command by the device. Only OK means that the device is ready to perform the command.

Allowed values:

FAILEDOKPENDING

device_status_reason

string | null

optional

It helps to share more human-readable information when setting the device_status. We will use it when we set device_status to PENDING, and feel free to use it as well when setting to OK or FAILED.

created_at

string <date-time>

read-onlyrequired

updated_at

string <date-time>

read-onlyrequired

Example

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
  "device_id": "string",
  "starts_at": "2019-08-24T14:15:22Z",
  "ends_at": "2019-08-24T14:15:22Z",
  "duration_s": 0,
  "is_preparatory_action": true,
  "battery_commands": {
    "mode": "BACKUP",
    "power_mode": "FOLLOW_LOAD",
    "setpoint_w": 0,
    "enable_grid_import": true,
    "enable_grid_export": true,
    "backup_reserve_percentage": 0,
    "maximum_charge_percentage": 0
  },
  "status": "CANCELED",
  "device_status": "FAILED",
  "device_status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

🟠400Invalid input

🟠404Record not found

Request

Request samples

Responses