Cap an EV Charger's Power

Overview

An EV charger’s maximum charging power is a ceiling the charger operates under, not a one-off command, so it is a device setting: max_charge_rate in kw, or max_charge_current in amps. Write it once and it persists across sessions until you change it or the charger reverts to its own defaults. Use it to balance against household consumption, throttle to a cheaper tariff window, or coordinate multiple chargers behind a single supply. Commands can carry a rate cap too, and the difference is what makes each one the right tool. A power or current parameter on a charge command caps that session and nothing else. max_charge_rate is the standing ceiling the charger stays under whatever anyone asks it for next — including a session someone starts from the manufacturer’s own app. Reach for the setting when the constraint belongs to the site, and for the command parameter when it belongs to the session. Commands run through POST /ev-charger/{deviceId}; the setting runs through POST /ev-charger/{deviceId}/settings. See canonical actions on the actions-versus-settings boundary. Pick one unit, not both. Kilowatts and amperes describe the same ceiling, so a request carrying both leaves it ambiguous and is refused rather than resolved. On a command that is 422 UNSUPPORTED_PARAMETER_COMBINATION (details.conflictingParameters); on the settings write it is 422 UNSUPPORTED_SETTING_COMBINATION (details.conflictingSettings). A charger declaring both is normal and means you may write in either one.

Coming soon. Live control for EV chargers. The sandbox environment serves the full commands and settings surface, so the walkthrough below works against a sandbox device today. A live EV charger push returns 503 NOT_YET_AVAILABLE until the live path opens.

Step 1: Read the current state

Every response is wrapped in { success, data, meta }; the device sits under data.

curl -X GET https://api.amps.ai/ev-charger/device_ev_001 \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "id": "device_ev_001",
    "vendor": "example_vendor_a",
    "sync": { "available": true, "lastPulledAt": "2026-05-08T11:30:00.000Z" },
    "metadata": { "model": "7kW AC Charger", "source": "projection" },
    "state": {
      "status": "charging",
      "isConnected": true,
      "isCharging": true,
      "currentPower": 11,
      "maxCurrent": 32,
      "powerRateLimit": 11,
      "sessionEnergy": 12.6,
      "phases": 3,
      "voltage": 400
    },
    "conflictStrategies": ["cancel_and_replace", "queue_after"],
    "sessions": true,
    "commands": {
      "charge": {
        "parameters": {
          "power":   { "unit": "kw", "min": 1.4, "max": 22, "step": 0.1 },
          "current": { "unit": "amps", "min": 6, "max": 32, "step": 1 },
          "energy":  { "unit": "kwh", "min": 1, "max": 100 }
        },
        "execution": ["immediate", "scheduled", "windowed"]
      },
      "idle": { "parameters": {}, "execution": ["immediate", "scheduled"] },
      "auto.charge_tariff": { "parameters": {}, "execution": ["immediate", "scheduled"] }
    },
    "settings": {
      "max_charge_rate":    { "value": 11, "unit": "kw", "min": 0, "max": 50, "step": 0.1 },
      "max_charge_current": { "value": 32, "unit": "amps", "min": 6, "max": 32, "step": 1 },
      "cable_lock":         { "value": true }
    },
    "vehicle": { "id": "device_veh456", "links": { "self": "/vehicle/device_veh456" } },
    "lastAction": null,
    "currentSchedule": null
  },
  "meta": {
    "requestId": "req_1uM5iVyL",
    "environment": "sandbox",
    "timestamp": "2026-05-08T11:30:00.000Z",
    "latencyMs": 33
  }
}

The charger is connected and drawing 11 kW. data.settings.max_charge_rate is the writable ceiling, bounded 0 to 50 kw in steps of 0.1 — a value between the increments is refused, so read step before you write. commands is abridged here; a charger that implements the full surface also advertises the two surplus modes, auto.charge_surplus_only (pauses when generation drops) and auto.charge_surplus_first (lets the grid top up). Every auto.* mode takes an empty parameters map and no windowed execution: the mode hands timing to the charger’s own optimiser and runs until another command replaces it. metadata.source reports where the reading came from. Sandbox device reads always carry source: "projection" because sandbox devices are simulated, not physical hardware. In live, the value is one of cache, live, or fallback, naming the data-freshness tier the read came back from.

Step 2: Cap the power

Write max_charge_rate through the settings endpoint. The body is a sparse map: send only the settings you want to change. The value is the canonical {value, unit} shape.

curl
Node
Python

curl -X POST https://api.amps.ai/ev-charger/device_ev_001/settings \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "max_charge_rate": { "value": 7.4, "unit": "kw" }
  }'

await fetch("https://api.amps.ai/ev-charger/device_ev_001/settings", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AMPS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    max_charge_rate: { value: 7.4, unit: "kw" },
  }),
});

import os, requests

requests.post(
    "https://api.amps.ai/ev-charger/device_ev_001/settings",
    headers={
        "x-api-key": os.environ["AMPS_API_KEY"],
        "Content-Type": "application/json",
    },
    json={"max_charge_rate": {"value": 7.4, "unit": "kw"}},
)

Settings are fire-and-forget. The response acknowledges the write and echoes the keys that changed, under the standard data envelope.

{
  "success": true,
  "data": {
    "deviceId": "device_ev_001",
    "updated": ["max_charge_rate"]
  },
  "meta": {
    "requestId": "req_2vN6jWzM",
    "environment": "sandbox",
    "timestamp": "2026-05-08T11:31:14.000Z",
    "latencyMs": 71
  }
}

