Schedules

Schedules provide the ability to trigger timed commands to groups or lights.

Create schedule

POST /api/<apikey>/schedules

Creates a new schedule.

Parameters

Field	Type	Description	Required
name	String	The name of the new schedule. If the name already exists a number will be appended.	optional
description	String	The description of the schedule.	optional
command	Object	The command to execute when the schedule triggers.	required
command.address	String	The address of a light or group ressource	required
command.method	String	must be “PUT”	required
command.body	Object	The state that the light or group will activate when the schedule triggers	required
status	String (“enabled”\|“disabled”)	Whether the schedule is enabled or disabled. Default is enabled.	optional
autodelete	Bool	If true the schedule will be deleted after triggered. Else it will be disabled. Default is true.	optional
time	String	Time when the schedule shall trigger in UTC ISO 8601:2004 format. specific date: “yyyy-MM-ddThh:mm:ss” repeated days: “W[0..127]/Thh:mm:ss” timer: “PThh:mm:ss” recurring timer: “R[0..99]/PThh:mm:ss” `Repeated days use a bitmap to determine on which day of the week the alarm should trigger. The Format is: 0MTWTFSS. Example: 01111100 = 124 is weekdays, 00000011 = 3 is weekend.<br />` The number after R of recurring timer determine the number of repetitions of the timer. Not specifying a number means infinity.	required

Example request data

{
    "name": "blue moon",
    "description": "Turns all lights blue",
    "command": {
        "address": "/api/8918fbad2100nag17ca1/groups/5/action",
        "method": "PUT",
        "body": { "on": true, "hue": 43000, "sat": 255 }
    },
    "time": "2013-07-29T09:30:00"
}

Note The address in the command object must contain a valid API key.

Response

HTTP/1.1 200 OK

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

Response fields

Field	Type	Description
id	String	The unique identifier of the new schedule.

Possible errors

400 Bad Request

403 Forbidden

Get all schedules

GET /api/<apikey>/schedules

Returns a list of all schedules.

Parameters

None

Response

HTTP/1.1 200 OK
Etag: 203941fel3ds8ad61903224

{
    "1": {
        "autodelete": false,
        "command": {
            "address": "/api/8918fbad2100nag17ca1/groups/2/action",
            "method": "PUT",
            "body": { "on": false }
        },
        "description": "Turns all lights off",
        "etag": "4e100d1c4e3497154a77bc0865c89030",
        "name": "turn all off",
        "status": "enabled",
        "time": "2013-07-30T20:10:00"
    },
    "2": {
        "autodelete": false,
        "command": {
            "address": "/api/AD4F14F244/groups/4/scenes/1/recall",
            "body": {},
            "method": "PUT"
        },
        "description": "",
        "etag": "4e100d1c4e3497154a77bc0865c89030",
        "name": "call scene",
        "status": "enabled",
        "time": "W120/T10:00:00"
    }
}

Response fields

The full schedule object as in Get schedule attributes.

Possible errors

403 Forbidden

Get schedule attributes

GET /api/<apikey>/schedules/<id>

Returns all attributes of a schedule.

Parameters

None

Response

HTTP/1.1 200 OK
Etag: 0b32030b31ef30a4446c9adff6a6f9e5

{
    "autodelete": false,
    "command": {
        "address": "/api/8918fbad2100nag17ca1/groups/2/action",
        "method": "PUT",
        "body": { "on": false }
    },
    "description": "Turns all lights off",
    "etag": "4e100d1c4e3497154a77bc0865c89030",
    "name": "turn all off",
    "status": "enabled",
    "time": "2013-07-30T20:10:00"
}

Response fields

Field	Type	Description
autodelete	Bool	If set to true the schedule will be deleted after trigger. Else it will be disabled.
command	Object	The command to execute when the schedule triggers.
command.address	String	The address of a light or group ressource	required
command.method	String	must be “PUT”	required
command.body	Object	The state that the light or group will activate when the schedule triggers	required
description	String	The description of the schedule.
etag	String	The etag of the schedule.
name	String	Name of the schedule.
status	String	The status of the schedule (enabled or disabled).
time	String	Time when the schedule shall trigger in UTC ISO 8601:2004 format. specific date: “yyyy-MM-ddThh:mm:ss” repeated days: “W[0..127]/Thh:mm:ss” timer: “PThh:mm:ss” recurring timer: “R[0..99]/PThh:mm:ss” `Repeated days use a bitmap to determine on which day of the week the alarm should trigger. The Format is: 0MTWTFSS. Example: 01111100 = 124 is weekdays, 00000011 = 3 is weekend.<br /> The number after R of recurring timer determine the number of repetitions of the timer. Not specifying a number means infinity. </td> </tr>`

Possible errors

403 Forbidden

404 Not Found

Set schedule attributes

PUT /api/<apikey>/schedules/<id>

Sets attributes of a schedule.

Parameters

<tr>
  <td>command.address</td>
  <td>String</td>
  <td>The address of a light or group ressource</td>
  <td>optional</td>
</tr>
<tr>
  <td>command.method</td>
  <td>String</td>
  <td>must be "PUT"</td>
  <td>optional</td>
</tr>
<tr>
  <td>command.body</td>
  <td>Object</td>
  <td>The state that the light or group will activate when the schedule triggers</td>
  <td>optional</td>
</tr>
<tr>
  <td>status</td>
  <td>String ("enabled"|"disabled")</td>
  <td>Whether the schedule is enabled or disabled. Default is enabled.</td>
  <td>optional</td>
</tr>
<tr>
  <td>autodelete</td>
  <td>Bool</td>
  <td>If true the schedule will be deleted after triggered. Else it will be disabled. Default is true.</td>
  <td>optional</td>
</tr>
<tr>
  <td>time</td>
  <td>String</td>
  <td>Time when the schedule shall trigger in UTC ISO 8601:2004 format. The time must be in the future.
    <ul>
      <li>specific date: "yyyy-MM-ddThh:mm:ss"</li>
      <li>repeated days: "W[0..127]/Thh:mm:ss"</li>
      <li>timer: "PThh:mm:ss"</li>
      <li>recurring timer: "R[0..99]/PThh:mm:ss"</li>
    </ul>
    Repeated days use a bitmap to determine on which day of the week the alarm should trigger. The Format is: 0MTWTFSS. Example: 01111100 = 124 is weekdays, 00000011 = 3 is weekend.<br />
    The number after R of recurring timer determine the number of repetitions of the timer. Not specifying a number means infinity.
  </td>
  <td>optional</td>
</tr>

Field	Type	Description	Required
name	String	The name of the new schedule. If the name already exists a number will be appended.	optional
description	String	The description of the schedule.	optional
command	Object	The command to execute when the schedule triggers.	optional

Example request data

{
    "name": "working"
}

Response

HTTP/1.1 200 OK
Etag: 030cf8c1c0025420f3a0659afab251f5

[ { "success": { "/schedules/1/name": "working" } } ]

Possible errors

400 Bad Request

403 Forbidden

404 Not Found

Delete schedule

DELETE /api/<apikey>/schedules/<id>

Deletes a schedule.

Parameters

None

Response

HTTP/1.1 200 OK

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

Response fields

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

Possible errors

403 Forbidden

404 Not Found