Get Device Status

Retrieve complete device state including temperature, mode, and settings

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

Hosted service only. This endpoint is part of the hosted API at https://nolongerevil.com/api/v1 and requires an nle_ API key. It is not available on the self-hosted server.

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": "[e-mail]"
      }
    },
    "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

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