API Reference: Resources

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

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

Users

Registered end-users of a project.

Get Users

Fetch users of a project. If the optional search parameter is used, users with matching name, email address or phone number will be returned. The search string is tokenized using whitespace and most punctuation as delimiters. Items matching at least one of the tokens will be returned. To search for exact phrases, wrap the search string in double-quotes ("). To exclude items matching a word, prepend a minus sign (-) to the word.

API Endpoint
get /users
Headers
Header Description Required
Authorization
string

Must contain a Project API Key with admin permission.

Yes
Query Parameters
Field Description Required
projectId
integer

Return users of the specified project.

Yes
search
string

Search for users by keywords.

No
skip
integer

Number of users to skip over.

No
limit
integer

Maximum number of users to return.

No
Response
Code Body Description
200 Array of Users

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. (However, if reqeuest is made using an Admin Project API Key, the user is "pre-verified", and no confirmation text will be sent.)

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 addition, 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. (However, if request is made using an Admin Project API Key, the user is "pre-verified", and no confirmation email will be sent.)

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

If project is BYOU, a Project API Key with the BYOU or Admin permission is required. Otherwise, an Admin Project API Key can be used to add a "pre-verified" user to system.

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, or a Project API Key with admin permission.

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, or a Project API Key with admin permission.

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, or a Project API Key with admin permission.

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 of a project (by using the projectId parameter), or homes of which a user is a member (by using the userId parameter). To fetch the homes of a project, the request must be made using a project API key with "Admin" privileges.

API Endpoint
get /homes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Query Parameters
Field Description Required
projectId
integer

Return homes of the specified project.

No
userId
integer

Return homes of which the specified user is a member.

No
skip
integer

Number of homes to skip over.

No
limit
integer

Maximum number of homes to return.

No
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 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.

API Endpoint
post /homes
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

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. However, the deactivated field of a home can be changed only if the request is made using a project API key with "Admin" privileges.

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

Home ID

Yes
Headers
Header Description Required
Authorization
string

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

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

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 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 user API key of the home owner, or Project API key with "Admin" privileges.

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
role
string

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

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.

Update Home Member

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.

API Endpoint
patch /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 user API key of the home owner, or Project API key with "Admin" privileges.

No
Request Body
Home Member (JSON)
Response
Code Body Description
204

The member 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 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. 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.

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 user API key, or Project API key with "Admin" privileges.

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 a user API key or a project API key with "Admin" privileges.

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 or will be manufactured for a project. Each object represents an instance of a device class defined for the project.

Get Devices

Get the list of devices of a project (by using the projectId parameter), or devices belonging to a home (by using the homeId parameter). To fetch the devices of a project, the request must be made using a project API key with "Admin" privileges. An optional deviceClass parameter can be used to return only devices of the specified device class.

API Endpoint
get /devices
Headers
Header Description Required
Authorization
string

Must contain a user or project API key.

Yes
Query Parameters
Field Description Required
projectId
integer

Return devices of the specified project.

No
homeId
integer

Return devices that belong to the specified home.

No
deviceClass
string

Return devices of the specified Device Class ID.

No
skip
integer

Number of devices to skip over.

No
limit
integer

Maximum number of devices to return.

No
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
deviceClass
string

Override the default Device Class associated with the token. Only used 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. Normally, only the name field of the device instance can be changed. But if the request is made with a Project API Key with "Admin" privileges, the device instance can be moved or added to a home by specifying a homeId field in the request body.

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

Device ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a project or user API key.

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 (or "Un-provision") the device with the specified ID. The actual process depends on how the project is set up.

Devices are Pre-provisioned

If the project was configured to pre-provision all its devices, deleting a device simply means removing the device from its current home. The device can be claimed by another home in the future, and the device ID and device API key remain valid.

Devices are Provisioned on Demand

If the project was configured to allow On-Demand Device Provisioning, deleting a device means removing the device from its home and erasing the device from the system permanently. The device ID and device API key will become invalid.

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

Device ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a project or device API key.

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 an 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.

Get Key-Value Pairs (and Receive Updates)

Get all key-value pairs stored for the specified device, if request is a regular REST call. However, if the caller is the device itself, it can upgrade the request into a WebSocket connection. In that scenario, the device will automatically receive a full dump of all key-value pairs right after the WebSocket upgrade, and will receive real-time key-value updates thereafter.

This is part of the Device Data Proxy feature.

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

Device ID

Yes
Headers
Header Description Required
Authorization
string

Must contain a user key, project API key, or API key of the matching device.

Yes
Query Parameters
Field Description Required
keyPrefix
string

If specified, only items with keys containing the prefix are returned. This parameter is ignored for WebSocket requests.

No
Response
Code Body Description
101

Successfully established a WebSocket connection.

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 /devices/{deviceId}/kv/{key}
URI Parameters
Field Description Required
deviceId
integer

Device ID

Yes
key
string

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

Yes
Headers
Header Description Required
Authorization
string

Must contain a user key, project API key, or API key of the matching device.

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 /devices/{deviceId}/kv/{key}
URI Parameters
Field Description Required
deviceId
integer

Device ID

Yes
key
string

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

Yes
Headers
Header Description Required
Authorization
string

Must contain a user key, project API key, or API key of the matching device.

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 /devices/{deviceId}/kv/{key}
URI Parameters
Field Description Required
deviceId
integer

Device ID

Yes
key
string

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

Yes
Headers
Header Description Required
Authorization
string

Must contain a user key, project API key, or API key of the matching device.

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.

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.

Activate User Account

When a new user is invited to a home, the user is originally in an inactive state. An email will be sent to the invited user with an activation token. The user can activate their account by submitting the account name and password along with the token. This API call is only allowed for projects with email address-based user accounts.

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

Activation token emailed to user.

Yes
name
string

User's name to be associated with the account.

Yes
password
string

Password for logging into the account.

Yes
Response
Code Body Description
200

User's account has be activated.

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.

Authenticate by Sudo

A special endpoint for project administrator to assume the identity of a user to log into an app (a practice commonly known as "sudo"). This is useful for troubleshooting user issues. The caller must first obtain a sudo authorization token, usually from the project's "admin server". The User Session resulted from sudo will automatically expire after 30 minutes. This API call is not allowed for BYOU projects.

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

Sudo authorization token.

Yes
Response
Code Body Description
200 Client Authentication

Sudo access granted.

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 Sudo Authentication

Request a sudo authorization token for an authorized project administrator (the "sudoer"). This is usually done from some kind of "admin server" created for administrators to manage their applications or support their users. The returned token should be passed onto the sudoer immediately to complete the sudo process. This API call is not allowed for BYOU projects.

API Endpoint
post /auth/sudo/start
Headers
Header Description Required
Authorization
string

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

Yes
Request Body
Web Form:
Field Description Required
sudoer
string

Identity of the administrator requesting sudo access.

Yes
targetUserId
integer

User ID of the sudo target.

Yes
targetAppId
string

ID of the app expected to be used to access the API.

Yes
Response
Code Body Description
200 Sudo Authorization Token

Sudo authorization token issued and 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.

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. If the claimable parameter is true, the duration parameter must also be specified.

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 Event JSON objects. Use the homeId or deviceId query parameter to limit what events to be sent through the conenction. (If both homeId and deviceId parameters are present at the same time, only deviceId will take effect.) 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
homeId
integer

If this parameter is present, only events for the specified home will be sent through this WebSocket connection. This parameter can be used multiple times to capture events for multiple homes.

No
deviceId
integer

If this parameter is present, only events from the specified device will be sent through this WebSocket connection. This parameter can be used multiple times to capture events from multiple devices.

No
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.