Skip to main content

​
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/device_abc123 \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "command": "auto.balanced"
    }
  }'
You get back 202 Accepted. This is an immediate push (no start), so the action lands in acknowledged without passing through scheduled. The response, like every other, is wrapped in { success, data, meta }. 
{
  "success": true,
  "data": {
    "id": "act_inflight_002",
    "deviceId": "device_abc123",
    "deviceType": "battery",
    "command": "auto.balanced",
    "parameters": null,
    "state": "acknowledged",
    "createdAt": "2026-05-08T11:30:00.000Z",
    "links": { "self": "/actions/act_inflight_002" }
  },
  "meta": { "requestId": "req_2fX6tGjW", "environment": "sandbox", "timestamp": "2026-05-08T11:30:00.000Z", "latencyMs": 95 }
}
The response mirrors the command. auto.balanced is an intent with no constraints, so data.parameters is null. Track the action at data.links.self.

​
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_test_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "id": "act_inflight_002",
    "deviceId": "device_abc123",
    "deviceType": "battery",
    "command": "auto.balanced",
    "parameters": null,
    "state": "completed",
    "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",
    "start": null,
    "end": null,
    "links": { "self": "/actions/act_inflight_002" }
  },
  "meta": { "requestId": "req_3gY7uHkX", "environment": "sandbox", "timestamp": "2026-05-08T11:30:05.000Z", "latencyMs": 12 }
}

​
Step 3: Verify the live state

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

{
  "success": true,
  "data": {
    "id": "device_abc123",
    "vendor": "foxess",
    "sync": { "available": true, "lastPulledAt": "2026-05-08T11:30:09.000Z" },
    "metadata": { "model": "FoxESS H1-5.0-E", "source": "projection" },
    "state": {
      "status": "charging",
      "capacity": 10.4,
      "level": 67,
      "chargeRate": 1.6,
      "dischargeLimit": 10,
      "currentMode": "auto.balanced"
    },
    "conflictStrategies": ["cancel_and_replace", "queue_after"],
    "lastAction": {
      "id": "act_inflight_002",
      "command": "auto.balanced",
      "state": "completed",
      "createdAt": "2026-05-08T11:30:00.000Z",
      "updatedAt": "2026-05-08T11:30:04.000Z",
      "errorCode": null,
      "errorMessage": null,
      "links": { "self": "/actions/act_inflight_002" }
    },
    "currentSchedule": null
  },
  "meta": { "requestId": "req_4hZ8vIlY", "environment": "sandbox", "timestamp": "2026-05-08T11:30:09.000Z", "latencyMs": 286 }
}
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

Schedule a charge for later

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.