Push battery action - Amps AI Documentation

curl --request POST \ --url 'https://api.amps.ai/battery/device_abc123' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' \ --header 'content-type: application/json' \ --data '{ "action": { "command": "charge", "parameters": { "target": { "value": 80, "unit": "percent" } } } }'

{ "success": true, "data": { "id": "act_2026050710b3c4d5", "deviceId": "dev_b1a2c3d4e5", "deviceType": "battery", "command": "charge", "parameters": { "target": { "value": 80, "unit": "percent" } }, "state": "acknowledged", "createdAt": "2026-05-07T10:00:00.000Z", "start": null, "links": { "self": "/actions/act_2026050710b3c4d5" } }, "meta": { "requestId": "req_8a2Bf3kP", "environment": "sandbox", "timestamp": "2026-06-02T12:00:00.000Z", "latencyMs": 12 } }

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

Battery Action · object

required

A canonical battery command. charge/discharge move energy to/from the battery (bounded by target, rate-capped by power); idle pauses; the auto.* modes declare an optimisation intent.

Show child attributes

Examples:

{
  "command": "charge",
  "parameters": {
    "target": { "value": 90, "unit": "percent" },
    "power": { "value": 5, "unit": "kw" }
  }
}

{
  "command": "charge",
  "start": "2026-05-08T22:00:00",
  "parameters": {
    "target": { "value": 100, "unit": "percent" }
  }
}

{
  "command": "discharge",
  "start": "2026-05-08T17:00:00",
  "end": "2026-05-08T20:00:00",
  "parameters": {
    "target": { "value": 30, "unit": "percent" }
  }
}

{ "command": "auto.balanced" }

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.

Show child attributes

Response

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

success

boolean

required

Always true for success responses.

data

Battery Push Response · object

required

Result of a push. Mirrors the dispatch (command + parameters + deviceType) and carries links.self to track the action. For immediate actions, state reflects the dispatch outcome. For deferred actions, state is scheduled, start carries the fire time, and end the window close when a window was requested.

Show child attributes