JSON API

Check back soon! This documentation is scheduled to be completed before the 3rd of April 2019

Starting from version 0.8.4, WLED implements a powerful JSON API over HTTP. It is accessable 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

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.

Note: In 0.8.4, segments are not supported and any but the first will be ignored.

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

JSON key	Value range	Description
on	bool	On/Off state of the light
bri	0 to 255	Brightness of the light. If on is false, contains last brightness when light was on (aka brightness when on is set to true). Setting bri to 0 is supported but deprecated, it is recommended to use the range 1-255. The state response will never have the value 0 for bri.
transition	0 to 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.
ps	-1 to 65535	ID of currently set preset. 0.8.4 will always return -1.
pl	-1 to 0	ID of currently set playlist. In 0.8.4 only, this sets the preset cycle feature, -1 is off and 0 is on.
nl.on	bool	Nightlight currently active
nl.dur	1 to 255	Duration of nightlight in minutes
nl.fade	bool	If true, the light will gradually dim over the course of the nightlight duration. If false, it will instantly turn to the target brightness once the duration has elapsed.
nl.tbri	0 to 255	Target brightness of nightlight feature
udpn.send	bool	Send WLED broadcast (UDP sync) packet on state change
udpn.recv	bool	Receive broadcast packets
udpn.nn	bool	Don't send a broadcast packet (applies to just the current API call). Not included in state response.
seg	Array of segment objects	Segments are individual parts of the LED strip. In 0.9.0 this will enable running different effects on different parts of the strip.

Contents of the segment object

Notice: start, stop, and len are not settable in 0.8.4. Any segment with id > 0 is ignored.

JSON key	Value range	Description
id	0 to info.maxseg-1	Zero-indexed ID of the segment. May be omitted, in that case the ID will be inferred from the order of the segment objects in the seg array. As such, not included in state response.
start	0 to info.leds.count-1	LED the segment starts at.
stop	0 to info.leds.count	LED the segments stops at, not included in range. If stop is set to a lower or equal value than start (setting to 0 is recommended), the segment is invalidated and deleted.
len	0 to info.leds.count	Length of the segment (stop - start). stop has preference, so if it is included, len is ignored.