WLED versions since 0.8.4 implement a powerful JSON API over HTTP.
It is accessible using the /json subpage.

Obtaining light information

Sending a GET request will return an object similar to the sample below The response consists of four objects:

• state contains the current state of the light. All values may be modified by the client (see below)
• info contains general information about the device. No value can be modified using this API
• effects contains an array of the effect mode names
• palettes contains an array of the palette names

You may also obtain those objects individually using the URLs /json/state /json/info /json/eff, and /json/pal.

!!! info “Reserved effect IDs” In WLED versions 0.14+, some effects are unsupported in certain builds (e.g. some audio reactive effects may only work on ESP32). In order for each effect to have an unique ID on all devices, having unsupported ones in between supported ones is possible. If called, these will fallback to the Solid effect, in the effects list they have the name RSVD or -. To improve user experience, it is recommended to remove effects with the names RSVD or - form the UI effect selection.

Example Library

WLED JSON API Library in rust. Even if you are not using rust, or don’t know how to read rust, the up-to-date JSON structure is included and documented in this project.

Setting new values

Sending a POST request to /json or /json/state with (parts of) the state object will update the respective values. Example: {"on":true,"bri":255} sets the brightness to maximum. {"seg":[{"col":[[0,255,200]]}]} sets the color of the first segment to teal. {"seg":[{"id":X,"on":"t"}]} and replacing X with the desired segment ID will toggle on or off that segment.

!!! tldr “CURL example” This will toggle on and off and return the new state (v0.13+): curl -X POST "http://[WLED-IP]/json/state" -d '{"on":"t","v":true}' -H "Content-Type: application/json"

Sample JSON API response (v0.8.4):

{
  "state": {
    "on": true,
    "bri": 127,
    "transition": 7,
    "ps": -1,
    "pl": -1,
    "nl": {
      "on": false,
      "dur": 60,
      "fade": true,
      "tbri": 0
    },
    "udpn": {
      "send": false,
      "recv": true
    },
    "seg": [{
      "start": 0,
      "stop": 20,
      "len": 20,
      "col": [
        [255, 160, 0, 0],
        [0, 0, 0, 0],
        [0, 0, 0, 0]
      ],
      "fx": 0,
      "sx": 127,
      "ix": 127,
      "pal": 0,
      "sel": true,
      "rev": false,
      "cln": -1
    }]
  },
  "info": {
    "ver": "0.8.4",
    "vid": 1903252,
    "leds": {
      "count": 20,
      "rgbw": true,
      "pin": [2],
      "pwr": 0,
      "maxpwr": 65000,
      "maxseg": 1
    },
    "name": "WLED Light",
    "udpport": 21324,
    "live": false,
    "fxcount": 80,
    "palcount": 47,
    "arch": "esp8266",
    "core": "2_4_2",
    "freeheap": 13264,
    "uptime": 17985,
    "opt": 127,
    "brand": "WLED",
    "product": "DIY light",
    "btype": "src",
    "mac": "60019423b441"
  },
  "effects": [
    "Solid", "Blink", "Breathe", "Wipe", "Wipe Random", "Random Colors", "Sweep", "Dynamic", "Colorloop", "Rainbow",
    "Scan", "Dual Scan", "Fade", "Chase", "Chase Rainbow", "Running", "Saw", "Twinkle", "Dissolve", "Dissolve Rnd",
    "Sparkle", "Dark Sparkle", "Sparkle+", "Strobe", "Strobe Rainbow", "Mega Strobe", "Blink Rainbow", "Android", "Chase", "Chase Random",
    "Chase Rainbow", "Chase Flash", "Chase Flash Rnd", "Rainbow Runner", "Colorful", "Traffic Light", "Sweep Random", "Running 2", "Red & Blue","Stream",
    "Scanner", "Lighthouse", "Fireworks", "Rain", "Merry Christmas", "Fire Flicker", "Gradient", "Loading", "In Out", "In In",
    "Out Out", "Out In", "Circus", "Halloween", "Tri Chase", "Tri Wipe", "Tri Fade", "Lightning", "ICU", "Multi Comet",
    "Dual Scanner", "Stream 2", "Oscillate", "Pride 2015", "Juggle", "Palette", "Fire 2012", "Colorwaves", "BPM", "Fill Noise", "Noise 1",
    "Noise 2", "Noise 3", "Noise 4", "Colortwinkle", "Lake", "Meteor", "Smooth Meteor", "Railway", "Ripple"
  ],
  "palettes": [
    "Default", "Random Cycle", "Primary Color", "Based on Primary", "Set Colors", "Based on Set", "Party", "Cloud", "Lava", "Ocean",
    "Forest", "Rainbow", "Rainbow Bands", "Sunset", "Rivendell", "Breeze", "Red & Blue", "Yellowout", "Analogous", "Splash",
    "Pastel", "Sunset 2", "Beech", "Vintage", "Departure", "Landscape", "Beach", "Sherbet", "Hult", "Hult 64",
    "Drywet", "Jul", "Grintage", "Rewhi", "Tertiary", "Fire", "Icefire", "Cyane", "Light Pink", "Autumn",
    "Magenta", "Magred", "Yelmag", "Yelblu", "Orange & Teal", "Tiamat", "April Night"
  ]
}

