Push

A push sends one command to one device. Every writable device type takes the same body, and every push creates an action you can track.

Send a command

Post to the device’s route: POST /battery/{deviceId}, POST /ev-charger/{deviceId}, or POST /hvac/{deviceId}.

curl -X POST https://api.amps.ai/battery/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "command": "charge",
      "parameters": {
        "target": { "value": 80, "unit": "percent" },
        "power": { "value": 3, "unit": "kw" }
      }
    }
  }'

Solar inverters and vehicles are read-only. They have no push route, so a POST to them returns 405 METHOD_NOT_ALLOWED.

Request body

Field	Required
`action.command`	Yes	The command to run, such as `charge`, `idle`, or `heat`.
`action.parameters`	No	Inputs the command accepts. Each is a Quantity.
`action.start`	No	When to run. Omit to run now.
`action.end`	No	When to stop and revert.
`onConflict`	No	What to do if the device already has an active action. See Conflicts.
`sandbox`	No	Sandbox only. Simulate a failure, for example `{ "result": "failed", "errorCode": "DEVICE_OFFLINE" }`. Ignored in live.

The commands, parameters, and bounds a device accepts are listed in its commands map. See Capabilities.

Commands by device type

Device type	Commands
Battery	`charge`, `discharge`, `idle`, `auto.balance`, `auto.reserve`, `auto.export`
EV charger	`charge`, `idle`, `auto.charge_tariff`, `auto.charge_surplus_only`, `auto.charge_surplus_first`
HVAC	`heat`, `cool`, `idle`, `auto.maintain`, `auto.schedule`

A given device may support a subset. A command, parameter, or unit the device doesn’t list returns 422 DEVICE_NOT_CAPABLE, with the offending value and what the device supports in details.

Quantities

Every numeric parameter is a Quantity: a value and a unit.

{ "value": 80, "unit": "percent" }

Valid units are percent, kw, watts, kwh, amps, volts, hours, minutes, celsius, and fahrenheit. Each parameter accepts the unit declared in the device’s commands map. A value outside the declared bounds returns 422 PARAMETER_OUT_OF_RANGE.

When it runs

Execution	Body	Behaviour
`immediate`	No `start`, no `end`	Runs now.
`scheduled`	`start` only	Runs at `start`.
`windowed`	`start` and `end`	Runs at `start`, reverts at `end`.
`windowed`	`end` only	Runs now, reverts at `end`.

Each command lists the execution types it supports in its execution array. An unsupported one returns 422 DEVICE_NOT_CAPABLE with requestedExecution and supportedExecution in details. Time format, time zones, and limits are covered in Scheduling.

The response

A push returns 202 Accepted with the new action. Track it at links.self.

{
  "success": true,
  "data": {
    "id": "action_qjSucnQFAk",
    "deviceId": "device_abc123",
    "deviceType": "battery",
    "command": "charge",
    "state": "acknowledged",
    "links": { "self": "/actions/action_qjSucnQFAk" }
  }
}

Pushes that run now return acknowledged. Pushes with a start return scheduled, with start and end echoed as UTC timestamps. An immediate push may also carry warnings, such as no vehicle plugged in. The command is still accepted. If the manufacturer refuses an immediate command straight away, the push returns that error instead of 202. The action is still recorded as failed, and a push.failed is sent.

Action states

State	Meaning
`scheduled`	Waiting for its `start` time. Can be cancelled.
`acknowledged`	Sent to the manufacturer. Waiting for the result.
`completed`	The manufacturer accepted the command.
`failed`	The command didn’t succeed. `errorCode` says why.
`cancelled`	Cancelled before it ran.

States move scheduled → acknowledged → completed or failed. Immediate pushes start at acknowledged. completed, failed, and cancelled are final. A windowed action is completed while its window is still running. Its endedAt is set when the window closes.

Check an action

curl https://api.amps.ai/actions/action_qjSucnQFAk \
  -H "x-api-key: $AMPS_API_KEY"

{
  "success": true,
  "data": {
    "id": "action_qjSucnQFAk",
    "state": "failed",
    "errorCode": "DEVICE_OFFLINE",
    "errorMessage": "The device is currently offline at the manufacturer.",
    "completedAt": "2026-05-07T10:30:05.000Z"
  }
}

In production, use webhooks instead of polling.

List actions

GET /actions returns actions across all your devices, newest first.

curl "https://api.amps.ai/actions?deviceId=device_abc123&state=scheduled" \
  -H "x-api-key: $AMPS_API_KEY"

Query parameter
`deviceId`	Only this device.
`state`	`scheduled`, `acknowledged`, `completed`, `failed`, or `cancelled`.
`type`	Device type: `battery`, `ev_charger`, `hvac`, `solar_inverter`, or `vehicle`.
`userId`	Only devices linked to this end user.
`limit`	1 to 50. Default 10.
`offset`	Default 0.

The response is data: { items, pagination }, with the same item shape as GET /actions/{actionId}.

Next steps

Conflicts

What happens when a device already has an active action.

Scheduling

Run commands later or inside a time window.

Webhooks

Get notified when an action completes or fails.

Capabilities

Find out what a device accepts before you push.

Get started

API Reference

Guides

Cookbooks

Send a command

Request body

Commands by device type

Quantities

When it runs

The response

Action states

Check an action

List actions

Next steps

Conflicts

Scheduling

Webhooks

Capabilities

​Send a command

​Request body

​Commands by device type

​Quantities

​When it runs

​The response

​Action states

​Check an action

​List actions

​Next steps

Conflicts

Scheduling

Webhooks

Capabilities

Send a command

Request body

Commands by device type

Quantities

When it runs

The response

Action states

Check an action

List actions

Next steps