Sets the state of the lights within the selector. All parameters (except for the selector) are optional. If you don't supply a parameter, the API will leave that value untouched.

For example, if you want to turn the light on to a pale blue at 50% brightness over 5 seconds, you'd send:

// PUT /v1/lights/all/state
{
  "power": "on",
  "color": "blue saturation:0.5",
  "brightness": 0.5,
  "duration": 5
}

Fast mode

The API is designed to ensure consistent transitions for devices from one state to another. For many operations, this involves having an accurate view of the current state of the device before taking any action, so we need to ask it for its state first. Other transitions, in order to be smooth, require intermediate state changes; for example, to switch on and set to blue a light that is off and set to red, we first switch it to blue, wait for that to succeed, then switch it on, to avoid jarring transitions.

As this involves various network hops to the device, this process is slower than many traditional web APIs. There are use-cases where this is unnecessary, for example those in which the client has a pretty good idea of the current state and just wants to send one state change message to the device.

To speed things up for such use-cases, when setting fast=true, we do none of checks described above, and just send the targets the end-state messages. Because we don't wait around for a reply from the device in fast mode, you'll just get 202 Accepted with no body if your request was valid.

Infrared

If you want to set Infrared to maximum brightness and shutdown the visible bands, you would send:

// PUT /v1/lights/all/state
{
  "power": "off",
  "infrared": 1.0, 
}

202202

2XX2XX