Homes

A "home" represents a container of devices and is owned/managed by one or more users.

Endpoints

The Home object

  • idinteger

    Unique ID assigned at time of creation.

  • projectIdinteger

    Project that this home belongs to.

  • creationTimestring| format is date-time

    Timestamp of home creation.

  • namestring

    Display name of home.

  • deactivatedboolean

    True if home has been deactivated by project admin.

The Home object

{
  "id":9,
  "projectId":11,
  "creationTime":"2015-04-21T00:16:22.381Z",
  "name":"My Home"
}

The Home Member object

  • userIdinteger

    User ID of home member.

  • creationTimestring| format is date-time

    Timestamp when member was added to home.

  • namestring

    Display name of member.

  • phoneNumberstring

    Phone number used by member.

  • emailstring

    Email address of member.

  • verifiedboolean

    True if member is a verified user.

  • role| options are owner, member

    If the role is OWNER, this member can add or remove other members.

The Home Member object

{
    "userId": 2081,
    "creationTime": "2019-12-18T19:00:26.521Z",
    "name": "Jane Doe",
    "phoneNumber": "+1719999999",
    "verified": true,
    "role": "owner"
}

The Smart Module object

  • idstring

    Smart Module ID. Must be unique within the project.

  • moduleTypestring

    Type of Smart Module. Must be one of the recognized type IDs.

  • creationTimestring| format is date-time

    Timestamp of entry creation.

  • descriptionstring

    A short description of the Smart Module.

  • suspendedboolean

    Set to true to disable this Smart Module.

  • subscribedEventsarray

    If module accepts events, this is the list of event types the Smart Module subscribes to.

  • bulkDataLabelstring

    If module accepts bulk data, this is an identifier for bulk data upload.

  • dataSourceModulesarray

    If module uses other modules as data sources, this is the list of module IDs of the data sources.

  • configDataobject

    Configuration data. Used only during creation/update of the Smart Module.

Get all homes

Endpoint
get /homes
Description

Get a list of homes of a project (by using the projectId parameter), or homes of which a user is a member (by using the userId parameter). Either the projectId or userId must be specified. To fetch the homes of a project, the request must be made using a project API key with "Admin" privileges.

Query Parameters

  • projectId

    integer

    Return homes of the specified project.

  • userId

    integer

    Return homes of which the specified user is a member.

  • skip

    integer

    Number of homes to skip over.

  • limit

    integer

    Maximum number of homes to return.

    Default value is 25

    Minimum value is 1

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200Successful retrieval of list of homes.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

[
  {
    "id": 1696,
    "projectId": 1260,
    "creationTime": "2019-09-16T22:10:30.384Z",
    "name": "Home_1"
  },
  {
    "id": 1885,
    "projectId": 1260,
    "creationTime": "2019-12-17T22:52:13.917Z",
    "name": "Home_2"
  }
]

Create a home

Endpoint
post /homes
Description

Create a home. If the request is made by a user, the user will be automatically added as a member of the home.

If the request is made using a project API key with "Admin" privileges, the home will be created without any member. (Members must be explicitly added later.)

In either cases, the request body must contain the "name" field.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Request Body

  • name

    string

    required

    Display name of home.

  • deactivated

    boolean

    True if home has been deactivated by project admin.

Response
  • 201Successfully created a new home.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "name": "Home_Base"
}

Response Body Sample

{
  "id": 1888,
  "projectId": 1260,
  "creationTime": "2019-12-18T19:00:26.512Z",
  "name": "Home_Base"
}

Get a home

Endpoint
get /homes/{homeId}
Description

Return the home with the specified ID.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200Successfully retrieved home with specified ID.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested home does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": 1888,
  "projectId": 1260,
  "creationTime": "2019-12-18T19:00:26.512Z",
  "name": "Home3"
}

Update a home

Endpoint
patch /homes/{homeId}
Description

Update the home with the specified ID. However, the deactivated field of a home can be changed only if the request is made using a project API key with "Admin" privileges.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key or a project API key with "Admin" privileges.

Request Body

  • name

    string

    required

    Display name of home.

  • deactivated

    boolean

    True if home has been deactivated by project admin.

Response
  • 204Successfully updated home with specified ID. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested home does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "name": "New_Home"
}

Delete a home

Endpoint
delete /homes/{homeId}
Description

Delete the home with the specified ID.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

Request Headers What's this?

  • Authorization

    required

    A User API Key is required.

Response
  • 201Successfully deleted home with the specified ID. There is no return body.
  • 204The home has been successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required home does not exist or is not accessible.
  • 409The home cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get all home members

Endpoint
get /homes/{homeId}/members
Description

Get all members belonging to the specified home.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200A list of member objects are returned in the response body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

