Public API
Everything in the stack, over one API.
Fully documented RESTful API with telemetry, control and scheduling for any WattStack-connected device, and webhooks that push live telemetry to you. Hardware safety clamping at the Edge. Point it at the WattStack cloud or at your own service. Your call.
Get early API access# 1 · authenticate (OAuth2 client credentials) export WS_HOST="https://api.wattstack.io" export WS_TOKEN=$(curl -s -X POST $WS_HOST/oauth/token \ -d "grant_type=client_credentials" \ -d "client_id=$WS_ID&client_secret=$WS_SECRET" \ | jq -r .access_token) export WS_DEV="3fa85f64-5717-4562-b3fc-2c963f66afa6" # 2 · fetch the descriptor: what the ids mean curl $WS_HOST/api/v1/devices/$WS_DEV/descriptor \ -H "Authorization: Bearer $WS_TOKEN" # → functions, each with its own controls and telemetry # "functions": [ { "id": 1, "name": "Heat Pump", # "controls": [ { "id": 10, "name": "Flow Temperature", "unit": "degc", # "role": { "quantity": "temperature" } } ], # "telemetry": [ { "id": 12, "name": "Power Draw", "unit": "watt", # "role": { "quantity": "power" } } ] } ] # 3 · latest state, keyed by the ids above curl $WS_HOST/api/v1/devices/$WS_DEV/state \ -H "Authorization: Bearer $WS_TOKEN" # → { "telemetry": { "12": { "value": 1850, "measured_at": "..." } } } # 4 · take control (five-minute window, renewable) curl -X POST $WS_HOST/api/v1/devices/$WS_DEV/takeover \ -H "Authorization: Bearer $WS_TOKEN" # 5 · set the flow temperature, in display units curl -X POST $WS_HOST/api/v1/devices/$WS_DEV/control \ -H "Authorization: Bearer $WS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "values": { "10": 45 } }' # → 200 OK · command receipt returned # 6 · release control curl -X POST $WS_HOST/api/v1/devices/$WS_DEV/release \ -H "Authorization: Bearer $WS_TOKEN"
# 1 · authenticate (OAuth2 client credentials) import requests WS_HOST = "https://api.wattstack.io" token = requests.post(f"{WS_HOST}/oauth/token", data={ "grant_type": "client_credentials", "client_id": WS_ID, "client_secret": WS_SECRET, }).json()["access_token"] auth = {"Authorization": f"Bearer {token}"} dev = "3fa85f64-5717-4562-b3fc-2c963f66afa6" # 2 · fetch the descriptor: what the ids mean descriptor = requests.get(f"{WS_HOST}/api/v1/devices/{dev}/descriptor", headers=auth).json() # → functions, each with its own controls and telemetry # "functions": [ { "id": 1, "name": "Heat Pump", # "controls": [ { "id": 10, "name": "Flow Temperature", "unit": "degc", # "role": { "quantity": "temperature" } } ], # "telemetry": [ { "id": 12, "name": "Power Draw", "unit": "watt", # "role": { "quantity": "power" } } ] } ] # 3 · latest state, keyed by the ids above state = requests.get(f"{WS_HOST}/api/v1/devices/{dev}/state", headers=auth).json() # → { "telemetry": { "12": { "value": 1850, "measured_at": "..." } } } # 4 · take control (five-minute window, renewable) requests.post(f"{WS_HOST}/api/v1/devices/{dev}/takeover", headers=auth) # 5 · set the flow temperature, in display units receipt = requests.post(f"{WS_HOST}/api/v1/devices/{dev}/control", headers=auth, json={"values": {"10": 45} }).json() # → 200 OK · command receipt returned # 6 · release control requests.post(f"{WS_HOST}/api/v1/devices/{dev}/release", headers=auth)
// 1 · authenticate (OAuth2 client credentials) const WS_HOST = "https://api.wattstack.io"; const { access_token } = await fetch(`${WS_HOST}/oauth/token`, { method: "POST", body: new URLSearchParams({ grant_type: "client_credentials", client_id: WS_ID, client_secret: WS_SECRET }), }).then(r => r.json()); const auth = { Authorization: `Bearer ${access_token}` }; const dev = "3fa85f64-5717-4562-b3fc-2c963f66afa6"; // 2 · fetch the descriptor: what the ids mean const descriptor = await fetch(`${WS_HOST}/api/v1/devices/${dev}/descriptor`, { headers: auth }).then(r => r.json()); // → functions, each with its own controls and telemetry // "functions": [ { "id": 1, "name": "Heat Pump", // "controls": [ { "id": 10, "name": "Flow Temperature", "unit": "degc", // "role": { "quantity": "temperature" } } ], // "telemetry": [ { "id": 12, "name": "Power Draw", "unit": "watt", // "role": { "quantity": "power" } } ] } ] // 3 · latest state, keyed by the ids above const state = await fetch(`${WS_HOST}/api/v1/devices/${dev}/state`, { headers: auth }).then(r => r.json()); // → { "telemetry": { "12": { "value": 1850, "measured_at": "..." } } } // 4 · take control (five-minute window, renewable) await fetch(`${WS_HOST}/api/v1/devices/${dev}/takeover`, { method: "POST", headers: auth }); // 5 · set the flow temperature, in display units const receipt = await fetch(`${WS_HOST}/api/v1/devices/${dev}/control`, { method: "POST", headers: { ...auth, "Content-Type": "application/json" }, body: JSON.stringify({ values: { "10": 45 } }), }).then(r => r.json()); // → 200 OK · command receipt returned // 6 · release control await fetch(`${WS_HOST}/api/v1/devices/${dev}/release`, { method: "POST", headers: auth });
Public API
API features.
Control and schedules
Schedules and time windows configurable via API with on device prioritisation and arbitration. You decide schedule priority order and if a flex event, user schedule or a resident override trigger overlapping demands, the Edge arbitrates the priority order locally, all whilst ensuring that the manufacturer's safety limits are enforced.
Device timed events
Use date ranges, time of day and day of week to program simple or complex behaviour. The Edge implements scheduling on the device's behalf, so stop worrying about how many timer slots a device has. Every device is controlled with the same fidelity, keeps its schedule through a network outage, and window boundaries are spread across a fleet so a cheap tariff starting on the hour ramps rather than steps.
Events and webhooks
Subscribe once and every device the account can see reports in, so your own store or optimiser stays current without polling. Multiple event types covering device and gateway state, telemetry, and commands, and one subscription per prefix covers them. Deliveries are signed and logged, with built in retry logic, and are replay configurable.
Telemetry
Query device telemetry over REST, or have it pushed to you as it lands. Resilience is built in at hardware level, with telemetry cached at the Edge when the connection drops and forwarded on reconnection. Because devices sample on aligned clocks, uploads are spread so a fleet reporting on the hour does not arrive all at once.
Command acknowledgement
Commands are receipted so you can confirm they landed. Simple state flags for online status and telemetry buffered while a device was disconnected arrives marked as offline cache, timestamped when it was measured rather than when it arrived. The audit trail records why a command ran, which source issued it, and who authorised that source and when, so a "why is my device doing that" call is answered from the record.
Versioning and change
Major versioning support via path with deprecation of endpoints handled transparently with backwards compatibility and announced dates.
Errors and rate limits
RFC 9457 error treatment with machine-readable code you can branch on without parsing text. Differential rate limits between command and read operations with retry_after functionality.
Access and auth
Per integration, OAuth2 client credentials make access simple, controlled and granular.
Build against it.
API early access is available for companies looking to use WattStack. Tell us what you're building and we will set you up against real devices, with the engineers who built the interface alongside you. Full public access coming soon.