Skip to main content

​
Overview

The No Longer Evil API is a modern REST API that lets you programmatically control your thermostats, monitor temperature, and integrate with home automation systems.

Secure Authentication

API key authentication with Bearer tokens and granular permission scopes

Comprehensive Control

Temperature, mode, fan, away mode, schedules, and more

Rate Limited

Built-in rate limiting to protect the service (20 req/min for API keys)

RESTful Design

Clean, predictable endpoints with JSON requests and responses

​
Base URL

All API requests should be made to: 
https://nolongerevil.com/api/v1
Self-hosted users: Replace the base URL with your own domain or use http://localhost:3000/api/v1 for local development.

​
Getting Started

​
1. Get an API Key

Navigate to https://nolongerevil.com/settings and click on the API Keys tab to generate your first API key. When creating an API key, you’ll configure:
  • Name: A descriptive name for the key
  • Scopes: read (view status) and/or write (control devices)
  • Device restrictions: Optional limits to specific devices
API keys are shown only once when created. Store them securely!

​
2. Make Your First Request

Use your API key to list your devices: 
curl https://nolongerevil.com/api/v1/devices \
  -H "Authorization: Bearer nle_your_api_key_here"

​
3. Control Your Thermostat

Set the temperature: 
curl -X POST https://nolongerevil.com/api/v1/thermostat/{deviceId}/temperature \
  -H "Authorization: Bearer nle_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"value": 72, "mode": "heat", "scale": "F"}'

​
Authentication

All API requests require authentication using an API key in the Authorization header: 
Authorization: Bearer nle_your_api_key_here
API keys support two permission scopes:
  • read: View device status and settings
  • write: Control devices (temperature, mode, fan, etc.)
Learn more in the Authentication Guide.

​
Request Format

All requests use JSON for request bodies with clear, RESTful endpoints.

​
Example: Set Temperature

POST /api/v1/thermostat/{deviceId}/temperature
Content-Type: application/json
Authorization: Bearer nle_your_api_key_here

{
  "value": 72,
  "mode": "heat",
  "scale": "F"
}

​
Example: List Devices

GET /api/v1/devices
Authorization: Bearer nle_your_api_key_here

​
Response Format

All responses are JSON with consistent structure:

​
Success Response

{
  "success": true,
  "message": "Command handled",
  "device": "02AA01AB01234567",
  "revision": 155,
  "timestamp": 1764026377395
}

​
Error Response

{
  "error": "Temperature value must be a number"
}

​
Rate Limits

Rate limits are actively enforced to protect the service:
Authentication TypeLimitWindow
User accounts (Clerk)100 requestsPer minute
API keys20 requestsPer minute
Rate Limit Headers (included in all responses): 
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 2025-01-24T12:34:56.000Z
When rate limited, you’ll receive a 429 Too Many Requests response: 
{
  "error": "Rate limit exceeded",
  "retryAfter": "2025-01-24T12:35:00.000Z"
}
Monitor the X-RateLimit-Remaining header to track your usage and avoid hitting the limit.

​
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

All errors return a JSON object with an error field: Validation Error (400): 
{
  "error": "Temperature value must be a number"
}
Authentication Error (401): 
{
  "error": "Unauthorized"
}
Permission Error (403): 
{
  "error": "Access denied to this device"
}
Rate Limit Error (429): 
{
  "error": "Rate limit exceeded",
  "retryAfter": "2025-01-24T12:35:00.000Z"
}

​
Available Endpoints

The API provides comprehensive control over your thermostats:

​
Device Management

  • GET /devices - List all accessible devices
  • GET /thermostat//status - Get device status and settings
  • DELETE /thermostat/ - Remove device from account

​
Temperature Control

  • POST /thermostat//temperature - Set target temperature
  • POST /thermostat//temperature/range - Set temperature range (heat-cool mode)

​
HVAC Control

  • POST /thermostat//mode - Set HVAC mode (heat/cool/auto/off)
  • POST /thermostat//away - Toggle away mode
  • POST /thermostat//fan - Control fan mode or timer

​
Advanced Features

  • GET/PUT /thermostat//schedule - Manage heating/cooling schedule
  • POST /thermostat//lock - Enable temperature lock with PIN
See the full endpoint documentation in the User API (v1) section.

​
Next Steps

Get an API Key

Create your first API key in Settings

Authentication Guide

Learn about API key authentication and scopes

List Devices

Get all your thermostats

Set Temperature

Start controlling your thermostat