Push HVAC action - Amps AI Documentation

curl --request POST \ --url 'https://api.amps.ai/hvac/device_abc123' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' \ --header 'content-type: application/json' \ --data '{ "action": { "command": "heat", "parameters": { "target": { "value": 21, "unit": "celsius" } } } }'

{ "success": true, "data": { "id": "act_20260507100hvac01", "deviceId": "dev_hv4c9d2e", "deviceType": "hvac", "command": "heat", "parameters": { "target": { "value": 21, "unit": "celsius" } }, "state": "acknowledged", "createdAt": "2026-05-07T10:00:00.000Z", "start": null, "links": { "self": "/actions/act_20260507100hvac01" } }, "meta": { "requestId": "req_8a2Bf3kP", "environment": "sandbox", "timestamp": "2026-06-02T12:00:00.000Z", "latencyMs": 12 } }

Authorizations

x-api-key

string

header

required

Path Parameters

deviceId

string

required

The unique identifier for the HVAC device

Example:

"device_abc123"

Body

application/json

The action to perform on the HVAC device

A single HVAC action plus optional onConflict strategy and sandbox controls.

Action variants describe what the API accepts. Per-device support varies; the commands map on GET /hvac/{deviceId} shows which actions a specific device handles.

action

HVAC Action · object

required

A canonical HVAC command. heat/cool hold a target temperature; auto maintains a comfort band between heatSetpoint and coolSetpoint; idle pauses; follow_schedule resumes the device’s native program.

Show child attributes

Examples:

{
  "command": "heat",
  "parameters": {
    "target": { "value": 21, "unit": "celsius" }
  }
}

{
  "command": "auto",
  "parameters": {
    "heatSetpoint": { "value": 20, "unit": "celsius" },
    "coolSetpoint": { "value": 24, "unit": "celsius" }
  }
}

{ "command": "follow_schedule" }

onConflict

enum<string>

cancel_and_replace cancels the active action before running this one; queue_after defers this one until the active action completes. Omit to receive 409 on conflict.

Available options:

cancel_and_replace,

queue_after

sandbox

Hvac Sandbox Config · object

Sandbox controls for testing error paths. Ignored in live environments.

Show child attributes

Response

Action acknowledged and queued for processing

success

boolean

required

Always true for success responses.

data

Hvac Push Response · object

required

Result of a push. Mirrors the dispatch (command + parameters + deviceType) and carries links.self to track the action. For immediate actions, state reflects the dispatch outcome. For deferred actions, state is scheduled, start carries the fire time, and end the window close when a window was requested.

Show child attributes