Skip to content

HTTP request API

Def3nder edited this page Jan 23, 2020 · 37 revisions

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.

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 79 LED Effect Index 0.3
&SX= 0 to 255 Effect Speed 0.3
&IX= 0 to 255 Effect Intensity 0.5.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
&SW none Set secondary color to white 0.4
&SB none Set secondary color to black 0.4
&SP none Set secondary color to primary 0.4
&SC none Swap primary and secondary color 0.4
&FP= 0 to 46 FastLED Palette 0.8.0

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
&PA= 1 to 16 Applies brightness from preset 0.4
&PC= 1 to 16 Applies colors from preset 0.4
&PX= 1 to 16 Applies effects from preset 0.4
&CY= 0 or 1 Toggle Preset cycle 0.6.3
&PA= 0 or 1 Cycle applies brightness 0.7.0
&PC= 0 or 1 Cycle applies color 0.7.0
&PX= 0 or 1 Cycle applies effects 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

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
<th> Hex Colors Current theme (&IT call required)

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)

You can’t perform that action at this time.