A value outside 0 to 50, or one that misses the 0.1 kw grid, returns 422 SETTING_OUT_OF_RANGE with min, max, and step in details so you can round and retry without a second GET. An unknown key returns 422 UNSUPPORTED_SETTING; a read-only key returns 422 READ_ONLY_SETTING. Sending max_charge_rate and max_charge_current together returns 422 UNSUPPORTED_SETTING_COMBINATION. The bounds come from the device read, so check data.settings on the GET before you write.

Step 3: Verify the cap applied

Read the device again. The new ceiling shows on data.settings, and live throughput settles to the cap.

{
  "success": true,
  "data": {
    "id": "device_ev_001",
    "vendor": "example_vendor_a",
    "sync": { "available": true, "lastPulledAt": "2026-05-08T11:32:02.000Z" },
    "metadata": { "model": "7kW AC Charger", "source": "projection" },
    "state": {
      "status": "charging",
      "isConnected": true,
      "isCharging": true,
      "currentPower": 7.4,
      "maxCurrent": 32,
      "powerRateLimit": 7.4,
      "sessionEnergy": 14.1,
      "phases": 3,
      "voltage": 400
    },
    "conflictStrategies": ["cancel_and_replace", "queue_after"],
    "sessions": true,
    "settings": {
      "max_charge_rate":    { "value": 7.4, "unit": "kw", "min": 0, "max": 50, "step": 0.1 },
      "max_charge_current": { "value": 32, "unit": "amps", "min": 6, "max": 32, "step": 1 },
      "cable_lock":         { "value": true }
    },
    "vehicle": { "id": "device_veh456", "links": { "self": "/vehicle/device_veh456" } },
    "lastAction": null,
    "currentSchedule": null
  },
  "meta": { "requestId": "req_3wO7kXaN", "environment": "sandbox", "timestamp": "2026-05-08T11:32:02.000Z", "latencyMs": 35 }
}

Start and stop a session

The cap is configuration; starting and stopping a session is intent. Commands go in the canonical action envelope.

Command	Use
`charge`	Begin or resume a session on a connected vehicle.
`idle`	Pause the session, holding it.
`auto.charge_tariff`	Hand timing to the charger’s own price optimiser. Runs until replaced.
`auto.charge_surplus_only`	Charge from on-site generation the home is not using, pausing when that surplus runs out.
`auto.charge_surplus_first`	Use that surplus first and top up from the grid, so charging never pauses.

Read commands on the device to see which of these a given charger declares and what each one accepts — a command that is not in the map is refused with 422 UNSUPPORTED_MODE, which lists the ones that are. Set the cap before starting a session to keep the first kWh inside a cheap rate, or change it mid-session as household demand spikes. The most recent setting wins.

curl -X POST https://api.amps.ai/ev-charger/device_ev_001 \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "action": { "command": "charge" } }'

{
  "success": true,
  "data": {
    "id": "act_ev_007",
    "deviceId": "device_ev_001",
    "deviceType": "ev_charger",
    "command": "charge",
    "parameters": null,
    "state": "acknowledged",
    "createdAt": "2026-05-08T12:00:01.000Z",
    "links": { "self": "/actions/act_ev_007" }
  },
  "meta": { "requestId": "req_4xP8lYbO", "environment": "sandbox", "timestamp": "2026-05-08T12:00:01.000Z", "latencyMs": 92 }
}

This is an immediate push, so the action begins life in acknowledged rather than passing through scheduled. To pause without unplugging, push idle. Only one command is in flight at a time; submit a second while the first is acknowledged and you get 409 CONFLICT. Add onConflict: "cancel_and_replace" to drop the in-flight action and run the new one, or queue_after to hold yours until the running window closes. queue_after needs an end to queue behind. An auto.* command has none, because it runs until another command replaces it, so queueing behind one returns 409 CONFLICT and points at cancel_and_replace instead. A conflicting action still mid-flight returns 409 CONFLICT_IN_EXECUTION with an empty strategy list, which means wait for it.

Why this works

The split between the max_charge_rate setting and the charger’s commands is the actions-versus-settings boundary applied to a charger. A ceiling is persistent and non-conflicting, so it is a setting; starting a session or handing timing to a strategy is a time-bound intent, so it is a command. The same boundary puts a battery’s safety_reserve on settings and its charge on commands. See canonical actions and capabilities.

What next

Subscribe to webhooks

Get push.completed events on charger state changes.

Handle conflicts

Resolve 409s when a charger write is already in flight.

Hold an HVAC device

The mirrored command pattern on a thermostat.

Canonical actions

Where EV charger commands sit in the canonical model.

Get Started

Concepts

API Reference

Guides

Quick reference

More

Overview

Step 1: Read the current state

Step 2: Cap the power

Step 3: Verify the cap applied

Start and stop a session

Why this works

What next

Subscribe to webhooks

Handle conflicts

Hold an HVAC device

Canonical actions

​Overview

​Step 1: Read the current state

​Step 2: Cap the power

​Step 3: Verify the cap applied

​Start and stop a session

​Why this works

​What next

Subscribe to webhooks

Handle conflicts

Hold an HVAC device

Canonical actions

Overview

Step 1: Read the current state

Step 2: Cap the power

Step 3: Verify the cap applied

Start and stop a session

Why this works

What next