Skip to main content
To fetch all devices configuration data you can call the following endpoint:
cURL
However, how you should use the /devices endpoint is to fetch device info after the user completed the authentication flow. You should have received the user_id and/or device_id in the redirect_uri callback parameters. Use the parameters received from the redirect and the /devices endpoint to fetch on a per user_id or per device_id basis. This can be done using the query parameters like the below example:
cURL
Key response fields:
  • device_id - Unique identifier per device. Each nox user_id can have multiple device_id’s.
  • brand - Manufacturer brand of the device. We currently only support 1 heat pump brand per user. If a user has multiple brands, during the auth process, a new user_id is created.
  • model_type - Signifies the type of device (e.g. air-to-water/air-to-air/… device)
  • has_delayed_power_data_1d - Signifies if the device can or cannot provide real-time power data but instead provides its power data with a delay of 1 day between 2-4 AM UTC of the full previous day.
If there is a need to have real-time data updates on specific fields. You can request us to see data change events from some of these fields like needs_reauthentication through our webhook. You can communicate to us which fields you are interested in and we can set up a custom webhook with a POST endpoint you provide to us and you will receive real-time updates on change events. We suggest you read Partner webhooks page for more info. Alternatively, you can also use the /devices/telemetry/current endpoint to poll for current telemetry data. This is only recommended if you are interested to show real time data temporarily for users when they are interacting with your app. This is not meant as a solution to have consistently higher granularity telemetry data. If you want higher granularity telemetry data then we recommend you to use our webhook solution to receive real-time updates on change events. A lot of query parameters exist on the /devices we recommend you to use them if relevant, to reduces the size of data transfer.

Showing how NOX steers a device

steerable_status.steering_method on /devices tells you what NOX changes on the heat pump when it steers it. Use it to explain to your users what they will see on their heat pump or in its app, for example why their target room temperature changes during the day, or why their hot water schedule is paused. Every value is a code, not text, so you write what your users see, in their own language. New codes may be added in any release; the meaning of an existing code never changes. Show a code you don’t know generically, for example as “NOX may change this setting”. It is structured per steered function, then per setting:
steering_method is null when the device isn’t steerable, for air to air heat pumps, and for brands or models whose steering NOX doesn’t describe. The order of settings and of reasons carries no meaning.

Steered functions

What the heat pump does for the home. A function is null when NOX does not steer it on this device. Each function holds:
  • schedule_paused: true when the user’s own schedule (time program) for this function is paused while NOX steers.
  • settings: the settings NOX changes for this function. A setting that isn’t listed is never touched by NOX.

Settings

A value on the heat pump that NOX changes to steer a function.

Uses

How often NOX changes a setting. when_needed and rarely always come with at least one reason; the other uses never have one.

Reasons

Why NOX changes a setting whose use is when_needed or rarely. A setting can have several.

Example: from codes to text

NOX builds the English description from four building blocks. You can do the same in any language. Take this steering method:
Each field becomes one part of the text: Together, this is the description NOX returns:
For space heating, NOX changes the target room temperature. For hot water, NOX changes the target hot water temperature. NOX follows the heating mode you set on your heat pump. It only changes this mode to start heating when your home is too cold and the heating is set to another mode. To keep steering reliable, NOX may also switch the hot water mode if your heat pump is in a mode where NOX’s settings have no effect. Your own space heating schedule is paused while NOX steers.
steering_method.description is NOX’s English rendering of the same information, built from the settings, their use and their reasons. Show it as-is in an English app, or build your own text from the codes.

All steering methods

Every steering method NOX currently returns, with the description that comes with it. Expand the table to see, per function, each setting with its use and reasons. When NOX adds a brand, a model or a code, this list is updated.
#Space heatingSpace coolingHot water
1schedule paused
room_setpoint
  every_action
operation_mode
  rarely
   ↳ comfort_start
room_setpoint
  every_action
operation_mode
  user_controlled
schedule paused
dhw_setpoint
  every_action
operation_mode
  when_needed
   ↳ schedule_would_override
For space heating and cooling, NOX changes the target room temperature. For hot water, NOX changes the target hot water temperature. NOX follows the heating and cooling modes you set on your heat pump. It only changes the heating mode to start heating when your home is too cold and the heating is set to another mode. To keep steering reliable, NOX may also switch the hot water mode if your own time program would override NOX. Your own space heating and hot water schedules are paused while NOX steers.
2schedule paused
room_setpoint
  every_action
flow_temperature_setpoint
  every_action
operation_mode
  rarely
   ↳ comfort_start
room_setpoint
  every_action
operation_mode
  user_controlled
schedule paused
dhw_setpoint
  every_action
operation_mode
  when_needed
   ↳ schedule_would_override
For space heating, NOX changes the target room temperature and water temperature in the heating circuit. For cooling, NOX changes the target room temperature. For hot water, NOX changes the target hot water temperature. NOX follows the heating and cooling modes you set on your heat pump. It only changes the heating mode to start heating when your home is too cold and the heating is set to another mode. To keep steering reliable, NOX may also switch the hot water mode if your own time program would override NOX. Your own space heating and hot water schedules are paused while NOX steers.
3——schedule paused
dhw_setpoint
  every_action
