From f5842568b9fca55e68daafa0783518519ba20ae5 Mon Sep 17 00:00:00 2001
From: windyboy <windyboy@gmail.com>
Date: Thu, 13 Aug 2026 17:20:49 +0800
Subject: [PATCH] docs: add Home Assistant API access notes

---
 hosts/hass.windy.lan.md | 48 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/hosts/hass.windy.lan.md b/hosts/hass.windy.lan.md
index 0ac9dcd..97fbff4 100644
--- a/hosts/hass.windy.lan.md
+++ b/hosts/hass.windy.lan.md
@@ -36,6 +36,54 @@ recovery codes in this repository.
 LAN55 clients reach the HTTP API on `dns.windy.lan:80` for the AdGuard Home
 integration; see [hosts/dns.windy.lan.md](dns.windy.lan.md).
 
+## API access
+
+Home Assistant exposes a REST API at `http://hass.windy.lan:8123/api/` (same
+as `http://192.168.55.11:8123/api/`). Authenticate with a **long-lived access
+token** created under **Profile → Security → Long-lived access tokens**.
+
+```bash
+HA_URL="http://hass.windy.lan:8123"
+HA_TOKEN="<long-lived-access-token>"
+
+# Health check — expect {"message":"API running."} and HTTP:200
+curl -sS -w "\nHTTP:%{http_code}\n" \
+  -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/"
+
+# Read one entity state
+curl -sS -H "Authorization: Bearer $HA_TOKEN" \
+  "$HA_URL/api/states/sensor.csg_30d_max"
+
+# List entities / recent errors
+curl -sS -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states"
+curl -sS -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/error_log"
+```
+
+- `401` → token invalid or expired; create a new one.
+- `404` on `/api/states/<id>` → entity does not exist.
+- The token is a secret: never commit it here; keep it in the shell
+  environment or a secrets file outside the repo.
+
+### HTTP proxy gotcha (verified 2026-08-13)
+
+The WSL client had `http_proxy` set to Mihomo (`192.168.66.99:7890`). LAN
+hostnames sent **through that proxy** returned empty `502`, even though DNS
+resolved and the HA UI was up. Direct `192.168.55.11:8123` worked, and
+`hass.windy.lan:8123` worked only after clearing the HTTP proxy.
+
+Before debugging a "502" on a LAN URL, check `env | grep -i proxy` and bypass
+the proxy:
+
+```bash
+unset http_proxy HTTP_PROXY all_proxy ALL_PROXY
+curl -sS -w "\nHTTP:%{http_code}\n" \
+  -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/"
+```
+
+For a persistent fix, add `.windy.lan` (leading dot) and the LAN ranges to
+`NO_PROXY`, or add `*.windy.lan` to the proxy's own bypass/skip-proxy list.
+See `~/.config/zsh/env/local/environment.env` for the client-side setting.
+
 ## Safe verification
 
 ```bash