gru/gree-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7fd5921ba9b2430ebe6277819ad25e0bd278e309
gree-controller/docs/API.md
T
Mateusz Gruszczyński 7fd5921ba9 v0.12.1
2026-09-04 08:59:11 +02:00

49 KiB
Raw Blame History

GREE Controller API reference

HTTP and WebSocket API for GREE Controller 0.12.1.

← Main documentation

Base URL and content type

Default local address:

http://127.0.0.1:8787

JSON requests use:

Content-Type: application/json

If GREE_CONTROLLER_BASE_PATH=/gree is configured, every HTTP and WebSocket path below is prefixed with /gree.

Interactive and machine-readable API documentation is served by the application itself:

GET /api-docs                 Swagger UI
GET /api-docs/openapi.json    OpenAPI 3.1 document

The OpenAPI document contains endpoint descriptions, authentication schemes, parameters, request/response models, examples and common error responses. Its servers entry follows the configured GREE_CONTROLLER_BASE_PATH, so requests sent from Swagger UI target the current controller instance correctly.

Authentication

There are three access levels.

Public

No token is required for:

GET /api/health
GET /api-docs
GET /api-docs/openapi.json
GET /
GET /index.html
GET /app.js
GET /theme-init.js
GET /styles.css
GET /manifest.webmanifest
GET /sw.js
GET /favicon.svg
GET /lang/index.json
GET /lang/{file}

Administrator API

