Flip Energy API
  1. Commands
Flip Energy API
  • Overview
  • Important concepts
  • Authentication
  • Enrollment process
  • End-user app design
  • Monitoring / Telemetry
  • Control
  • Change log
  • Mobile App API
    • Devices
      • Create Device
      • Read Devices
      • Read Device
      • Update Device
      • Delete Device
    • Enrollments
      • Create Enrollment
      • Read Enrollments
      • Read Enrollment
      • Delete Enrollment
    • Events
      • Read Events
      • Read Event
      • Update Event Participation
    • Programs
      • Read Programs
      • Read Program
    • Sites
      • Read Site
      • Update Site
  • Cloud API
    • Sites
      • Get Site Token
      • Get Sites
    • Commissioning
      • Commission Site And Devices
    • Sessions
      • Sessions
    • Commands
      • Command Created
      • Update Command Status
        PATCH
    • Programs
      • Read Programs
    • Telemetry
      • Report Battery Telemetry
    • Webhooks
      • Overview
      • List of events
      • Webhook headers
      • Schemas
        • Command
        • Enrollment
        • Event
  1. Commands

Update Command Status

Cloud Mock
https://mock.apidog.com/m1/479670-0-default
Cloud Mock
https://mock.apidog.com/m1/479670-0-default
PATCH
/v1/command/{id}
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
id
string <uuid>
required
Body Params application/json
device_status
enum<string> 
required
Allowed values:
FAILED_OFFLINEFAILED_FAULTOK
Example:
OK
device_status_reason
string 
optional
Example:
Command scheduled
Example
{
    "device_status": "FAILED_OFFLINE",
    "device_status_reason": "Command scheduled"
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request PATCH 'https://mock.apidog.com/m1/479670-0-default/v1/command/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "device_status": "FAILED_OFFLINE",
    "device_status_reason": "Command scheduled"
}'

Responses

🟢200Success
application/json
Body
id
string <uuid>
read-onlyrequired
event_id
string <uuid> | null 
read-onlyrequired
device_id
string 
required
Example:
xyz-123
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.
Example:
2025-04-30 12:00:00.000Z
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.
Example:
2025-04-30 14:00:00.000Z
duration_s
number  | null 
read-onlyrequired
Duration of the action, in seconds. If null, the action should continue until replaced by another one.
Example:
7200
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.
Example:
5000
enable_grid_import
boolean  | null 
read-onlyoptional
Allow importing from the grid if charging.
enable_grid_export
boolean  | null 
deprecated
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
Example:
20
maximum_charge_percentage
integer  | null 
deprecated
The maximum state of charge the battery will charge to, only when charging from the grid.
>= 0<= 100
Example:
90
status
enum<string> 
read-onlyrequired
The status of the command itself. Only OK means that the command is happening.
Allowed values:
CANCELEDOKOPT_OUT
Example:
OK
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:
FAILED_OFFLINEFAILED_FAULTOKPENDING
Example:
OK
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.
Example:
Command scheduled
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": "xyz-123",
    "starts_at": "2025-04-30 12:00:00.000Z",
    "ends_at": "2025-04-30 14:00:00.000Z",
    "duration_s": 7200,
    "is_preparatory_action": true,
    "battery_commands": {
        "mode": "BACKUP",
        "power_mode": "FOLLOW_LOAD",
        "setpoint_w": 5000,
        "enable_grid_import": true,
        "enable_grid_export": true,
        "backup_reserve_percentage": 20,
        "maximum_charge_percentage": 90
    },
    "status": "CANCELED",
    "device_status": "FAILED_OFFLINE",
    "device_status_reason": "Command scheduled",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
}
🟠400Invalid input
🟠404Record not found
Modified at 2025-04-29 20:56:43
Previous
Command Created
Next
Read Programs
Built with