Skip to main content
This feature only exists if you are using the partner control package. If you are using the NOX control package, you can skip this section.
For partners who want to run their own optimization, a set of additional endpoints exposes the heat pump in a form that is ready to optimize. This data is deliberately expressed in a way similar to how a battery would be described: a value representing the current state of the system (the current temperature), an upper and a lower bound, a passive drain, a charge rate, and the electrical power that comes with it. The intent is that no modeling of the heat pump, the domestic hot water tank or the house is required, allowing partners to focus on the optimization itself.

Getting Heat pump information representated as a thermal battery

Each heat pump is exposed as two independent parts: the domestic hot water (DHW) tank and the house. Two endpoints carry the model. current-state returns the measured thermal state and refreshes every 15 minutes; forecast returns the comfort bounds and the expected thermal behaviour as 15-minute records, 72 hours ahead, regenerated hourly. This section works through a complete DHW scheduling decision and introduces each field at the point where it is used. The exhaustive field reference for both endpoints, including the deprecated Q_* variants, is in the API reference.

The battery model

The chart below shows the DHW tank of a single device over roughly 20 hours. DHW tank thermal bounds DHW_temperature (green) is the state of charge; upperbound_Z (red) and lowerbound_X (blue) are the limits it has to stay between. The steep declines are hot water draw-off, which you do not control. The sharp recoveries are heat pump activations, which you do. Scheduling therefore reduces to one binary decision per 15-minute slot: activate, or do not. The rest of this section covers the data needed to make that decision well.

Establishing the current state

The scenario used throughout is a device at 2025-01-15 11:58 UTC, with day-ahead prices low over the early afternoon and high from 17:00 onwards.
cURL
Restricted to the tank, the response is:
DHW_temperature is measured rather than predicted, which makes it the only defensible initial condition for a forward simulation. This endpoint is also what you poll to detect a device drifting towards its comfort bounds.

Comfort bounds and activation constraints

cURL
The forecast returns one record per 15 minutes. The record covering 12:00–12:15 is:
upperbound_Z and lowerbound_X delimit the usable capacity. At 60 °C and 42 °C respectively, a tank measuring 43.0 °C is close to depleted and has roughly 17 °C of headroom. upperbound_Z is the appliance’s maximum DHW setpoint and is effectively constant. lowerbound_X is not. In the chart it rests at 42 °C but rises for isolated 15-minute intervals; each of those is positioned immediately ahead of hot water demand we expect the household to draw, and raises the floor to the temperature required to serve it. Treat such an interval as a deadline, the tank must be at least that warm by then. It is visible only in the forecast, never in the current state, which is the main reason to plan against the forecast rather than react to the measured temperature. tank_activation_limit_temp is a hard precondition. A heat pump only initiates a DHW cycle once the tank has fallen below its own restart threshold, being the appliance’s maximum setpoint minus its hysteresis. We report that threshold; we do not impose it. At 43.0 °C the tank is below the 55 °C limit, so an activation will take effect. Above the limit, a request to heat the tank is accepted by the API and then produces nothing.
Y_avg is the midpoint of the comfort band, (60 + 42) / 2, and used as a reference to calculate T_loss, T_gain & P_if_activated, since these variables are temperature dependent. Y_avg is not a prediction of the tank temperature. It should not be used as the initial condition of a simulation.

Activation profiles

T_gain and P_if_activated describe the consequences of activating. Both are arrays, because both change as an activation progresses. Each array describes one activation, divided into consecutive quarter hours. Index 0 covers minutes 0–15 of that activation, index 1 minutes 15–30, and so on. T_gain is the temperature the water gains over each quarter, in °C; P_if_activated is the average electrical power drawn over the same quarter, in kW.
The indices are positions in time, not selectable power levels. Index 3 is not a higher setting. It is the state of the same activation after 45 minutes of running. An activation beginning at 12:15 rather than 12:00 is read from index 0 of the 12:15 record: the arrays are always relative to the moment of activation, never to the clock.
Tank profiles hold 4 values, covering 1 hour, since DHW cycles on most brands are shorter than that. Space heating and cooling profiles hold 8 values, covering 2 hours. To model an activation running beyond the end of an array, hold its last value. P_if_activated typically increases across the array because the same activation becomes less efficient as it proceeds: a warmer tank requires a higher condensing temperature, which costs more electrical power per unit of heat delivered. That higher power is not available at a lower tank temperature, as heat exchanger sizing caps the input at any given temperature. Read side by side, the two arrays show the efficiency degrading over the cycle: 7.65 °C of gain for 2.37 kW in the first quarter, the same gain for 3.48 kW in the fourth. Note that P_if_activated is returned in kW under both unit settings.

Standing loss and expected demand

