Monitor and control single lights.


Get all lights 

GET /api/<apikey>/lights

Returns a list of all lights.

Parameters

None

Response


HTTP/1.1 200 OK


{
    "1": {
        "etag": "026bcfe544ad76c7534e5ca8ed39047c"
        "hascolor": true
        "manufacturer": "dresden elektronik"
        "modelid": "FLS-PP3"
        "name": "Light 1"
        "pointsymbol": {}
        "state": {
            "alert": "none"
            "bri": 111
            "colormode": "ct"
            "ct": 307
            "effect": "none"
            "hue": 7998
            "on": false
            "reachable": true
            "sat": 172
            "xy": [ 0.421253, 0.39921 ]
        }
        "swversion": "020C.201000A0"
        "type": "Extended color light"
        "uniqueid": "00:21:2E:FF:FF:00:73:9F-0A"
    }
    
    "2": {
        "etag": "026bcfe544ad76c7534e5ca8ed39047c"
        "hascolor": false
        "manufacturer": "dresden elektronik"
        "modelid": "FLS-PP3 White"
        "name": "Light 2"
        "pointsymbol": {}
        "state": {
            "alert": "none"
            "bri": 1
            "effect": "none"
            "on": false
            "reachable": true
        }
        "swversion": "020C.201000A0"
        "type": "Dimmable light"
        "uniqueid": "00:21:2E:FF:FF:00:73:9F-0B"
    }
}

Response fields

The whole light object as descripted in Get light state.

Possible errors

403 Forbidden


Get light state 

GET /api/<apikey>/lights/<id>

Returns the full state of a light.

Parameters

None

Response


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


{
        "etag": "026bcfe544ad76c7534e5ca8ed39047c"
        "hascolor": true
        "manufacturer": "dresden elektronik"
        "modelid": "FLS-PP3"
        "name": "Light 1"
        "pointsymbol": {}
        "state": {
            "alert": "none"
            "bri": 111
            "colormode": "ct"
            "ct": 307
            "effect": "none"
            "hue": 7998
            "on": false
            "reachable": true
            "sat": 172
            "xy": [ 0.421253, 0.39921 ]
        }
        "swversion": "020C.201000A0"
        "type": "Extended color light"
        "uniqueid": "00:21:2E:FF:FF:00:73:9F-0A"
    }

Response fields

FieldTypeDescription
etag String HTTP etag which changes on any action to the light.
hascolor bool Indicates if the light can change color. Deprecated - use state instead: if light has no color colormode, hue and xy will not be shown.
manufacturer String The manufacturer of the light device.
name String Name of a light.
modelid String An identifier unique to the product.
pointsymbol Object Not used in the current version.
swversion String Firmware version.
type String Human readable type of the light.
state Object The current state of the light.
state.on Bool true if the light is on.
state.bri Number (0..255) Brightness of the light. Depending on the light type 0 might not mean visible "off" but minimum brightness.
state.hue Number (0..65535) Color hue of the light. The hue parameter in the HSV color model is between 0°-360° and is mapped to 0..65535 to get 16-bit resolution.
state.sat Number (0..255) Color saturation of the light. There 0 means no color at all and 255 is the greatest saturation of the color.
state.ct Number (153..500) Mired color temperature of the light. (2000K - 6500K)
state.xy Array CIE xy color space coordinates as array [x, y] of real values (0..1).
state.alert String Temporary alert effect. Following values are possible:
  • none - light is not performing an alert
  • select - light is blinking a short time
  • lselect - light is blinking a longer time
state.colormode String The current color mode of the light:
  • hs - hue and saturation
  • xy - CIE xy values
  • ct - color temperature
state.effect String Effect of the light:
  • none - no effect
  • colorloop
state.reachable Bool true if the light is reachable and accepts commands.
uniqueid String The unique id of the light. It consists of the MAC address of the light followed by a dash and an unique endpoint identifier in the range 01 to FF.

Possible errors

304 Not Modified

403 Forbidden

404 Not Found


Set light state 

PUT /api/<apikey>/lights/<id>/state

Sets the state of a light.

Parameters

FieldTypeDescriptionRequired
on Bool Set to true to turn the light on, false to turn it off. optional
bri Number (0..255) Set the brightness of the light. Depending on the light type 0 might not mean visible "off" but minimum brightness. If the light is off and the value is greater 0 a on=true shall also be provided. optional
hue Number (0..65535) Set the color hue of the light. The hue parameter in the HSV color model is between 0°-360° and is mapped to 0..65535 to get 16-bit resolution. optional
sat Number (0..255) Set the color saturation of the light. There 0 means no color at all and 255 is the greatest saturation of the color. optional
ct Number (153..500) Set the Mired color temperature of the light. (2000K - 6500K) optional
xy Array Set the CIE xy color space coordinates as array [x, y] of real values (0..1). optional
alert String Trigger a temporary alert effect:
  • none - light is not performing an alert
  • select - light is blinking a short time
  • lselect - light is blinking a longer time
optional
effect String Trigger an effect of the light:
  • none - no effect
  • colorloop - the light will cycle continously through all colors with the speed specified by colorloopspeed
optional
colorloopspeed Number (1..255) Specifies the speed of a colorloop. 1 = very fast, 255 = very slow (default: 15). This parameter only has an effect when it is called together with effect colorloop. optional
transitiontime Number Transition time in 1/10 seconds between two states. optional

Example request data

{
  "on": true,
  "bri": 180,
  "hue": 43680,
  "sat": 255,
  "transitiontime": 10
}

Response


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


[
    { "success": { "/lights/1/state/on": true   }},
    { "success": { "/lights/1/state/bri": 180   }},
    { "success": { "/lights/1/state/hue": 43680 }},
    { "success": { "/lights/1/state/sat": 255   }}
]

Possible errors

400 Bad Request

403 Forbidden

404 Not Found


Set light attributes 

PUT /api/<apikey>/lights/<id>

Sets attributes of a light which are not related to its state.

Parameters

FieldTypeDescriptionRequired
name String (0..32) Set the name of the light. required

Example request data

{ "name": "Living Room 1" }

Response


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


[{ "success": { "/lights/1/name": "Living Room 1"}}]

Possible errors

400 Bad Request

403 Forbidden

404 Not Found


Delete light 

DELETE /api/<apikey>/lights/<id>

Removes the light from the gateway. It will not be shown in any rest api call. Also deletes all groups and scenes on the light device.

Parameters

FieldTypeDescriptionRequired
reset Bool If true sends a network leave command to the light device (may not supported by each manufacturer). optional

Response


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


[{ "success": { "id": "1"}}]

Possible errors

400 Bad Request

404 Not Found


Remove all groups 

DELETE /api/<apikey>/lights/<id>/groups

Remove the light from all groups it is a member of.

Response


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


[{ "success": { "id": "1"}}]

Possible errors

404 Not Found


Remove all scenes 

DELETE /api/<apikey>/lights/<id>/scenes

Remove the light from all scenes it is a member of.

Response


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


[{ "success": { "id": "1"}}]

Possible errors

404 Not Found