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
Self-hosted? Use http://localhost:3000/api/v1/devices instead.
Authentication This endpoint requires API key authentication.
Required Scopes : readInclude your API key in the Authorization header:
Authorization: Bearer nle_your_api_key_here
Request Header Value Required AuthorizationBearer nle_your_api_key_hereYes
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 devicesarray Array of device objects devices[].idstring Unique device identifier (UUID) devices[].serialstring Device serial number (17 characters) devices[].namestring | null Custom device name (null if not set) devices[].accessTypestring 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
JavaScript/Node.js
Python
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:
No device restrictions : Returns all devices you own or have shared access toSpecific 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