Skip to main content
POST
/
battery
/
{deviceId}
curl --request POST \
  --url https://api.example.com/battery/{deviceId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "action": "set_operation_mode",
  "mode": "charge"
}
'
{
  "actionId": "act_abc123xyz",
  "state": "acknowledged",
  "type": "battery:set_operation_mode",
  "createdAt": "2025-01-23T10:30:00.000Z",
  "deferredUntil": "2025-06-01T18:00:00Z"
}
The deferUntil parameter is not yet operational and will be available in a future release.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
deviceId
string
required

The unique identifier for the battery device

Example:

"device_abc123"

Body

application/json

The action to perform on the battery device

​
action
enum<string>
required

Action type - set battery operation mode

Available options:
set_operation_mode
Example:

"set_operation_mode"

​
mode
enum<string>
required

Target operation mode for the battery

Available options:
charge,
discharge,
idle
Example:

"charge"

​
deferUntil
string

Defer execution until a specific time. Accepts either an ISO 8601 UTC timestamp (e.g. '2025-06-01T18:00:00Z') or a relative duration: '{x}m' for minutes or '{x}h' for hours, where x is a number with up to 2 decimal places (e.g. '30m', '1.5h', '0.25h').

Example:

"30m"

​
sandbox
object

Optional sandbox configuration for testing

Response

Action acknowledged and queued for processing

​
actionId
string
required

Unique identifier for the action

Example:

"act_abc123xyz"

​
state
enum<string>
required

Current state of the action

Available options:
acknowledged,
deferred,
completed,
failed
Example:

"acknowledged"

​
type
enum<string>
required

Type of action being performed

Available options:
battery:set_operation_mode
Example:

"battery:set_operation_mode"

​
createdAt
string
required

Timestamp when the action was created

Example:

"2025-01-23T10:30:00.000Z"

​
deferredUntil
string | null

Resolved ISO 8601 UTC timestamp the action is deferred until. Null if the action was not deferred.

Example:

"2025-06-01T18:00:00Z"