HeatingControl External API (1.11.0 (Draft))

Download OpenAPI specification:

Last updated: 2026-11-16

Overview

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.

Important: API Status and Compatibility

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.

Authentication

The API uses OAuth2 client credentials flow.

  1. Obtain a token — call POST /v1/oauth/token with your client_id and client_secret to receive an access token.
  2. Authorize requests — include the token in the Authorization header:
    Authorization: Bearer <access_token>
    
  3. Token renewal — tokens expire after a limited time. Following RFC 6749 §4.4.3, the 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.

Common workflows

A typical integration follows this sequence:

  1. Authenticate — obtain an access token.
  2. List homes — GET /v1/homes to discover available homes.
  3. List devices — GET /v1/devices to enumerate devices (optionally filter by homeId).
  4. Read device state — 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).
  5. Read device settings — GET /v1/devices/{deviceId}/settings to read current settings.
  6. Send commands — POST /v1/devices/{deviceId}/commands/{key} to control a device.

Developer journey: controlling electric heaters

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.

Step 1 — Obtain an access token

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>.

Step 2 — List your devices

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.

Step 3 — Read the state of a heater

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.

Step 4 — Change the mode and temperature

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"
}

Step 5 — Read the power of another heater

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.

Step 6 — Explore device settings

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 }'

Live readings

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>"
  • A live read waits for the device, so it is slower than a plain state read. Only ask for it when you need those fields.
  • If the device doesn't answer, the field is null and the rest of the state is still returned.
  • A heater's power is not a live field: it is always present.

Gateways

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.

Power budget

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.

  • The exact ranges, and a description of each command, are in GET /v1/devices/<gatewayId>/commands.
  • If the gateway doesn't answer a command, the API returns 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.
  • A budget ends on its own, and a gateway that loses power starts with none. To keep one active, send it again before it expires (every 15 minutes, for example).

Pagination

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.

Error handling

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).

Auth

Obtain access tokens

Obtain an access token

header Parameters
authorization
required
string
Request Body schema: application/json
required
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 /devs/*:R or /devs/*:W.

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials",
  • "client_id": "string",
  • "client_secret": "string",
  • "scope": "/devs/*:W"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIs...",
  • "expires_in": 3600,
  • "token_type": "Bearer"
}

Homes

List and retrieve homes

List homes

Authorizations:
bearer
query Parameters
limit
number [ 1 .. 100 ]
Default: 20

Maximum number of homes to return

cursor
string

Cursor from a previous response to fetch the next page

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Get a home

Authorizations:
bearer
path Parameters
homeId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "aabbccdd-eeff-0011-2233-445500000000",
  • "name": "My Home",
  • "deviceCount": 3,
  • "location": {
    }
}

Devices

Manage devices, state, settings, and commands

List devices

Authorizations:
bearer
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Get device info

Authorizations:
bearer
path Parameters
deviceId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "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
}

Update device metadata

Authorizations:
bearer
path Parameters
deviceId
required
string <uuid>
Request Body schema: application/json
required
name
string

New display name for the device

Responses

Request samples

Content type
application/json
{
  • "name": "Bedroom Heater"
}

Response samples

Content type
application/json
{
  • "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
}

Get device state

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.

Authorizations:
bearer
path Parameters
deviceId
required
string <uuid>
query Parameters
live
boolean
Default: false

Also read the fields that only the device itself can report: a power meter power and a gateway powerBudget. These need a round trip to the device, so they are left out unless asked for, and are null when the device does not answer.

Responses

Response samples

Content type
application/json
Example
{
  • "type": "gateway",
  • "online": true,
  • "discovery": false,
  • "powerBudget": {
    }
}

Get device settings

Authorizations:
bearer
path Parameters
deviceId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Get a specific device setting

Authorizations:
bearer
path Parameters
deviceId
required
string <uuid>
key
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "type": "boolean",
  • "key": "locked",
  • "label": "Keyboard Lock Enabled",
  • "description": "Prevents changes from the buttons on the device.",
  • "sensitive": true,
  • "value": false,
  • "editable": true
}

Update a device setting

Authorizations:
bearer
path Parameters
deviceId
required
string <uuid>
key
required
string
Request Body schema: application/json
required
One of
value
required
boolean

New boolean value

Responses

Request samples

Content type
application/json
Example
{
  • "value": false
}

Response samples

Content type
application/json
Example
{
  • "type": "boolean",
  • "key": "locked",
  • "label": "Keyboard Lock Enabled",
  • "description": "Prevents changes from the buttons on the device.",
  • "sensitive": true,
  • "value": false,
  • "editable": true
}

List available commands

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.

Authorizations:
bearer
path Parameters
deviceId
required
string <uuid>

Responses

Response samples

Content type
application/json
Example
{
  • "setDiscovery": {
    },
  • "setPowerBudgetLimit": {
    },
  • "setPowerBudgetSurplus": {
    },
  • "cancelPowerBudget": {
    }
}

Execute a command

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.

Authorizations:
bearer
path Parameters
deviceId
required
string <uuid>
key
required
string
Example: setPowerBudgetSurplus

A command key from GET /v1/devices/:deviceId/commands

Request Body schema: application/json
required
object

Command parameters. Use GET /devices/:id/commands to discover the expected parameter schema for each command.

Responses

Request samples

Content type
application/json
Example

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": {
    }
}

Response samples

Content type
application/json
{
  • "command": "setPowerBudgetSurplus",
  • "state": "APPLIED",
  • "appliedAt": "2026-11-11T18:00:00.000Z"
}
Postman Collection OpenAPI Spec