Overview of values

State object

Contents of the segment object

Notice: start, stop, and len are not changeable in 0.8.4. Any segment with id > 0 is ignored. Unless stated otherwise, every value may be changed via an HTTP POST request. The tertiary color is not gamma-corrected in 0.8.4, but is in subsequent releases.

Info object

No value may be changed by means of this API.

Examples of frequently requested custom API:

Per-segment individual LED control

Using the i property of the segment object, you can set the LED colors in the segment using the JSON API.
Keep in mind that this is non-persistent, if the light is turned off the segment will return to effect mode.
The segment is frozen when using individual control, the set effect will not run.
To unfreeze the segment, click the “eye” icon, change any property of the segment or turn off the light.

To set individual LEDs starting from the beginning, use an array of Color arrays [255,0,0] or hex values "FF0000". Hex values are more efficient than Color arrays and should be preferred when setting a large number of colors.
{"seg":{"i":["FF0000","00FF00","0000FF"]}} or {"seg":{"i":[[255,0,0],[0,255,0],[0,0,255]]}} will set the first LED red, the second green and the third blue.

To set individual LEDs, use the LED index followed by its color value.
{"seg":{"i":[0,"FF0000",2,"00FF00",4,"0000FF"]}} is the same as above, but leaves blank spaces between the lit LEDs.

To set ranges of LEDs, use the LED start and stop index followed by its color value.
{"seg":{"i":[0,8,"FF0000",10,18,"0000FF"]}} sets the first eight LEDs to red, leaves out two, and sets another 8 to blue.

To set a large number of colors, send multiple api calls of 256 colors at a time.
{"seg": {"i":[0,"CC0000","00CC00","0000CC","CC0000"...]}} {"seg": {"i":[256,"CC0000","00CC00","0000CC","CC0000"...]}} {"seg": {"i":[512,"CC0000","00CC00","0000CC","CC0000"...]}}

Do not make several calls in parallel, that is not optimal for the device. Instead make your call in sequence, where each call waits for the previous to complete before making a new one. How this is done depends on your choice of tool, but with CURL you que your commands by separating then with ` && ` i.e. CURL [command 1] && CURL [command 2] && CURL [command 3].

!!! tip “Command buffer size” If you are trying to set many LEDs and it fails to work, you can check your request here for length. Select ESP32 and Deserialize. If the required buffer size is above 10K for ESP8266 and 24K for ESP32, please split it into multiple sequential requests and consider using the Hex string syntax.

Keep in mind that the LED indices are segment-based, so LED 0 is the first LED of the segment, not of the entire strip. Segment features, including Grouping, Spacing, Mirroring and Reverse are functional.

Matrices are handled as a non-serpentine layout.

!!! info “Brightness interaction” For your colors to apply correctly, make sure the desired brightness is set beforehand. Turning on the LEDs from an off state and setting individual LEDs in the same JSON request will not work!

Playlists

(Available since 0.11.0)

Sample playlist API call:

{
  "playlist": {
    "ps": [26, 20, 18, 20],
    "dur": [30, 20, 10, 50],
    "transition": 0,
    "repeat": 10,
    "end": 21
  }
}

This example applies preset ID 26 for 3 seconds, then preset 20 for 2 seconds, then preset 18 for 1 second, lastly preset 20 again for 5 seconds.This repeats 10 times, then preset 21 is applied.

Playlist object:

Light capabilities

In order to e.g. only show color controls relevant to a given setup, it is necessary to obtain the color capabilities of the light.
The info.leds.seglc array can be used to do so on a per-segment level. It contains n+1 8-bit integers, where n is the id of the last active segment, each index corresponds to the segment with that ID.
This integer indicates whether a given segment supports (24 bit) RGB colors, an extra (8 bit) white channel and/or adjustable color temperature (CCT):

Therefore:

Note that CCT is controllable per-segment, while RGB color and white channel have 3 color slots each per segment.

info.leds.lc contains this info on a global level, and is a bitwise AND of the per-segment light capability values.

CCT control

Please also see the general info about CCT.

Supported value ranges

Given that the white spectrum handling is agnostic to the true color temperature of the LEDs used, a relative range is preferred for the time being, where a value of 0 indicates the warmest possible color temperature, while a value of 255 indicates the coldest temperature.

It is also possible to pass a value in the range of 1900 to 10091, in which case it is treated as a Kelvin color temperature, where 1900 is mapped to a relative value of 0 and 10091 to a relative value of 255.

