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. Must begin with country code (beginning with the '+' symbol).
- emailstring
Email address of member.
- verifiedboolean
True if member is a verified user.
- role
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. Must be 3 or more lowercase alphanumeric characters; dashes ('-') and underscores ('_') may be used after the first character but must be followed by 1+ lowercase alphanumeric characters.
- 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). Optionally, results can be filtered by keywords. Either the projectId or userId must be specified. To fetch the homes of a project, the request must be made using the API key of a user who has permission to read all homes, or 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.
search
string
Search for homes by keywords.
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 the API key of a user who has permission to create homes, or 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": "Time series database for sensor data",
"id": "sensor-data",
"moduleType": "tsdb",
"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. Must begin 1 or more alpha characters; dashes ('-') and underscores ('_') may be used after the first character but must be followed by 1+ alphanumeric characters.
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.
Get Log Entries
Endpoint
get /homes/{homeId}/logEntries
Description
Get debug and error log entries for home.
Path Parameters
homeId
integer
required
The unique ID for a specified home.
Query Parameters
begin
string
required
Return entries bound by this timestamp. Format must conform to RFC3339.
end
string
required
Return entries bound by this timestamp. Format must conform to RFC3339.
maxEntries
integer
Limit the number of entries returned.
Request Headers What's this?
Authorization
required
Must contain the API key of a user with permissions to read home logs or a Project API Key.
Response
- 200A list of logEntry 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.
Get HTTP Access Log Entries
Endpoint
get /homes/{homeId}/httpLogEntries
Description
Get HTTP access log entries for home.
Path Parameters
homeId
integer
required
The unique ID for a specified home.
Query Parameters
begin
string
required
Return entries bound by this timestamp. Format must conform to RFC3339.
end
string
required
Return entries bound by this timestamp. Format must conform to RFC3339.
maxEntries
integer
Limit the number of entries returned.
Request Headers What's this?
Authorization
required
Must contain the API key of a user with permissions to read home logs or a Project API Key.
Response
- 200A list of httpLogEntry 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.
Get all data sources
Endpoint
get /homes/{homeId}/dataSources
Description
Get the list of data sources of a home. Data sources are represented as data generated sources such as sensors, Web APIs, databases, and so on. It's used for enabling sensors on gateways and accepting requests from data sources to the MODE Cloud.
Path Parameters
homeId
integer
required
The unique ID for a specified home.
Query Parameters
deviceId
integer
Return data sources of the specified devices.
catalogId
string
Return data sources of the specified catalogId.
dataType
string
Return data sources of the specified dataType. dataType allows "metrics" and "locations" only.
skip
integer
Number of data sources to skip over.
limit
integer
Maximum number of data sources to return.
Default value is
25
Minimum value is
1
headers
string
required
responses
string
required
Response
- 200A list of dataSource 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.
Add a data source
Endpoint
post /homes/{homeId}/dataSources
Description
Add a data source to a home. Data sources must be associated with Data Source Catalog ID which is allowed by the system administrator.
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.
Request Body
name
string
required
Display name of data source.
enabled
boolean
The flag indicates whether the data source is enabled.
attributes
object
Optional/informational key-values associated with device. Can be used to store the serial number, for example.
Response
- 201Successfully created a new data source.
- 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
{
"projectId": 1234,
"homeId": 1234,
"name": "Sensor 1",
"catalogId": "bu01",
"sourceId": "a3b2ac399abc",
"dataType": "metrics",
"enabled": true,
"multi": false,
"attributes": {
"manufacturer": "MODE, inc.",
"serial": "0000001234"
}
}
Response Body Sample
{
"projectId": 1234,
"homeId": 1234,
"name": "Sensor 1",
"catalogId": "bu01",
"sourceId": "a3b2ac399abc",
"dataType": "metrics",
"enabled": true,
"multi": false,
"attributes": {
"manufacturer": "MODE, inc.",
"serial": "0000001234"
}
}
Get a data source
Endpoint
get /homes/{homeId}/dataSources/{dataSourceKey}
Description
Return the data source with the specified key.
Path Parameters
homeId
integer
required
The unique ID for a specified home.
dataSourceKey
string
required
A compound key consisted catalogId and sourceId with the separator
::
e.g.bu01::a4dd89297bfd
.
Request Headers What's this?
Authorization
required
Must contain a user or project API key.
Response
- 200Successfully retrieved data source with specified key.
- 401Authorization is required to access this resource.
- 403Request failed because of denied permission.
- 404The requested dataSource does not exist or is not accessible.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Response Body Sample
{
"projectId": 1234,
"homeId": 1234,
"name": "Sensor 1",
"catalogId": "bu01",
"sourceId": "a3b2ac399abc",
"dataType": "metrics",
"enabled": true,
"multi": false,
"attributes": {
"manufacturer": "MODE, inc.",
"serial": "0000001234"
}
}
Update a data source
Endpoint
patch /homes/{homeId}/dataSources/{dataSourceKey}
Description
Update the data source with the specified key. deviceId
is optional and must be the ID of
a device in the home.
Path Parameters
homeId
integer
required
The unique ID for a specified home.
dataSourceKey
string
required
A compound key consisted catalogId and sourceId with the separator
::
e.g.bu01::a4dd89297bfd
.
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 data source.
enabled
boolean
The flag indicates whether the data source is enabled.
attributes
object
Optional/informational key-values associated with device. Can be used to store the serial number, for example.
Response
- 204Successfully updated the data source with specified key. There is no return body.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 404The requested dataSource does not exist or is not accessible.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Request Body Sample
{
"projectId": 1234,
"homeId": 1234,
"name": "Sensor 1",
"catalogId": "bu01",
"sourceId": "a3b2ac399abc",
"dataType": "metrics",
"enabled": true,
"multi": false,
"attributes": {
"manufacturer": "MODE, inc.",
"serial": "0000001234"
}
}
Delete a data source
Endpoint
delete /homes/{homeId}/dataSources/{dataSourceKey}
Description
Delete the data source with the specified key.
Path Parameters
homeId
integer
required
The unique ID for a specified home.
dataSourceKey
string
required
A compound key consisted catalogId and sourceId with the separator
::
e.g.bu01::a4dd89297bfd
.
Request Headers What's this?
Authorization
required
Must contain a user API key or a project API key with "Admin" privileges.
Response
- 204Successfully deleted the data source with the specified key. There is no return body.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 404The required dataSource does not exist or is not accessible.
- 409The dataSource 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 list of data routes
Endpoint
get /homes/{homeId}/dataRoutes
Description
Get all data routes defined for a project.
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.
dataType
Returns data routes of the specified data type.
skip
Number of data routes to skip over.
limit
Maximum number of data routes to return.
Response
- 200Successful retrieval of data routes.
- 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
[
{
"routeId": "655353717e1e0d5217c55c93",
"projectId": 1234,
"homeId": 1234,
"name": "Data Route 1",
"filterTypes": [
"conversion"
],
"dataType": "metrics",
"source": {
"catalogId": "bu01",
"sourceId": "a3b2ac399abc"
},
"destination": {
"entityClass": "warehouse",
"entityId": "floor_1",
"metricsDefinitionId": "environment"
}
},
{
"routeId": "655353717e1e0d5217c55c94",
"projectId": 1234,
"homeId": 1234,
"name": "Data Route 2",
"dataType": "locations",
"source": {
"catalogId": "extsvc",
"sourceId": "a3b2ac*"
},
"destination": {
"entityClass": "warehouse",
"entityId": "forklift_{{sourceId}}"
}
}
]
Create data routes
Endpoint
post /homes/{homeId}/dataRoutes
Description
Create a new data routes in the project
Path Parameters
homeId
integer
required
The unique ID for a specified home.
Request Headers What's this?
Authorization
required
Must contain the API key of a user who has the permission to create all data routes of a project, or a Project API Key with admin permission.
Request Body
homeId
integer
Home that this data route belongs to.
filterTypes
array
Filter types of the data route. The filter rules matched by the specified filter type are automatically applied to the data route. They must be supported filter type: conversion.
name
string
required
Display name of data route.
source
object
required
Source is the definition of the data source of the data route. The source must be referred to a Data Source or a wildcard data source.
destination
object
required
Destination is the definition of the target entity of the data route. The entity must be predefined in the project or a wildcard entityId.
Response
- 201Successful creation of data route.
- 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
{
"routeId": "655346bb7e1e0d5217c55c92",
"projectId": 1234,
"homeId": 1234,
"name": "Data Route 1",
"filterTypes": [
"conversion"
],
"dataType": "metrics",
"source": {
"catalogId": "bu01",
"sourceId": "a3b2ac399abc"
},
"destination": {
"entityClass": "warehouse",
"entityId": "floor_1",
"metricsDefinitionId": "environment"
}
}
Response Body Sample
{
"routeId": "655346bb7e1e0d5217c55c92",
"projectId": 1234,
"homeId": 1234,
"name": "Data Route 1",
"filterTypes": [
"conversion"
],
"dataType": "metrics",
"source": {
"catalogId": "bu01",
"sourceId": "a3b2ac399abc"
},
"destination": {
"entityClass": "warehouse",
"entityId": "floor_1",
"metricsDefinitionId": "environment"
}
}
Get data route
Endpoint
get /homes/{homeId}/dataRoutes/{routeId}
Description
Get the specified data route
Path Parameters
homeId
integer
required
The unique ID for a specified home.
routeId
string
required
Data Route ID
Request Headers What's this?
Authorization
required
Must contain a user or project API key.
Response
- 200Successful retrieval of the data route
- 401Authorization is required to access this resource.
- 403Request failed because of denied permission.
- 404The requested dataRoute does not exist or is not accessible.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Response Body Sample
{
"routeId": "655346bb7e1e0d5217c55c92",
"projectId": 1234,
"homeId": 1234,
"name": "Data Route 1",
"filterTypes": [
"conversion"
],
"dataType": "metrics",
"source": {
"catalogId": "bu01",
"sourceId": "a3b2ac399abc"
},
"destination": {
"entityClass": "warehouse",
"entityId": "floor_1",
"metricsDefinitionId": "environment"
}
}
Update data route
Endpoint
patch /homes/{homeId}/dataRoutes/{routeId}
Description
Update specified data route
Path Parameters
homeId
integer
required
The unique ID for a specified home.
routeId
string
required
Data Route ID
Request Headers What's this?
Authorization
required
Must contain the API key of a user who has the permission to update all data routes of a project, or a Project API Key with admin permission.
Request Body
homeId
integer
Home that this data route belongs to.
filterTypes
array
Filter types of the data route. The filter rules matched by the specified filter type are automatically applied to the data route. They must be supported filter type: conversion.
name
string
required
Display name of data route.
source
object
required
Source is the definition of the data source of the data route. The source must be referred to a Data Source or a wildcard data source.
destination
object
required
Destination is the definition of the target entity of the data route. The entity must be predefined in the project or a wildcard entityId.
Response
- 204Successfully updated data route.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 404The requested dataRoute does not exist or is not accessible.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.
Request Body Sample
{
"routeId": "655346bb7e1e0d5217c55c92",
"projectId": 1234,
"homeId": 1234,
"name": "Data Route 1",
"filterTypes": [
"conversion"
],
"dataType": "metrics",
"source": {
"catalogId": "bu01",
"sourceId": "a3b2ac399abc"
},
"destination": {
"entityClass": "warehouse",
"entityId": "floor_1",
"metricsDefinitionId": "environment"
}
}
Delete data route
Endpoint
delete /homes/{homeId}/dataRoutes/{routeId}
Description
Delete specified data route
Path Parameters
homeId
integer
required
The unique ID for a specified home.
routeId
string
required
Data Route ID
Request Headers What's this?
Authorization
required
Must contain the API key of a user who has the permission to delete all data routes of a project, or a Project API Key with admin permission.
Response
- 204Successfully deleted data route.
- 401Authorization is required to access this resource.
- 403Request failed because of invalid data or denied permission.
- 404The required dataRoute does not exist or is not accessible.
- 409The dataRoute cannot be deleted because it is being used by another part of the system.
- 500An unexpected error has occurred.
- 503The service is temporarily unavailable.