> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nolongerevil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CardGroup cols={2}>
  <Card title="Hosted Service API" icon="cloud">
    `https://nolongerevil.com/api/v1` — REST API for cloud-managed devices. Requires an `nle_` API key.
  </Card>

  <Card title="Self-Hosted Control API" icon="server">
    `http://your-server:8082` — Local control API for self-hosted deployments. No auth required by default.
  </Card>
</CardGroup>

***

## 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 |

<Info>
  **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.
</Info>

### 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
```

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

***

## Quick Start

### Self-Hosted: Send a Command

No API key needed. Just POST to port 8082:

```bash theme={null}
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

```bash theme={null}
curl http://your-server:8082/status?serial=02AB01AC012345678
```

### Hosted Service: List Devices

```bash theme={null}
curl https://nolongerevil.com/api/v1/devices \
  -H "Authorization: Bearer nle_your_api_key_here"
```

***

## Response Format

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    "object_key": "shared.02AB01AC012345678",
    "values": { "target_temperature": 21.5 }
  }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "message": "Unknown command: set_foo"
}
```

***

## API Sections

<CardGroup cols={2}>
  <Card title="Self-Hosted Control API" icon="terminal" href="/api-reference/control/control-overview">
    Commands, status, device management — port 8082
  </Card>

  <Card title="Device Protocol API" icon="microchip" href="/api-reference/thermostat/entry">
    Nest protocol endpoints — port 8000 (advanced/reference)
  </Card>

  <Card title="Hosted Service API" icon="cloud" href="/api-reference/v1/devices">
    REST API for the hosted service at nolongerevil.com
  </Card>

  <Card title="Authentication" icon="shield-check" href="/api-reference/authentication">
    Auth differences between hosted and self-hosted
  </Card>
</CardGroup>