API Reference: Resources

List of resources and endpoints available on the MODE cloud API.

Version
2.1
Base URL
https://api.tinkermode.com

Users

Registered end-users of a project.

Create User

When a project is created on MODE, developer must specify how user accounts should be handled. By default, a project uses the built-in user account system provided by MODE. But a project can also implement its own separate account system for its users. So based on the type of the project, this API call does one of the following.

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

Register a new user. The request body must be a valid user object containing the projectId, phoneNumber and name fields. The phone number must not be in use by a current user of the project. An SMS text containing a verification code will be sent to the user to confirm the registration.

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

Register a new user. The request body must be a valid user object containing the projectId, email and name fields. In addtion, a password field must also be present. The email address must not be in use by a current user of the project. An email message containing a verification URL will be sent to the user to confirm the registration.

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

Create an entry in MODE that corresponds to an existing user in the project's own account system. The request object only needs to contain the projectId field. The request must also come with an Authorization header that contains a Project API Key with the permission to handle BYOU. The returned user object contains a unique user ID. The caller should store this user ID for future MODE API calls.

API Endpoint
post /users
Headers
Header Description Required
Authorization
string

Must contain a Project API Key with the BYOU permission. Required for BYOU projects only.

No
Request Body
User (JSON)
Response
Code Body Description
201 User

Successfully created the user. The created object is returned in the response body.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Get User

Return the user with the specified ID.

API Endpoint
get /users/{userId}
URI Parameters
Field Description Required
userId
integer

User ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of the matching user.

Yes
Response
Code Body Description
200 User

The requested user is returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

404 Error

The requested user does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Update User

Update the user with the specified ID.

API Endpoint
patch /users/{userId}
URI Parameters
Field Description Required
userId
integer

User ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of the matching user.

Yes
Request Body
User (JSON)
Response
Code Body Description
204

The user has been successfully updated.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The requested user does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Delete User

Delete the user with the specified ID.

API Endpoint
delete /users/{userId}
URI Parameters
Field Description Required
userId
integer

User ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of the matching user.

Yes
Response
Code Body Description
204

The user has been successfully deleted.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The required user does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Homes

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

Get Homes

Get a list of homes a user belongs to.

API Endpoint
get /homes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Query Parameters
Field Description Required
userId
integer

Return homes of which the specified user is a member.

Yes
Response
Code Body Description
200 Array of Homes

A list of home objects are returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Create Home

Create a new home for the user who is making this request. The request body must contain the "name" field. The user is automatically added as a member of the home.

API Endpoint
post /homes
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Request Body
Home (JSON)
Response
Code Body Description
201 Home

Successfully created the home. The created object is returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Get Home

Return the home with the specified ID.

API Endpoint
get /homes/{homeId}
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Response
Code Body Description
200 Home

The requested home is returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

404 Error

The requested home does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Update Home

Update the home with the specified ID.

API Endpoint
patch /homes/{homeId}
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Request Body
Home (JSON)
Response
Code Body Description
204

The home has been successfully updated.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The requested home does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Delete Home

Delete the home with the specified ID.

API Endpoint
delete /homes/{homeId}
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Response
Code Body Description
204

The home has been successfully deleted.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The required home does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Get Home Members

Get all members belonging to the specified home.

API Endpoint
get /homes/{homeId}/members
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Response
Code Body Description
200 Array of Home Members

A list of member objects are returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Add Home Member

Based on the type of the project, this API call does one of the following:

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 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 is BYOU ("Bring-Your-Own-Users")

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

API Endpoint
post /homes/{homeId}/members
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Request Body
Web Form:
Field Description Required
phoneNumber
string

Member's phone number. Required for projects with phone number-based user accounts.

No
email
string

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

No
userId
integer

A valid user ID. Required for BYOU projects.

No
Response
Code Body Description
201 Home Member

Successfully created the member. The created object is returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Get Home Member

Get the home member with the specified user ID.

API Endpoint
get /homes/{homeId}/members/{userId}
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
userId
integer

User ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Response
Code Body Description
200 Home Member

The requested member is returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

404 Error

The requested member does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Delete Home Member

Delete the specified user as a member of the home.

API Endpoint
delete /homes/{homeId}/members/{userId}
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
userId
integer

User ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Response
Code Body Description
204

The member has been successfully deleted.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The required member does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Get Smart Modules

Get the list of Smart Modules available for the home.

API Endpoint
get /homes/{homeId}/smartModules
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Response
Code Body Description
200 Array of Smart Modules

A list of smartModule objects are returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Get Smart Module

Get the info on the specified Smart Module.

API Endpoint
get /homes/{homeId}/smartModules/{moduleId}
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
moduleId
string

Module ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Response
Code Body Description
200 Smart Module

The requested Smart Module is returned. Only public information such as description will be included.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

404 Error

The requested smartModule does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Send Event to Home

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.

API Endpoint
put /homes/{homeId}/event
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
Headers
Header Description Required
Authorization
string

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

Yes
Request Body
Event (JSON)
Example:
{
    "eventType": "sprinkler-status",
    "eventData": {
        "zones": [0,0,0,0,0,0,0,1],
        "serial": 12,
        "timestamp": 1402313424,
        "appSerial": 14,
        "appTimestamp": 14243423423
    }
}
Response
Code Body Description
204

Data have been sent successfully.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The requested event does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Initiate On-Demand Device Provisioning

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.

API Endpoint
post /homes/{homeId}/deviceProvisioning
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Request Body
Web Form:
Field Description Required
deviceClass
string

Device Class ID of the device to be added.

Yes
deviceTag
string

An optional tag assigned to the device to be added.

No
Response
Code Body Description
200 Device Provisioning Token

A device provisiong token is returned.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Get Key-Value Pairs

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

API Endpoint
get /homes/{homeId}/kv
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Query Parameters
Field Description Required
keyPrefix
string

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

No
Response
Code Body Description
200 Array of Key-Value Pairs

An array of key-value pair objects are returned.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Look Up a Key-Value Pair

Get the key-value pair for the specified key.

API Endpoint
get /homes/{homeId}/kv/{key}
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
key
string

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

Yes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Response
Code Body Description
200 Key-Value Pair

The matching key-value pair is returned.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

404 Error

The requested kv does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Delete a Key-Value Pair

Delete the key-value pair for the specified key.

API Endpoint
delete /homes/{homeId}/kv/{key}
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
key
string

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

Yes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Response
Code Body Description
204

The key-value pair has been successfully deleted.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The required kv does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Create/Update a Key-Value Pair

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

API Endpoint
put /homes/{homeId}/kv/{key}
URI Parameters
Field Description Required
homeId
integer

Home ID

Yes
key
string

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

Yes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Request Body
Key-Value Pair (JSON)
Response
Code Body Description
204

Key-value pair has been successfully stored.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The requested <> does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Devices

Cloud-aware devices that have been registered to a home. Some devices connect to the cloud directly, while some are under the control of a hub.

Get Devices

Get the list of devices of a home.

API Endpoint
get /devices
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Query Parameters
Field Description Required
homeId
integer

Return devices that belong to the specified home.

Yes
Response
Code Body Description
200 Array of Devices

A list of device objects are returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Add Device to Home

Add a device to a user's home. The complete process depends on how the project was set up and is carried out in one of two possible ways.

Devices are Pre-provisioned

If the project was configured to pre-provision all its devices, adding a device to a home means claiming ownership of an existing device and registering it to the specified home. In this scenario, the device in question must first enable registration before the user calls this API method.

Devices are Provisioned on Demand

If the project was configured to allow On-Demand Device Provisioning, a user must first initiate the device provisioning process and obtain a provisioning token. The token should be passed to the device hardware which will then call this API method to complete the process. The Device object returned will contain an API key. The device hardware should store the device ID and API key, so that it can begin communicating with the MODE API directly.

API Endpoint
post /devices
Headers
Header Description Required
Authorization
string

Must contain API key of a user. Required only if device is pre-provisioned.

No
Request Body
Web Form:
Field Description Required
homeId
integer

ID of the home to which the device will be added. Required if device is pre-provisioned.

No
claimCode
string

Unique claim code assigned to the device to be added. Required if device is pre-provisioned.

No
token
string

Device provisioning token issued for the device to be added. Required for On-Demand Device Provisioning.

No
Response
Code Body Description
201 Device

