> ## 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. # Push > Send a command to a device, choose when it runs, and track the action to completion. 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}`. ```bash theme={null} 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](/guides/push/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](/guides/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`. ```json theme={null} { "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](/guides/scheduling). ## The response A push returns `202 Accepted` with the new action. Track it at `links.self`. ```json theme={null} { "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`](/guides/webhooks/events#push-failed) is sent. ## Action states | State | Meaning | | - | - | | `scheduled` | Waiting for its `start` time. Can be [cancelled](/guides/push/cancelling). | | `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 ```bash theme={null} curl https://api.amps.ai/actions/action_qjSucnQFAk \ -H "x-api-key: $AMPS_API_KEY" ``` ```json theme={null} { "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](/guides/webhooks) instead of polling. ## List actions `GET /actions` returns actions across all your devices, newest first. ```bash theme={null} 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 What happens when a device already has an active action. Run commands later or inside a time window. Get notified when an action completes or fails. Find out what a device accepts before you push. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.