WLEDwiki/JSON-API.md

Starting from version 0.8.4, WLED implements 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

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.

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 it is recommended to use the range 1-255 and use on: false to turn off. 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.
tt	0 to 255	Similar to transition, but applies to just the current API call. Not included in state response.
ps	-1 to 65535	ID of currently set preset.
psave	1 to 16	Save current light config to specified preset slot. Not included in state response.
pl	-1 to 0	ID of currently set playlist. For now, 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.
v	bool	If set to true in a JSON POST command, the response will contain the full JSON state object. Not included in state response.
lor	0, 1, or 2	Live data override. 0 is off, 1 is override until live data ends, 2 is override until ESP reboot (available since 0.10.0)
time	uint32	Set module time to unix timestamp. Not included in state response.
mainseg	0 to info.leds.maxseg-1	Main Segment
seg	Array of segment objects	Segments are individual parts of the LED strip. In 0.9.0 this will enables running different effects on different parts of the strip.

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 will be in subsequent releases.

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 segment 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.
col	Array of colors	Array that has up to 3 color arrays as elements, the primary, secondary (background) and tertiary colors of the segment. Each color is an array of 3 or 4 bytes, which represent an RGB(W) color.
fx	0 to info.fxcount -1	ID of the effect.
sx	0 to 255	Relative effect speed
ix	0 to 255	Effect intensity
pal	0 to info.palcount -1	ID of the color palette
sel	bool	true if the segment is selected. Selected segments will have their state (color/FX) updated by APIs that don't support segments (currently any API except this JSON API). If no segment is selected, the first segment (id:0) will behave as if selected. WLED will report the state of the first (lowest id) segment that is selected to APIs (UDP sync, HTTP, MQTT, Blynk...).
rev	bool	Flips the segment, causing animations to change direction.
on	bool	Turns on and off the individual segment. (available since 0.10.0)
bri	0 to 255	Sets the individual segment brightness (available since 0.10.0)

Info object

No value may be changed by means of this API.

JSON key	Value range	Description
ver	string	Version name.
vid	uint32	Build ID (YYMMDDB, B = daily build index).
leds.count	1 to 1200	Total LED count.
leds.rgbw	bool	true if LEDs are 4-channel (RGBW).
leds.pin	byte array	LED strip pin(s). In 0.8.4, always one element.
leds.pwr	0 to 65000	Current LED power usage in milliamps as determined by the ABL. 0 if ABL is disabled.
leds.maxpwr	0 to 65000	Maximum power budget in milliamps for the ABL. 0 if ABL is disabled.
leds.maxseg	byte	Maximum number of segments supported by this version.
name	string	Friendly name of the light. Intended for display in lists and titles.
udpport	uint16	The UDP port for realtime packets and WLED broadcast.
live	bool	If true, the software is currently receiving realtime data via UDP or E1.31.
fxcount	byte	Number of effects included.
palcount	uint16	Number of palettes configured.
wifi.bssid	string	The BSSID of the currently connected network.
wifi.signal	0 to 100	Relative signal quality of the current connection.
wifi.channel	1 to 14	The current WiFi channel.
arch	string	Name of the platform.
core	string	Version of the underlying (Arduino core) SDK.
freeheap	uint32	Bytes of heap memory (RAM) currently available. Problematic if <10k.
uptime	uint32	Time since the last boot/reset in seconds.
opt	uint16	Used for debugging purposes only.
brand	string	The producer/vendor of the light. Always WLED for standard installations.
product	string	The product name. Always DIY light for standard installations.
btype	string	The origin of the build. src if a release version is compiled from source, bin for an official release image, dev for a development build (regardless of src/bin origin) and exp for experimental versions. ogn if the image is flashed to hardware by the vendor.
mac	string	The hexadecimal hardware MAC address of the light, lowercase and without colons.