operation_mode
  when_needed
   ↳ schedule_would_override
For hot water, NOX changes the target hot water temperature. To keep steering reliable, NOX may also switch the hot water mode if your own time program would override NOX. Your own hot water schedule is paused while NOX steers.
4schedule paused
operation_mode
  every_action
room_setpoint
  every_action
flow_temperature_setpoint
  every_action
schedule paused
flow_temperature_setpoint
  every_action
operation_mode
  when_needed
   ↳ mode_blocks_steering
dhw_setpoint
  every_action
For space heating, NOX changes the heating mode, target room temperature and water temperature in the heating circuit. For cooling, NOX changes the water temperature in the cooling circuit. For hot water, NOX changes the target hot water temperature. To keep steering reliable, NOX may also switch the cooling mode if your heat pump is in a mode where NOX’s settings have no effect. Your own space heating and cooling schedules are paused while NOX steers.
5schedule paused
operation_mode
  every_action
room_setpoint
  every_action
schedule paused
operation_mode
  every_action
room_setpoint
  every_action
schedule paused
dhw_setpoint
  every_action
operation_mode
  when_needed
   ↳ mode_blocks_steering
   ↳ mode_is_off_switch
For space heating, NOX changes the heating mode and target room temperature. For cooling, NOX changes the cooling mode and target room temperature. For hot water, NOX changes the target hot water temperature. To keep steering reliable, NOX may also switch the hot water mode if your heat pump is in a mode where NOX’s settings have no effect or when that is the only way to stop heating. Your own space heating, cooling and hot water schedules are paused while NOX steers.
6schedule paused
room_setpoint
  every_action
operation_mode
  rarely
   ↳ comfort_start
   ↳ schedule_would_override
schedule paused
room_setpoint
  every_action
operation_mode
  rarely
   ↳ schedule_would_override
schedule paused
dhw_setpoint
  every_action
operation_mode
  when_needed
   ↳ mode_blocks_steering
   ↳ schedule_would_override
For space heating and cooling, NOX changes the target room temperature. For hot water, NOX changes the target hot water temperature. NOX follows the heating and cooling modes you set on your heat pump. It only changes the heating mode to start heating when your home is too cold and the heating is set to another mode or if your own time program would override NOX. It only changes the cooling mode if your own time program would override NOX. To keep steering reliable, NOX may also switch the hot water mode if your heat pump is in a mode where NOX’s settings have no effect or if your own time program would override NOX. Your own space heating, cooling and hot water schedules are paused while NOX steers.
7schedule paused
operation_mode
  every_action
schedule paused
operation_mode
  every_action
schedule paused
dhw_setpoint
  every_action
operation_mode
  when_needed
   ↳ mode_blocks_steering
   ↳ schedule_would_override
For space heating, NOX changes the heating mode. For cooling, NOX changes the cooling mode. For hot water, NOX changes the target hot water temperature. To keep steering reliable, NOX may also switch the hot water mode if your heat pump is in a mode where NOX’s settings have no effect or if your own time program would override NOX. Your own space heating, cooling and hot water schedules are paused while NOX steers.
8operation_mode
  every_action
room_setpoint
  every_action
flow_temperature_setpoint
  every_action
—operation_mode
  every_action
For space heating, NOX changes the heating mode, target room temperature and water temperature in the heating circuit. For hot water, NOX changes the hot water mode.
9room_setpoint
  every_action
operation_mode
  when_needed
   ↳ mode_blocks_steering
room_setpoint
  every_action
operation_mode
  when_needed
   ↳ mode_blocks_steering
—
For space heating and cooling, NOX changes the target room temperature. To keep steering reliable, NOX may also switch the heating and cooling modes if your heat pump is in a mode where NOX’s settings have no effect.
10flow_temperature_setpoint
  every_action
operation_mode
  when_needed
   ↳ mode_blocks_steering
flow_temperature_setpoint
  every_action
operation_mode
  when_needed
   ↳ mode_blocks_steering
—
For space heating, NOX changes the water temperature in the heating circuit. For cooling, NOX changes the water temperature in the cooling circuit. To keep steering reliable, NOX may also switch the heating and cooling modes if your heat pump is in a mode where NOX’s settings have no effect.
11——dhw_setpoint
  every_action
operation_mode
  when_needed
   ↳ mode_blocks_steering
For hot water, NOX changes the target hot water temperature. To keep steering reliable, NOX may also switch the hot water mode if your heat pump is in a mode where NOX’s settings have no effect.
12schedule paused
operation_mode
  every_action
room_setpoint
  every_action
—dhw_setpoint
  every_action
For space heating, NOX changes the heating mode and target room temperature. For hot water, NOX changes the target hot water temperature. Your own space heating schedule is paused while NOX steers.
13——dhw_setpoint
  every_action
For hot water, NOX changes the target hot water temperature.