Get Device Status

Overview

The /thermostat/{deviceId}/status endpoint returns the complete state of a thermostat, including current temperature, target temperature, HVAC mode, fan settings, schedule, and all other device properties.

Endpoint

GET https://nolongerevil.com/api/v1/thermostat/{deviceId}/status

Self-hosted? Use http://localhost:3000/api/v1/thermostat/{deviceId}/status instead.

Authentication

Required Scopes: read Include your API key in the Authorization header:

Authorization: Bearer nle_your_api_key_here

Request

Path Parameters

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID) from the `/devices` endpoint

Headers

Header	Value	Required
`Authorization`	`Bearer nle_your_api_key_here`	Yes

Example Request

GET https://nolongerevil.com/api/v1/thermostat/dev_abc123xyz/status
Authorization: Bearer nle_your_api_key_here

Response

Success Response (200 OK)

{
  "device": {
    "id": "dev_abc123xyz",
    "serial": "02AA01AB01234567",
    "name": "Living Room"
  },
  "state": {
    "shared.02AA01AB01234567": {
      "object_revision": 152,
      "object_timestamp": 1764026373459,
      "value": {
        "target_temperature": 21.5,
        "target_temperature_type": "heat",
        "current_temperature": 20.2,
        "hvac_heater_state": true,
        "hvac_ac_state": false,
        "fan_mode": "auto",
        "auto_away": 0,
        "leaf": false,
        "can_cool": true,
        "can_heat": true,
        "postal_code": "85388",
        "country_code": "US"
      }
    },
    "device.02AA01AB01234567": {
      "object_revision": 89,
      "object_timestamp": 1764026373000,
      "value": {
        "temperature_scale": "C",
        "fan_timer_timeout": 0,
        "compressor_lockout_enabled": true,
        "eco_mode_enabled": false,
        "temperature_lock_enabled": false
      }
    },
    "user.67032595": {
      "object_revision": -23671,
      "object_timestamp": 1764024643855,
      "value": {
        "away": false,
        "name": "Guest",
        "email": "[email protected]"
      }
    },
    "structure.95d0a01f-1c25-447f-ba61-edb275e9ae25": {
      "object_revision": -15172,
      "object_timestamp": 1764024645708,
      "value": {
        "name": "Home",
        "away": false,
        "postal_code": "85388",
        "country_code": "US",
        "time_zone": "America/Chicago"
      }
    }
  }
}

Response Fields

Field	Type	Description
`device`	object	Basic device information
`device.id`	string	Device UUID
`device.serial`	string	Device serial number
`device.name`	string \| null	Custom device name
`state`	object	Object containing all device state data
`state.shared.{serial}`	object	Shared device state (temperature, mode, etc.)
`state.device.{serial}`	object	Device-specific settings
`state.user.{userId}`	object	User-specific settings
`state.structure.{structureId}`	object	Structure/home settings

Key State Fields (shared..value)

Field	Type	Description
`current_temperature`	number	Current room temperature (°C)
`target_temperature`	number	Target temperature (°C)
`target_temperature_type`	string	`"heat"`, `"cool"`, or `"range"`
`target_temperature_low`	number	Low temp for heat-cool mode (°C)
`target_temperature_high`	number	High temp for heat-cool mode (°C)
`hvac_heater_state`	boolean	Heating currently active
`hvac_ac_state`	boolean	Cooling currently active
`hvac_fan_state`	boolean	Fan currently running
`fan_mode`	string	`"auto"`, `"on"`, or `"off"`
`auto_away`	number	0 = home, 2 = away
`can_cool`	boolean	Device supports cooling
`can_heat`	boolean	Device supports heating

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

Cause: Missing or invalid API key.

403 Forbidden

{
  "error": "Access denied to this device"
}

Cause: Your API key doesn’t have permission to access this device. Solution: Check that the device ID is correct and your API key has access to it.

404 Not Found

{
  "error": "Device not found"
}

Cause: Device ID doesn’t exist or you don’t have access to it.

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "retryAfter": "2025-01-24T12:35:00.000Z"
}