Successfully created the device. The created object is returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Get Device Info

Return the device with the specified ID.

API Endpoint
get /devices/{deviceId}
URI Parameters
Field Description Required
deviceId
integer

Device ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a project, user or device API key.

Yes
Response
Code Body Description
200 Device

The requested device is returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

404 Error

The requested device does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Update Device Info

Update the device with the specified ID.

API Endpoint
patch /devices/{deviceId}
URI Parameters
Field Description Required
deviceId
integer

Device ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Request Body
Device (JSON)
Response
Code Body Description
204

The device has been successfully updated.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The requested device does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Delete Device

Delete the device with the specified ID.

API Endpoint
delete /devices/{deviceId}
URI Parameters
Field Description Required
deviceId
integer

Device ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Response
Code Body Description
204

The device has been successfully deleted.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The required device does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Send Command

Issue a command to the specified device.

API Endpoint
put /devices/{deviceId}/command
URI Parameters
Field Description Required
deviceId
integer

Device ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Request Body
Device Command (JSON)
Example:
{
    "action": "sprinkler-on",
    "parameters": {
        "zone": 2,
        "duration": 120
    }
}
Response
Code Body Description
204

Data have been sent successfully.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The requested command does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Receive Commands

Establish a WebSocket connection and listen for commands. Only the corresponding device itself can make this call. Any non-WebSocket requests will be rejected. Once the connection is established, the client can expect incoming messages in the form of Device Command JSON objects as used in the PUT method. Since not all WebSocket client implementations allow you to set the Authorization HTTP header, you can pass the device API key as the authToken query parameter.

API Endpoint
get /devices/{deviceId}/command
URI Parameters
Field Description Required
deviceId
integer

Device ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of the matching device.

Yes
Query Parameters
Field Description Required
authToken
string

API key assigned to device. Needed only if the Authorization header cannot be set.

No
Response
Code Body Description
101

Successfully established a WebSocket connection.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The requested resource does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Send Device Event

Send a device event to the cloud, which propagates the event to the other relevant listeners. Only the corresponding device itself can make this call.

API Endpoint
put /devices/{deviceId}/event
URI Parameters
Field Description Required
deviceId
integer

Device ID

Yes
Headers
Header Description Required
Authorization
string

Must contain API key of the matching device.

Yes
Request Body
Event (JSON)
Example:
{
    "eventType": "sprinkler-status",
    "eventData": {
        "zones": [0,0,0,0,0,0,0,1],
        "serial": 12,
        "timestamp": 1402313424,
        "appSerial": 14,
        "appTimestamp": 14243423423
    }
}
Response
Code Body Description
204

Data have been sent successfully.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The requested event does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Authentication

For handling API client authentication. These resources do not adhere strictly to a RESTful model.

Get Authentication State

Test the authentication token used in the HTTP Authorization header of the API request.

API Endpoint
get /auth
Headers
Header Description Required
Authorization
string

Must contain a valid API key.

Yes
Response
Code Body Description
200 Authentication Info

Info about the identity of the client.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Authenticate a User

Based on the type of the project, this API call does one of the following.

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

Exchange the auth code sent to user via SMS for an API key. The request body must contain the phoneNumber, appId and code parameters.

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

Authenticate a user by password and return an API key. The request body must contain the email, appId and password parameters.

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

Obtain an API key for a user. The request body must contain the userId and projectId parameters. The request must also come with an Authorization header that contains a Project API Key with the permission to handle BYOU.

API Endpoint
post /auth/user
Headers
Header Description Required
Authorization
string

Must contain a Project API Key with BYOU permission. Required for BYOU projects only.

No
Request Body
Web Form:
Field Description Required
projectId
integer

ID of project to which the user belongs.

Yes
appId
string

ID of the app being used to access the API. Required except for BYOU projects.

No
phoneNumber
string

Phone number of user to be authenticated. Required only for projects with phone number-based user accounts.

No
code
string

Auth code sent to user via SMS. Required only for projects with phone number-based user accounts.

No
email
string

Email address of user to be authenticated. Required only for projects with email address-based user accounts.

No
password
string

Password of user to be authenticated. Required only for projects with email address-based user accounts.

No
userId
integer

ID of user to be authenticated. Required only for BYOU projects.

