WLED Logo
API docs by Redocly

WLED JSON API (0.15.0)

Download OpenAPI specification:

URL: https://github.com/Aircoookie/WLED License: MIT Terms of Service

JSON API for controlling WLED LED controllers. This API allows you to control LED effects, colors, and device settings.

WLED Wiki and Documentation

Introduction

WLED is a fast and feature-rich implementation of an ESP8266/ESP32 webserver to control NeoPixel (WS2812B, WS2811, SK6812) LEDs or also SPI based chipsets like the WS2801 and APA102.

Authentication

Basic authentication can be enabled in WLED settings. When enabled, all API endpoints require basic auth.

State Management

LED state control (brightness, effects, segments)

Get complete WLED API data

Retrieve all essential WLED device information in a single comprehensive request. This is the most complete endpoint, containing device state, information, available effects, and palette names all in one response. This endpoint is ideal for: - Initial application setup and discovery - Getting a complete snapshot of device capabilities - Reducing the number of API calls needed for full device status Response contains: - state: Complete current device state (same as /json/state) - info: Complete device information (same as /json/info) - effects: Array of effect names (same as /json/eff) - palettes: Array of palette names (same as /json/pal) Note: For detailed palette color data, use /json/palx. For effect metadata, use /json/fxda. This endpoint provides names and basic information only.

Responses

Request samples 

curl --request GET \
  --url http://{host}/json

Response samples

Content type
application/json
{
  • "state": {
    },
  • "info": {
    },
  • "effects": [
    ],
  • "palettes": [
    ]
}

Get current device state

Retrieve the current state of the WLED device including brightness, colors, effects, segments, and all other state properties.

Responses

Response samples

Content type
application/json
Example
{
  • "on": true,
  • "bri": 128,
  • "transition": 7,
  • "ps": -1,
  • "pl": -1,
  • "mainseg": 0,
  • "seg": [
    ]
}

Update device state

Update the WLED device state. All properties are optional - only include the properties you want to change. The device will respond with the updated state if the 'v' parameter is set to true.

Request Body schema: application/json
required

State properties to update

on
boolean

On/Off state of the light

bri
integer [ 1 .. 255 ]

Brightness of the light. Setting bri to 0 is supported but it is recommended to use the range 1-255 and use on: false to turn off.

transition
integer [ 0 .. 255 ]

Duration of the crossfade between different colors/brightness levels. One unit is 100ms, so a value of 4 results in a transition of 400ms.

tt
integer [ 0 .. 255 ]

Similar to transition, but applies to just the current API call.

ps
integer [ -1 .. 65535 ]

ID of preset to apply. -1 indicates no preset.

psave
integer [ 1 .. 250 ]

Save current light config to specified preset slot.

pl
integer [ -1 .. 0 ]

ID of playlist. -1 is off and 0 is on.

object (Nightlight)

Nightlight configuration for automatic dimming

object (UdpSync)

UDP sync configuration for WLED broadcast synchronization

v
boolean

If set to true, the response will contain the full JSON state object.

rb
boolean

If set to true, device will reboot immediately.

live
boolean

If set to true, enters realtime mode and blanks the LEDs.

lor
integer [ 0 .. 2 ]

Live data override. 0 is off, 1 is override until live data ends, 2 is override until ESP reboot.

time
integer >= 0

Set module time to unix timestamp.

mainseg
integer >= 0

Main Segment.

object (Playlist)

Custom preset playlists for automatically cycling through different presets. Not included in state response. Available since 0.11.0.

Array of objects (Segment)

Array of segment objects to update. Only segments included will be modified.

Responses

Request samples

Content type
application/json
Example
{
  • "on": true
}

Response samples

Content type
application/json
{
  • "on": true,
  • "bri": 128,
  • "transition": 7,
  • "ps": 1,
  • "pl": -1,
  • "mainseg": 0,
  • "seg": [
    ]
}

Get combined device state and info

Retrieve both the current device state and device information in a single request. This endpoint combines the responses from /json/state and /json/info into one JSON object for efficiency. The response contains: - state: Current device state (brightness, effects, segments, etc.) - info: Device information (version, hardware, capabilities, etc.)

Responses

Request samples 

#!/bin/bash
# Get combined WLED device state and info
curl -X GET "http://192.168.1.100/json/si" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "state": {
    },
  • "info": {
    }
}

Configuration Management

Device configuration and settings

Get device configuration

Retrieve the complete WLED device configuration including network settings, hardware configuration, lighting parameters, and all other system settings. Note: Sensitive information like WiFi passwords are not returned in full.

Responses

Response samples

