POST /command

Overview

The /command endpoint lets you control thermostat settings programmatically from the Control API (port 8082).

Endpoint

POST http://your-server:8082/command

This endpoint has no authentication by default. Secure it with a reverse proxy if exposing publicly.

Request

Headers

POST /command HTTP/1.1
Host: your-server:8082
Content-Type: application/json

Body

{
  "serial": "02AB01AC012345678",
  "command": "set_temperature",
  "value": 21.5
}

Parameters

Parameter	Type	Required	Description
`serial`	string	Yes	Device serial number
`command`	string	Yes	Command name (see below)
`value`	varies	Yes	Command value (type depends on command)

Supported Commands

`set_temperature`

Set the target temperature. Routes to the shared bucket.

Value type	Description	Example
`number`	Single temperature in °C	`21.5`
`{"high": number, "low": number}`	Range mode (heat-cool)	`{"high": 24, "low": 18}`

{"serial": "02AB01AC012345678", "command": "set_temperature", "value": 21.5}

{"serial": "02AB01AC012345678", "command": "set_temperature", "value": {"high": 24, "low": 18}}

Temperatures are always in Celsius (4.5–32°C). The thermostat displays them in the user’s preferred scale. Temperature changes also set target_change_pending: true to wake the display.

`set_mode`

Set the HVAC mode. Routes to the shared bucket.

Value	Description
`"off"`	System off
`"heat"`	Heating only
`"cool"`	Cooling only
`"heat-cool"`	Auto (maintains temperature range)
`"emergency"`	Emergency heat (requires `has_emer_heat`)

{"serial": "02AB01AC012345678", "command": "set_mode", "value": "heat"}

The server checks device capabilities before applying the mode. Requesting heat on a cooling-only device returns a 400 error."eco" is not a valid mode here — use set_away instead to engage eco mode.

`set_away`

Enable or disable eco (away) mode via manual_eco_all in the structure bucket.

Value	Description
`true`	Enable eco/away mode
`false`	Return to normal operation

{"serial": "02AB01AC012345678", "command": "set_away", "value": true}

This uses manual_eco_all rather than the away field, because the firmware’s schedule preconditioning can revert away-triggered eco but respects manual eco. A manual_eco_timestamp is automatically set to the current time.

`set_fan`

Control the fan. Routes to the device bucket. Requires has_fan: true.

Value	Description
`"on"`	Run fan using stored duration preference (default 60 min)
`"auto"`	Turn off fan timer (auto mode)
`number`	Run fan for this many seconds

{"serial": "02AB01AC012345678", "command": "set_fan", "value": "on"}

{"serial": "02AB01AC012345678", "command": "set_fan", "value": 1800}

`set_eco_temperatures`

Set the eco mode (away) temperature bounds. Routes to the device bucket.

{
  "serial": "02AB01AC012345678",
  "command": "set_eco_temperatures",
  "value": {"high": 26.0, "low": 15.5}
}

Field	Description
`high`	Upper eco temperature in °C
`low`	Lower eco temperature in °C

`set_schedule`

Replace the full weekly schedule. Routes to the schedule bucket (full replacement, not merge).

{
  "serial": "02AB01AC012345678",
  "command": "set_schedule",
  "value": {
    "ver": 2,
    "schedule_mode": "HEAT",
    "days": {
      "0": [{"type": "HEAT", "time": 25200, "temp": 20.0}],
      "1": [{"type": "HEAT", "time": 25200, "temp": 20.0}]
    }
  }
}

Schedule format requirements:

ver must be 2
schedule_mode: "HEAT", "COOL", or "RANGE"
Day keys: "0" (Monday) through "6" (Sunday)
time: seconds from midnight (0–86399)
type: "HEAT", "COOL", or "RANGE"
RANGE type requires "temp-min" and "temp-max" instead of "temp"

`set_schedule_mode`

Change the active schedule mode without replacing the schedule. Routes to the shared bucket.

Value	Description
`"HEAT"`	Heat schedule
`"COOL"`	Cool schedule
`"RANGE"`	Heat-cool range schedule

{"serial": "02AB01AC012345678", "command": "set_schedule_mode", "value": "HEAT"}

`set_device_setting`

Set one or more cloud-writable device bucket fields. Routes to the device bucket. Only fields from the whitelist are accepted.

{
  "serial": "02AB01AC012345678",
  "command": "set_device_setting",
  "value": {
    "temperature_scale": "F",
    "learning_mode": true
  }
}

Whitelisted device fields

Category	Fields
Safety	`lower_safety_temp_enabled`, `upper_safety_temp_enabled`, `lower_safety_temp`, `upper_safety_temp`
Temperature lock	`temp_lock_on`, `temp_lock_pin_hash`, `temp_lock_high_temp`, `temp_lock_low_temp`
Learning	`learning_mode`, `preconditioning_enabled`, `preconditioning_active`
Humidity	`target_humidity_enabled`, `target_humidity`
Display	`temperature_scale`, `time_to_target`, `time_to_target_training_status`
Sunblock	`sunlight_correction_enabled`
Fan	`fan_timer_duration_minutes`, `fan_duty_cycle`, `fan_duty_start_time`, `fan_duty_end_time`, `fan_schedule_speed`
Heat pump	`heat_pump_aux_threshold_enabled`, `heat_pump_aux_threshold`, `heat_pump_comp_threshold_enabled`, `heat_pump_comp_threshold`
Wiring	`equipment_type`, `heat_source`
Hot water	`hot_water_boost_time_to_end`, `hot_water_active`
Filter	`filter_reminder_enabled`, `filter_reminder_level`
Locale	`postal_code`, `country_code`

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "object_key": "shared.02AB01AC012345678",
    "values": {
      "target_temperature": 21.5,
      "target_change_pending": true
    }
  }
}

Error (400 Bad Request)

{
  "success": false,
  "message": "Unknown command: set_foo"
}

{
  "success": false,
  "message": "Device does not support heating (can_heat=false)"
}

Error (500 Internal Server Error)

{
  "success": false,
  "message": "..."
}

Examples

curl -X POST http://your-server:8082/command \
  -H "Content-Type: application/json" \
  -d '{"serial": "02AB01AC012345678", "command": "set_temperature", "value": 21.5}'

Overview

Self-Hosted Control API

Device Protocol API

Hosted Service API

Overview

Endpoint

Request

Headers

Body

Parameters

Supported Commands

`set_temperature`

`set_mode`

`set_away`

`set_fan`

`set_eco_temperatures`

`set_schedule`

`set_schedule_mode`

`set_device_setting`

Response

Success (200 OK)

Error (400 Bad Request)

Error (500 Internal Server Error)

Examples

Next Steps

GET /status

GET /api/devices

Overview

Self-Hosted Control API

Device Protocol API

Hosted Service API

Documentation Index

​Overview

​Endpoint

​Request

​Headers

​Body

​Parameters

​Supported Commands

​set_temperature

​set_mode

​set_away

​set_fan

​set_eco_temperatures

​set_schedule

​set_schedule_mode

​set_device_setting

​Response

​Success (200 OK)

​Error (400 Bad Request)

​Error (500 Internal Server Error)

​Examples

​Next Steps

GET /status

GET /api/devices

Overview

Endpoint

Request

Headers

Body

Parameters

Supported Commands

`set_temperature`

`set_mode`

`set_away`

`set_fan`

`set_eco_temperatures`

`set_schedule`

`set_schedule_mode`

`set_device_setting`

Response

Success (200 OK)

Error (400 Bad Request)

Error (500 Internal Server Error)

Examples

Next Steps