[
    {
        "userId": 2081,
        "creationTime": "2019-12-18T19:00:26.521Z",
        "name": "Jane Doe",
        "phoneNumber": "+17149999999",
        "verified": true,
        "role": "owner"
    },
    {
        "userId": 2082,
        "creationTime": "2019-11-18T19:00:26.521Z",
        "name": "John Doe",
        "phoneNumber": "+17149999999",
        "verified": true,
        "role": "owner"
    }
]

Add a home member

Endpoint
post /homes/{homeId}/members
Description

Add a member to the home. Only existing home members with the OWNER role may make this request. Based on the type of the project, this API call does one of the following:

Project Uses the Built-In Account System (Based on Email Addresses)

Add a member to the home. The member's email address must be specified. If the member is not an existing user, the "verified" field of the returned member object will be false. An email notification will be sent to the invited member.

Project Uses the Built-In Account System (Based on Phone Numbers)

Add a member to the home. The member's phone number must be specified. If the member is not an existing user, the "verified" field of the returned member object will be false. It is the app's responsibility to send an SMS invite to the invited member.

Project is BYOU ("Bring-Your-Own-Users")

Add an existing user with the specified user ID to a home.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

Request Headers What's this?

  • Authorization

    required

    Must contain user API key of the home owner, or Project API key with "Admin" privileges.

Request Body

  • email

    string

    Member's email address. Required for projects with email address-based user accounts.

  • phoneNumber

    string

    Member's phone number.

    Required for projects with phone number-based user accounts.

  • userId

    integer

    A valid user ID. Required for BYOU projects.

  • role

    string

    Optional field to set the role of the new member. By default, new members are given the OWNER role.

  • silent

    boolean

    Optional field to suppress email notification to the new member. Applicable only to email address-based user accounts.

Response
  • 201Successfully added a new home member.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "phoneNumber": "+17149999999"
}

Response Body Sample

{
  "userId": 2083,
  "creationTime": "2019-12-18T20:12:13.478Z",
  "phoneNumber": "+17149999999",
  "verified": false,
  "role": "owner"
}

Get a home member

Endpoint
get /homes/{homeId}/members/{userId}
Description

Get the home member with the specified user ID.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • userId

    integer

    required

    The unique ID for a specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200Successfully retrieved home member from the specified home ID and user ID.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested member does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
    "userId": 2081,
    "creationTime": "2019-12-18T19:00:26.521Z",
    "name": "Jane Doe",
    "phoneNumber": "+1719999999",
    "verified": true,
    "role": "owner"
}

Update home member role

Endpoint
patch /homes/{homeId}/members/{userId}
Description

Update the home member with the sepcified user ID. Only the "role" of the member can be changed at this time. Regular members of a home are not permitted to make this request.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • userId

    integer

    required

    The unique ID for a specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain user API key of the home owner, or Project API key with "Admin" privileges.

Request Body

  • role

    If the role is OWNER, this member can add or remove other members.

    Options are owner, member

Response
  • 204Successfully updated home member's role. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested member does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "role": "owner"
}

Remove a home member

Endpoint
delete /homes/{homeId}/members/{userId}
Description

Delete the specified user as a member of the home. This removes a member from the home but does not delete the user from the system. If the request is made by the same user to be removed, this is equivalent to leaving a home. Otherwise, only owners of the home can remove another member.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • userId

    integer

    required

    The unique ID for a specified user.

Request Headers What's this?

  • Authorization

    required

    Must contain user API key, or Project API key with "Admin" privileges.

Response
  • 204Successfully updated home member's role. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required member does not exist or is not accessible.
  • 409The member cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get all smart modules

Endpoint
get /homes/{homeId}/smartModules
Description

Get the list of Smart Modules available for the home.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200Successful retrieval of all smart modules.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

[
    {
        "description": "Webhook for device commands",
        "id": "001",
        "moduleType": "webhooks",
        "suspended": false
    },
    {
        "description": "Google Analytics for sensor data",
        "id": "GA",
        "moduleType": "google_analytics",
        "suspended": false
    }
]

Get a smart module

Endpoint
get /homes/{homeId}/smartModules/{moduleId}
Description

Get the info on the specified Smart Module.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • moduleId

    string

    required

    Module ID

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested Smart Module is returned. Only public information such as description will be included.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested smartModule does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
    "description": "Webhook for device commands",
    "id": "001",
    "moduleType": "webhooks",
    "suspended": false
}

Send event to a home

Endpoint
put /homes/{homeId}/event
Description

Send an event to the specified home and propagate it to the relevant listeners. This endpoint is used by authorized clients that have been assigned the proper project API keys.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key with permission to send events.

