> ## 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.

# Battery

> What a battery reports, the commands it accepts, and recipes for common tasks.

Read a home battery's charge level and mode, and tell it to charge, discharge, or run itself. Each recipe below covers one task end to end.

## What a battery reports

`GET /battery/{id}` returns the battery's `state` alongside the `commands` and `settings` it supports.

```json theme={null}
{
  "success": true,
  "data": {
    "state": {
      "status": "idle",
      "level": 67,
      "capacity": 10.4,
      "chargeRate": 0,
      "dischargeLimit": 10,
      "currentMode": "auto.balance"
    }
  }
}
```

| Field | |
| - | - |
| `status` | `charging`, `discharging`, `idle`, or `standby`. |
| `level` | State of charge, in percent. |
| `capacity` | Total capacity, in kWh. |
| `chargeRate` | Current rate in kW. Negative while discharging. |
| `dischargeLimit` | Discharge limit, in percent. |
| `currentMode` | The command the battery is running. Absent when the mode has no canonical name. |

See [Pull](/guides/pull) for freshness, caching, and the rest of the device read.

## Commands

| Command | What it does | Parameters | Execution |
| - | - | - | - |
| `charge` | Charge from grid or solar. Stops at `target`. | `target`, `power`, `reserve` | immediate, scheduled, windowed |
| `discharge` | Discharge to the home or grid. Stops at `target`. | `target`, `power`, `reserve` | immediate, scheduled, windowed |
| `idle` | Pause charging and discharging. | none | immediate, scheduled |
| `auto.balance` | Self-consumption: store surplus solar, cover the home's load. | none | immediate, scheduled |
| `auto.reserve` | Hold charge in reserve for a grid outage. | none | immediate, scheduled |
| `auto.export` | Favour exporting to the grid. | none | immediate, scheduled |

`target` and `reserve` are in `percent`, `power` is in `kw`. The table shows the most a battery can accept. Each device lists its own subset, bounds, and execution shapes in `commands`, and anything outside that list returns `422 DEVICE_NOT_CAPABLE`. See [Capabilities](/guides/capabilities).

## Recipes

<CardGroup cols={2}>
  <Card title="Charge in a cheap-rate window" icon="moon" href="/cookbooks/battery/charge-in-window">
    Charge between a `start` and `end`.
  </Card>

  <Card title="Start a charge later" icon="clock" href="/cookbooks/battery/defer-charge">
    Defer a charge to a future time.
  </Card>

  <Card title="Discharge during a peak" icon="bolt" href="/cookbooks/battery/discharge-in-window">
    Discharge or export in a peak-rate window.
  </Card>

  <Card title="Return to self-consumption" icon="rotate" href="/cookbooks/battery/auto-balance">
    Hand control back with `auto.balance`.
  </Card>

  <Card title="Change a setting" icon="sliders" href="/cookbooks/battery/change-settings">
    Update the discharge floor, charge ceiling, and more.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.