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| options are owner, member

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

The Home Member object

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

The Smart Module object

  • idstring

    Smart Module ID. Must be unique within the project. 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.