API > Quick Start Guide

This guide will help you discover your device, authenticate, and send your first commands. Perfect if you want to get started fast ⚡

What You’ll Need

• A Nanoleaf device (Light Panels, Shapes, Canvas, Lines, Elements, or Skylight)

• Device connected to your Wifi

• A computer (or Raspberry Pi, server, etc.) on the same local network

• A way to send HTTP requests (curl, Postman, or your favorite programming language)

— — —

1 -  FIND YOUR DEVICE

The Nanoleaf API runs locally on port 16021.

Manual discovery: Check your router’s device list for “Nanoleaf” and note its IP address (e.g., 192.168.1.120).

OR

Automatic discovery (developers):

Devices advertise themselves via mDNS (Bonjour): service type _nanoleafapi._tcp or SSDP: responds to M-SEARCH queries.

— — —

 2 -  AUTHENTICATION

Before sending API commands, you’ll need an authentication token. 

First, enter pairing mode:

Light Panels, Shapes, Canvas, Lines, Elements: Hold the controller’s power button for 5–7 seconds until the LED starts flashing.

Skylight: Open the Nanoleaf app > Device Settings > Connect to API.

Next, send a token request within 30 seconds:

curl -X POST http://192.168.1.120:16021/api/v1/new

Response:

{"auth_token" : "xxxxxxxxxxxxxxxxxxx"}

⚠️ Save this token! You’ll use it in every request.

— — —

3 - TURN THE LIGHTS ON

The Nanoleaf API follows a hierarchical JSON structure. This means:

• Use a specific sub-endpoint (e.g., /state/on) to read an attribute.
• Use the parent endpoint (/state) with JSON to set attributes.

Read current power state:

curl http://192.168.1.120:16021/api/v1/{auth_token}/state/on

Response:

{"value" : true}

Common Errors:

400 Bad Request

401 Unauthorized

404 Resource Not Found

— — —

Now you’re authenticated, let’s control your lights and turn them on:

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"on":{"value":true}}' \
  http://192.168.1.120:16021/api/v1/{auth_token}/state

Turn them off again by setting "value":false.

Response:

204 No Content (success)

Common Errors:

400 Bad Request

401 Unauthorized

404 Resource Not Found

— — —

You can now:

✅ Discover your device
✅ Authenticate with an API token
✅ Read and update its power state

— — —

Continue exploring:

🔗 Light Panels Open API Documentation
🔗Light Panels SDK Documentation
🔗Nanoleaf Matter Wifi Essentials Open API Documentation
🔗Nanoleaf USB Lightstrip Communication Protocol