As such, it is unlikely to match the actual color temperature output by the light, therefore the relative values 0-255 are preferred for the time being.

In the future, an option to specify the Kelvin temperatures of the utilized hardware may be added, once this is done, a color temperature can be set to more accurately match other lights.

Therefore, for forward compatibility, your integration should expect both either a 0-255 value for seg.cct, in which case it is a relative value, or an absolute Kelvin value in the range 1000-16000 K. In case a Kelvin value is provided, you can consider the color temperature as accurate, which is not possible with relative 0-255 values as the Kelvin points of the white channels are unknown.
It is preferred that you set a new CCT value in the same range as received from WLED, that is, use 0-255 if the original value was within this range, and 1000-20000 K otherwise.

If your code relies on absolute Kelvin values, a reasonable estimate for the warm white point (relative 0) could be 2700K, while cold white (relative 255) could commonly be 6500K.

Effect of the seg.cct value

seg.cct can always be set, but only has an effect on the physical state of the light if one or both of the following conditions is met:

• White Balance correction is enabled
• A bus supporting CCT is configured and Calculate CCT from RGB is not enabled

CCT support is indicated by info.leds.cct being true, in which case you can regard the instance as a CCT light and e.g. display a color temperature control.

Effect metadata

!!! tip “Why effect metadata?” Prior to 0.14, user interfaces showed Speed and Intensity slider, palette controls, and all three color slots regardless of the effect selected. This may cause confusion to the user because controls are displayed that have no immediate effect in the current configuration. Effect metadata allows you to dynamically hide certain controls, so that the user only sees controls actually utilized by the selected effect mode.

Starting with WLED 0.14, effect metadata is available under the /json/fxdata URL.
This returns an array of strings with info.fxcount entries. The string at a given index corresponds to the metadata of the effect with the same ID as that index. Metadata is stored in a memory-optimized string format, for example the Aurora effect has the metadata !,!;;!;1;sx=24,pal=50.

The metadata string consists of up to five sections, separated by semicolons: <Effect parameters>;<Colors>;<Palette>;<Flags>;<Defaults>

Effect parameters

The first section specifies the number and labels of effect parameters (e.g. speed, intensity). Up to 5 sliders and 3 checkboxes are supported (sx,ix,c1,c2,c3,o1,o2,o3 parameters in the seg object). For more details about the ranges of the sliders see contents-of-the-segment-object. Slider/checkbox labels are comma separated. An empty or missing label disables this control. ! specifies the default label is used:

The fallback value if this section is missing is two sliders, Effect speed and Effect intensity.

Examples:

Colors

Up to 3 colors can be used. Please note that only the first two characters of the label are visible in the WLED UI.
! specifies the default label is used. The default labels for the color slots are Fx, Bg, and Cs.

The fallback value if this section is missing is 3 colors: Fx + Bg + Cs.

Examples:

Palette

If empty, the effect does not use palettes. If !, palette selection is enabled.

The fallback value if this section is missing is palette selection enabled.

Flags

Flags allow filtering for effects with certain characteristics. They are a single character each and not comma-separated. Currently, the following flags are specified:

For example, a Flag string of 2v denotes a volume reactive effect that is to be used on 2D matrices.

The fallback value if this section is missing is 1, i.e. a 1D optimized effect.

Defaults

Defaults are values for effect parameters that work particularly well on that effect. They are set automatically when the effect is selected in UI unless configured otherwis in UI settings. To specify defaults, use the standard segment parameter name (e.g. ix) followed by an = and the default value. For example, sx=24,pal=50 sets the effect speed to 24 (slow) and the palette to ID 50 (Aurora).

If no default is specified for a given parameter, it retains the current value.

Sensors

!!! warning This section about the Sensor API is a DRAFT specification. It is not yet implemented and subject to change.

Various types of sensors (e.g. for Temperature, light intensity, PIR) may be added to WLED via usermods. To allow read access to sensor data via the JSON API in a standardized way, the info.sensor array is used.

If the info.sensor array is missing or empty, no sensor values are exposed.

Sensor object

Each sensor/measurement is represented by an object within the info.sensor array.

For example,

{"type":"T","n":"Outside","val":12}

refers to a 12 °C temperature measurement in Celsius with the sensor name “Outside”.

The object may contain the following properties, of which all are optional, except type.

Sensor types

These are the standardized sensor types that may be implemented by usermods:

If a client is only interested in certain sensor types (e.g. Temperature), it may disregard all other sensor objects.

API

there is all routes for JSON API:

• /json/state
• /json/info
• /json/si
• /json/nodes
• /json/eff
• /json/palx
• /json/fxdata
• /json/net
• /json/live // only if flag WLED_ENABLE_JSONLIVE is on
• /json/pal
• /json/cfg