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

To sell stored energy during peak-rate hours, or shave household load during a demand event, push a windowed discharge. The body mirrors a windowed charge: command: "discharge", start, end, and a target that names the lower SoC at which discharging stops. Confirm the device supports windowed discharge before pushing. Look for windowed in commands.discharge.execution.

​
Step 1: Check capability before pushing

curl -X GET https://api.amps.ai/battery/dev_abc123 \
  -H "x-api-key: sk_live_abc123xyz"

{
  "id": "dev_abc123",
  "vendor": "foxess",
  "state": {
    "status": "idle",
    "capacity": 10.4,
    "level": 92,
    "chargeRate": 0,
    "dischargeLimit": 10
  },
  "commands": {
    "discharge": {
      "type": "set_operation_mode",
      "parameters": {
        "target": { "unit": "percent", "min": 10, "max": 100 },
        "power": { "unit": "kw", "min": 0, "max": 5 },
        "reserve": { "unit": "percent", "min": 0, "max": 100 }
      },
      "execution": ["windowed"]
    }
  }
}
For a discharge, target is the lower bound: discharging stops at this level. reserve is a second floor that protects against full depletion if the window overruns.

​
Step 2: Push the windowed discharge

Discharge from late afternoon into the early evening, stopping at 30%. 
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": "discharge",
      "start": "2026-05-08T16:00:00Z",
      "end": "2026-05-08T19:00:00Z",
      "parameters": {
        "target": { "value": 30, "unit": "percent" },
        "power": { "value": 5, "unit": "kw" },
        "reserve": { "value": 20, "unit": "percent" }
      }
    }
  }'
You get back the scheduled action. 
{
  "actionId": "act_pending_007",
  "state": "scheduled",
  "type": "battery:set_operation_mode",
  "createdAt": "2026-05-08T08:30:00.000Z",
  "start": "2026-05-08T16:00:00.000Z"
}

​
Step 3: Confirm the window opened

After start, read the action to confirm dispatch. acknowledgedAt is the moment the OEM accepted the write. 
curl -X GET https://api.amps.ai/actions/act_pending_007 \
  -H "x-api-key: sk_live_abc123xyz"

{
  "id": "act_pending_007",
  "deviceId": "dev_abc123",
  "type": "battery:set_operation_mode",
  "state": "acknowledged",
  "parameters": {
    "mode": "discharge",
    "target": { "value": 30, "unit": "percent" },
    "power": { "value": 5, "unit": "kw" },
    "reserve": { "value": 20, "unit": "percent" }
  },
  "result": null,
  "errorCode": null,
  "errorMessage": null,
  "createdAt": "2026-05-08T08:30:00.000Z",
  "updatedAt": "2026-05-08T16:00:02.000Z",
  "acknowledgedAt": "2026-05-08T16:00:02.000Z",
  "completedAt": null,
  "start": "2026-05-08T16:00:00.000Z",
  "end": "2026-05-08T19:00:00.000Z"
}
A second GET /battery/dev_abc123 confirms live state. While the window is active, state.status reports discharging and state.chargeRate is negative. 
{
  "id": "dev_abc123",
  "state": {
    "status": "discharging",
    "level": 78,
    "chargeRate": -4.8,
    "capacity": 10.4,
    "dischargeLimit": 10
  }
}
At end, the battery reverts to its prior mode and the action transitions to completed.

​
What next

Charge overnight

The mirrored recipe for cheap-rate charging.

Subscribe to webhooks

Get push.completed events when the window closes.

Handle conflicts

What to do when a colliding action is in flight.

Canonical actions

The semantic model behind charge, discharge, and auto.