T_loss is the temperature the tank loses over the record’s 15-minute slot if it is not activated. It is a scalar rather than an array, since the loss does not depend on how long the heat pump has been running. It is not restricted to insulation losses. T_loss also carries the hot water we expect the household to draw during that interval, so it is a fraction of a degree overnight and can reach several degrees in an interval containing expected demand. Because the value varies per record, a forward simulation must read each record’s own T_loss rather than assume a constant.

Worked example: scheduling a DHW cycle

Starting from the measured 43.0 °C and using the 12:00 record, simulate an activation beginning at the next quarter hour. Per quarter, apply T_gain and subtract T_loss, stopping before upperbound_Z is crossed: Two quarters fit; a third would exceed 60 °C. The activation runs from 12:00 to 12:30 and consumes (2.37 + 2.89) × 0.25 h = 1.32 kWh. That figure is also the answer to how much electrical energy the device can absorb at this moment: 1.32 kWh over 30 minutes, limited by the comfort bound rather than by the compressor rating. Priced against the corresponding day-ahead intervals, it can be compared directly against activating later in the day. To establish when the next activation becomes necessary, continue the simulation past 12:30 without activating, subtracting each record’s T_loss and testing the result against that record’s lowerbound_X. Whichever occurs first, depletion to the standing floor, or a floor raised ahead of expected demand, sets the deadline. The resulting decision is submitted as a schedule:
See 5.2 for the request itself and for the failsafes that can override it, including the cut-off that terminates DHW heating after 1 continuous hour. The pattern generalises to a model predictive controller: take the measured temperature, simulate forward under T_gain while activating and T_loss while not, constrain the trajectory to the bounds, and select the cheapest feasible schedule. Recompute as new data lands, current state every 15 minutes, forecast every hour, retain only the leading slots of each solution, and submit only when the plan changes.
Two refinements to the simulation. T_gain is a gross gain, so the strict per-quarter update is +T_gain − T_loss; for the tank that correction is minor except in intervals carrying expected demand. And the profiles attached to a record are computed by simulating an activation starting from that record’s Y_avg, so their accuracy degrades as your simulated temperature diverges from the middle of the band.

Space heating and cooling

The house battery follows the same structure under different field names: The house additionally returns Y_ideal, the temperature the user sees as his ideal temperature between their comfort bounds. Simulation is identical in form: apply T_heating or T_cooling per quarter while activating and T_natural while not, and keep the trajectory within lowerbound_X and upperbound_Z.

Units

Every example above uses unit=celsius. The endpoints still default to unit=kWh, which returns the same model with state and bounds expressed in kWh and thermal flows as Q_loss / Q_gain / Q_natural in kW. We intend to phase that representation out.
The kWh view is derived from the temperature model through a fixed thermal capacity. For our more advanced models that conversion loses physical meaning and can yield implausible COPs, particularly on systems with fast dynamics such as air-to-air units. The celsius values are what the models produce directly, and will remain correct as those models develop.
Migration carries no functional cost. The P_* fields are returned in kW under either setting, so energy, cost and consumption reporting are unaffected by the change.

Call frequency

The forecast is most accurate over approximately the first 12 hours and degrades gradually beyond that, being dependent on weather forecasts and occupant behaviour. Because it is regenerated hourly, querying it once per hour always returns the current best prediction; polling more frequently returns the same data. Comfort bounds should not be cached. They change when the heat pump switches between heating and cooling operation, and when the user modifies their comfort settings.

Controlling the heat pump

This feature only exists if you are using the partner control package. If you are using the NOX control package, you can skip this section.
Submit a 24-hour steering schedule with POST /device/thermal-control/schedule. The schedule has 96 slots of 15 minutes each, starting from the next quarter-hour (e.g. submit at 10:07 → the schedule runs from 10:15 to 10:00 the next day). Only submit a new schedule when you actually want to change it.
cURL
The house_heating, house_cooling, and tank arrays are shortened to 8 values (2 hours) above for readability. A real request must always send exactly 96 values, one per 15-minute slot covering the next 24 hours.
  • house_heating / house_cooling / tank – arrays of 96 booleans that switch space heating, space cooling, or DHW tank heating on/off for that slot. Only set house_cooling slots to true for devices where has_cooling is true (see steerable_status below).
  • timestamp – optional, defaults to the next quarter-hour. If provided, it must land exactly on a quarter-hour boundary in the future.
Before submitting, check the device’s steerable_status from /devices: steering_enabled and steerable must both be true, and DHW.can_activate_action / room.can_activate_action tell you whether the tank/house can currently accept a new schedule. If steerable is false, general_reason explains why (e.g. reauthentication required, too many heating zones, still learning the device). Failsafes you don’t control:
  • DHW tank heating never runs for more than 1 continuous hour, no matter what the schedule says, unless the following field dhw_max_cycle_time in cycle_config is set to a higher value than 60 minutes in the devices endpoint.
  • If the tank or house temperature drifts outside its comfort bounds, we override the schedule with a failsafe heat/cool action until it’s back in bounds.
On success:
More info at /device/thermal-control/schedule.