Heat for a window - Amps AI Documentation

Add start and end to a heat or cool command to hold a temperature for a fixed window, such as warming the house before people get home. This is a one-off window, not a recurring schedule.

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",
    "commands": {
      "heat": {
        "parameters": { "target": { "unit": "celsius", "min": 10, "max": 35 } },
        "execution": ["immediate", "scheduled", "windowed"]
      },
      "auto.maintain": {
        "parameters": {
          "heatSetpoint": { "unit": "celsius", "min": 10, "max": 35 },
          "coolSetpoint": { "unit": "celsius", "min": 10, "max": 35 }
        },
        "execution": ["immediate", "scheduled"]
      }
    }
  }
}

Only commands with windowed in execution accept an end. Here that’s heat, not auto.maintain.

2. Send the command

Heat to 21 °C from 17:00 to 22:00, plant-local time:

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" } },
      "start": "2026-06-01T17:00:00",
      "end": "2026-06-01T22:00:00"
    }
  }'

{
  "success": true,
  "data": {
    "id": "action_watbxVmQ8q",
    "command": "heat",
    "state": "scheduled",
    "start": "2026-06-01T16:00:00.000Z",
    "end": "2026-06-01T21:00:00.000Z"
  }
}

You write plant-local wall-clock time and read back UTC. See Scheduling for the time format, limits, and what happens at end.

3. Confirm

The action moves from scheduled to completed once it runs. Track it on GET /actions/action_watbxVmQ8q or with webhooks. To call it off before start, cancel it.

Next steps

Hold a temperature

Override the schedule with no end time.

Scheduling

Deferred and windowed commands in detail.