Get Thermal Control Current State

curl --request GET \
  --url https://api.nox.energy/v1/device/thermal-control/current-state \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.nox.energy/v1/device/thermal-control/current-state"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.nox.energy/v1/device/thermal-control/current-state', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nox.energy/v1/device/thermal-control/current-state",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nox.energy/v1/device/thermal-control/current-state"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.nox.energy/v1/device/thermal-control/current-state")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nox.energy/v1/device/thermal-control/current-state")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "device_id": "HP123456",
    "timestamp": "2025-01-15 12:15:12",
    "tank": {
      "Y": 25.12,
      "DHW_temperature": 47,
      "Q_loss": 0.25,
      "Q_gain": [
        16.35,
        16.35,
        16.35,
        16.35
      ],
      "P_if_activated": [
        2.38,
        2.87,
        3.18,
        3.31
      ]
    },
    "house": {
      "Y": 521.76,
      "Q_natural": -2.04,
      "Q_heating": [
        8.26,
        8.26,
        8.26,
        8.26,
        8.26,
        8.26,
        8.26,
        8.26
      ],
      "Q_cooling": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ],
      "P_heating": [
        1.8,
        1.8,
        1.8,
        1.8,
        1.8,
        1.8,
        1.8,
        1.8
      ],
      "P_cooling": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    }
  },
  "meta": {
    "timestamp_time_zone": "UTC",
    "temperature_unit": "°C",
    "tank_Y_unit": "kWh",
    "tank_Q_loss_unit": "kW",
    "tank_Q_gain_unit": "kW",
    "tank_P_unit": "kW",
    "house_Y_unit": "kWh",
    "house_Q_natural_unit": "kW",
    "house_Q_heating_unit": "kW",
    "house_Q_cooling_unit": "kW",
    "house_P_heating_unit": "kW",
    "house_P_cooling_unit": "kW",
    "energy_supplier": "Energy Supplier A"
  }
}

Thermal Control

Get Thermal Control Current State

Get the current thermal state of a specific device.

This returns the most recent 15-minute snapshot of the thermal model state for both the domestic hot water (DHW) tank and the house (space heating/cooling). It reflects the latest known thermal energy flows, temperatures, and heat pump power consumption.

Tank fields:

Y (kWh mode only) — Current energy state of the DHW tank.
DHW_temperature — Current domestic hot water temperature in °C (always present).
Q_loss / Q_gain (kW) or T_loss / T_gain (°C) — Thermal loss to the environment and gain per activation level.
P_if_activated — Electrical power consumption (kW) per activation level if the heat pump is activated for DHW.

House fields:

Y (kWh mode only) — Current energy state of the house.
Space_temperature (celsius mode only) — Current room temperature in °C.
Q_natural / Q_heating / Q_cooling (kW) or T_natural / T_heating / T_cooling (°C) — Natural thermal drift, and heating/cooling effect per activation level.
P_heating / P_cooling — Electrical power consumption (kW) per activation level for space heating and cooling.

Use the unit query parameter to choose between energy values (kWh, default) or temperature equivalents (celsius / °C). In celsius mode, bounds are returned in °C and thermal flows as temperature change rates (°C per 15min) instead of energy (kWh/kW). Power fields (P_*) are always returned in kW regardless of the unit choice.

The timestamp refers to the data that will happen in the next 15 minutes after the timestamp. All timestamps are in UTC.

GET

device

thermal-control

current-state

Get Thermal Control Current State

curl --request GET \
  --url https://api.nox.energy/v1/device/thermal-control/current-state \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.nox.energy/v1/device/thermal-control/current-state"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.nox.energy/v1/device/thermal-control/current-state', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nox.energy/v1/device/thermal-control/current-state",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nox.energy/v1/device/thermal-control/current-state"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.nox.energy/v1/device/thermal-control/current-state")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nox.energy/v1/device/thermal-control/current-state")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "device_id": "HP123456",
    "timestamp": "2025-01-15 12:15:12",
    "tank": {
      "Y": 25.12,
      "DHW_temperature": 47,
      "Q_loss": 0.25,
      "Q_gain": [
        16.35,
        16.35,
        16.35,
        16.35
      ],
      "P_if_activated": [
        2.38,
        2.87,
        3.18,
        3.31
      ]
    },
    "house": {
      "Y": 521.76,
      "Q_natural": -2.04,
      "Q_heating": [
        8.26,
        8.26,
        8.26,
        8.26,
        8.26,
        8.26,
        8.26,
        8.26
      ],
      "Q_cooling": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ],
      "P_heating": [
        1.8,
        1.8,
        1.8,
        1.8,
        1.8,
        1.8,
        1.8,
        1.8
      ],
      "P_cooling": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    }
  },
  "meta": {
    "timestamp_time_zone": "UTC",
    "temperature_unit": "°C",
    "tank_Y_unit": "kWh",
    "tank_Q_loss_unit": "kW",
    "tank_Q_gain_unit": "kW",
    "tank_P_unit": "kW",
    "house_Y_unit": "kWh",
    "house_Q_natural_unit": "kW",
    "house_Q_heating_unit": "kW",
    "house_Q_cooling_unit": "kW",
    "house_P_heating_unit": "kW",
    "house_P_cooling_unit": "kW",
    "energy_supplier": "Energy Supplier A"
  }
}

Authorizations

x-api-key

string

header

required

API Key authentication. Enter your API key in the format: YOUR_API_KEY

Query Parameters

device_id

string

required

The ID of the device.

unit

enum<string>

default:kWh

Unit for thermal values returned in the response.

'kWh' (default) returns energy in kWh and power in kW.

'celsius' returns temperature equivalents in °C.

Available options:

kWh,

celsius

Response

Successful response

Get Thermal Control Forecast Submit Thermal Control Schedule

API setup

Full NOX Control Package

Supplier Control Package

Manufacturer Package

Connecting Users and Devices

PV

Get Thermal Control Current State

Authorizations

Query Parameters

Response