Start and stop a session

Start charging with charge and pause with idle. Add start and end to charge only inside a time window, such as a cheap overnight rate.

1. Check the device supports it

curl https://api.amps.ai/ev-charger/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY"

{
  "success": true,
  "data": {
    "id": "device_abc123",
    "state": { "status": "available", "isConnected": true, "isCharging": false },
    "commands": {
      "charge": {
        "parameters": {
          "power": { "unit": "kw", "min": 1.4, "max": 22, "step": 0.1 },
          "energy": { "unit": "kwh", "min": 1, "max": 100 }
        },
        "execution": ["immediate", "scheduled", "windowed"]
      },
      "idle": { "parameters": {}, "execution": ["immediate", "scheduled"] },
      "auto.charge_tariff": { "parameters": {}, "execution": ["immediate", "scheduled"] }
    },
    "conflictStrategies": ["cancel_and_replace", "queue_after"]
  }
}

charge accepts windowed, so it can take both start and end. This charger caps by power and stops by energy; it doesn’t declare target, so sending one returns 422 DEVICE_NOT_CAPABLE.

2. Send the command

Charge at up to 7 kW from 00:30 to 04:30, plant-local time:

curl -X POST https://api.amps.ai/ev-charger/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "command": "charge",
      "parameters": { "power": { "value": 7, "unit": "kw" } },
      "start": "2026-06-02T00:30:00",
      "end": "2026-06-02T04:30:00"
    }
  }'

{
  "success": true,
  "data": {
    "id": "action_AUR2pdqvgT",
    "command": "charge",
    "parameters": { "power": { "value": 7, "unit": "kw" } },
    "state": "scheduled",
    "start": "2026-06-01T23:30:00.000Z",
    "end": "2026-06-02T03:30:00.000Z",
    "links": { "self": "/actions/action_AUR2pdqvgT" }
  }
}

Omit start and end to charge now. Send { "action": { "command": "idle" } } to pause. Send power or current, not both, or you get 422 UNSUPPORTED_PARAMETER_COMBINATION. See Scheduling for time format and what happens at end, and Conflicts if you get a 409.

Let the charger pick the time

To hand timing to the charger’s own price or solar optimiser instead, push an auto.* command. See Smart charging.

3. Confirm

Poll GET /actions/action_AUR2pdqvgT or listen for webhooks. See Push for the action lifecycle. Chargers that report it then read activeControlMode: "charge". If no vehicle is plugged in, an immediate push either comes back with a vehicle_not_connected entry in warnings (accepted, starts when a car plugs in) or, on chargers that can’t arm a charge in advance, 409 VEHICLE_NOT_CONNECTED.

Next steps

Charge an exact amount

Stop the session after a set number of kWh.

Cancelling

Cancel a scheduled session before it starts.

Webhooks

Get notified when the session starts.

Get started

API Reference

Guides

Cookbooks

1. Check the device supports it

2. Send the command

Let the charger pick the time

3. Confirm

Next steps

Charge an exact amount

Cancelling

Webhooks

​1. Check the device supports it

​2. Send the command

​Let the charger pick the time

​3. Confirm

​Next steps

Charge an exact amount

Cancelling

Webhooks

1. Check the device supports it

2. Send the command

Let the charger pick the time

3. Confirm

Next steps