API Introduction

Overview of the No Longer Evil APIs — hosted service and self-hosted server

Overview

No Longer Evil exposes two separate APIs depending on how you run it:

Hosted Service API

https://nolongerevil.com/api/v1 — REST API for cloud-managed devices. Requires an nle_ API key.

Self-Hosted Control API

http://your-server:8082 — Local control API for self-hosted deployments. No auth required by default.

---

Two-Port Architecture (Self-Hosted)

The self-hosted server runs two independent HTTP services on different ports:

Port	Purpose	Used By
8000	Device Protocol API — Nest protocol emulation	Thermostats (firmware)
8082	Control API — User/automation-facing control	Dashboard, scripts, integrations

Port 8000 speaks the Nest Cloud Protocol. Thermostats connect here using long-poll subscribe/PUT requests.

Port 8082 is where you send commands, query status, and manage devices. This is the API you call from scripts, Home Assistant, or any automation tool.

Self-Hosted Base URLs

Device Protocol (thermostats):  http://your-server:8000
Control API (you call this):     http://your-server:8082

---

Hosted Service Base URL

https://nolongerevil.com/api/v1

The hosted REST API (/api/v1) does not exist on the self-hosted server. Self-hosted uses a flat control API on port 8082.

---

Quick Start

Self-Hosted: Send a Command

No API key needed. Just POST to port 8082:

curl -X POST http://your-server:8082/command \
  -H "Content-Type: application/json" \
  -d '{"serial": "02AB01AC012345678", "command": "set_temperature", "value": 21.5}'

Self-Hosted: Get Device Status

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

Hosted Service: List Devices

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

---

Response Format

Success Response

{
  "success": true,
  "data": {
    "object_key": "shared.02AB01AC012345678",
    "values": { "target_temperature": 21.5 }
  }
}

Error Response

{
  "success": false,
  "message": "Unknown command: set_foo"
}

---

API Sections

Self-Hosted Control API

Commands, status, device management — port 8082

Device Protocol API

Nest protocol endpoints — port 8000 (advanced/reference)

Hosted Service API

REST API for the hosted service at nolongerevil.com

Authentication

Auth differences between hosted and self-hosted