All normal /api/* routes are administrator routes. If GREE_CONTROLLER_APP_TOKEN is empty, the controller intentionally operates in trusted-LAN mode and these routes do not require authentication.

When an app token is configured, send either:

Authorization: Bearer APP_TOKEN

or:

x-api-token: APP_TOKEN

Example:

BASE='http://127.0.0.1:8787'
TOKEN='replace-me'
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/bootstrap"

Restricted Home Assistant API

Generated Home Assistant access tokens always authenticate only the restricted integration surface under /api/integrations/home-assistant/*. The administrator app token is also accepted there.

Generated token secrets are returned only at creation time. SQLite stores their SHA-256 hash and a display prefix.

Errors and HTTP status codes

API errors are JSON:

{
  "error": "message"
}

Common statuses:

Status Meaning
200 OK Successful read/update/action.
201 Created Resource created.
204 No Content Successful delete/revoke.
400 Bad Request Validation error or unsafe/invalid operation.
401 Unauthorized Missing/incorrect token.
404 Not Found Resource ID does not exist.
409 Conflict Revision/concurrency conflict.
502 Bad Gateway GREE/HA/integration communication failure.
500 Internal Server Error Unexpected server/storage error.

Endpoint index

Public and system

Method Endpoint Description
GET /api/health Lightweight process/control-engine health.
GET /api/bootstrap Complete initial application snapshot.
GET /api/system/info Runtime/system diagnostic information.
GET /ws Live WebSocket event stream.

Devices and discovery

Method Endpoint Description
POST /api/discovery Discover/bind GREE devices.
GET /api/devices List devices.
POST /api/devices Add a device manually.
GET /api/devices/{id} Read a device.
PATCH /api/devices/{id} Edit technical device configuration.
DELETE /api/devices/{id} Delete a device after safety checks.
POST /api/devices/{id}/bind Bind/re-bind a physical unit.
POST /api/devices/{id}/probe Minimal non-mutating GREE round-trip diagnostic.
POST /api/devices/{id}/poll Poll one unit immediately.
POST /api/devices/{id}/command Send a direct/manual device command.

Thermostat zones, groups and house

Method Endpoint Description
GET /api/zones List zones.
POST /api/zones Create a zone.
GET /api/zones/{id} Read a zone.
PUT /api/zones/{id} Replace editable zone configuration.
DELETE /api/zones/{id} Delete zone after safe device shutdown.
POST /api/zones/{id}/control Quick/thermostat control of a zone.
POST /api/zones/{id}/schedule-template Replace zone schedules with a built-in template.
GET /api/groups List climate groups.
POST /api/groups Create a climate group.
GET /api/groups/{id} Read a group.
PUT /api/groups/{id} Replace group definition.
DELETE /api/groups/{id} Delete a group.
POST /api/groups/{id}/control Group control enable/mode/preset/custom-temperature control.
POST /api/house/control Set global thermostat mode.
POST /api/house/power Bulk ON/OFF for all thermostats and enabled units; no persistent global gate.
POST /api/house/preset Set/clear whole-house preset override.

Schedules and automations

Method Endpoint Description
GET /api/schedules List schedules.
POST /api/schedules Create schedule.
GET /api/schedules/{id} Read schedule.
PUT /api/schedules/{id} Replace schedule.
DELETE /api/schedules/{id} Delete schedule.
GET /api/automations List automations.
POST /api/automations Create automation.
GET /api/automations/{id} Read automation.
PUT /api/automations/{id} Replace automation.
DELETE /api/automations/{id} Delete automation.

History, control plan and events

Method Endpoint Description
GET /api/readings Legacy/device reading history.
GET /api/history Rich device/zone/HA history.
GET /api/control-plan Current resolved thermostat plan.
GET /api/events Event/debug log.

Settings, configuration and diagnostics

Method Endpoint Description
GET/PUT /api/settings/application Application runtime switches.
GET/PUT /api/settings/gree GREE controller, polling, discovery and compressor settings.
GET/PUT /api/settings/history Metric/event retention and compaction settings.
GET/PUT /api/settings/influxdb InfluxDB history settings.
GET/PUT /api/settings/notifications Notification provider and alert settings.
GET/PUT /api/settings/night Night mode settings.
GET/PUT /api/settings/home-assistant Home Assistant, aliases, shared Flow inputs and outdoor assist.
GET/PUT /api/settings/debug Debug overlay/GREE frame settings.
GET /api/configuration/export Export full application configuration.
POST /api/configuration/import Import/replace application configuration.
POST /api/integrations/home-assistant/test Test HA temperature read.
POST /api/integrations/home-assistant/entity Read raw HA entity state/attributes for shared Flow input diagnostics.
POST /api/integrations/notifications/test Send a test notification.

Access tokens and restricted Home Assistant API

Method Endpoint Description
GET /api/access-tokens List generated HA tokens without secrets.
POST /api/access-tokens Create restricted HA token.
DELETE /api/access-tokens/{id} Revoke token.
GET /api/integrations/home-assistant/devices Restricted device list.
POST /api/integrations/home-assistant/devices/{id}/command Restricted direct device command.
GET /api/integrations/home-assistant/control-plan Restricted control plan.
GET /api/integrations/home-assistant/groups HA-oriented group state.
POST /api/integrations/home-assistant/groups/{id}/control Restricted group control.
POST /api/integrations/home-assistant/house/control Restricted house mode.
POST /api/integrations/home-assistant/house/preset Restricted house preset.
POST /api/integrations/home-assistant/house/power Restricted bulk all-thermostat/all-unit power action.
POST /api/integrations/home-assistant/zones/{id}/control Restricted thermostat-zone control.

System endpoints

GET /api/health

Public lightweight health check.

Response:

{
  "status": "ok",
  "name": "gree-controller",
  "version": "0.12.1",
  "uptime_seconds": 1234,
  "control_ready": true,
  "time": "2026-08-30T06:54:00Z"
}

control_ready=false means the process is running but the thermostat engine has not yet completed its initial physical device synchronization.

GET /api/bootstrap

Returns the initial Web UI snapshot:

{
  "devices": [],
  "zones": [],
  "groups": [],
  "schedules": [],
  "automations": [],
  "access_tokens": [],
  "house": {"mode": "cool"},
  "outdoor_temperature": null,
  "system": {
    "version": "0.12.1",
    "uptime_seconds": 1234,
    "auth_required": false,
    "control_ready": true,
    "database": "./data/gree-controller.db",
    "device_count": 2,
    "online_count": 2,
    "simulator_count": 0,
    "bind": "0.0.0.0:8787",
    "base_path": "/",
    "gree_interface": "auto",
    "gree_received_frames": 809,
    "gree_received_frames_by_device": {}
  }
}

GET /api/system/info

Returns the system diagnostic object independently of the full bootstrap. Useful for monitoring and Settings → System status.

Device API

Device object

A device response contains:

Field Type Description
id string Stable controller ID.
mac string Normalized GREE MAC/CID identity.
name string User-visible name.
ip string Device IPv4 address.
port integer Usually 7000.
protocol_version integer 0 unknown/auto, 1 legacy AES-ECB, 2 AES-GCM.
model, firmware string Discovered metadata when available.
key string/null GREE binding key. Treat as secret.
cid string/null GREE client/device identifier.
enabled boolean Technical device enable state.
simulated boolean Simulated vs physical.
power boolean Last known power.
mode string auto, cool, dry, fan, heat.
target_temperature number Last known unit setpoint.
fan_speed integer 0..5; 0 is Auto.
swing_vertical, swing_horizontal boolean Swing state.
quiet, turbo, light, air, xfan, health, sleep boolean Optional GREE features.
supports_* boolean/null Capability learned from device status.
current_temperature number/null GREE indoor temperature.
outdoor_temperature number/null GREE outdoor temperature if available.
temperature_sensor_offset boolean/null Whether +40 °C wire offset behavior was detected.
online boolean Current communication state.
response_time_ms integer/null Latest successful controller round-trip.
last_seen ISO-8601/null Last successful communication.
last_error string/null Latest communication error.
communication_failures integer Consecutive/recorded communication failure counter.
created_at, updated_at ISO-8601 Resource timestamps.

POST /api/discovery

Request body, all fields optional:

{
  "timeout_ms": 6000,
  "broadcast": "255.255.255.255:7000",
  "protocol_version": 0,
  "passes": 3
}

Rules:

  • timeout_ms: effective range 500..30000 ms.
  • protocol_version: 0 auto/both, 1 AES-ECB only, 2 AES-GCM only.
  • passes: 1..10.
  • Missing values use runtime GREE settings.

Successful discovery merges known devices, tries binding devices that do not have a key, persists results and returns:

{
  "count": 1,
  "devices": [],
  "new_device_ids": ["gree-aabbccddeeff"]
}

GET /api/devices

Returns Device[].

POST /api/devices

Manual add request:

{
  "name": "Living room",
  "mac": "AABBCCDDEEFF",
  "ip": "192.168.50.30",
  "port": 7000,
  "protocol_version": 1,
  "key": null,
  "simulated": false
}

Defaults: port=7000, protocol_version=1, simulated=false. MAC values are normalized. Duplicate MACs are rejected.

Returns 201 Created with Device.

GET /api/devices/{id}

Returns one Device or 404.

PATCH /api/devices/{id}

All fields optional:

{
  "name": "Bedroom",
  "ip": "192.168.50.31",
  "port": 7000,
  "protocol_version": 2,
  "key": "optional-binding-key",
  "enabled": true
}

key:null clears the key. Changing protocol version clears the existing key/capability cache so the unit can be re-bound cleanly. Disabling a device goes through the controller's safe disable path.

DELETE /api/devices/{id}

Returns 204. Deletion is rejected if the device is referenced by an automation or cannot be safely detached from thermostat ownership. Associated zones/groups are cleaned only after the safety checks pass.

POST /api/devices/{id}/bind

Performs/repeats GREE binding and returns updated Device. Simulated devices return unchanged.

POST /api/devices/{id}/probe

Performs a minimal, non-mutating GREE status round-trip and returns response_time_ms. It does not update device online/error counters, readings, capabilities, thermostat ownership, or persisted device state. A real device must already be bound.

{
  "device_id": "gree-aabbccddeeff",
  "response_time_ms": 18,
  "ok": true
}

POST /api/devices/{id}/poll

Immediately polls one unit and returns updated Device.

POST /api/devices/{id}/command

Direct/manual device control. This is deliberately different from thermostat-zone control.

All fields optional; at least one meaningful field should be sent:

{
  "power": true,
  "mode": "cool",
  "target_temperature": 22,
  "fan_speed": 3,
  "swing_vertical": true,
  "swing_horizontal": false,
  "quiet": false,
  "turbo": false,
  "light": true,
  "air": false,
  "xfan": false,
  "health": false,
  "sleep": false
}

Rules:

  • modes: auto, cool, dry, fan, heat,
  • target temperature is normalized to the supported GREE Celsius range 8..30,
  • fan speed is 0..5,
  • optional feature commands should be used only when the corresponding supports_* capability is true.

The backend sends only properties that differ from the last known device state. Climate-relevant direct commands can create/continue a manual-device takeover for an enabled thermostat zone so automation does not immediately fight the user.

When the physical device belongs to a disabled thermostat zone, direct web/API control requires "manual_override": true. The web UI asks for explicit confirmation before sending that flag. Home Assistant direct-device control remains blocked for disabled zones.

Zones

Zone configuration

POST /api/zones and PUT /api/zones/{id} use this editable shape:

{
  "name": "Living room",
  "device_id": "gree-aabbccddeeff",
  "enabled": true,
  "mode": "cool",
  "inherit_house_mode": true,
  "setpoint": 23.0,
  "cool_comfort_setpoint": 23.0,
  "cool_sleep_setpoint": 24.5,
  "cool_away_setpoint": 27.0,
  "heat_comfort_setpoint": 21.0,
  "heat_sleep_setpoint": 19.0,
  "heat_away_setpoint": 17.0,
  "hysteresis": 0.6,
  "separate_hysteresis": false,
  "cool_hysteresis": 0.6,
  "heat_hysteresis": 0.6,
  "min_on_seconds": 180,
  "min_off_seconds": 180,
  "min_adjust_seconds": 120,
  "standby_offset_c": 2.0,
  "smart_fan": true,
  "sensor_source": "combined",
  "ha_entity_id": "sensor.living_room_temperature",
  "external_sensor_weight": 0.4,
  "max_sensor_difference": 3.0,
  "sensor_stale_after_seconds": 300,
  "revision": 12
}

Important rules:

  • name is required.
  • device_id must reference an existing device and thermostat ownership must remain valid/safe.
  • mode: cool or heat when not inheriting house mode.
  • temperature/profile values are constrained to the supported thermostat range.
  • hysteresis: shared controller hysteresis, valid range 0.1..5.0 °C.
  • separate_hysteresis: when true, cooling uses cool_hysteresis and heating uses heat_hysteresis; both use the same 0.1..5.0 °C range.
  • standby_offset_c: bounded thermostat offset.
  • sensor_source: device, home_assistant or combined.
  • external_sensor_weight: 0..1.
  • revision is used for optimistic concurrency where supplied; stale updates can return 409.

The returned Zone also contains runtime state including sensor readings, resolved/effective setpoints, demand, current preset, manual overrides, local Quick Thermostat ownership, temporary session state, device-manual takeover, control owner/source/reason, lockout timestamps and created_at/updated_at.

GET /api/zones

Returns Zone[].

POST /api/zones

Creates a zone and returns 201 Created with Zone.

GET /api/zones/{id}

Returns one Zone.

PUT /api/zones/{id}

Replaces editable zone configuration while preserving/reconciling runtime safety state. Returns updated Zone.

DELETE /api/zones/{id}

Safely powers the owned device off before detaching thermostat ownership. Returns 204.

POST /api/zones/{id}/control

Manual setpoint values are retained with 0.1 °C precision. The physical GREE unit setpoint is still rounded to the whole-degree resolution supported by the protocol.

Quick thermostat endpoint. Body fields are optional and can be combined:

{
  "setpoint": 22.5,
  "power": true,
  "mode": "house",
  "enabled": true,
  "preset": "comfort",
  "clear_override": false,
  "clear_device_manual_override": false,
  "clear_local_thermostat_override": false,
  "temporary_quick_thermostat": null,
  "clear_temporary_quick_thermostat": false
}

Semantics:

  • setpoint: creates a quick custom thermostat target.
  • preset: auto, comfort, sleep, away, custom; auto clears the profile override.
  • mode: house, cool, heat; house restores global mode inheritance.
  • enabled: zone automation enable state.
  • power:true: local Quick Thermostat ownership — this zone can run through full thermostat logic regardless of whether group-level control is enabled for its climate group.
  • power:false: turns this zone off and creates a fresh backend-owned local hand-back timer (currently 15 minutes).
  • clear_local_thermostat_override:true: immediately return local Quick Thermostat ownership to normal automation. If there is no active schedule, manual preset/setpoint, Temporary Quick Thermostat or other explicit thermostat intent, the zone remains physically OFF instead of falling back to implicit Comfort.
  • clear_device_manual_override:true: explicitly hand a physical/direct manual takeover back to the thermostat.
  • clear_override:true: clear ordinary quick preset/setpoint override.
  • temporary_quick_thermostat: start/replace a persisted temporary session.
  • clear_temporary_quick_thermostat:true: cancel that temporary session only.

Returns updated Zone.

Temporary Quick Thermostat request

{
  "start_kind": "now",
  "start_delay_minutes": null,
  "start_at": null,
  "finish_kind": "duration",
  "duration_minutes": 90,
  "until": null,
  "target_temperature": 23.0,
  "temperature_operator": "within",
  "tolerance_c": 0.3,
  "hold_minutes": 60,
  "max_duration_minutes": 240
}

start_kind:

  • now
  • delay + start_delay_minutes
  • at + ISO-8601 start_at

finish_kind:

  • duration + duration_minutes
  • until + ISO-8601 until
  • temperature_reached
  • temperature_stable + hold_minutes
  • schedule_boundary

Temperature operators:

  • within
  • at_or_below
  • at_or_above

max_duration_minutes is an optional fail-safe for temperature-based sessions. Delayed sessions do not own the zone until their effective start. Runtime session state is persisted and exposed inside the returned zone.

Examples:

# Preset until next schedule boundary
curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"preset":"sleep"}'

# Return to schedule
curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"preset":"auto"}'

# Run a 90-minute temporary thermostat
curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"temporary_quick_thermostat":{"start_kind":"now","finish_kind":"duration","duration_minutes":90,"target_temperature":23}}'

POST /api/zones/{id}/schedule-template

Body:

{
  "template": "family"
}

Built-in templates:

Template Result
family Comfort 06:30–22:30, Sleep overnight.
child Comfort 06:30–20:30, Sleep overnight.
bedroom Comfort 06:30–22:00, Sleep overnight.
workday Weekday morning/away/evening/sleep plus weekend blocks.
always 24-hour Comfort.

Existing schedules for the zone are replaced after overlap validation. Response:

{
  "zone": {},
  "schedules": []
}

Groups

Group object

{
  "id": "uuid",
  "name": "Bedrooms",
  "zone_ids": ["zone-1", "zone-2"],
  "power_enabled": true,
  "created_at": "...",
  "updated_at": "..."
}

GET /api/groups

Returns groups.

POST /api/groups

{
  "name": "Bedrooms",
  "zone_ids": ["zone-1", "zone-2"],
  "power_enabled": true
}

A group must contain at least one existing zone. Returns 201 Created.

GET /api/groups/{id} / PUT /api/groups/{id} / DELETE /api/groups/{id}

Read, replace or delete a group. DELETE returns 204.

POST /api/groups/{id}/control

{
  "power": true,
  "mode": "house",
  "preset": "custom",
  "setpoint": 22.3
}

All fields optional:

  • power: enable/disable group-level control (legacy field name; this is not a device power gate),
  • mode: house, cool, heat,
  • preset: auto, comfort, sleep, away, custom,
  • setpoint: custom group target in the 8–30°C range; requires preset: "custom".

A custom setpoint creates the same override for every member zone. For explicit Web/Home Assistant group control it stays active until the group is changed/released; scheduled group automation remains bounded by the normal schedule hand-back. Returns a group control/result object including updated members/state.

Group power is a scoped bulk-power/control action. power=false immediately powers member units off and releases group:* ownership; members are stored as individually-off thermostats rather than being blocked by membership in an OFF group. This group-created OFF is indefinite (no 15-minute local hand-back), so the regulator cannot restart the unit by itself; a user can still turn an individual thermostat back on independently. power=true clears that scoped thermostat-OFF state and immediately re-runs group thermostat arbitration. Explicit Web/Home Assistant group control has higher priority than house rules and schedules; scheduled group automations still respect higher-priority manual/local ownership. Group mode/preset/setpoint changes are accepted only while the group is ON. Global ON/OFF never creates a persistent global gate. Global OFF does leave member thermostats locally OFF until they are explicitly re-enabled by local/group/global ON.

Whole-house control

House thermostat rules and global power actions are intentionally separate. Global ON/OFF does not create a master automation gate; OFF is persisted as per-zone local OFF so ordinary demand cannot immediately undo it.

POST /api/house/control

{
  "mode": "cool"
}

Valid modes: cool, heat, off.

  • cool/heat select the house rule used by zones that inherit the global mode and immediately re-run arbitration for free zones. Explicit local/group/direct ownership is preserved.
  • off means do not perform house-level thermostat control for inherited free zones. It does not block local thermostats, groups, device-manual control or controller automations.

Returns { "mode": "cool|heat|off" }.

POST /api/house/power

{
  "power": false
}

This endpoint is a bulk thermostat power action without a persistent blocking global gate. false first stores every thermostat as an indefinite local OFF and then sends immediate OFF to every technically enabled unit, so the next normal demand cycle cannot turn the house back on. A later per-zone Resume automation clears that local OFF but does not invent a Comfort demand: without an active schedule/override/temporary or another explicit intent the zone stays OFF. true is itself an explicit whole-house ON intent, releases local OFF markers for all thermostats and sends ON to all technically enabled units. Group enablement, profiles, schedules and house mode are preserved. Pending compressor-protection tasks from before the action are cleared. When compressor protection is enabled, protected global starts are queued until their safe deadline; OFF is never delayed.

Response includes:

{
  "power": false,
  "one_shot": true,
  "devices": [],
  "groups": [],
  "failed": []
}

POST /api/house/preset

{
  "preset": "sleep"
}

Valid: auto, comfort, sleep, away.

A non-auto preset creates overrides for free house-controlled zones and normally expires at each zone's next schedule boundary. auto clears those free-zone overrides. Explicit local thermostat, group, temporary thermostat and direct/manual ownership is not overwritten by a house profile action.

Response contains preset, the updated zones, current devices, and a failed array for immediate-control errors. It does not embed settings; settings are available only from the functional /api/settings/* resources.

Schedules

Schedule object/request:

{
  "zone_id": "zone-1",
  "name": "Night",
  "enabled": true,
  "weekdays": [1, 2, 3, 4, 5, 6, 7],
  "start_time": "22:30",
  "end_time": "06:30",
  "preset": "sleep",
  "setpoint": 24.5
}

Rules:

  • weekdays use ISO numbers 1=Monday ... 7=Sunday,
  • times use local HH:MM,
  • crossing midnight is supported,
  • start_time == end_time represents a 24-hour window for selected weekdays,
  • preset: comfort, sleep, away, custom,
  • custom setpoint: 8..30 °C,
  • enabled schedules for the same zone cannot overlap.

For non-custom presets, the effective target comes from the zone's seasonal profile; setpoint is retained for compatibility.

Routes:

GET    /api/schedules
POST   /api/schedules
GET    /api/schedules/{id}
PUT    /api/schedules/{id}
DELETE /api/schedules/{id}

Create returns 201; delete returns 204.

Automations

Automation request/object fields:

{
  "name": "Hot room",
  "enabled": true,
  "trigger_kind": "temperature_above",
  "trigger_device_id": "gree-aabbccddeeff",
  "threshold": 27.0,
  "at_time": null,
  "action_device_id": "gree-aabbccddeeff",
  "action_group_id": null,
  "action_preset": null,
  "action": {
    "power": true,
    "mode": "cool",
    "target_temperature": 23
  },
  "cooldown_seconds": 300
}

Triggers:

  • temperature_above: requires trigger_device_id + threshold,
  • temperature_below: requires trigger_device_id + threshold,
  • time: requires local at_time in HH:MM.

Action target is either:

  • direct device: action_device_id + full DeviceCommand, or
  • group: action_group_id; group automation supports only power, house/cool/heat mode and optional action_preset (auto|comfort|sleep|away).

The response also contains runtime last_fired_at, created_at, updated_at.

Routes:

GET    /api/automations
POST   /api/automations
GET    /api/automations/{id}
PUT    /api/automations/{id}
DELETE /api/automations/{id}

Create returns 201; delete returns 204.

History and readings

GET /api/readings

Legacy/lightweight device history.

Query parameters:

Parameter Default Description
device_id all Optional device filter.
hours 24 Clamped to 1..87600 (10 years).
limit 1500 Row limit.

Response:

{
  "readings": [
    {
      "id": 1,
      "device_id": "gree-aabbccddeeff",
      "timestamp": "...",
      "indoor_temperature": 23.4,
      "outdoor_temperature": 30.1,
      "target_temperature": 23,
      "power": true,
      "source": "poll"
    }
  ]
}

GET /api/history

Rich chart/history API.

Query parameters:

Parameter Description
scope overview, zones/zone, devices, sensors; default zones.
zone_id Zone filter for zone scope.
device_id Device filter for device scope.
entity_id Home Assistant entity filter for sensor scope.
hours Default 24, clamped to 10 years.
limit Default 12000, clamped to 1..20000.

Bucket resolution:

Range Bucket
≤ 6 h 30 s
≤ 24 h 2 min
≤ 7 d 10 min
≤ 30 d 30 min
≤ 90 d 2 h
≤ 1 y 6 h
> 1 y 24 h

Zone reading fields:

id, zone_id, device_id, timestamp,
gree_temperature, external_temperature, control_temperature,
target_temperature, device_setpoint, outdoor_temperature,
power, mode, fan_speed, demand, control_source, active_preset

Device reading fields are the Reading fields documented above. HA sensor rows contain:

id, entity_id, zone_id, kind, timestamp, temperature

scope=overview returns all three families plus counts and per-family storage source.

When InfluxDB is enabled, older history can be read from Influx and merged with recent SQLite rows. A failed Influx query falls back to available SQLite data and reports storage_warning rather than failing the entire chart response.

Control plan

GET /api/control-plan

Returns the resolved machine-readable thermostat plan:

Top-level fields:

generated_at
house_mode
house_preset
house_power
outdoor_temperature
control_strategy
night_mode_active
night_mode_start
night_mode_end
night_mode_max_fan_speed
next_events[]
zones[]
rules[]

Each zone plan includes:

zone_id, zone_name, device_id, device_name,
enabled, effective_enabled,
mode, configured_mode, inherit_house_mode,
preset, preset_override,
current_temperature, target_temperature, device_setpoint,
desired_power, desired_mode,
actual_power, actual_mode, actual_setpoint,
demand, control_source,
manual_override_until,
local_thermostat_power, local_thermostat_resume_at,
device_manual_override, device_manual_override_until,
control_owner, control_command_source, control_since, resume_at, control_reason,
blocked_reason, lockout_until,
current_schedule_id, current_schedule_name,
next_events[]

This endpoint is the best way for another client to understand desired vs actual state, who owns control, and why a zone is blocked/paused.

Events and retention

GET /api/events?limit=100

Response:

{
  "events": [
    {
      "id": 1,
      "timestamp": "...",
      "level": "info",
      "kind": "device.updated",
      "message": "...",
      "metadata": {}
    }
  ]
}

Runtime settings — 0.12.0

Version 0.12.0 replaces the monolithic settings document with functional resources. There are no compatibility aliases for the removed /api/settings, /api/debug or /api/events/retention endpoints.

Every settings resource supports GET and PUT. A PUT replaces only that functional section; it never requires or overwrites unrelated settings.

/api/settings/application

{
  "simulator_enabled": false
}

/api/settings/gree

{
  "controller_id": "gree-controller",
  "poll_interval_seconds": 15,
  "zone_interval_seconds": 5,
  "discovery_timeout_ms": 3000,
  "discovery_broadcast": "255.255.255.255:7000",
  "suppress_device_beep": false,
  "compressor_protection_enabled": true,
  "compressor_protection_seconds": 180
}

Validation/normalization:

  • controller_id cannot be empty;
  • polling and zone intervals: 2..3600 seconds;
  • discovery timeout: 300..30000 ms;
  • discovery broadcast: auto, auto:* or a socket address;
  • compressor protection: 30..1800 seconds.

Changing compressor protection clears pending compressor runtime queues before thermostat control continues.

/api/settings/history

{
  "retention_days": 30,
  "compaction_enabled": true,
  "event_retention_days": 30
}

Retention values are clamped to 1..3650 days. Updating this section immediately prunes expired event rows. The former /api/events/retention endpoint no longer exists.

/api/settings/influxdb

GET returns a secret-safe view:

{
  "enabled": true,
  "version": "2",
  "url": "http://influxdb:8086",
  "database": "gree_controller",
  "username": "",
  "password_configured": false,
  "org": "home",
  "bucket": "gree_controller",
  "token_configured": true,
  "history_threshold_days": 30
}

PUT uses the same non-secret fields plus optional password and token. Omitting either field (or sending null) preserves the stored secret. Sending an explicit empty string clears it. history_threshold_days is clamped to 1..3650; the complete InfluxDB configuration is validated before persistence.

/api/settings/notifications

GET returns provider state without secret values:

{
  "enabled": true,
  "mode": "problems",
  "provider": "pushover",
  "pushover_configured": true,
  "slack_configured": false,
  "discord_configured": false,
  "cooldown_seconds": 300,
  "communication_failure_threshold": 3,
  "target_timeout_minutes": 60,
  "alert_types": {
    "stale_sensor": true,
    "sensor_errors": true,
    "communication": true,
    "target_timeout": true,
    "automation": true,
    "control_errors": true,
    "important_events": true,
    "other": true
  }
}

PUT accepts the same behavioral fields plus optional pushover_app_token, pushover_user_key, slack_webhook_url and discord_webhook_url. Omitted/null secrets are preserved; an explicit empty string clears them. Modes: problems, important. Providers: pushover, slack, discord. Cooldown is clamped to 30..86400 seconds, failure threshold to 2..100, target timeout to 5..1440 minutes.

/api/settings/night

{
  "enabled": false,
  "start_time": "22:00",
  "end_time": "06:00",
  "max_fan_speed": 1,
  "force_quiet": true,
  "use_native_sleep": true
}

Times must use HH:MM; maximum fan speed is clamped to 1..5.

/api/settings/home-assistant

GET returns:

{
  "url": "http://homeassistant.local:8123",
  "token_configured": true,
  "default_entity_id": "sensor.room_temperature",
  "outdoor_entity_id": "sensor.outdoor_temperature",
  "sensor_stale_after_seconds": 300,
  "allow_invalid_tls": false,
  "sensor_aliases": {
    "sensor.room_temperature": "Living room"
  },
  "flow_inputs": [],
  "outdoor_assist_enabled": true
}

PUT replaces token_configured with optional token. Omitted/null token preserves the saved token; an explicit empty string clears it. Sensor age is clamped to 30..86400 seconds. URLs, aliases, entity IDs and shared Flow inputs are normalized/validated before persistence. Shared inputs are value sources only; comparison operators and thresholds belong to Flow nodes.

/api/settings/debug

{
  "overlay_enabled": true,
  "gree_frames": true
}

When overlay_enabled=true, live HTTP diagnostics can emit api.request; gree_frames=true enables sanitized gree.frame events.

Settings WebSocket events

Each section has its own event and payload:

settings.application.updated
settings.gree.updated
settings.history.updated
settings.influxdb.updated
settings.notifications.updated
settings.night.updated
settings.home_assistant.updated
settings.debug.updated

The generic settings.updated and debug.settings events were removed in 0.12.0.

Configuration backup and restore

GET /api/configuration/export

Returns configuration format version 3:

format_version
exported_at
settings
devices[]
zones[]
groups[]
schedules[]
automations[]
flows[]

The export contains GREE binding keys and integration credentials. It excludes metric history, event rows and generated API-token records. Treat it as a secret backup.

POST /api/configuration/import

Accepts only format version 3 and the setpoint control strategy used by 0.12.0. The backend validates IDs/references (including shared Flow inputs against resources inside the backup), Flow draft safety, schedules, settings and ownership relationships; safely powers off devices being detached; clears transient runtime/ownership state; replaces configuration; re-polls imported devices; then resumes thermostat control.

Metric/event history and generated access-token records are preserved.

Response:

{
  "ok": true
}

Integration tests

POST /api/integrations/home-assistant/test

{
  "entity_id": "sensor.room_temperature"
}

entity_id is optional; controller defaults/aliases are resolved. Response:

{
  "ok": true,
  "temperature_c": 23.4,
  "entity_id": "sensor.room_temperature"
}

POST /api/integrations/home-assistant/entity

Reads the current raw Home Assistant entity document used by the shared-Flow-input diagnostics UI.

{
  "entity_id": "climate.gas_boiler"
}

Response includes the raw state, availability, attributes and timestamps:

{
  "ok": true,
  "entity_id": "climate.gas_boiler",
  "state": "heat",
  "available": true,
  "attributes": { "hvac_action": "heating" },
  "last_changed": "2026-09-02T06:30:00Z",
  "last_updated": "2026-09-02T06:30:05Z"
}

POST /api/integrations/notifications/test

Accepts a NotificationSettings object. Blank secret/webhook fields reuse saved secrets for the test.

Response:

{
  "ok": true
}

Access tokens

GET /api/access-tokens

Returns:

[
  {
    "id": "uuid",
    "name": "Home Assistant",
    "token_prefix": "gree_controller_abc...",
    "created_at": "..."
  }
]

POST /api/access-tokens

{
  "name": "Home Assistant"
}

Name length: 1..80. If omitted, default is Home Assistant.

Response 201 Created:

{
  "token": "gree_controller_FULL_SECRET_SHOWN_ONCE",
  "item": {
    "id": "uuid",
    "name": "Home Assistant",
    "token_prefix": "gree_controller_...",
    "created_at": "..."
  }
}

DELETE /api/access-tokens/{id}

Revokes token and returns 204.

Restricted Home Assistant API

These routes always require a generated token or the administrator app token.

GET /api/integrations/home-assistant/devices

Returns Device[].

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

Accepts DeviceCommand. A direct command is rejected if the device belongs to a disabled thermostat zone; re-enable the zone for normal HA/controller ownership or use the administrator technical device endpoint deliberately.

GET /api/integrations/home-assistant/control-plan

Same payload as administrator GET /api/control-plan.

GET /api/integrations/home-assistant/groups

Returns an HA-oriented derived group list. Each object includes:

id, name, zone_ids, zone_names,
power_enabled, effective_power,
mode, preset, house_mode,
zone_count, enabled_zones, active_zones, demanding_zones,
device_count, online_devices, current_temperature,
members[], next_events[]

Member rows include zone/device identity, configured/effective enable state, mode/preset, room/target temperature, demand, source, schedule and current manual/local ownership markers.

POST /api/integrations/home-assistant/groups/{id}/control

Same body/semantics as normal group control.

POST /api/integrations/home-assistant/house/control

Same { "mode": "cool|heat|off" } semantics as administrator house mode.

POST /api/integrations/home-assistant/house/preset

Same { "preset": "auto|comfort|sleep|away" } semantics.

POST /api/integrations/home-assistant/house/power

Same { "power": true|false } semantics.

POST /api/integrations/home-assistant/zones/{id}/control

Same ZoneControlPatch thermostat semantics as the normal zone control endpoint. The internal source is recorded as Home Assistant thermostat control.

WebSocket

Connection

Without administrator authentication:

ws://HOST:8787/ws

When GREE_CONTROLLER_APP_TOKEN is configured:

ws://HOST:8787/ws?token=APP_TOKEN

Generated restricted HA tokens are not WebSocket administrator tokens.

Message envelope

Every server event uses:

{
  "event": "device.updated",
  "timestamp": "2026-08-30T06:54:00Z",
  "data": {}
}

The first frame is always bootstrap with the same payload as GET /api/bootstrap, unless bootstrap generation itself fails.

Common live events include:

bootstrap
device.created
device.updated
device.deleted
devices.discovered
zone.created
zone.updated
zone.deleted
group.created
group.updated
group.deleted
schedule.created
schedule.updated
schedule.deleted
schedule.template_applied
automation.created
automation.updated
automation.deleted
settings.application.updated
settings.gree.updated
settings.history.updated
settings.influxdb.updated
settings.notifications.updated
settings.night.updated
settings.home_assistant.updated
settings.debug.updated
house.mode_changed
configuration.imported
api.request
gree.frame
log.created

Additional engine/integration events may be introduced without changing the envelope.

api.request data:

{
  "method": "GET",
  "path": "/api/system/info",
  "status": 200,
  "duration_ms": 2
}

GREE debug events are emitted only when enabled and are intended for diagnostics, not as a stable protocol API.

Localization endpoints

Language files are public so the UI can localize before administrator authentication.

GET /lang/index.json

Returns the generated catalog of embedded packs.

GET /lang/{code}.json

Returns one embedded language pack, e.g.:

GET /lang/en.json
GET /lang/pl.json

Practical API examples

Assume:

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

Discover devices:

curl -X POST "$BASE/api/discovery" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"protocol_version":0,"passes":3}'

Directly poll a device:

curl -X POST "$BASE/api/devices/DEVICE_ID/poll" -H "$AUTH"

Set a zone target:

curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"setpoint":22.5}'

Return zone to automatic scheduling:

curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"preset":"auto","clear_local_thermostat_override":true}'

Turn the whole managed house off:

curl -X POST "$BASE/api/house/power" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"power":false}'

Read current ownership/desired-vs-actual state:

curl "$BASE/api/control-plan" -H "$AUTH"

Read 90 days of zone history:

curl "$BASE/api/history?scope=zones&zone_id=ZONE_ID&hours=2160" -H "$AUTH"

Create a restricted Home Assistant token:

curl -X POST "$BASE/api/access-tokens" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"name":"Home Assistant"}'

Use that token:

curl -H 'Authorization: Bearer gree_controller_RESTRICTED_TOKEN' \
  "$BASE/api/integrations/home-assistant/control-plan"

Visual Flow API

Flow is the source-of-truth representation for visual schedule/automation logic. GET /api/flows lists Flows; GET /api/flows/:id, POST /api/flows, PUT /api/flows/:id and DELETE /api/flows/:id manage them. A Flow payload contains name, enabled, optional draft, optional description, nodes and edges. draft=true is reserved for work-in-progress graphs: the backend forces them disabled and stores no generated schedules or automations.

Saving an executable Flow validates the DAG and compiles it atomically. If the editor receives HTTP 400 during normal save, it can offer to retry with draft=true; draft validation preserves the editable graph while allowing missing actions or unfinished semantic wiring. Drafts never execute, and converting an existing Flow to a draft atomically removes its previously generated outputs. A thermostat action driven only by one weekday block and one time-range block is emitted as a native schedule when its settings are schedule-compatible. More complex graphs are emitted as Flow-triggered automations. Generated schedules and automations expose flow_id / flow_node_id, use stable names in the form flow-<stable-unique-id>, and cannot be edited or deleted through their legacy endpoints; edit the owning Flow instead.

Condition blocks support weekday, time/date ranges, optional 5-field CRON, application Night mode, outdoor/device/zone temperatures, house/device/zone/group state, arbitrary Home Assistant state/numeric/attribute/availability sources, rolling mean/median, oscillation detection, and shared_input references. Stateful gate blocks include stable_for, delay, state_duration (min_seconds, optional max_seconds), on_change (mode: result|value) and rate_limit (max_count, period_seconds). on_change establishes a baseline on its first observation and does not fire immediately. rate_limit must feed an action directly and consumes quota only after a successful action execution. Shared inputs are stored in home_assistant.flow_inputs and resolve dynamically at evaluation time. Shared inputs store reusable value sources only. They never store a comparison operator or threshold. For comparison-capable source kinds, each shared_input Flow node defines its own operator and value. PUT /api/settings/home-assistant rejects shared-input configs that contain an operator, and rejects comparison value fields for comparison-capable source kinds. Logic blocks support AND, OR and NOT. Action blocks target thermostat zones, GREE devices, climate groups or a generic Home Assistant service. Direct GREE actions map to the existing DeviceCommand fields including fan, swing, quiet, turbo, light, air, xfan, health and sleep; ownership rules may suppress fields that would fight an active thermostat. Flow group actions use the existing group controller and support power, house/heat/cool mode, auto/comfort/sleep/away and the existing custom group target.

Compressor protection queue

Runtime settings expose compressor_protection_enabled and compressor_protection_seconds (30–1800; default 180). While enabled, thermostat starts and Heat/Cool reversals that fall inside the protection window are represented on the owning zone by compressor_pending_action, compressor_pending_since, and compressor_pending_until.

  • POST /api/zones/:id/compressor-queue/cancel cancels the currently pending compressor-protection task for one thermostat.
  • POST /api/compressor-queue/cancel-all cancels all currently pending compressor-protection tasks.

Cancellation suppresses the same pending intent until a new explicit thermostat/group/house command re-arms it, a scheduled Temporary Quick Thermostat session takes ownership, or a different mode/target creates a new intent. Safety OFF commands are not delayed by compressor protection. Direct technical device commands remain immediate manual-control operations.

Flow portability and diagnostics

GET /api/flows/:id/export returns a versioned gree-controller-flow JSON document containing only the source graph. Generated schedules/automations are not exported.

POST /api/flows/import accepts either that envelope or a direct Flow source payload, creates a new Flow ID/revision, and preserves draft state. Executable imports are validated and recompiled; draft imports remain disabled with no generated outputs.

POST /api/flows/simulate accepts { flow, flow_id?, at?, overrides?, log? }. at is RFC3339. overrides maps Flow node IDs to simulated values. The endpoint validates and compiles the graph, evaluates every action and returns per-node traces plus matched, would_execute and blocked_reason (for example disabled zone/device, manual/local/temporary thermostat ownership, thermostat-output conflict or disabled Flow). It never mutates thermostat/device/group/schedule/automation state. Home Assistant read/attribute/parse failures evaluate safely as false and are visible in the trace instead of accidentally satisfying NOT/neq logic.

GET /api/flows/:id/logs?limit=100 returns events associated with the Flow or its generated automations.

Existing Flow updates require expected_revision. A mismatched revision returns HTTP 409 to prevent stale editor tabs from overwriting newer graphs. Source Flow plus generated outputs are replaced atomically in one database transaction while configuration/automation/schedule/thermostat-cycle operations are serialized.

Additional Flow condition blocks are house_mode, device_state, zone_state, group_state, night_mode, ha_attribute, ha_available, constant and shared_input, alongside weekday/time/date, temperature, Home Assistant state/numeric and AND/OR/NOT blocks. device_state can inspect enabled/online/power/mode/fan/swing/quiet/turbo/light/air/xfan/health/sleep state. The editor ships 37 categorized editable templates covering comfort, energy, safety, night, reliability, Home Assistant heat-source coordination and advanced multi-branch logic. The template UI adds search, favorites/recent history, a graph preview and runtime requirement checks; shared inputs expose usage links and HA-backed inputs can be tested against live entity state.

Reference in New Issue View Git Blame Copy Permalink