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

FieldTypeDescriptionRequired
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescriptionRequired
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescriptionRequired
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. Note that not all states support a transition time. For example, a transition time when setting
on
will be ignored as the Zigbee On and Off commands do not support transition times. In general, light attributes that support a range of values support transition times, while boolean values do not.
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

FieldTypeDescription
id String The unique identifier of the scene.

Possible errors

403 Forbidden

404 Not Found

503 Service Unavailable