Skip to main content

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.

​
Overview

Use this when the customer has finished a manual override and the device should go back to running itself. A common pattern: a tariff-aware app schedules a windowed charge overnight, then drops the device to auto.balanced for the day so the battery covers the home as solar comes and goes. auto.balanced is the canonical name for the OEM’s own self-consumption mode. Push it and Amps maps the verb onto whichever native mode the device exposes for that intent. The device’s firmware does the optimisation. The body is short: no parameters, no window. Use it to drop back to self-managing after a windowed charge or discharge completes.

​
Step 1: Push auto.balanced

curl -X POST https://api.amps.ai/battery/dev_abc123 \
  -H "x-api-key: sk_live_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "command": "auto.balanced"
    }
  }'
You get back 202 Accepted. Auto modes run immediately, so the action lands in acknowledged state without a stop in scheduled. 
{
  "actionId": "act_inflight_002",
  "state": "acknowledged",
  "type": "battery:set_operation_mode",
  "createdAt": "2026-05-08T11:30:00.000Z"
}

​
Step 2: Confirm the mode applied

Once the OEM accepts the write, the action moves to completed. 
curl -X GET https://api.amps.ai/actions/act_inflight_002 \
  -H "x-api-key: sk_live_abc123xyz"

{
  "id": "act_inflight_002",
  "deviceId": "dev_abc123",
  "type": "battery:set_operation_mode",
  "state": "completed",
  "parameters": { "mode": "auto.balanced" },
  "result": { "success": true, "message": "Mode applied" },
  "errorCode": null,
  "errorMessage": null,
  "createdAt": "2026-05-08T11:30:00.000Z",
  "updatedAt": "2026-05-08T11:30:04.000Z",
  "acknowledgedAt": "2026-05-08T11:30:01.000Z",
  "completedAt": "2026-05-08T11:30:04.000Z"
}

​
Step 3: Verify the live state

Read the device to see the mode in action. state.status reports idle, charging, or discharging depending on solar output and home demand. 
curl -X GET https://api.amps.ai/battery/dev_abc123 \
  -H "x-api-key: sk_live_abc123xyz"

{
  "id": "dev_abc123",
  "vendor": "foxess",
  "sync": { "available": true, "lastPulledAt": "2026-05-08T11:30:09.000Z" },
  "state": {
    "status": "charging",
    "capacity": 10.4,
    "level": 67,
    "chargeRate": 1.6,
    "dischargeLimit": 10
  },
  "metadata": { "model": "FoxESS H1-5.0-E", "source": "live", "cacheType": "expedite" }
}
The battery is self-managing from this point. It charges when solar exceeds home draw, discharges when production drops, all without further API calls.

​
Other auto modes

Three auto variants share the same shape. Pick by intent.
CommandIntent
auto.balancedMaximise self-consumption from solar.
auto.reserveHold capacity in reserve for grid outages.
auto.exportMaximise grid export when the export tariff is attractive.
Switch between them with the same body, varying only command. Not every device supports every auto mode. Check commands on the device read before pushing.

​
What next

Charge overnight

Combine an overnight charge with auto.balanced for the day.

Cancel an action

Drop back to auto by cancelling an in-flight schedule.

Canonical actions

Why auto modes are intent declarations, not OEM passthroughs.

Subscribe to webhooks

Get push.completed events the moment the mode applies.