Scenes

Scenes provide an easy and performant way to recall often used states to a group.

Create scene

POST /api/<apikey>/groups/<group_id>/scenes

Creates a new scene for a group. The actual state of each light will become the lights scene state.

Parameters

Field Type Description Required
name String The name of the new scene required

Example request data

{ "name": "Garage" }

Response

HTTP/1.1 200 OK
[ { "success": { "id": "3" } } ]

Response fields

Field Type Description
id String The unique identifier of the scene.

Note Creating a scene with a name which already exists will not create a new scene or fail. Such a call will only return the id of the existing scene and store the current state of all lights.

Possible errors

400 Bad Request

403 Forbidden

404 Not Found

503 Service Unavailable

Get all scenes

GET /api/<apikey>/groups/<group_id>/scenes

Returns a list of all scenes of a group.

Parameters

None

Response

HTTP/1.1 200 OK
Etag: 203941fel3ds8ad61903224
{
    "1": {
        "lights": ["1","2"],
        "name": "working"
    },
    "2": {
        "lights": ["3"],
        "name": "reading"
    }
}

Response fields

Field Type Description
lights Array Lights which are members of the scene.
name String Name of the scene.

Possible errors

403 Forbidden

404 Not Found

Get scene attributes

GET /api/<apikey>/groups/<group_id>/scenes/<scene_id>

Returns all attributes of a scene.

Parameters

None

Response

HTTP/1.1 200 OK
Etag: 0b32030b31ef30a4446c9adff6a6f9e5
{
    "lights": [
        {
            "bri": 111,
            "id": "3",
            "on": false,
            "transitiontime": 0,
            "x": 27499,
            "y": 26060
        }
    ],
    "name": "reading",
    "state": 0
}

Response fields

Field Type Description
lights Array Contains objects which describe the state fof each light in the scene.
lights[].id String The id of the light.
lights[].on Bool True if the light is on.
lights[].bri Number (0..255) The brightness of the light.
lights[].transitiontime Number The scene fading transition time in 1/10 seconds.
lights[].x Number (0..1) The color x value of the light.
lights[].y Number (0..1) The color y value of the light.
lights[].ct Number The mired color temperature value of the light.
lights[].hue Number (0.65535) The hue value of the light.
lights[].sat Number (0.255) The saturation value of the light.
name String Name of the scene.
state Number Deprecated - will be removed in future.

Possible errors

403 Forbidden

404 Not Found

Set scene attributes

PUT /api/<apikey>/groups/<group_id>/scenes/<scene_id>

Sets attributes of a scene.

Parameters

Field Type Description Required
name String Name of the scene. optional

Example request data

{
  "name": "working"
}

Response

HTTP/1.1 200 OK
Etag: 030cf8c1c0025420f3a0659afab251f5
[ { "success": { "/groups/1/scenes/1/name": "working" } } ]

Possible errors

400 Bad Request

403 Forbidden

404 Not Found

Store scene

PUT /api/<apikey>/groups/<group_id>/scenes/<scene_id>/store

Stores the current group state in the scene. The actual state of each light in the group will become the lights scene state.

Parameters

None

Response

HTTP/1.1 200 OK
[ { "success": { "id": "3" } } ]

Response fields

Field Type Description
id String The unique identifier of the scene.

Possible errors

400 Bad Request

403 Forbidden

404 Not Found

503 Service Unavailable

Recall scene

PUT /api/<apikey>/groups/<group_id>/scenes/<scene_id>/recall

Recalls a scene. The actual state of each light in the group will become the lights scene state stored in each light.

Note Lights which are not reachable (turned off) won’t be affected!

Parameters

None

Response

HTTP/1.1 200 OK
[ { "success": { "id": "3" } } ]

Response fields

Field Type Description
id String The unique identifier of the scene.

Possible errors

400 Bad Request

403 Forbidden

404 Not Found

503 Service Unavailable

Modify scene

PUT /api/<apikey>/groups/<group_id>/scenes/<scene_id>/lights/<light_id>/state

Modifies the state of a light of the scene.

Note The light must be a member of the scene.

Example request data

{
    "bri": 111,
    "on": true,
    "transitiontime": 10,
    "xy": [ 0.44, 0.98 ]
}

Parameters

Field Type Description Required
bri Number (0..255) Brightness of the light optional
on Bool On/off status of the light optional
transitiontime Number Transitiontime of the light when the scene is called in 1/10 seconds optional
xy Array Xy color values of the light mapped to [0..1] optional

Response

HTTP/1.1 200 OK
[ { "success": { "id": "1" } } ]

Possible errors

400 Bad Request

403 Forbidden

404 Not Found

503 Service Unavailable

Delete scene

DELETE /api/<apikey>/groups/<group_id>/scenes/<scene_id>

Deletes a scene.

Parameters

None

Response

HTTP/1.1 200 OK
[ { "success": { "id": "3" } } ]

Response fields

Field Type Description
id String The unique identifier of the scene.

Possible errors

403 Forbidden

404 Not Found

503 Service Unavailable