API Guide

API Guide

Glasscalibur runs ESPHome, whose built‑in web server exposes a simple REST API over HTTP. Use it from Node‑RED, scripts, cron jobs, webhooks — anything that can make an HTTP request. No cloud, no account.

Prefer Home Assistant? If you use HA, the native integration is easier and more capable than raw HTTP — use that instead.

Base URL & entity id

Everything hangs off your device's address:

http://glasscalibur-XXXXXX.local

(or its IP address — see Wi‑Fi Setup).

The cover's entity id is glasscalibur, so its endpoint base is /cover/glasscalibur.

Position model

Position is a fraction from 0.0 (fully closed) to 1.0 (fully open) — e.g. 0.5 is halfway. (In Home Assistant the same value shows as 0–100 %.)

Read state — GET

curl http://glasscalibur-XXXXXX.local/cover/glasscalibur

Returns JSON describing the cover, including its position and current_operation (IDLE / OPENING / CLOSING):

{ "id": "cover-glasscalibur", "position": 0.5, "current_operation": "IDLE", "state": "OPEN" }

Control — POST

Control actions are POST requests (a plain browser address‑bar visit is a GET and won't trigger them — use curl, Node‑RED, etc.):

# Open fully
curl -X POST http://glasscalibur-XXXXXX.local/cover/glasscalibur/open

# Close fully
curl -X POST http://glasscalibur-XXXXXX.local/cover/glasscalibur/close

# Stop
curl -X POST http://glasscalibur-XXXXXX.local/cover/glasscalibur/stop

# Move to a specific position (0.0–1.0). 0.5 = halfway:
curl -X POST "http://glasscalibur-XXXXXX.local/cover/glasscalibur/set?position=0.5"

Other entities

The same pattern works for the device's other entities, e.g.:

# Press a button (e.g. restart)
curl -X POST http://glasscalibur-XXXXXX.local/button/restart/press

# Toggle a switch (e.g. the schedule)
curl -X POST http://glasscalibur-XXXXXX.local/switch/schedule_enabled/turn_on

You can see every entity's exact id by opening the web UI, or by streaming the live state events at GET /events (Server‑Sent Events).

Example — Node‑RED

Use an http request node set to POST with the URL http://glasscalibur-XXXXXX.local/cover/glasscalibur/set?position=0 to close the window, wired to whatever trigger you like (a schedule, an air‑quality sensor, a weather check, etc.).

If your .local hostname doesn't resolve from the machine running your automations, use the device's IP address instead and consider reserving it as a static lease in your router.