Code Examples

curl https://nolongerevil.com/api/v1/thermostat/dev_abc123xyz/status \
  -H "Authorization: Bearer nle_your_api_key_here"

Use Cases

Temperature Monitoring

Poll device status to monitor temperature changes:

async function monitorTemperature(deviceId, callback) {
  setInterval(async () => {
    const status = await getDeviceStatus(deviceId);
    const shared = status.state[`shared.${status.device.serial}`]?.value;

    callback({
      current: shared.current_temperature,
      target: shared.target_temperature,
      heating: shared.hvac_heater_state,
      cooling: shared.hvac_ac_state
    });
  }, 60000); // Every minute
}

monitorTemperature('dev_abc123xyz', (temps) => {
  console.log(`Room: ${temps.current}°C → ${temps.target}°C`);
});

Energy Usage Tracking

Track HVAC system activity:

async function logEnergyUsage(deviceId) {
  const status = await getDeviceStatus(deviceId);
  const shared = status.state[`shared.${status.device.serial}`]?.value;

  const timestamp = new Date().toISOString();
  const usage = {
    timestamp,
    heating: shared.hvac_heater_state,
    cooling: shared.hvac_ac_state,
    fan: shared.hvac_fan_state,
    currentTemp: shared.current_temperature,
    targetTemp: shared.target_temperature
  };

  // Save to database or analytics platform
  await saveToDatabase(usage);
}

Smart Automations

Build conditional logic based on device state:

async function smartAwayMode(deviceId) {
  const status = await getDeviceStatus(deviceId);
  const shared = status.state[`shared.${status.device.serial}`]?.value;

  // If home and temperature is comfortable, don't run HVAC
  if (shared.auto_away === 0) { // Home
    const tempDiff = Math.abs(
      shared.current_temperature - shared.target_temperature
    );

    if (tempDiff < 0.5 && !shared.hvac_heater_state && !shared.hvac_ac_state) {
      console.log('Temperature comfortable, HVAC idle');
      // Could adjust target temp to save energy
    }
  }
}

State Object Keys

The state object contains multiple sub-objects with different types of data:

shared.{serial}: Shared device state (temperature, mode, HVAC status)
device.{serial}: Device-specific settings (scale, timers, locks)
user.{userId}: User preferences and settings
structure.{structureId}: Home/structure-wide settings
schedule.{serial}: Device schedule (if configured)

Object revisions (object_revision) and timestamps (object_timestamp) are used for state synchronization and conflict resolution. You typically don’t need to use these values.

Next Steps

Set Temperature

Change the target temperature

Set Mode

Change HVAC mode

Set Away Mode

Toggle between home and away

List Devices

Get all your devices

API Documentation

User API (v1)

Overview

Endpoint

Authentication

Request

Path Parameters

Headers

Example Request

Response

Success Response (200 OK)

Response Fields

Key State Fields (shared..value)

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

Code Examples

Use Cases

Temperature Monitoring

Energy Usage Tracking

Smart Automations

State Object Keys

Next Steps

Set Temperature

Set Mode

Set Away Mode

List Devices

API Documentation

User API (v1)

​Overview

​Endpoint

​Authentication

​Request

​Path Parameters

​Headers

​Example Request

​Response

​Success Response (200 OK)

​Response Fields

​Key State Fields (shared..value)

​Error Responses

​401 Unauthorized

​403 Forbidden

​404 Not Found

​429 Too Many Requests

​Code Examples

​Use Cases

​Temperature Monitoring

​Energy Usage Tracking

​Smart Automations

​State Object Keys

​Next Steps

Set Temperature

Set Mode

Set Away Mode

List Devices

Overview

Endpoint

Authentication

Request

Path Parameters

Headers

Example Request

Response

Success Response (200 OK)

Response Fields

Key State Fields (shared..value)

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

Code Examples

Use Cases

Temperature Monitoring

Energy Usage Tracking

Smart Automations

State Object Keys

Next Steps