List Devices

Get all thermostats accessible by your API key

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

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

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:

1. No device restrictions: Returns all devices you own or have shared access to
2. 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