Rooms

A Room is a grouping of devices in a Location.

For example, if a user has many connected devices at home, Rooms can further organize them into a "Kitchen", "Office", and "Living Room".

This article explains how your application can use our API to create and manage Rooms.

Managing Rooms

Be aware of the following requirements:

  • Each Location can have up to 20 Rooms.
  • A Room can have up to 200 devices. This counts toward the device limit for the Location.

A Room is owned by its Location. The Location owner and all members invited to a Location can create/read/update/delete Rooms in the Location.

Authorization

You must pass an OAuth token in the request header when calling each of the below API methods.

Example

Authorization: Bearer <token>

Rooms API

List Rooms in a Location

GET /locations/<locationId>/rooms

Call this API to list all Rooms defined for a Location.

You must include a locationId in the URL path.

OAuth scope: r:locations:*

Example response

{
  "items": [
    {
      "roomId": "bdd8a15f-33d4-41fc-b33c-75ce85e99d24",
      "locationId": "6b3d1909-1e1c-43ec-adc2-5f941de4fbf9",
      "name": "Living Room"
    }
  ],
  "_links": {
    "next": {
      "href": "https://..."
    },
    "previous": {
      "href": "https://..."
    }
  }
}

Each Room is returned with its roomId and the corresponding locationId in the items array.

Create a Room

POST /locations/<locationId>/rooms

This call will create a Room within a Location.

You must include a locationId in the URL path and a Room name (e.g. "Living Room") in the request body.

OAuth scope: w:locations:*

Example request

{
  "name": "Living Room"
}

Example response

{
  "roomId": "bdd8a15f-33d4-41fc-b33c-75ce85e99d24",
  "locationId": "6b3d1909-1e1c-43ec-adc2-5f941de4fbf9",
  "name": "Living Room"
}

Get a Room

GET /locations/<locationId>/rooms/<roomId>

This call will return a specific Room within a Location.

You must include a locationId and roomId in the URL path.

OAuth scope: r:locations:*

Example response

{
  "roomId": "bdd8a15f-33d4-41fc-b33c-75ce85e99d24",
  "locationId": "6b3d1909-1e1c-43ec-adc2-5f941de4fbf9",
  "name": "Living Room"
}

Update a Room

PUT /locations/<locationId>/rooms/<roomId>

This call will only update specified fields. All the fields in the request are optional.

You must include a locationId and roomId in the URL path, and the Room name in the request body.

OAuth scope: w:locations:*

Example request

{
  "name": "Living Room", 
}

Example response

{
  "roomId": "bdd8a15f-33d4-41fc-b33c-75ce85e99d24",
  "locationId": "6b3d1909-1e1c-43ec-adc2-5f941de4fbf9",
  "name": "Living Room"
}

Delete a Room

DELETE /locations/<locationId>

This call will delete a Room within a Location. Devices belonging to the Location will remain in the user's account.

You must include a locationId and roomId in the URL path.

OAuth scope: w:locations:*

Example response

{}