Hold a temperature - Amps AI Documentation

Push heat or cool with a target to hold that temperature until you say otherwise. Push auto.schedule to release the hold.

1. Check the device supports it

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

{
  "success": true,
  "data": {
    "id": "device_abc123",
    "state": { "temperature": 18.5, "mode": "heat", "heatSetpoint": 19, "holdType": "schedule" },
    "commands": {
      "heat": {
        "parameters": { "target": { "unit": "celsius", "min": 10, "max": 35 } },
        "execution": ["immediate", "scheduled", "windowed"]
      },
      "auto.schedule": { "parameters": {}, "execution": ["immediate"] }
    },
    "conflictStrategies": ["cancel_and_replace"]
  }
}

2. Send the command

curl -X POST https://api.amps.ai/hvac/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "command": "heat",
      "parameters": { "target": { "value": 21, "unit": "celsius" } }
    }
  }'

{
  "success": true,
  "data": {
    "id": "action_MXfJmEfsEp",
    "command": "heat",
    "parameters": { "target": { "value": 21, "unit": "celsius" } },
    "state": "acknowledged"
  }
}

To hold a band instead, push auto.maintain with heatSetpoint and coolSetpoint. A new command replaces the hold; if the previous one is still in flight you’ll get a 409 (see Conflicts).

3. Confirm

When the action is completed, the device reads holdType: "permanent" and heatSetpoint: 21. See Push for the lifecycle.

Release the hold

curl -X POST https://api.amps.ai/hvac/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": { "command": "auto.schedule" } }'

The device reads holdType: "schedule" again. auto.schedule is immediate only: sending start or end with it returns 422 DEVICE_NOT_CAPABLE.

Next steps

Heat for a window

Hold a temperature between a start and end time.

Webhooks

Get notified when the hold is applied.