v0.4.4

docs/API.md

@@ -176,12 +176,30 @@ curl "$BASE/lang/en.json"
 
 ### `GET /api/history`
 
-Returns rich per-zone climate history. Query parameters:
+The history API exposes three independent data families and a combined overview. Common parameters are `hours=6|24|168|720` and `limit` up to 20,000 rows. Downsampling is performed in SQLite: 30-second buckets up to 6 hours, 2-minute buckets up to 24 hours, 10-minute buckets up to 7 days, and 30-minute buckets for longer ranges.
 
-- `zone_id=<zone id>` for one zone, or `zone_id=all` for all zones,
-- `hours=6|24|168|720`,
-- `limit` up to 20,000 rows.
+```text
+GET /api/history?scope=overview&hours=24
+GET /api/history?scope=devices&device_id=DEVICE_ID&hours=24
+GET /api/history?scope=zones&zone_id=ZONE_ID&hours=24
+GET /api/history?scope=sensors&entity_id=sensor.room_temperature&hours=24
+```
 
-Each row contains `gree_temperature`, `external_temperature` (HA room sensor), `control_temperature`, `target_temperature`, `device_setpoint`, `outdoor_temperature`, `power`, `mode`, `fan_speed`, `demand`, `control_source`, and `active_preset`.
+`scope=overview` returns:
 
-The endpoint automatically downsamples in SQLite to keep charts responsive: 30-second buckets up to 6 hours, 2-minute buckets up to 24 hours, 10-minute buckets up to 7 days, and 30-minute buckets for longer ranges.
+```json
+{
+  "scope": "overview",
+  "bucket_seconds": 120,
+  "zones": [],
+  "devices": [],
+  "sensors": [],
+  "counts": {"devices": 0, "zones": 0, "ha": 0}
+}
+```
+
+Device rows come from the existing `readings` table and contain `indoor_temperature`, optional GREE `outdoor_temperature`, `target_temperature`, `power`, and `source`. This makes old device history immediately available after an upgrade.
+
+Zone rows contain `gree_temperature`, `external_temperature` (HA room sensor), `control_temperature`, `target_temperature`, `device_setpoint`, `outdoor_temperature`, `power`, `mode`, `fan_speed`, `demand`, `control_source`, and `active_preset`. If a zone has no rich samples yet, the API falls back to that zone's existing GREE device readings instead of returning an empty timeline.
+
+Sensor rows contain `entity_id`, optional `zone_id`, `kind` (`room` or `outdoor`), `timestamp`, and `temperature`. New HA samples start being collected after the upgrade; where older rich zone samples contain the same HA values, the API can expose them as compatibility history.