Skip to main content
POST
/
battery
/
{deviceId}
curl
curl --request POST \
  --url 'https://api.amps.ai/battery/dev_abc123' \
  --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'content-type: application/json' \
  --data '{
    "action": {
      "command": "charge",
      "parameters": {
        "target": {
          "value": 80,
          "unit": "percent"
        }
      }
    }
  }'
{
  "actionId": "act_2026050710b3c4d5",
  "state": "acknowledged",
  "type": "battery:set_operation_mode",
  "createdAt": "2026-05-07T10:00:00.000Z",
  "start": null
}

Documentation Index

Fetch the complete documentation index at: https://docs.amps.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

A single battery action plus optional onConflict strategy and sandbox controls.

Action variants describe what the API accepts. Per-device support varies; the commands map on GET /battery/{deviceId} shows which actions a specific device handles.

​
action
Charge · object
required

Actively charge the battery from grid or solar. target bounds the upper SoC; power caps the rate.

Execution shapes supported: immediate, scheduled, windowed.

Example:
{
  "command": "charge",
  "parameters": {
    "target": { "value": 90, "unit": "percent" },
    "power": { "value": 5, "unit": "kw" }
  }
}
​
onConflict
enum<string>

cancel_and_replace cancels the active action before running this one; queue_after defers this one until the active action completes. Omit to receive 409 on conflict.

Available options:
cancel_and_replace,
queue_after
​
sandbox
Battery Sandbox Config · object

Sandbox controls for testing error paths. Ignored in live environments.

Response

Action accepted. For immediate actions, state: acknowledged means the connector has been dispatched; for deferred actions, state: scheduled and start carries the fire time.

Result of a push. For immediate actions, state reflects the connector handoff outcome. For deferred actions, state is scheduled and start carries the fire time.

​
actionId
string
required

Unique identifier for the action.

Example:

"act_abc123xyz"

​
state
enum<string>
required

Current state of the action. scheduled indicates a deferred action awaiting its fire time. cancelled is a terminal state reachable from scheduled via POST /actions/{actionId}/cancel.

Available options:
acknowledged,
completed,
failed,
scheduled,
cancelled
​
type
enum<string>
required

Type of action being performed.

Available options:
battery:set_operation_mode
​
createdAt
string<date-time>
required

Timestamp when the action was created.

​
start
string<date-time> | null

Absolute firing instant for deferred actions, as an ISO 8601 timestamp. Null or absent for immediate actions.