Skip to main content

​
Overview

The No Longer Evil API server provides two distinct APIs on different ports:

Thermostat Communication API

Port 443 (HTTPS)Handles direct communication with Nest thermostats

Control API

Port 8081 (HTTP)Provides external control and status monitoring

​
Base URLs

# Thermostat Communication API
https://backdoor.nolongerevil.com

# Control API
http://backdoor.nolongerevil.com:8081

​
API Differences

​
Thermostat Communication API (Port 443)

Purpose: Replicate Google’s Nest API for thermostat compatibility Clients: Nest thermostat devices only Protocol: HTTPS with SSL/TLS Authentication:
  • Basic Auth with device serial number as username
  • Entry key validation for device claiming
Key Features:
  • Device state synchronization (long-polling)
  • Weather data proxying
  • Entry key generation for device linking
  • Object-based state management
This API is designed to be 100% compatible with the original Nest protocol. The thermostat believes it’s talking to Google’s servers.

​
Control API (Port 8081)

Purpose: Provide external control interface for dashboards and automation Clients: Web frontends, mobile apps, home automation systems Protocol: HTTP (can be localhost-only for security) Authentication: Optional (add your own if exposing publicly) Key Features:
  • Simple command interface (set temperature, mode)
  • Device status queries
  • List all connected devices
  • Real-time status updates
The Control API has no built-in authentication by default. If exposing publicly, implement authentication at the reverse proxy level or modify the server code.

​
Data Format

All APIs use JSON for request/response bodies.

​
Thermostat Communication API

Uses Nest’s proprietary object-key format: 
{
  "objects": {
    "device.SERIAL": {
      "current_temperature": 21.5,
      "target_temperature": 22.0,
      "hvac_mode": "heat"
    },
    "shared.SERIAL": {
      "name": "Living Room",
      "target_temperature_high": 24.0,
      "target_temperature_low": 18.0
    }
  }
}

​
Control API

Uses simplified command format: 
{
  "serial": "02AB01AC012345678",
  "action": "temp",
  "value": "22"
}

​
Rate Limits

No rate limits currently enforced on hosted service or self-hosted setups.However, excessive requests may impact thermostat performance. Recommended limits:
  • Control API: Max 10 requests/minute per device
  • Status queries: Max 60 requests/minute

​
Error Handling

​
HTTP Status Codes

CodeMeaningCommon Causes
200SuccessRequest processed successfully
400Bad RequestInvalid parameters or malformed JSON
401UnauthorizedInvalid authentication or entry key
404Not FoundDevice or endpoint doesn’t exist
500Server ErrorInternal server error, check logs

​
Error Response Format

{
  "error": "Invalid entry key",
  "code": "INVALID_KEY",
  "details": "Entry key has expired or already been used"
}

​
Long-Polling

The Thermostat Communication API uses long-polling for real-time updates:
  1. Client (thermostat) subscribes via POST /transport with chunked: true
  2. Server keeps connection open
  3. When state changes, server pushes update
  4. Client reconnects after receiving data or timeout
This allows push notifications without WebSockets.

​
State Synchronization

State is managed using a revision-based system:
  • Each object has a $version field
  • Clients send their current version
  • Server returns only changed objects since that version
  • Prevents unnecessary data transfer
Example: 
{
  "device.SERIAL": {
    "$version": "ABCD1234",
    "current_temperature": 21.5
  }
}

​
Next Steps

Authentication

Learn about authentication methods

Thermostat API

Explore thermostat communication endpoints

Control API

Learn to send commands and query status

Examples

See real-world API usage examples