Skip to main content

​
Overview

Returns the complete current state for a single device, including temperatures, HVAC state, capabilities, and availability.

​
Endpoint

GET http://your-server:8082/status?serial={serial}

​
Query Parameters

ParameterTypeRequiredDescription
serialstringYesDevice serial number

​
Response

​
Success (200 OK)

{
  "serial": "02AB01AC012345678",
  "api_key": "02AB01AC012345678",
  "is_available": true,
  "last_seen": "2026-04-01T12:00:00",
  "name": "Living Room",
  "current_temperature": 20.5,
  "target_temperature": 21.0,
  "target_temperature_high": null,
  "target_temperature_low": null,
  "humidity": 45,
  "target_humidity": null,
  "target_humidity_enabled": false,
  "mode": "heat",
  "hvac": {
    "heater": true,
    "heat_x2": false,
    "heat_x3": false,
    "ac": false,
    "cool_x2": false,
    "cool_x3": false,
    "fan": false,
    "aux_heat": false,
    "emer_heat": false,
    "alt_heat": false,
    "humidifier": false,
    "dehumidifier": false,
    "auto_dehum": false,
    "fan_cooling": false
  },
  "fan_timer_active": false,
  "fan_timer_timeout": 0,
  "eco_temperatures": {
    "high": 26.0,
    "low": 15.5
  },
  "is_online": true,
  "has_leaf": false,
  "software_version": "5.9.3-5",
  "temperature_scale": "C",
  "capabilities": {
    "can_heat": true,
    "can_cool": false,
    "has_fan": false,
    "has_emer_heat": false,
    "has_humidifier": false,
    "has_dehumidifier": false
  },
  "eco_mode": "schedule",
  "time_to_target": 15,
  "time_to_target_training_status": "trained",
  "safety_state": null,
  "safety_temp_activating_hvac": null,
  "learning_mode": true,
  "preconditioning_enabled": false,
  "backplate_temperature": 20.1,
  "structure_id": "abc123",
  "away": false,
  "schedule_mode": "HEAT"
}

​
Response Fields

FieldTypeDescription
serialstringDevice serial number
api_keystringDevice API key (same as serial for self-hosted)
is_availablebooleanWhether the device is currently reachable
last_seenstring | nullISO 8601 timestamp of last device activity
namestringDevice display name
current_temperaturenumber | nullAmbient temperature in °C
target_temperaturenumber | nullTarget setpoint in °C (single-mode)
target_temperature_highnumber | nullTarget high in °C (heat-cool range mode)
target_temperature_lownumber | nullTarget low in °C (heat-cool range mode)
humiditynumber | nullCurrent relative humidity (%)
target_humiditynumber | nullTarget humidity (%)
target_humidity_enabledbooleanWhether humidity control is active
modestring | nullActive HVAC mode (heat, cool, range, off, emergency)
hvacobjectCurrent HVAC equipment runtime states
hvac.heaterbooleanHeater running
hvac.acbooleanAC running
hvac.fanbooleanFan running
hvac.aux_heatbooleanAuxiliary heat running
fan_timer_activebooleanWhether fan timer is active
fan_timer_timeoutnumberFan timer expiry (Unix seconds)
eco_temperaturesobjectEco mode temperature bounds
eco_temperatures.highnumber | nullEco upper bound in °C
eco_temperatures.lownumber | nullEco lower bound in °C
is_onlinebooleanWhether the device self-reports as online
has_leafbooleanNest Leaf indicator
software_versionstring | nullFirmware version string
temperature_scalestring"C" or "F" (display preference)
capabilitiesobjectEquipment capabilities
capabilities.can_heatbooleanDevice has heating wired
capabilities.can_coolbooleanDevice has cooling wired
capabilities.has_fanbooleanDevice has a fan
capabilities.has_emer_heatbooleanDevice has emergency heat
eco_modestring | nullEco mode state ("schedule", "manual-eco", "auto-eco")
time_to_targetnumber | nullMinutes until target temperature reached
learning_modeboolean | nullWhether learning is enabled
backplate_temperaturenumber | nullBackplate sensor temperature in °C
structure_idstring | nullStructure ID this device belongs to
awaybooleanAway mode flag
schedule_modestring | nullActive schedule mode ("HEAT", "COOL", "RANGE")

​
Error (400 Bad Request)

{"error": "Serial parameter required"}

​
Error (404 Not Found)

{"error": "Device not found"}

​
Example

curl "http://your-server:8082/status?serial=02AB01AC012345678"

​
Next Steps

POST /command

Control the device

GET /api/events

Subscribe to live state changes