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

# EV charger

> What an EV charger reports, what it accepts, and recipes for common tasks.

Read an EV charger's session state, start and stop charging, cap how much power it draws, and read its charging history.

## What it reports

```bash theme={null}
curl https://api.amps.ai/ev-charger/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY"
```

| Field | |
| - | - |
| `status` | `available`, `charging`, `discharging`, `scheduled`, `error`, or `offline`. |
| `isConnected` | A vehicle is plugged in. |
| `isCharging` | The charger is delivering power to the vehicle now. `false` while exporting from it. |
| `currentPower` | Power in kW. Positive while charging, negative while exporting. |
| `sessionEnergy` | Energy delivered in the current session, in kWh. Resets each plug-in. |
| `notChargingReason` | Why a plugged-in vehicle isn't charging, such as `authorization` or `schedule`. |
| `activeControlMode` | The command the charger reports it is running under, such as `charge` or `auto.charge_tariff`. |

Optional fields are absent when the charger doesn't report them. Beside `state`, `sessions` says whether the charger keeps a charging history. See [Pull](/guides/pull) for the full read shape and freshness.

## What it accepts

| Type | Name | Parameters |
| - | - | - |
| Command | `charge` | Optional rate cap (`power` in `kw` or `current` in `amps`) and stop condition (`target` in `percent` or `energy` in `kwh`). |
| Command | `idle` | None. Pauses charging and holds the session. |
| Command | `auto.charge_tariff` | None. Charges in the cheapest hours of the tariff set in the manufacturer's app. |
| Command | `auto.charge_surplus_only` | None. Charges only from spare solar. |
| Command | `auto.charge_surplus_first` | None. Uses spare solar first, then tops up from the grid. |
| Setting | `max_charge_rate` | `{ value, unit: "kw" }`. Standing power cap. |
| Setting | `max_charge_current` | `{ value, unit: "amps" }`. The same cap in amps. |
| Setting | `cable_lock` | `{ value: true }` or `{ value: false }`. |
| Setting | `smart_charging` | `{ value: true }` or `{ value: false }`. Turns the charger's own smart schedule on or off. |

Each device's `commands` and `settings` show what that charger supports. Which chargers you can control in live depends on the manufacturer: see [Capabilities](/guides/capabilities).

## Recipes

<CardGroup cols={2}>
  <Card title="Start and stop a session" icon="plug" href="/cookbooks/ev-charger/start-stop-session">
    Charge now, pause, or charge inside a time window.
  </Card>

  <Card title="Smart charging" icon="bolt" href="/cookbooks/ev-charger/smart-charging">
    Let the charger pick cheap hours or spare solar.
  </Card>

  <Card title="Charge an exact amount" icon="battery-charging" href="/cookbooks/ev-charger/charge-energy-amount">
    Stop the session after a set number of kWh.
  </Card>

  <Card title="Cap charging power" icon="gauge" href="/cookbooks/ev-charger/cap-power">
    Set a standing power limit, or cap for a grid event and restore.
  </Card>

  <Card title="Why isn't it charging?" icon="circle-help" href="/cookbooks/ev-charger/why-not-charging">
    Read why a plugged-in car takes no power.
  </Card>

  <Card title="Read session history" icon="receipt" href="/cookbooks/ev-charger/session-history">
    List past charging sessions and the energy each one delivered.
  </Card>
</CardGroup>


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