API examples

TOKEN is optional when GREE_CONTROLLER_APP_TOKEN is empty.

AUTH='Authorization: Bearer TOKEN'
BASE='http://127.0.0.1:8787'

Home Assistant access tokens

Create and revoke integration tokens from the controller Web UI under Settings -> Home Assistant integration access. The clear-text secret is returned only once and the SQLite database stores only its SHA-256 hash.

Administrator endpoints:

GET    /api/access-tokens
POST   /api/access-tokens
DELETE /api/access-tokens/{id}

The Home Assistant custom integration uses a restricted API surface:

GET    /api/integrations/home-assistant/devices
POST   /api/integrations/home-assistant/devices/{id}/command

These two endpoints always require Authorization: Bearer <generated-token> (or the administrator GREE_CONTROLLER_APP_TOKEN). A generated HA token cannot update settings, run discovery, delete devices, manage tokens, or use the controller WebSocket.

Discovery

curl -X POST "$BASE/api/discovery" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"timeout_ms":3000,"broadcast":"255.255.255.255:7000"}'

Device command

{
  "power": true,
  "mode": "cool",
  "target_temperature": 22.0,
  "fan_speed": 3,
  "swing_vertical": true,
  "quiet": false,
  "turbo": false,
  "light": true
}

Supported modes: auto, cool, dry, fan, heat. Fan speed: 0..5.

Zone

{
  "name": "Living room",
  "device_id": "gree-aabbccddeeff",
  "enabled": true,
  "mode": "cool",
  "setpoint": 23.0,
  "hysteresis": 0.6,
  "min_on_seconds": 180,
  "min_off_seconds": 180,
  "sensor_source": "combined",
  "ha_entity_id": "sensor.living_room_temperature",
  "external_sensor_weight": 0.4,
  "max_sensor_difference": 3.0
}

sensor_source supports:

device — GREE indoor sensor only,
combined — GREE + this zone's HA room sensor,
home_assistant — this zone's HA room sensor, with GREE fallback.

For combined and home_assistant, set a per-zone ha_entity_id. external_sensor_weight is 0.0..1.0. If a combined sensor pair differs by more than max_sensor_difference, the controller falls back to GREE. The returned zone object includes device_temperature, external_temperature, current_temperature, and control_temperature_source.

Schedule

Weekdays use ISO numbers: Monday 1, Sunday 7.

{
  "zone_id": "UUID",
  "name": "Night",
  "enabled": true,
  "weekdays": [1,2,3,4,5,6,7],
  "start_time": "22:00",
  "end_time": "06:00",
  "setpoint": 24.0
}

WebSocket

Connect to ws://HOST:8787/ws?token=TOKEN. The first message uses event type bootstrap; later events include device.updated, zone.updated, settings.updated and log.created.

Localization assets

Localization endpoints are public because the login dialog also needs translations. Language packs are embedded in the Rust binary at build time.

curl "$BASE/lang/index.json"
curl "$BASE/lang/en.json"

GET /lang/index.json returns the automatically generated language catalog. GET /lang/<code>.json returns the corresponding language pack. Add a valid lang/<code>.json file and rebuild to expose a new language.

3.1 KiB Raw Blame History