Content type
application/json
{
  • "id": {
    },
  • "nw": {
    },
  • "def": {
    },
  • "hw": {
    },
  • "light": {
    }
}

Update device configuration

Update WLED device configuration. All properties are optional - only include the properties you want to change. WARNING: Incorrect configuration changes can render the device inaccessible. Always backup configurations before making changes. The device may reboot after certain configuration changes.

Request Body schema: application/json
required

Configuration properties to update

object (AccessPointConfig)

Information about the access point that the ESP hosts when enabled, or when connecting to other AP fails

object (DefaultConfig)

Default settings for WLED device after power-up

object (DmxConfig)

DMX configuration settings (only included in some WLED builds)

object (EthernetConfig)

Ethernet configuration settings

object (HardwareConfig)

Hardware configuration settings

object (DeviceIdentification)

Device identification and naming configuration

object (InterfaceConfig)

Interface configuration settings for various protocols and services

object (LightConfig)

Light configuration settings

object (NetworkConfig)

Network configuration settings

object (AnalogClock)

Analog clock overlay configuration

object (OtaConfig)

Over-The-Air (OTA) update configuration

object (RemoteConfig)

Remote control configuration

object (TimersConfig)

Timer and countdown configuration

object (WifiConfig)

WiFi configuration settings for WLED device

Responses

Request samples

Content type
application/json
Example
{
  • "id": {
    }
}

Response samples

Content type
application/json
{
  • "id": {
    },
  • "def": {
    }
}

Device Information

Device information and capabilities

Get complete WLED API data

Retrieve all essential WLED device information in a single comprehensive request. This is the most complete endpoint, containing device state, information, available effects, and palette names all in one response. This endpoint is ideal for: - Initial application setup and discovery - Getting a complete snapshot of device capabilities - Reducing the number of API calls needed for full device status Response contains: - state: Complete current device state (same as /json/state) - info: Complete device information (same as /json/info) - effects: Array of effect names (same as /json/eff) - palettes: Array of palette names (same as /json/pal) Note: For detailed palette color data, use /json/palx. For effect metadata, use /json/fxda. This endpoint provides names and basic information only.

Responses

Request samples 

curl --request GET \
  --url http://{host}/json

Response samples

Content type
application/json
{
  • "state": {
    },
  • "info": {
    },
  • "effects": [
    ],
  • "palettes": [
    ]
}

Get combined device state and info

Retrieve both the current device state and device information in a single request. This endpoint combines the responses from /json/state and /json/info into one JSON object for efficiency. The response contains: - state: Current device state (brightness, effects, segments, etc.) - info: Device information (version, hardware, capabilities, etc.)

Responses

Request samples 

#!/bin/bash
# Get combined WLED device state and info
curl -X GET "http://192.168.1.100/json/si" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "state": {
    },
  • "info": {
    }
}

Get device information

Retrieves comprehensive information about the WLED device including:

  • Version and build information
  • Hardware capabilities and status
  • LED configuration
  • Network status
  • System resources
Authorizations:
basicAuth

Responses

Request samples 

curl --request GET \
  --url http://{host}/json/info

Response samples

Content type
application/json
{
  • "ver": "0.14.0",
  • "vid": 2310130,
  • "leds": {
    },
  • "name": "WLED",
  • "udpport": 21324,
  • "live": false,
  • "liveseg": -1,
  • "fxcount": 187,
  • "palcount": 71,
  • "wifi": {
    },
  • "fs": {
    },
  • "ndc": 0,
  • "platform": {
    },
  • "freeheap": 200300,
  • "uptime": 6,
  • "time": "1970-1-1, 00:00:06",
  • "brand": "WLED",
  • "product": "FOSS",
  • "mac": "a842e38d9828",
  • "ip": "192.168.1.40"
}

Effects and Palettes

LED effects and color palette management

Get complete WLED API data

Retrieve all essential WLED device information in a single comprehensive request. This is the most complete endpoint, containing device state, information, available effects, and palette names all in one response. This endpoint is ideal for: - Initial application setup and discovery - Getting a complete snapshot of device capabilities - Reducing the number of API calls needed for full device status Response contains: - state: Complete current device state (same as /json/state) - info: Complete device information (same as /json/info) - effects: Array of effect names (same as /json/eff) - palettes: Array of palette names (same as /json/pal) Note: For detailed palette color data, use /json/palx. For effect metadata, use /json/fxda. This endpoint provides names and basic information only.

Responses

Request samples 

curl --request GET \
  --url http://{host}/json

Response samples

Content type
application/json
{
  • "state": {
    },
  • "info": {
    },
  • "effects": [
    ],
  • "palettes": [
    ]
}

