Setting colour temperature with cycle API

I’ve just noticed a slight inconsistency in the API endpoints around the formatting of the “state” objects for PUT lights/states vs POST lights/selector/cycle. I’ve only got White 800 bulbs so it’s kelvin is the only colour adjustment I have to play with so I hit this almost straight away.

The lights/states endpoint seems to be happy enough with this PUT:

{
  "states" : [ { "kelvin" : 3000, "selector" : "all" } ],
  "defaults" : { "duration" : 0 , "power" : "on" }
}

However POSTing to /lights/all/cycle does not except the “kelvin” parameter, instead forcing use of {“color”:“kelvin:0000”}, for JSON data like this:

{
  "defaults" : { "duration" : 30 , "power" : "on" },
  "states" : [
    { "color" : "kelvin:7000", "brightness" : 1 },
    { "color" : "kelvin:5000", "brightness" : 0.66 },
    { "color" : "kelvin:3000", "brightness" : 0.33 },
    { "power" : "off" }
  ]
}

Use of “kelvin” as its own attribute instead of in the “color” attribute you get an error response that looks like this:

{
  'warnings': [ 
    {
      'unknown_params' : { 
        'defaults' : {},
        'states' => [ { 'kelvin' : 3000, 'brightness' : '0.33' } ]
      },
     'warning' => 'Unknown params'
    }
  ]
}

It seems like using “color”:“kelvin:0000” is the correct (or at least preferred) method as the “kelvin” attribute does not appear in the docs for the state object, but since it does work in at least one place it would be nice if it worked everywhere.

I believe that accepting the kelvin value outside the color parameter is a remnant of an older version and wasn’t documented for that reason. You should be using the service as documented as we can’t guarantee that undocumented usage will continue to work.