HTTP API

HTTP API

Everything the web panel shows is plain HTTP on port 80 (port 8080 in the Android app). The panel's API tab carries the same reference with live examples from your own device.

With a panel password set, every endpoint requires HTTP Basic Auth: curl -u admin:PASSWORD ...

Endpoints

Endpoint	Method	What it does
/api/state	GET	Live JSON: flights with routes and trails, weather, network, stats
/api/config	GET	Current settings (passwords never included)
/api/config	POST	Update any subset of settings; saves and restarts
/api/backup	GET	Full settings backup as JSON, including credentials; served as a download
/api/log	GET	Spotting history TSV: epoch, hex, callsign, type, airline
/api/alerts	GET	Alert history TSV: epoch, title, message
/api/airport	GET	Airport lookup: ?code=EDDF (ICAO or IATA) returns name, city, coordinates
/screen.bmp	GET	Live screenshot of the display as BMP
/metrics	GET	Prometheus metrics: aircraft counts, session records, heap
/ota	POST	Firmware update; 403 unless unlocked on the device, 400 if the file is built for a different board

Examples

Current traffic, prettified:

curl -s http://esp32flight.local/api/state | python3 -m json.tool | head -50

Move the radar to Frankfurt for a busy evening:

curl -X POST -H "Content-Type: application/json" \
  -d '{"fixed": true, "lat": 50.04, "lon": 8.56}' \
  http://esp32flight.local/api/config

Turn the ship layer on and set the key in one call:

curl -X POST -H "Content-Type: application/json" \
  -d '{"ships_enabled": true, "ais_key": "YOUR-KEY"}' \
  http://esp32flight.local/api/config

Any field from /api/backup can be POSTed back; unknown fields are ignored, omitted fields keep their value. POSTing a full backup file restores everything (this is exactly what the panel's Restore button does).

Grab a screenshot and convert it (macOS):

curl -s http://esp32flight.local/screen.bmp -o shot.bmp && sips -s format png shot.bmp --out shot.png

Scrape it with Prometheus:

scrape_configs:
  - job_name: esp32flight
    static_configs:
      - targets: ['esp32flight.local:80']

Push a firmware update from the command line (after unlocking OTA on the device):

curl -X POST --data-binary @esp32flight-vX.Y.Z-ota.bin http://esp32flight.local/ota

Spotting log format

/api/log returns tab-separated lines, newest last:

1785698422	3c6487	DLH1560	A321	Lufthansa

Columns: Unix epoch of first sighting, ICAO hex, callsign, type code, airline (when known). The web panel History tab renders this with CSV export.