No
Response
Code Body Description
200 Client Authentication

User is successfully authenticated.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Initiate User Authentication with SMS

Initiate the authentication process by triggering an SMS text to a user. The text contains an auth code for the user to exchange for an authentication token. This API call is only allowed for projects with phone number-based user accounts.

API Endpoint
post /auth/user/sms
Request Body
Web Form:
Field Description Required
projectId
integer

ID of project to which the user belongs.

Yes
phoneNumber
string

Phone number of user to be authenticated. It needs to be registered already on MODE cloud by Create User API call.

Yes
Response
Code Body Description
200 SMS Message Receipt

SMS message successfully sent.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Verify User Email Address

Verify a user account by an email verification token. This API call is only allowed for projects with email address-based user accounts.

API Endpoint
post /auth/user/emailVerification
Request Body
Web Form:
Field Description Required
token
string

Verification token emailed to user.

Yes
Response
Code Body Description
200

User's identity has been verified.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Initiate User Email Verification

Initiate the account verification process by sending out a verification email. For users who have lost the original message. This API call is only allowed for projects with email address-based user accounts.

API Endpoint
post /auth/user/emailVerification/start
Request Body
Web Form:
Field Description Required
projectId
integer

ID of project to which the user belongs.

Yes
email
string

Email address of user.

Yes
Response
Code Body Description
200

An email has been sent to the specified email address.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Reset User Password

Reset the password of a user. This API call is only allowed for projects with email address-based user accounts.

API Endpoint
post /auth/user/passwordReset
Request Body
Web Form:
Field Description Required
token
string

Password reset token emailed to user.

Yes
newPassword
string

New password for user's account.

Yes
Response
Code Body Description
200

User's password has been updated.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Initiate User Password Reset

Initiate the password reset process by sending out an email containing a password reset token. For users who have forgotten their passwords. This API call is only allowed for projects with email address-based user accounts.

API Endpoint
post /auth/user/passwordReset/start
Request Body
Web Form:
Field Description Required
projectId
integer

ID of project to which the user belongs.

Yes
email
string

Email address of user.

Yes
Response
Code Body Description
200

An email has been sent to the specified email address.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Device Registration

For initiating the process to register devices to homes. This step is required unless the project was configured to allow On-Demand Device Provisioning.

Update Device Registration State

Modify the registration state of the specified device. Only the device itself can make this request.

API Endpoint
post /deviceRegistration
Headers
Header Description Required
Authorization
string

Must contain API key of the matching device.

Yes
Request Body
Web Form:
Field Description Required
deviceId
integer

ID of device to be modified.

Yes
claimable
boolean

Set device to be claimable if it is true.

Yes
duration
integer

Duration of the claimable state in seconds.

No
Response
Code Body Description
200 Registration State Response

Successfully set the specified device to the new state.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

User Session

This resource becomes available after a user has successfully authenticated with the API service.

Get User Session Info

Get info about the current user session.

API Endpoint
get /userSession
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Response
Code Body Description
200 User Session Info

The requested userSession is returned in the response body.

401

Authorization is required to access this resource.

403 Error

Request failed because of denied permission.

404 Error

The requested userSession does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Terminate User Session

Terminate a user session. The associated API key will also be invalidated.

API Endpoint
delete /userSession
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Response
Code Body Description
204

User session terminated.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The required userSession does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.

Listen to Events

Establish a WebSocket connection and listen for events. Any non-WebSocket requests will be rejected. Once the connection is established, the client can expect incoming messages in the form of Device Event JSON objects. Since not all WebSocket client implementations allow you to set the Authorization HTTP header, you can pass the user API key as the authToken query parameter. This API call is not allowed for BYOU projects.

API Endpoint
get /userSession/websocket
Headers
Header Description Required
Authorization
string

Must contain API key of a user.

Yes
Query Parameters
Field Description Required
authToken
string

User API key. Needed only if the Authorization header cannot be set.

No
Response
Code Body Description
101

Successfully established a WebSocket connection.

401

Authorization is required to access this resource.

403 Error

Request failed because of invalid data or denied permission.

404 Error

The requested resource does not exist or is not accessible.

500 Error

An unexpected error has occurred.

503 Error

The service is temporarily unavailable.