> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nolongerevil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /command

> Send a control command to a thermostat

## Overview

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

## Endpoint

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

<Warning>
  This endpoint has **no authentication** by default. Secure it with a reverse proxy if exposing publicly.
</Warning>

## Request

### Headers

```http theme={null}
POST /command HTTP/1.1
Host: your-server:8082
Content-Type: application/json
```

### Body

```json theme={null}
{
  "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}` |

```json theme={null}
{"serial": "02AB01AC012345678", "command": "set_temperature", "value": 21.5}
```

```json theme={null}
{"serial": "02AB01AC012345678", "command": "set_temperature", "value": {"high": 24, "low": 18}}
```

<Note>
  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.
</Note>

***

### `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`) |

```json theme={null}
{"serial": "02AB01AC012345678", "command": "set_mode", "value": "heat"}
```

<Note>
  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.
</Note>

***

### `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 |

```json theme={null}
{"serial": "02AB01AC012345678", "command": "set_away", "value": true}
```

<Note>
  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.
</Note>

***

### `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                             |

```json theme={null}
{"serial": "02AB01AC012345678", "command": "set_fan", "value": "on"}
```

```json theme={null}
{"serial": "02AB01AC012345678", "command": "set_fan", "value": 1800}
```

***

### `set_eco_temperatures`

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

```json theme={null}
{
  "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).

```json theme={null}
{
  "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 |

```json theme={null}
{"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.

```json theme={null}
{
  "serial": "02AB01AC012345678",
  "command": "set_device_setting",
  "value": {
    "temperature_scale": "F",
    "learning_mode": true
  }
}
```

<Accordion title="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`                                                                                                |
</Accordion>

***

## Response

### Success (200 OK)

```json theme={null}
{
  "success": true,
  "data": {
    "object_key": "shared.02AB01AC012345678",
    "values": {
      "target_temperature": 21.5,
      "target_change_pending": true
    }
  }
}
```

### Error (400 Bad Request)

```json theme={null}
{
  "success": false,
  "message": "Unknown command: set_foo"
}
```

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

### Error (500 Internal Server Error)

```json theme={null}
{
  "success": false,
  "message": "..."
}
```

***

## Examples

<CodeGroup>
  ```bash Set Temperature theme={null}
  curl -X POST http://your-server:8082/command \
    -H "Content-Type: application/json" \
    -d '{"serial": "02AB01AC012345678", "command": "set_temperature", "value": 21.5}'
  ```

  ```bash Set Mode to Heat theme={null}
  curl -X POST http://your-server:8082/command \
    -H "Content-Type: application/json" \
    -d '{"serial": "02AB01AC012345678", "command": "set_mode", "value": "heat"}'
  ```

  ```bash Enable Eco Mode theme={null}
  curl -X POST http://your-server:8082/command \
    -H "Content-Type: application/json" \
    -d '{"serial": "02AB01AC012345678", "command": "set_away", "value": true}'
  ```

  ```python Python theme={null}
  import requests

  def send_command(serial, command, value):
      resp = requests.post('http://your-server:8082/command', json={
          'serial': serial,
          'command': command,
          'value': value
      })
      return resp.json()

  # Set temperature to 21°C
  send_command('02AB01AC012345678', 'set_temperature', 21.0)

  # Switch to cool mode
  send_command('02AB01AC012345678', 'set_mode', 'cool')
  ```
</CodeGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="GET /status" href="/api-reference/control/status">
    Query current device state
  </Card>

  <Card title="GET /api/devices" href="/api-reference/control/devices">
    List all connected devices
  </Card>
</CardGroup>