HTTP request API

WLED's HTTP API allows you to set many properties of your lights, even more than the index page UI supports, via a simple GET web request.

Unsure how all this API stuff works? Check out this amazing guide by tynick!

The basic URL scheme is: [ipadress]/win. This will return an XML file with some current values (see bottom of page). Parameters can be added to control some of the variables.

• Example (AP): 192.168.4.1/win&A=255 sets the brightness to maximum
• Example (mdns): led.local/win&A=128&FX=0 sets the brightness to half and the effect to Solid

In conjunction with a router port forwarding this can be used to automate WLED, for example via IFTTT.

Add one or multiple of the following parameters after the base URL/IP to change values: (if the parameter is unknown or the value illegal nothing will happen)

LED control

Parameter	Value Range	Description	Since Version
&A=	0 to 255	Master brightness	0.2
&T=	0, 1, or 2	Master Off/On/Toggle	0.3
&R=	0 to 255	Primary Red value	0.2
&G=	0 to 255	Primary Green value	0.2
&B=	0 to 255	Primary Blue value	0.2
&W=	0 to 255	Primary White value	0.4
&FX=	0 to 101	LED Effect Index	0.3
&SX=	0 to 255	Effect Speed	0.3
&IX=	0 to 255	Effect Intensity	0.5.0
&FP=	0 to 46	FastLED Palette	0.8.0
&NL=	0 to 255	Nightlight active and duration	0.3
&ND	none	Toggles nightlight on but uses default duration	0.6.3
&NT=	0 to 255	Nightlight target brightness	0.5.0
&NF=	0 to 2	Fade Nightlight, 1 = fade brightness only, 2 = additionaly fade color from primary to secondary color	0.5.0

Advanced

Parameter	Value Range	Description	Since Version
&CL=	HEX/DEC	Primary color	0.8.0
&C2=	HEX/DEC	Secondary color	0.8.0
&R2=	0 to 255	Secondary Red value	0.4
&G2=	0 to 255	Secondary Green value	0.4
&B2=	0 to 255	Secondary Blue value	0.4
&W2=	0 to 255	Secondary White value	0.4
&HU=	0 to 65535	Hue	0.5.1
&SA=	0 to 255	Saturation (only in conjunction with Hue)	0.5.1
&H2	none	Hue + Saturation will set secondary color	0.5.1
&SR=	0 or 1	Set Primary/Secondary color to random hue	0.4
&SC	none	Swap primary and secondary color	0.4

Notifications

Parameter	Value Range	Description	Since Version
&RN=	0 or 1	Receive UDP Notifications	0.3
&SN=	0 or 1	Send UDP Notifications	0.3
&NN	none	No notification for this request	0.3
&HP=	0 to 99	Sets Hue polling light ID (0 is off)	0.5.1

Presets

Parameter	Value Range	Description	Since Version
&PS=	1 to 16	Saves current setup to preset	0.4
&PL=	0 to 16	Applies entire preset	0.4
&CY=	0 or 1	Toggle Preset cycle	0.6.3
&PA=	0 or 1	Presets apply brightness	0.7.0
&P1=	1 to 25	First cycle preset	0.6.3
&P2=	1 to 25	Last cycle preset	0.6.3
&PT=	50 to 65000	Cycle time in each preset (ms)	0.6.3
&TT=	0 to 65000	Set transition time (ms)	0.6.3

Macros

Parameter	Value Range	Description	Since Version
&MS=	0 to 16(String 0..64)	Save API macro	0.5.0
&M=	0 to 16	Apply macro	0.5.0

Segments

It is highly recommended to use the JSON API when dealing with Segments.

Parameter	Value Range	Description	Since Version
&SM=	0 to 9	Set the main segment (values are reported to XML)	0.9.0
&SS=	0 to 9	Select segment to apply THIS api call to	0.9.0
&SV=	0 or 1	Set segment selected	0.9.0
&S=	0 to ledcount-1	Set segment start	0.9.0
&S2=	0 to ledcount	Set segment stop	0.9.0
&GP=	1 to 255	Set segment grouping	0.9.1
&SP=	0 to 255	Set segment spacing	0.9.1

General and Experimental

Parameter	Value Range	Description	Since Version
&ST=	32bit	Current UTC time in Unix epoch	0.4
&CT=	32bit	UTC time for countdown end	0.4
&MD=	0 or 1	Set slider mode to RGB/HSB	0.3
&AX=	0 to 255	Debug feature, can be configured for general IO	0.3
&IN	none	Server will not respond to this request (internal)	0.3
&OL=	0 to 255	Experimental overlays	0.3
&L=	0 to 255	Lock pixel	0.4
&L2=	0 to 255	Lock pixel range L to L2	0.4
&UL	none	Unlock instead (used in conjunction with L and L2)	0.4
&NX=	String 1..6	Cronixie clockface	0.4
&NM=	0 or 1	Cronixie Time or Countdown mode	0.4
&NB=	0 or 1	Cronixie Backlight	0.4
&IT	none	Include UI color theme in API response	0.8.2
&RD=	0 or 1	Toggle realtime UDP	0.8.4

XML response

This is the XML file sent as response to every API call.

Parameter	Value Range	Description
<ac>	0 to 255	Master Brightness
<cl>	3x 0..255	Primary Color RGB
<cs>	3x 0..255	Secondary RGB
<ns>	0 or 1	Notification Sending on
<nr>	0 or 1	Notification Receive on
<nl>	0 or 1	Nightlight active
<nf>	0 or 2	Nightlight Fade type
<nd>	0 to 255	Nightlight delay
<nt>	0 to 255	Nightlight target brightness
<fx>	0 to 73	Effect index
<sx>	0 to 255	Effect speed
<ix>	0 to 255	Effect intensity
<fp>	0 to 43	FastLED palette
<wv>	-1 to 255	Primary White value
<ws>	0 to 255	Secondary White
<md>	0 or 1	RGB or HSB UI mode
<ds>	String 0..32	Server description

In-/decrementing values

You can use the ~ character to easily set values relative to their current value.
This is currently supported for the following parameters:
A, R, G, B, W, R2, G2, B2, W2, FX, SX, IX, FP, PL

For example, use PL=~ to go to the next preset. Using just ~ without a number will increase the value by 1, ~- will decrease it by 1. The value will then wrap around, so using A=~- when A is 0 will set A to 255.

You can also specify by how much to change the value. For example, using A=~10 will increase the brightness by 10. In case of using a number behind ~, the value will clip (so it will not wrap around, if the maximum brightness is set, A=~10 will not have any effect)