Get available effects

Returns a list of all available effects in WLED. The index of each effect in the array corresponds to the effect ID used in segment configurations.

Authorizations:
basicAuth

Responses

Request samples 

curl --request GET \
  --url http://{host}/json/eff

Response samples

Content type
application/json
[
  • "Solid",
  • "Blink",
  • "Breathe",
  • "Wipe",
  • "Wipe Random",
  • "Random Colors",
  • "Sweep",
  • "Dynamic",
  • "Colorloop",
  • "Rainbow"
]

Get effect metadata

Retrieve metadata for all available effects. Returns an array of metadata strings where each string contains parameter information for the corresponding effect. The metadata includes: - Effect parameter ranges and defaults - Custom slider configurations - Effect option settings - Visual behavior hints Each metadata string is extracted from the effect definition after the '@' character. Empty strings indicate effects with no additional metadata. Note: The array index corresponds to the effect ID used in segment configurations.

Responses

Request samples 

curl --request GET \
  --url http://{host}/json/fxda

Response samples

Content type
application/json
[
  • "",
  • "",
  • "",
  • "",
  • "",
  • "",
  • "",
  • "",
  • "",
  • "",
  • "sx=60,ix=128,1d;!,;;!,;1,2,3,4,5,6,7,8",
  • "!,,,160;!,,,164;;m12=1",
  • "sx=60,ix=128,1d;!,;;!,;1,2,3,4,5,6,7,8",
  • "",
  • "",
  • "sx=60,ix=128,1d;!,;;!,;1,2,3,4,5,6,7,8",
  • "",
  • "",
  • "sx=60,ix=128,1d;!,;;!,;1,2,3,4,5,6,7,8",
  • ""
]

Get available color palettes

Returns a list of all available color palettes in WLED. The index of each palette in the array corresponds to the palette ID used in segment configurations. The list includes both built-in palettes and custom palettes.

Authorizations:
basicAuth

Responses

Request samples 

curl --request GET \
  --url http://{host}/json/pal

Response samples

Content type
application/json
[
  • "Default",
  • "* Random Cycle",
  • "* Color 1",
  • "* Colors 1&2",
  • "* Color Gradient",
  • "Party",
  • "Cloud",
  • "Lava",
  • "Ocean",
  • "Forest"
]

Get paginated palette data with colors

Retrieve detailed palette data with full color information in a paginated format. Unlike /json/pal which returns only palette names, this endpoint provides the actual color data for each palette, including RGB values and special color references. Pagination: Due to memory constraints (especially on ESP8266), palette data is split into pages. ESP8266 devices return 5 palettes per page, while ESP32 devices return 8 palettes per page. Color Data Format: - RGB colors: Arrays of [position, red, green, blue] values (0-255) - Segment colors: Strings "c1", "c2", "c3" referring to current segment colors - Random colors: String "r" for random color generation Palette Types: - Built-in palettes (gradient definitions) - FastLED standard palettes - Custom user-defined palettes

query Parameters
page
integer >= 0
Default: 0

Page number to retrieve (0-based). If not specified, defaults to page 0. The maximum page number is returned in the response m field.

Responses

Request samples 

# Get first page of palette data
curl --request GET \
  --url "http://{host}/json/palx"

# Get specific page of palette data  
curl --request GET \
  --url "http://{host}/json/palx?page=1"

Response samples

Content type
application/json
Example
{
  • "m": 3,
  • "p": {
    }
}

Network

Network discovery and configuration

Network Features Documentation

Get discovered WLED nodes

Returns a list of WLED nodes discovered on the local network using mDNS/DNS-SD. Discovery records include device name, type, IP address, and version information.

Authorizations:
basicAuth

Responses

Request samples 

curl --request GET \
  --url http://{host}/json/nodes

Response samples

Content type
application/json
{
  • "nodes": [
    ]
}

Scan for WiFi networks

Performs a scan for available WiFi networks in range. Returns network details including SSID, signal strength, and encryption type. Note: Scanning may temporarily interrupt LED output.

Authorizations:
basicAuth

Responses

Request samples 

curl --request GET \
  --url http://{host}/json/net

Response samples

Content type
application/json
{
  • "networks": [
    ]
}

Live Data

Real-time LED control (experimental)

Live Data Documentation

Get live LED data stream

WARNING: This endpoint is incomplete and not recommended for use. The JSON streaming implementation is inefficient and may cause performance issues. For real-time LED control, use the DDP (Distributed Display Protocol) instead.

See: https://github.com/Aircoookie/WLED/wiki/UDP-Realtime-Control

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
{
  • "leds": [
    ],
  • "n": 2
}