Skip to main content

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.

​
Overview

To pin an HVAC device to a fixed mode and setpoints, push set_permanent_hold. The device’s own schedule is ignored until you release the hold. Use it for a manual override, a guest in the spare room, a skipped vacation week, or to drive the thermostat from your own logic. The companion action, follow_schedule, hands control back to the device’s own programming. Together they form an open-and-close pair.

​
Step 1: Set the hold

Push set_permanent_hold with mode, heatSetpoint, and coolSetpoint. Setpoints are in degrees Celsius, bounded to 10-35. 
curl -X POST https://api.amps.ai/hvac/dev_hvac_001 \
  -H "x-api-key: sk_live_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set_permanent_hold",
    "mode": "auto",
    "heatSetpoint": 20,
    "coolSetpoint": 24
  }'
Valid mode values are heat, cool, auto, and off. You get back 202 Accepted. 
{
  "actionId": "act_hvac_004",
  "state": "acknowledged",
  "type": "hvac:set_permanent_hold",
  "createdAt": "2026-05-08T10:00:00.000Z"
}

​
Step 2: Confirm the hold applied

Poll the action to watch the lifecycle. 
curl -X GET https://api.amps.ai/actions/act_hvac_004 \
  -H "x-api-key: sk_live_abc123xyz"

{
  "id": "act_hvac_004",
  "deviceId": "dev_hvac_001",
  "type": "hvac:set_permanent_hold",
  "state": "completed",
  "parameters": {
    "mode": "auto",
    "heatSetpoint": 20,
    "coolSetpoint": 24
  },
  "result": { "success": true, "message": "Hold applied" },
  "errorCode": null,
  "errorMessage": null,
  "createdAt": "2026-05-08T10:00:00.000Z",
  "updatedAt": "2026-05-08T10:00:02.000Z",
  "acknowledgedAt": "2026-05-08T10:00:01.000Z",
  "completedAt": "2026-05-08T10:00:02.000Z"
}
The hold persists until you release it or push a different setpoint. follow_schedule is the canonical release.

​
Step 3: Release the hold

When the override is no longer needed, hand control back to the device’s schedule. 
curl -X POST https://api.amps.ai/hvac/dev_hvac_001 \
  -H "x-api-key: sk_live_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "follow_schedule"
  }'

{
  "actionId": "act_hvac_005",
  "state": "acknowledged",
  "type": "hvac:follow_schedule",
  "createdAt": "2026-05-08T11:00:00.000Z"
}
A follow-up read confirms the device is back on its own schedule. 
{
  "id": "act_hvac_005",
  "deviceId": "dev_hvac_001",
  "type": "hvac:follow_schedule",
  "state": "completed",
  "parameters": null,
  "result": { "success": true },
  "errorCode": null,
  "errorMessage": null,
  "createdAt": "2026-05-08T11:00:00.000Z",
  "updatedAt": "2026-05-08T11:00:01.000Z",
  "acknowledgedAt": "2026-05-08T11:00:00.500Z",
  "completedAt": "2026-05-08T11:00:01.000Z"
}

​
Adjusting the hold

Push another set_permanent_hold with new values to raise or lower the setpoints. The new write supersedes the previous hold. No explicit cancel needed. 
curl -X POST https://api.amps.ai/hvac/dev_hvac_001 \
  -H "x-api-key: sk_live_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set_permanent_hold",
    "mode": "heat",
    "heatSetpoint": 22,
    "coolSetpoint": 26
  }'
If a previous hold is still being applied, you get 409 CONFLICT with the in-flight action ID. See the conflict cookbook page for resolution.

​
What next

EV charger power cap

Push pattern for capping max charging power.

Subscribe to webhooks

Get push.completed events on hold transitions.

Handle conflicts

Resolve 409s when an HVAC write is already in flight.

Canonical actions

Where HVAC actions sit in the canonical model.