List Devices

Overview

The /devices endpoint returns a list of all thermostats you have access to, including devices you own and devices that have been shared with you.

Endpoint

GET https://nolongerevil.com/api/v1/devices

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

This endpoint requires API key authentication. Required Scopes: read Include your API key in the Authorization header:

Authorization: Bearer nle_your_api_key_here

Request

Headers

Header	Value	Required
`Authorization`	`Bearer nle_your_api_key_here`	Yes

Query Parameters

None.

Response

Success Response (200 OK)

{
  "devices": [
    {
      "id": "dev_abc123xyz",
      "serial": "02AA01AB01234567",
      "name": "Living Room",
      "accessType": "owner"
    },
    {
      "id": "dev_def456uvw",
      "serial": "02AA01AB01234568",
      "name": "Bedroom",
      "accessType": "shared"
    }
  ]
}

Response Fields

Field	Type	Description
`devices`	array	Array of device objects
`devices[].id`	string	Unique device identifier (UUID)
`devices[].serial`	string	Device serial number (17 characters)
`devices[].name`	string \| null	Custom device name (null if not set)
`devices[].accessType`	string	Access level: `"owner"` or `"shared"`

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

Cause: Missing or invalid API key. Solution: Check that your API key is correct and included in the Authorization header.

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "retryAfter": "2025-01-24T12:35:00.000Z"
}

Cause: You’ve exceeded the rate limit (20 requests/minute for API keys). Solution: Wait until the time specified in retryAfter before making another request.

Rate Limiting

Rate Limit	Value
Requests per minute	20 (API keys) / 100 (user accounts)

Rate Limit Headers (included in response):

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 2025-01-24T12:34:56.000Z

Code Examples

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

const API_KEY = 'nle_your_api_key_here';
const BASE_URL = 'https://nolongerevil.com/api/v1';

async function listDevices() {
  const response = await fetch(`${BASE_URL}/devices`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();
  return data.devices;
}

// Usage
listDevices()
  .then(devices => {
    console.log('Found devices:', devices);
    devices.forEach(device => {
      console.log(`- ${device.name || device.serial} (${device.accessType})`);
    });
  })
  .catch(error => console.error('Error:', error));

import requests

API_KEY = 'nle_your_api_key_here'
BASE_URL = 'https://nolongerevil.com/api/v1'

def list_devices():
    headers = {
        'Authorization': f'Bearer {API_KEY}'
    }

    response = requests.get(f'{BASE_URL}/devices', headers=headers)
    response.raise_for_status()

    return response.json()['devices']

# Usage
try:
    devices = list_devices()
    print(f'Found {len(devices)} device(s):')
    for device in devices:
        name = device['name'] or device['serial']
        print(f'- {name} ({device["accessType"]})')
except requests.exceptions.HTTPError as e:
    print(f'Error: {e}')

Use Cases

Home Automation Integration

List all your devices at startup to build a device registry:

// Home Assistant integration example
async function discoverDevices() {
  const devices = await listDevices();

  // Register each device with your automation platform
  devices.forEach(device => {
    registerEntity({
      id: device.id,
      name: device.name || `Thermostat ${device.serial}`,
      type: 'climate',
      capabilities: ['temperature', 'mode', 'fan']
    });
  });
}

Multi-Zone Control

Control devices in different zones:

const devices = await listDevices();

// Group by location/name
const upstairs = devices.filter(d =>
  d.name && d.name.toLowerCase().includes('upstairs')
);

const downstairs = devices.filter(d =>
  d.name && d.name.toLowerCase().includes('downstairs')
);

// Set different temperatures
await setZoneTemperature(upstairs, 22); // 22°C upstairs
await setZoneTemperature(downstairs, 20); // 20°C downstairs

Monitoring Dashboard

Build a dashboard showing all your thermostats:

async function buildDashboard() {
  const devices = await listDevices();

  // Fetch status for each device
  const deviceStatuses = await Promise.all(
    devices.map(async (device) => {
      const status = await getDeviceStatus(device.id);
      return {
        ...device,
        temperature: status.state['shared.' + device.serial]?.value.current_temperature,
        targetTemp: status.state['shared.' + device.serial]?.value.target_temperature
      };
    })
  );

  return deviceStatuses;
}

Access Control

The devices returned depend on your API key’s permissions:

No device restrictions: Returns all devices you own or have shared access to
Specific device restrictions: Returns only devices specified in the API key’s serials array

Devices shared with you will have accessType: "shared". You may have limited permissions on shared devices depending on the sharing settings.

Next Steps

Get Device Status

Retrieve detailed device state and settings

Set Temperature

Control device temperature

Set Mode

Change HVAC mode (heat/cool/auto/off)

Authentication

Learn about API key management

Overview

Self-Hosted Control API

Device Protocol API

Hosted Service API

Overview

Endpoint

Authentication

Request

Headers

Query Parameters

Response

Success Response (200 OK)

Response Fields

Error Responses

401 Unauthorized

429 Too Many Requests

Rate Limiting

Code Examples

Use Cases

Home Automation Integration

Multi-Zone Control

Monitoring Dashboard

Access Control

Next Steps

Get Device Status

Set Temperature

Set Mode

Authentication

​Overview

​Endpoint

​Authentication

​Request

​Headers

​Query Parameters

​Response

​Success Response (200 OK)

​Response Fields

​Error Responses

​401 Unauthorized

​429 Too Many Requests

​Rate Limiting

​Code Examples

​Use Cases

​Home Automation Integration

​Multi-Zone Control

​Monitoring Dashboard

​Access Control

​Next Steps

Get Device Status

Set Temperature

Set Mode

Authentication

Overview

Endpoint

Authentication

Request

Headers

Query Parameters

Response

Success Response (200 OK)

Response Fields

Error Responses

401 Unauthorized

429 Too Many Requests

Rate Limiting

Code Examples

Use Cases

Home Automation Integration

Multi-Zone Control

Monitoring Dashboard

Access Control

Next Steps