Download OpenAPI specification:
Last updated: 2026-11-16
The HeatingControl External API allows external developers to integrate with the HeatingControl ecosystem. Through this API you can list homes, manage devices, read device state, update settings, and send commands.
This API is currently in DRAFT status. While in draft, breaking changes may still occur as the API design is being finalized. The draft period will end with the first official release.
After the first official release, this API may be extended at any time with non-breaking changes. Your client code must be designed to handle these gracefully and not break when encountering unknown data.
Non-breaking changes include but are not limited to:
- New fields added to response objects
- New values for existing string/enum fields
- New optional query parameters or request body fields
- New endpoints
- Relaxed validation on existing fields (e.g. accepting a wider range of values)
Breaking changes (removed fields, changed types, altered semantics) will only be introduced in a new API version (e.g.
/v2).As a best practice, ignore unknown fields rather than treating them as errors, and avoid strict schema validation that rejects unexpected properties.
The API uses OAuth2 client credentials flow.
POST /v1/oauth/token with your client_id and client_secret to receive an access token.Authorization header:Authorization: Bearer <access_token>
client_credentials grant does not issue refresh tokens. Simply call POST /v1/oauth/token again with your credentials to obtain a new token before expiry.A typical integration follows this sequence:
GET /v1/homes to discover available homes.GET /v1/devices to enumerate devices (optionally filter by homeId).GET /v1/devices/{deviceId}/state to read current state (add live=true for fields read from the device itself, such as a power meter's power).GET /v1/devices/{deviceId}/settings to read current settings.POST /v1/devices/{deviceId}/commands/{key} to control a device.This walkthrough shows a complete integration flow for managing electric heaters — from obtaining a token to reading state and sending commands. Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, and the base URL with your actual values.
curl -X POST https://external-api.heatingcontrol.eu/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}'
Response:
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"expires_in": 3600,
"token_type": "Bearer"
}
Save the access_token — you will include it in every subsequent request as Authorization: Bearer <access_token>.
Discover the devices available in your account:
curl https://external-api.heatingcontrol.eu/v1/devices \
-H "Authorization: Bearer <access_token>"
Response:
{
"items": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Living Room Heater",
"type": "heater",
"subtype": "wifi_heater",
"homeId": "aabbccdd-eeff-0011-2233-445500000000",
"online": true,
"fwVersion": "2.1.0",
"hwVersion": "1.0",
"gatewayId": null
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Bedroom Heater",
"type": "heater",
"subtype": "wifi_heater",
"homeId": "aabbccdd-eeff-0011-2233-445500000000",
"online": true,
"fwVersion": "2.1.0",
"hwVersion": "1.0",
"gatewayId": null
}
],
"pagination": {
"limit": 20,
"cursor": null,
"nextCursor": null,
"hasMore": false
}
}
Note the id of each device — you will use it in the next steps.
Get the current state of the Living Room Heater, including temperature and power:
curl https://external-api.heatingcontrol.eu/v1/devices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/state \
-H "Authorization: Bearer <access_token>"
Response:
{
"type": "heater",
"online": true,
"mode": "auto",
"indicators": ["active"],
"currentTemperature": 20.5,
"targetTemperature": 22.0,
"temperatureUnits": "C",
"power": 1500,
"maxPower": 1500
}
Key fields:
mode — the current operating mode (e.g. auto, manual, off).power — current power consumption in watts (0 when the heater is not actively heating).maxPower — the rated maximum power of the heater in watts.Switch the Living Room Heater to manual mode at 21 °C. First, check which commands are available:
curl https://external-api.heatingcontrol.eu/v1/devices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/commands \
-H "Authorization: Bearer <access_token>"
Then execute the setMode command:
curl -X POST https://external-api.heatingcontrol.eu/v1/devices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/commands/setMode \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"params": {
"mode": "manual",
"temperature": 21.0
}
}'
Response:
{
"command": "setMode",
"state": "APPLIED",
"appliedAt": "2026-03-18T12:00:00.000Z"
}
Check the Bedroom Heater to see if it is consuming power:
curl https://external-api.heatingcontrol.eu/v1/devices/b2c3d4e5-f6a7-8901-bcde-f12345678901/state \
-H "Authorization: Bearer <access_token>"
Response:
{
"type": "heater",
"online": true,
"mode": "auto",
"indicators": [],
"currentTemperature": 22.1,
"targetTemperature": 22.0,
"temperatureUnits": "C",
"power": 0,
"maxPower": 2000
}
Here power is 0 because the room has already reached the target temperature and the heater is not actively heating. The maxPower of 2000 tells you this is a 2 kW heater.
View the configurable settings for a device:
curl https://external-api.heatingcontrol.eu/v1/devices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/settings \
-H "Authorization: Bearer <access_token>"
Response (abbreviated):
{
"temperature_units": {
"key": "temperature_units",
"type": "enum",
"label": "Temperature Units",
"value": "C",
"editable": true,
"options": ["C", "F"]
},
"keyboard_locked": {
"key": "keyboard_locked",
"type": "boolean",
"label": "Keyboard Lock",
"value": false,
"editable": true
}
}
You can update a specific setting with a PATCH request:
curl -X PATCH https://external-api.heatingcontrol.eu/v1/devices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/settings/keyboard_locked \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "value": true }'
Most of what GET /v1/devices/{deviceId}/state returns comes from what the device last reported, so it answers quickly whether or not the device is reachable. A few fields can only be read from the device itself, on that request. They are left out unless you add live=true:
| Device type | Field read live |
|---|---|
power_meter |
power |
gateway |
powerBudget |
curl "https://external-api.heatingcontrol.eu/v1/devices/<deviceId>/state?live=true" \
-H "Authorization: Bearer <access_token>"
null and the rest of the state is still returned.power is not a live field: it is always present.A gateway (listed with includeGateways=true) works through the same routes as any other device: read it with GET /v1/devices/<gatewayId>/state?live=true, and change it with the commands GET /v1/devices/<gatewayId>/commands lists.
{
"type": "gateway",
"online": true,
"discovery": false,
"powerBudget": {
"type": "surplus",
"power": 2500,
"remainingSeconds": 3412,
"expiresAt": "2026-11-09T19:00:00.000Z"
}
}
discovery says whether the gateway is looking for new devices to pair. Turn it on or off with the setDiscovery command ({ "params": { "enabled": true } }).powerBudget is read from the gateway, so it is only included with live=true (see Live readings). It is null when the gateway doesn't answer, or doesn't have a power budget (see below). Its type is none when no budget is active.A gateway can take a temporary power budget for the devices it manages. Only gateways whose firmware has it list the power budget commands in GET /v1/devices/<gatewayId>/commands; on any other gateway they answer 404. Only one budget is active at a time, set with one of two commands:
| Command | Meaning of power |
Range |
|---|---|---|
setPowerBudgetLimit |
The gateway's devices may consume at most power W in total. This temporary cap is separate from the gateway's configured power limit: it is added on top of the existing limits and never loosens them. |
1000–60000 W |
setPowerBudgetSurplus |
The gateway's devices may consume at most power W in total from surplus heating. It replaces the meters as the source of surplus. |
500–60000 W |
power is a budget for these devices, not a meter reading. The gateway subtracts what its devices already consume, so power must not include that consumption. For example, don't send the current grid export to setPowerBudgetSurplus. Each device the gateway turns on lowers the export, so the next value you send is smaller, and the gateway subtracts its devices a second time. The devices then keep switching on and off. Send what is available for these devices instead, such as a PV forecast minus the house base load.
Set a budget. It replaces the active one, whatever its type, and lasts durationMinutes (1–1440, 60 by default):
curl -X POST https://external-api.heatingcontrol.eu/v1/devices/<gatewayId>/commands/setPowerBudgetSurplus \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "params": { "power": 2500, "durationMinutes": 60 } }'
Cancel it with the cancelPowerBudget command. The gateway goes back to its usual limits at once.
GET /v1/devices/<gatewayId>/commands.409 (DEVICE_UNREACHABLE).404 means the device isn't a gateway, or the gateway doesn't have a power budget.400 means the parameters are invalid (power is in whole watts), or the gateway refused the budget, for example while its clock is not set.List endpoints support cursor-based pagination:
| Parameter | Description |
|---|---|
limit |
Maximum number of items to return (default varies by endpoint). |
cursor |
Opaque cursor returned in the previous response to fetch the next page. |
When more results are available the response includes a cursor field. Pass it as a query parameter to retrieve the next page. When cursor is absent or null, you have reached the last page.
All error responses follow a standard envelope:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable description of the problem",
"requestId": "abc-123",
"details": ["field must be a string"]
}
}
| Field | Description |
|---|---|
code |
Machine-readable error code (e.g. VALIDATION_ERROR, UNAUTHORIZED, NOT_FOUND). |
message |
Human-readable explanation. |
requestId |
Unique identifier for the request — useful when contacting support. |
details |
Optional array of strings with additional context (e.g. field-level validation errors). |
| authorization required | string |
| grant_type required | string OAuth2 grant type |
| client_id | string Client identifier |
| client_secret | string Client secret |
| scope | string Requested permission scopes, space-separated; defaults to the client's. A multi-user client accepts only |
{- "grant_type": "client_credentials",
- "client_id": "string",
- "client_secret": "string",
- "scope": "/devs/*:W"
}{- "access_token": "eyJhbGciOiJIUzI1NiIs...",
- "expires_in": 3600,
- "token_type": "Bearer"
}| limit | number [ 1 .. 100 ] Default: 20 Maximum number of homes to return |
| cursor | string Cursor from a previous response to fetch the next page |
{- "items": [
- {
- "id": "aabbccdd-eeff-0011-2233-445500000000",
- "name": "My Home",
- "deviceCount": 3,
- "location": {
- "country": "ES",
- "state": "Catalonia",
- "city": "Barcelona",
- "timeZone": "Europe/Madrid",
- "latitude": 41.3851,
- "longitude": 2.1734,
- "geofenceRadius": 200
}
}
], - "pagination": {
- "limit": 20,
- "cursor": null,
- "nextCursor": null,
- "hasMore": false
}
}{- "id": "aabbccdd-eeff-0011-2233-445500000000",
- "name": "My Home",
- "deviceCount": 3,
- "location": {
- "country": "ES",
- "state": "Catalonia",
- "city": "Barcelona",
- "timeZone": "Europe/Madrid",
- "latitude": 41.3851,
- "longitude": 2.1734,
- "geofenceRadius": 200
}
}| limit | number [ 1 .. 100 ] Default: 20 Maximum number of devices to return |
| cursor | string Cursor from a previous response to fetch the next page |
| homeId | string Filter by home UUID |
| gatewayId | string Filter devices by gateway UUID. Returns only devices connected through this gateway. |
| includeGateways | boolean Default: false Include gateway devices in the response |
{- "items": [
- {
- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "name": "Living Room Heater",
- "type": "heater",
- "homeId": "aabbccdd-eeff-0011-2233-445500000000",
- "online": true,
- "subtype": "wifi_heater",
- "fwVersion": "1.3",
- "hwVersion": "3.0",
- "gatewayId": null
}
], - "pagination": {
- "limit": 20,
- "cursor": null,
- "nextCursor": null,
- "hasMore": false
}
}{- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "name": "Living Room Heater",
- "type": "heater",
- "homeId": "aabbccdd-eeff-0011-2233-445500000000",
- "online": true,
- "subtype": "wifi_heater",
- "fwVersion": "1.3",
- "hwVersion": "3.0",
- "gatewayId": null
}| deviceId required | string <uuid> |
| name | string New display name for the device |
{- "name": "Bedroom Heater"
}{- "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
- "name": "Living Room Heater",
- "type": "heater",
- "homeId": "aabbccdd-eeff-0011-2233-445500000000",
- "online": true,
- "subtype": "wifi_heater",
- "fwVersion": "1.3",
- "hwVersion": "3.0",
- "gatewayId": null
}Fields depend on the device type. Gateways report online and discovery instead of a mode. Fields only the device itself can report (a power meter power, a gateway powerBudget) need live=true, which reads them from the device on that request.
| deviceId required | string <uuid> |
| live | boolean Default: false Also read the fields that only the device itself can report: a power meter |
{- "type": "gateway",
- "online": true,
- "discovery": false,
- "powerBudget": {
- "type": "surplus",
- "power": 2500,
- "remainingSeconds": 3412,
- "expiresAt": "2026-11-11T18:56:52.000Z"
}
}{- "property1": {
- "type": "boolean",
- "key": "locked",
- "label": "Keyboard Lock Enabled",
- "description": "Prevents changes from the buttons on the device.",
- "sensitive": true,
- "value": false,
- "editable": true
}, - "property2": {
- "type": "boolean",
- "key": "locked",
- "label": "Keyboard Lock Enabled",
- "description": "Prevents changes from the buttons on the device.",
- "sensitive": true,
- "value": false,
- "editable": true
}
}| deviceId required | string <uuid> |
| key required | string |
{- "type": "boolean",
- "key": "locked",
- "label": "Keyboard Lock Enabled",
- "description": "Prevents changes from the buttons on the device.",
- "sensitive": true,
- "value": false,
- "editable": true
}| deviceId required | string <uuid> |
| key required | string |
| value required | boolean New boolean value |
{- "value": false
}{- "type": "boolean",
- "key": "locked",
- "label": "Keyboard Lock Enabled",
- "description": "Prevents changes from the buttons on the device.",
- "sensitive": true,
- "value": false,
- "editable": true
}The commands this device takes, each with its parameters and their constraints. Gateways list setDiscovery, plus setPowerBudgetLimit, setPowerBudgetSurplus and cancelPowerBudget when their firmware has a power budget.
| deviceId required | string <uuid> |
{- "setDiscovery": {
- "description": "Turns pairing mode on or off: while it is on, the gateway looks for new devices to add.",
- "params": {
- "enabled": {
- "type": "boolean",
- "description": "true to start, false to stop",
- "required": true
}
}
}, - "setPowerBudgetLimit": {
- "description": "Sets a temporary power budget that caps what the gateway's devices may draw in total, for a while. It is not the gateway's configured power limit, which it leaves untouched: the cap is added on top of the existing limits and never loosens them. Replaces any active power budget.",
- "params": {
- "power": {
- "type": "number",
- "description": "Watts the gateway's devices may draw in total",
- "constraints": {
- "min": 1000,
- "max": 60000,
- "step": 1
}, - "required": true
}, - "durationMinutes": {
- "type": "number",
- "description": "How long the budget lasts. Without it, the gateway keeps it for 60 minutes. A budget is not kept if the gateway loses power, so send it again before it ends to keep one active.",
- "constraints": {
- "min": 1,
- "max": 1440,
- "step": 1
}, - "required": false
}
}
}, - "setPowerBudgetSurplus": {
- "description": "Lets the gateway's devices use up to `power` W in total from surplus heating, for a while, in place of the meters as the source of surplus. `power` is what is available for these devices, not a meter reading: the gateway already subtracts what they consume, so sending the current grid export counts them twice and makes them switch on and off. Send what is available for them instead, such as a PV forecast minus the house base load. Replaces any active power budget.",
- "params": {
- "power": {
- "type": "number",
- "description": "Watts of surplus available for the gateway's devices",
- "constraints": {
- "min": 500,
- "max": 60000,
- "step": 1
}, - "required": true
}, - "durationMinutes": {
- "type": "number",
- "description": "How long the budget lasts. Without it, the gateway keeps it for 60 minutes. A budget is not kept if the gateway loses power, so send it again before it ends to keep one active.",
- "constraints": {
- "min": 1,
- "max": 1440,
- "step": 1
}, - "required": false
}
}
}, - "cancelPowerBudget": {
- "description": "Ends the active power budget, whatever its type. The gateway goes back to its usual limits at once.",
- "params": { }
}
}key is one of the commands GET /v1/devices/:deviceId/commands lists for the device, and params must fit the schema listed with it. The body examples are named after the command they go with.
| deviceId required | string <uuid> |
| key required | string Example: setPowerBudgetSurplus A command key from |
object Command parameters. Use GET /devices/:id/commands to discover the expected parameter schema for each command. |
Key: setPowerBudgetSurplus. power is what is available for the gateway devices (for example a PV forecast minus the house base load), not the current grid export: the gateway already subtracts what its devices consume. 500–60000 W, whole watts.
{- "params": {
- "power": 2500,
- "durationMinutes": 60
}
}{- "command": "setPowerBudgetSurplus",
- "state": "APPLIED",
- "appliedAt": "2026-11-11T18:00:00.000Z"
}