HTTP API
The settings page talks to the device through a small JSON API over plain HTTP, and scripts can use the same routes. The routes are registered in src/WebPortal.cpp, and the theme routes in src/features/theme/ThemeWeb.cpp.
Access rules
Section titled “Access rules”- With a web UI password set, every route needs HTTP digest auth (
curl --digest -u <user>:<password>). The exceptions arePOST /api/usage, which the usage daemon calls without credentials and which only writes the numbers on the screen, and the captive-portal probes. Only one client at a time stays logged in; see Troubleshooting - The device answers
403 Forbiddento a request whoseHostheader is not its IP address or hostname, and to a browser request from another site’s page. Scripts and curl send noOriginheader and are not affected. See Troubleshooting - The Home Assistant, notification and theme routes exist only in builds with that feature, and answer
404elsewhere. In a build without the usage meter,/api/usageand/api/activityanswer400
Routes
Section titled “Routes”| Method and route | What it does |
|---|---|
GET / |
The settings page |
GET /api/config |
The settings as JSON, without passwords or the WireGuard private key, plus features (which of ticker, usage, radar, ha, theme, wireguard and button the build has) and chip (esp8266, esp32c2 or esp32) |
POST /api/config |
Applies the settings in the JSON body and saves them. Answers {"ok":true,"reboot":<bool>}; reboot is true when the WiFi list or the hostname changed, and the device then restarts. An ha member says that Home Assistant needs a restart. 400 for a body that is not JSON, 503 with not enough memory when the device has no heap for the save, which keeps the old settings |
GET /api/status |
Live device state, see below |
GET /api/scan |
A WiFi scan: a list of up to 25 {"ssid","rssi","enc"} |
POST /api/refresh |
Fetches every ticker now |
POST /api/reboot |
Restarts the device |
POST /api/factory |
Erases every setting and restarts in SETUP MODE |
POST /api/crash/clear |
Clears the last-crash record (v3.5.0 or later) |
GET /api/export |
Downloads config.json, with the WiFi passwords and the WireGuard private key in clear text |
POST /api/import |
Applies a config.json from the body, saves it and restarts |
GET /api/checkupdate |
Compares the running version with the newest GitHub release: current, ok, latest, newer, and error when the check failed |
POST /api/selfupdate |
Starts the GitHub self-update |
POST /update |
Manual firmware upload, one multipart file. Answers OK and restarts, or a plain-text error. On the ESP8266 an upload that cannot get its 4 KB buffer is refused at the start (v3.6.0 or later) |
POST /api/usage |
The usage daemon’s push: {"s":29,"sr":142,"w":4,"wr":9876,"st":"normal","ok":true}, session and weekly percent and minutes to each reset. See Claude usage meter |
POST /api/activity?state=running|done|idle |
The Claude Code prompt state on the usage screen (v3.4.0 or later) |
POST /api/notify |
A notification overlay, see Notifications |
POST /api/ha/clear |
Wipes every Home Assistant screen from the device and deletes the broker’s retained copies: {"ok":true,"cleared":N,"broker":<bool>} |
GET /api/themes, POST /api/themes/install, /select, /delete |
Theme packages, see Theme clocks |
The status reply
Section titled “The status reply”GET /api/status is written in 128-byte pieces as the values are read, so it goes out chunked; an HTTP/1.0 client gets plain JSON that ends when the connection closes. A client that stops reading has its connection dropped (v3.10.0 or later). Members marked “when set” are left out otherwise.
| Member | Meaning |
|---|---|
fw, version, variant, repo |
Firmware name, version (with a fork’s suffix, see Build options for forks), the release variant such as esp8266-lean, and the repository URL |
updateMsg |
When set: the state or result of a GitHub update |
githubUpdate |
Only false, and only in a build without the GitHub self-update |
mode, connected, ssid, ip, rssi |
sta or ap, and the WiFi link |
wifiFail |
When set: why the last join failed |
heap, maxblk, contstk |
Free heap, the largest free block, and the free loop stack on the ESP8266, in bytes |
uptime, reset |
Seconds since boot, and the reason for the last reset |
synced, time, tz, clockFresh |
Whether NTP ever set the clock, the local time when known, the timezone, and whether the last sync is recent |
night, nightHeld |
Night mode dims the screen now; the night window is active but waits for a fresh NTP sync |
sun, bl |
Today’s sunrise and sunset when the sun schedule runs, and the backlight level 0 to 255. See Sunrise and sunset brightness |
ha |
When set: why Home Assistant is not running as set, memory, safe or reboot. See Home Assistant screens |
wg |
The tunnel: compiledIn, enabled, up, held, badConfig, and in a build with the client stage, attempts, endpointIp and lastHandshake (Unix time) |
lastCrash |
When a record exists (ESP8266, v3.5.0 or later): reason, fw, the registers exccause, epc and addr when the chip recorded them, and uptime in seconds |
fetchRefused, fetchLast |
Builds with theme clocks, once a theme data fetch has ended: fetches refused for memory since boot, and how the last one ended (ok, refused or failed) |
tickers |
One entry per ticker: symbol, valid, error, retryIn (seconds to the next attempt) after a failure, and price, changePct and basis (range or day) once there is data |
radar |
The radar’s last poll: count, error, stage, seenAc, and when known http, tlsRx, triedAgo, okAgo and url. See Plane radar |