Request Body

  • eventType

    string

    required

    Event type ID. Project Developers can define any event IDs.

  • eventData

    object

    required

    Event-specific data as a JSON hash. Opaque to the cloud service.

Response
  • 204Event sent to home successfully. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested event does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
    "eventType": "sprinkler-status",
    "eventData": {
        "zones": [0,0,0,0,0,0,0,1],
        "serial": 12,
        "timestamp": 1402313424,
        "appSerial": 14,
        "appTimestamp": 14243423423
    }
}

Initiate on-demand device provisioning

Endpoint
post /homes/{homeId}/deviceProvisioning
Description

If On-Demand Device Provisioning is enabled for your project, a home member can use this endpoint to initiate the process of adding a new device to the home. It returns a device provisioning token that should be passed to the device hardware (via local WiFi, Bluetooth, etc.). The device should then send this token to the Device endpoint to complete the process.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key or a project API key with "Admin" privileges.

Request Body

  • deviceClass

    string

    required

    Device Class ID of the device to be added.

  • deviceTag

    string

    An optional tag assigned to the device to be added.

Response
  • 200A device provisiong token is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "deviceClass": "smart_light",
  "deviceTag": "0001"
}

Get key-value pairs

Endpoint
get /homes/{homeId}/kv
Description

Get all key-value pairs stored for the specified home.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

Query Parameters

  • keyPrefix

    string

    required

    If specified, only items with keys containing the prefix are returned.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200An array of key-value pair objects are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

[
    {
        "key": "happy",
        "value": true,
        "modificationTime": "2020-01-02T23:18:16.915Z"
    },
    {
        "key": "neutral",
        "value": false,
        "modificationTime": "2020-01-02T23:17:39.852Z"
    },
    {
        "key": "clicks",
        "value": 100,
        "modificationTime": "2020-01-02T23:18:21.383Z"
    }
]

Find a key-value pair

Endpoint
get /homes/{homeId}/kv/{key}
Description

Get the key-value pair for the specified key.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • key

    string

    required

    A unique key for a key-value pair stored for a home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The matching key-value pair is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested kv does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "key": "happy",
  "value": true,
  "modificationTime": "2020-01-02T23:18:16.915Z"
}

Create or update a key-value

Endpoint
put /homes/{homeId}/kv/{key}
Description

Set the value for the specified key. If the key-value pair does not already exist, it is created.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • key

    string

    required

    A unique key for a key-value pair stored for a home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Request Body

  • value

    string

    required

    The value set to the key.

Response
  • 204Key-value pair has been successfully stored. There is no response body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The specified home does not exist.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
    "value": "value-to-the-key"
}

Delete a key-value pair

Endpoint
delete /homes/{homeId}/kv/{key}
Description

Delete the key-value pair for the specified key.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • key

    string

    required

    A unique key for a key-value pair stored for a home.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Response
  • 204The key-value pair has been successfully deleted. There is no response body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required kv does not exist or is not accessible.
  • 409The kv cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Proxy GET request to app server

Endpoint
get /homes/{homeId}/appProxy/{srcPath}
Description

Proxy a GET request to the a target app service if there is a matching App Proxy route for the specified source path. The response depends on the behavior of the target app service.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • srcPath

    string

    required

    A path that matches one of the source paths in the project's App Proxy configuration for homes.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Proxy POST request to app server

Endpoint
post /homes/{homeId}/appProxy/{srcPath}
Description

Proxy a POST request to the a target app service if there is a matching App Proxy route for the specified source path. The request body and response depend on the behavior of the target app service.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • srcPath

    string

    required

    A path that matches one of the source paths in the project's App Proxy configuration for homes.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Proxy PUT request to app server

Endpoint
put /homes/{homeId}/appProxy/{srcPath}
Description

Proxy a PUT request to the a target app service if there is a matching App Proxy route for the specified source path. The request body and response depend on the behavior of the target app service.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • srcPath

    string

    required

    A path that matches one of the source paths in the project's App Proxy configuration for homes.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Proxy PATCH request to app server

Endpoint
patch /homes/{homeId}/appProxy/{srcPath}
Description

Proxy a PATCH request to the a target app service if there is a matching App Proxy route for the specified source path. The request body and response depend on the behavior of the target app service.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • srcPath

    string

    required

    A path that matches one of the source paths in the project's App Proxy configuration for homes.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Proxy DELETE request to app server

Endpoint
delete /homes/{homeId}/appProxy/{srcPath}
Description

Proxy a DELETE request to the a target app service if there is a matching App Proxy route for the specified source path. The response depends on the behavior of the target app service.

Path Parameters

  • homeId

    integer

    required

    The unique ID for a specified home.

  • srcPath

    string

    required

    A path that matches one of the source paths in the project's App Proxy configuration for homes.

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.