Projects

This set of endpoints are used for operations that are scoped to an individual project. These include proxying application server requests that are project-scoped. There are also endpoints for accessing a project's Entity Classes and Entity Instances.

Endpoints

The Entity Class object

entityClassstring
ID of the entity class. Must be unique within a project.
projectIdinteger
Project that this entity class belongs to.
displaySettingsobject
Various user interface settings used for display of the entity class.
metricsDefinitionsarray
An array of metrics definitions that are applicable to this class of entities.
attributeSchemaarray
A schema used for validating the attributes of an entity instance.
createdAtstring| format is date-time
Timestamp of entity class creation.
updatedAtstring| format is date-time
Timestamp of the last update on the entity class.

The Entity Class object

{
    "projectId": 1,
    "entityClass": "freezer",
    "displaySettings": {
        "name": "Freezer",
        "description": "Freezer with a temperature sensor and a door sensor",
        "uiSettings": {
            "layout": "twoColumnsLayout",
            "componentPlacement": "placement1"
        }
    },
    "metricsDefinitions": [
        {
            "metricsDefinitionId": "ambient_sensor_module",
            "metricsType": "raw",
            "tagMetrics": [
                {
                    "name": "statusCode",
                    "displayName": "Status",
                    "enumDefinitions": [
                        {
                            "Name": "000",
                            "Value": "Normal"
                        },
                        {
                            "Name": "900",
                            "Value": "Error"
                        }
                    ]
                }
            ],
            "numericMetrics": [
                {
                    "name": "temperature",
                    "displayName": "Temperature",
                    "range": {
                        "min": 0,
                        "max": 100
                    },
                    "unit": "°C"
                }
            ],
            "dataStoreConfiguration": {
                "moduleType": "tsdb",
                "moduleInstanceId": "tsdb",
                "bulkDataLabel": "tsdb"
            }
        },
        {
            "metricsDefinitionId": "door_sensor_module",
            "metricsType": "raw",
            "numericMetrics": [
                {
                    "name": "count",
                    "displayName": "Count"
                }
            ],
            "dataStoreConfiguration": {
                "moduleType": "tsdb",
                "moduleInstanceId": "tsdb",
                "bulkDataLabel": "tsdb"
            }
        }
    ],
    "attributeSchema": [
        {
            "key": "robot_group",
            "type": "string",
            "required": true,
            "label": "Robot Group",
            "description": "The group that the robot entity instance belongs to.",
            "defaultValue": "medium_size_robot",
            "options": [
                {
                    "label": "Small Size Robot",
                    "value": "small_size_robot"
                },
                {
                    "label": "Medium Size Robot",
                    "value": "medium_size_robot"
                },
                {
                    "label": "Large Size Robot",
                    "value": "large_size_robot"
                }
            ]
        },
        {
            "key": "maxRobotSpeedMph",
            "type": "number",
            "required": false,
            "label": "Maximum Robot Speed (mph)",
            "description": "The maximum speed that the robot can be set to.",
            "defaultValue": 15.5,
            "min": 5,
            "max": 25
        }
    ],
    "createdAt": "2021-08-12T20:11:11Z",
    "updatedAt": "2021-09-02T22:19:39Z"
}

The Entity Instance object

entityIdstring
Unique entity ID.
projectIdinteger
Project that this entity belongs to.
homeIdinteger
Home that this entity belongs to.
parentIdstring
The ID of the entity instance that is a parent of the instance.
entityClassstring
The entity class that the entity was instantiated from.
displaySettingsobject
Various user interface settings used for display of the entity instance.
attributesobject
The attributes that belong to the entity instance, separated as key-value pairs.
uiSettingsobject
An opaque object used by UI applications to store any additional settings. These will override the entity class uiSettings.
metricsarray
Meta data of the metrics associated with this entity instance.
timeZonestring
The time zone that the entity exists in. This should be a time zone name defined in the IANA TZ Database.
suspendAlertRuleEvaluationConditionsarray
An array of condition for suspending alerts, which are evaluated as if they are concatenated with OR
createdAtstring| format is date-time
Timestamp of entity creation.
updatedAtstring| format is date-time
Timestamp of the last update on the entity.

The Entity Instance object

{
    "entityId": "warehouse_freezer_001",
    "projectId": 1,
    "homeId": 5,
    "parentId": "warehouse_room_003",
    "entityClass": "warehouse_freezer",
    "displaySettings": {
        "name": "Warehouse Freezer 001",
        "description": "A warehouse freezer in warehouse room #003.",
        "iconData": {
            "fileName": "freezer_icon.png",
            "url": "https://example.com/icons/freezer_icon.png"
        },
        "imageData": {
            "fileName": "freezer.png",
            "url": "https://example.com/images/freezer.png"
        }
    },
    "attributes": {
        "group": "samsung_freezer_model_4",
        "minTemperatureCelsius": -40.2
    },
    "timeZone": "Europe/Berlin",
    "createdAt": "2021-09-02T22:19:39Z",
    "updatedAt": "2021-09-02T22:19:39Z"
}

Get Project Log Entries

Endpoint

get /projects/{projectId}/logEntries

Description

Get a list of log entries for a given project.

Path Parameters

projectId
integer
required
The unique ID for a specified project.

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

Proxy GET request to app server

Endpoint

get /projects/{projectId}/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

projectId
integer
required
The unique ID for a specified project.
srcPath
string
required
A path that matches one of the source paths in the project's App Proxy configuration.

Request Headers What's this?

Authorization
required
Must contain a user or project API key.

Proxy POST request to app server

Endpoint

post /projects/{projectId}/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

projectId
integer
required
The unique ID for a specified project.
srcPath
string
required
A path that matches one of the source paths in the project's App Proxy configuration.

Request Headers What's this?

Authorization
required
Must contain a user or project API key.

Proxy PUT request to app server

Endpoint

put /projects/{projectId}/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

projectId
integer
required
The unique ID for a specified project.
srcPath
string
required
A path that matches one of the source paths in the project's App Proxy configuration.

Request Headers What's this?

Authorization
required
Must contain a user or project API key.

Proxy PATCH request to app server

Endpoint

patch /projects/{projectId}/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

projectId
integer
required
The unique ID for a specified project.
srcPath
string
required
A path that matches one of the source paths in the project's App Proxy configuration.

Request Headers What's this?

Authorization
required
Must contain a user or project API key.

Proxy DELETE request to app server

Endpoint

delete /projects/{projectId}/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

projectId
integer
required
The unique ID for a specified project.
srcPath
string
required
A path that matches one of the source paths in the project's App Proxy configuration.

Request Headers What's this?

Authorization
required
Must contain a user or project API key.

Get list of device classes

Endpoint

get /projects/{projectId}/deviceClasses

Description

Get all device classes defined for a project.

Path Parameters

projectId
integer
required
The unique ID for a specified project.

Request Headers What's this?

Authorization
required
Must contain a user or project API key.

Response

200List of device classes 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.

Get device class

Endpoint

get /projects/{projectId}/deviceClasses/{deviceClassId}

Description

Get the specified device class.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
deviceClassId
string
required
Device Class ID

Response

200Device Class is returned.
401Authorization is required to access this resource.
403Request failed because of denied permission.
404The requested deviceClass does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Get list of entity classes

Endpoint

get /projects/{projectId}/entityClasses

Description

Get all entity classes defined for a project.

Path Parameters

projectId
integer
required
The unique ID for a specified project.

Request Headers What's this?

Authorization
required
Must contain a user or project API key.

Response

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

Create entity class

Endpoint

post /projects/{projectId}/entityClasses

Description

Create a new entity class in the project

Path Parameters

projectId
integer
required
The unique ID for a specified project.

Request Headers What's this?

Authorization
required
Must contain the API key of a user who has the permission to create all Entity Classes of a project, or a Project API Key with admin permission.

Request Body

displaySettings
object
Various user interface settings used for display of the entity class.
metricsDefinitions
array
An array of metrics definitions that are applicable to this class of entities.
attributeSchema
array
A schema used for validating the attributes of an entity instance.

Response

201Successful creation of entity class.
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.

Get entity class

Endpoint

get /projects/{projectId}/entityClasses/{entityClassId}

Description

Get the specified entity class

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityClassId
string
required
Entity Class ID (unique within project)

Request Headers What's this?

Authorization
required
Must contain a user or project API key.

Response

200Successful retrieval of the entity class
401Authorization is required to access this resource.
403Request failed because of denied permission.
404The requested entityClass does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Update entity class

Endpoint

patch /projects/{projectId}/entityClasses/{entityClassId}

Description

Update specified entity class

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityClassId
string
required
Entity Class ID (unique within project)

Request Headers What's this?

Authorization
required
Must contain the API key of a user who has the permission to update all Entity Classes of a project, or a Project API Key with admin permission.

Response

204Successfully updated entity class.
401Authorization is required to access this resource.
403Request failed because of invalid data or denied permission.
404The requested entityClass does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Delete entity class

Endpoint

delete /projects/{projectId}/entityClasses/{entityClassId}

Description

Delete specified entity class

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityClassId
string
required
Entity Class ID (unique within project)

Request Headers What's this?

Authorization
required
Must contain the API key of a user who has the permission to delete all Entity Classes of a project, or a Project API Key with admin permission.

Response

204Successfully updated entity class.
401Authorization is required to access this resource.
403Request failed because of invalid data or denied permission.
404The required entityClass does not exist or is not accessible.
409The entityClass 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 entity instances

Endpoint

get /projects/{projectId}/entities

Description

Get entity instances of a project. If caller doesn't have admin permission, caller must specify either the homeId or userId parameter.

Path Parameters

projectId
integer
required
The unique ID for a specified project.

Query Parameters

homeId
integer
Return entity instances in a specific home. If the caller uses a user API key, the user must be a member of the home.
userId
integer
Return entity instances that a particular user has access to. The caller must contain the API key of the user, the API key of a user who has permission to all resources of a project, or a Project API Key with admin permission.
entityClass
string
Deprecated. Use entityClasses instead.
entityClasses
string
Returns entity instances of the passed entity classes by a comma-separated string like entityClasses=building,floor,room.
parentId
string
Returns child entity instances of the specified parent entity. If the reserved value 'root' is passed, only root entity instances will be returned.
sortBy
string
Sorts the returned results by the given sort field and sort order in the format sortField:sortOrder e.g. attributes.minTemp:asc sortOrder can be asc or desc.
skip
integer
Number of entity instances to skip over.
limit
integer
Maximum number of entity instances to return.
Default value is 25
Minimum value is 1
recursive
boolean
If the parentId query parameter is used, and this parameter is true, all descendants of the specified parent entity will be returned (children, grandchildren, and so on). This parameter is ignored if parentId is not specified.

Request Headers What's this?

Authorization
required
Must contain a user or project API key.

Response

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

Create entity instance

Endpoint

post /projects/{projectId}/entities

Description

Create a new entity instance.

Path Parameters

projectId
integer
required
The unique ID for a specified project.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to create child entities on the parent entity, or a project API key with admin permission.

Request Body

homeId
number
required
Home that this entity belongs to.
entityId
string
required
Unique entity ID.
entityClass
string
required
The entity class that the entity will be instantiated from.
parentId
string
The ID of the entity instance that is a parent of the instance.
timeZone
string
The time zone that the entity exists in. This should be a time zone name defined in the IANA TZ Database.
displaySettings
object
Various user interface settings used for display of the entity class.
attributes
object
The attributes that belong to the entity instance, separated as key-value pairs.
uiSettings
object
An opaque object used by UI applications to store any additional settings. These will override the entity class uiSettings.

Response

201Successful creation of entity instance.
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.

Get entity instance

Endpoint

get /projects/{projectId}/entities/{entityId}

Description

Get the specified entity instance.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity instance, or a project API key.

Response

200Successful retrieval of entity instance.
401Authorization is required to access this resource.
403Request failed because of denied permission.
404The requested entity does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Update entity instance

Endpoint

patch /projects/{projectId}/entities/{entityId}

Description

Update attributes of the specified entity instance.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to update the entity instance, or a project API key with admin permission.

Request Body

parentId
string
The ID of the entity instance that is a parent of the instance.
displaySettings
object
Various user interface settings used for display of the entity instance.
attributes
object
The attributes that belong to the entity instance, separated as key-value pairs.
uiSettings
object
An opaque object used by UI applications to store any additional settings. These will override the entity class uiSettings.
suspendAlertRuleEvaluationConditions
array
An array of condition for suspending alerts, which are evaluated as if they are concatenated with OR

Response

204The entity has been successfully updated.
401Authorization is required to access this resource.
403Request failed because of invalid data or denied permission.
404The requested entity does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Delete entity instance

Endpoint

delete /projects/{projectId}/entities/{entityId}

Description

Delete the specified entity instance.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Query Parameters

deleteDescendants
boolean
By default, entities with descendants cannot be deleted. In order to delete an entity and its descendants this parameter must be true.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to delete child entities on the parent entity, or a project API key with admin permission.

Response

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

Manage entity media

Endpoint

post /projects/{projectId}/entities/{entityId}/manageMedia

Description

Manage icon and image associated with an entity instance. The client may use this method to upload or delete the media. To upload media, the client must first acquire an upload URL by using the open-upload action in the request body. After completing the upload (by making a PUT request to the upload URL), the client must explicitly "close" the upload by using the close-upload action in the request body.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to update the entity instance, or a project API key with admin permission.

Request Body

action
string
required
Action to be taken.
Options are open-upload, close-upload, delete
target
string
required
Which media the action should be applied to.
Options are icon, image
fileName
string
Filename of the icon or image. Needed only if requesting to open an upload.

Response

200Request to upload an icon or image was successful. The response body is a JSON object that contains a signed upload URL. The client should make a PUT request with that URL to upload the icon or image file.
204Request to complete an upload, or to delete an icon/image, was successful.
401Authorization is required to access this resource.
403Request failed because of denied permission.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Request Body Sample

{
    "action": "open-upload",
    "target": "icon",
    "fileName": "freezer-icon.png"
}

Get metrics definition

Endpoint

get /projects/{projectId}/entities/{entityId}/metrics/{metricsDefinitionId}

Description

Get the specified metrics definition.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
metricsDefinitionId
string
required
Metrics definition ID (unique within entity class)

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity metrics, or a project API key.

Response

200Successful retrieval of metrics definition.
401Authorization is required to access this resource.
403Request failed because of denied permission.
404The requested metric does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Update metric

Endpoint

patch /projects/{projectId}/entities/{entityId}/metrics/{metricsDefinitionId}

Description

Update the metric with the specified ID.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
metricsDefinitionId
string
required
Metrics definition ID (unique within entity class)

Response

204The metric has been successfully updated.
401Authorization is required to access this resource.
403Request failed because of invalid data or denied permission.
404The requested metric does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Delete metric

Endpoint

delete /projects/{projectId}/entities/{entityId}/metrics/{metricsDefinitionId}

Description

Delete the metric with the specified ID.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
metricsDefinitionId
string
required
Metrics definition ID (unique within entity class)

Response

204The metric has been successfully deleted.
401Authorization is required to access this resource.
403Request failed because of invalid data or denied permission.
404The required metric does not exist or is not accessible.
409The metric 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 metrics data

Endpoint

get /projects/{projectId}/entities/{entityId}/metrics/{metricsDefinitionId}/data

Description

Get the metrics data. Use the begin and end parameters to fetch entries by time range, with the proper time resolution automatically applied. Use the ts and limit parameters to fetch a specific number of entries before or after a point in time. Use the selectValues parameter to specify which value fields of the collection should be returned. When raw data entries are being fetched, it is possible to use the selectTags parameter to retrieve the tag fields from the entries as well.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
metricsDefinitionId
string
required
Metrics definition ID (unique within entity class)

Query Parameters

begin
string
required
The beginning time of the data entries. The format follows RFC3339.
end
string
required
The end time of the data entries. The format follows RFC3339.
resolution
string
required
The resolution of time bucket. The string must be either '5sec', '15sec', '1min', '10min', '1hour', '1day', '1week', '1month'. Decided automatically based on the timespan between "begin" and "end" parameters if not provided.
aggregation
string
required
Aggregation function. The string must be either 'avg', 'min', 'max', 'sum' or 'count'. 'avg' is chosen if not provided.
ts
string
required
The point in time (in RFC3339) to fetch data entries from.
limit
integer
required
If positive, this is the maximum number of data entries at and after ts to be returned. If negative, this is the maximum number of data points before ts to be returned.
selectValues
string
required
A comma-delimited list of value names. Since each data entry in the collection contains multiple value fields, the fields to be returned must be specified
selectTags
string
required
A comma-delimited list of tag names. This is used only when fetching entries with the ts and limit parameters. If data entries contain tags, use this parameter to return the desired tag fields.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity metrics, or a project API key.

Response

200The requested metrics data entries are returned.
401Authorization is required to access this resource.
403Request failed because of denied permission.
404The requested datum does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Response Body Sample

{
  "begin": "2019-04-11T07:51:46.712Z",
  "end": "2020-01-29T01:26:08.101Z",
  "aggregation": "avg",
  "resolution": "1day",
  "data": [
    ["2019-04-11T00:00:00Z", 22.97349639133924, 0.66, 772],
    ["2019-04-12T00:00:00Z", 22.916217542079057, 0.77, 899],
    ["2019-04-13T00:00:00Z", 21.939217256214157, 0.80, 502],
    ["2019-04-14T00:00:00Z", 21.668999574649146, 0.50, 888],
    ["2019-04-15T00:00:00Z", 23.01144695453247, 0.55, 890],
    ["2019-04-16T00:00:00Z", 23.877712361878466, 0.63, 792],
    ["2019-04-17T00:00:00Z", 24.251540345449843, 0.45, 662],
    ["2019-04-18T00:00:00Z", 23.900341664030382, 0.80, 705],
    ["2019-04-19T00:00:00Z", 23.579976112920807, 0.78, 780]
  ]
}

Post metrics data

Endpoint

post /projects/{projectId}/entities/{entityId}/metrics/{metricsDefinitionId}/data

Description

Post metrics data. The client can use this method to inject time-series data of the metrics.

This method injects the data into the corresponding collection in the Time Series Database instance. Also, it sends an Entity metrics update system event (_entityMetricsUpdate_) to the home of the Entity.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
metricsDefinitionId
string
required
Metrics definition ID (unique within entity class)

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to create the entity metrics, or a project API key with admin permission.

Response

204The data has been successfully processed. There is no response body.

Request Body Sample

{
  "valueNames": ["loi", "tem", "bri"],
  "tagNames": ["pid", "diag"],
  "records": [
    {
      "timestamp":  "2021-04-10T01:12:22Z",
      "values": [89.8, 77, 9],
      "tags": ["5DEF12AA3B", "100"]
    },
    {
      "timestamp":  "2021-04-10T01:12:32Z",
      "values": [87.2, 77, 8.33],
      "tags": ["5DEF12AA3B", "102"]
    },
    {
      "timestamp":  "2021-04-10T01:12:43Z",
      "values": [87.5, 75, 7.92],
      "tags": ["5DEF12AA3B", "102"]
    },
    {
      "timestamp":  "2021-04-10T01:12:52Z",
      "values": [90.3, 75, 6.01],
      "tags": ["5DEF12AA3B", "100"]
    }
  ]
}

Delete metrics data

Endpoint

delete /projects/{projectId}/entities/{entityId}/metrics/{metricsDefinitionId}/data

Description

Delete data entries of a time series collection that fall within a given time range. If only the begin parameter is specified, all entries timestamped after begin will be deleted. If only the end parameter is specified, all entries timestamped before end will be deleted.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
metricsDefinitionId
string
required
Metrics definition ID (unique within entity class)

Query Parameters

begin
string
required
The beginning of the time range. The format follows RFC3339.
end
string
required
The end of the time range. The format follows RFC3339.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to delete the entity metrics, or a project API key with admin permission.

Response

204The data entries have been successfully deleted.
401Authorization is required to access this resource.
403Request failed because of invalid data or denied permission.
404The required datum does not exist or is not accessible.
409The datum cannot be deleted because it is being used by another part of the system.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Export metrics data

Endpoint

post /projects/{projectId}/entities/{entityId}/metrics/{metricsDefinitionId}/export

Description

Export the metrics data.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
metricsDefinitionId
string
required
Metrics definition ID (unique within entity class)

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity metrics, or a project API key.

Request Body

begin
string
required
The beginning time of the data entries. The format follows RFC3339.
end
string
required
The end time of the data entries. The format follows RFC3339.
includeHeader
boolean
required
If true, the exported CSV file will start with a header.
fileName
string
required
Optional parameter to specify the export CSV file name. If omitted, metrics ID will be used in the file name.

Response

200The URLs for downloading the exported data are returned.
401Authorization is required to access this resource.
403Request failed because of invalid request parameters.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Get location definition

Endpoint

get /projects/{projectId}/entities/{entityId}/location

Description

Get the location definition.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity location, or a project API key.

Response

200Successful retrieval of location definition.
401Authorization is required to access this resource.
403Request failed because of denied permission.
404The requested location does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Update location

Endpoint

patch /projects/{projectId}/entities/{entityId}/location

Description

Update the location with the specified ID.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Response

204The location has been successfully updated.
401Authorization is required to access this resource.
403Request failed because of invalid data or denied permission.
404The requested location does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Delete location

Endpoint

delete /projects/{projectId}/entities/{entityId}/location

Description

Delete the location with the specified ID.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Response

204The location has been successfully deleted.
401Authorization is required to access this resource.
403Request failed because of invalid data or denied permission.
404The required location does not exist or is not accessible.
409The location 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 location data

Endpoint

get /projects/{projectId}/entities/{entityId}/location/data

Description

Get the location data. Use the begin and end parameters to fetch entries by time range. But if the latest parameter is true, the begin and end parameters will be ignored, and the latest location will be returned.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Query Parameters

begin
string
required
The beginning time of the data entries. The format follows RFC3339.
end
string
required
The end time of the data entries. The format follows RFC3339.
latest
boolean
required
Set this to true to obtain the latest location. The default is false.
includeDescendants
boolean
required
Set this to true to include descendant entities' location. The default is false.
areaIds
string
required
If set, return only location records with matching area IDs. The value should be comma-separated list.
floorId
integer
required
If set, return only location records with matching floor ID.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity location, or a project API key.

Response

200The requested location data entries are returned.
401Authorization is required to access this resource.
403Request failed because of denied permission.
404The requested datum does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Response Body Sample

{
  "begin": "2023-03-25T09:00:00Z",
  "end": "2023-03-25T09:00:00.01Z",
  "data": [
    {
      "timestamp": "2023-03-25T09:00:00.01Z",
      "searchKey": "worker::user-1",
      "geometry": {
        "type": "Point",
        "coordinates": [
          138.7309,
          35.3628
        ]
      },
      "floorId": 0,
      "areas": [{"areaId": "mt_fuji"}],
      "attributes": {
        "placeId": "mt_fuji",
        "place_in": "2023-03-25T00:00:00.010Z"
      }
    },
    {
      "timestamp": "2023-03-25T09:00:00Z",
      "searchKey": "site::place-2",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[138.7309, 35.3628],[138.8079, 35.1983],[139.0248, 35.2248],[138.7309, 35.3628]]]
      },
      "floorId": 0,
      "attributes": {
        "placeId": "mt_fuji",
        "place_in": "2023-03-25T00:00:00.010Z"
      }
    }
  ]
}

Post location data

Endpoint

post /projects/{projectId}/entities/{entityId}/location/data

Description

Post location data. The client can use this method to update the location of an entity.

This method injects the data into the corresponding Geo Time Series Database instance. Also, it sends an Entity location update system event (_entityLocationUpdate_) to the home of the Entity if the data contains a point type GeoJSON record.

Note that this endpoint doesn't validate the field values. GeoTSDB will fail to process the data if it contains invalid records.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to create the entity location, or a project API key with admin permission.

Request Body

data
array
required
Time-series data. Each entry contains the timestamp of the value in RFC3339 format.

Response

204The data has been successfully processed. There is no response body.

Request Body Sample

{
  "data": [
    {
      "timestamp": "2023-01-01T00:00:00Z",
      "geometry": {
        "type": "Point",
        "coordinates": [138.7275, 35.3606, 3776.24]
      },
      "areas": [{"areaId": "mt_fuji"}],
      "floorId": 0,
      "attributes": {
        "speed": 0.0,
        "direction": 0.0
      }
    }
  ]
}

Delete location data

Endpoint

delete /projects/{projectId}/entities/{entityId}/location/data

Description

Delete data entries of a time series collection that fall within a given time range.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Query Parameters

begin
string
required
The beginning of the time range. The format follows RFC3339.
end
string
required
The end of the time range. The format follows RFC3339.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to delete the entity location, or a project API key with admin permission.

Response

204The data entries have been successfully deleted.
401Authorization is required to access this resource.
403Request failed because of invalid data or denied permission.
404The required datum does not exist or is not accessible.
409The datum 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 custom log definition

Endpoint

get /projects/{projectId}/entities/{entityId}/customLogs/{customLogDefinitionId}

Description

Get the specified custom log definition.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
customLogDefinitionId
string
required
Custom log definition ID (unique within entity class)

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity custom log, or a project API key.

Response

200Successful retrieval of custom log definition.
401Authorization is required to access this resource.
403Request failed because of denied permission.
404The requested customLog does not exist or is not accessible.
500An unexpected error has occurred.
503The service is temporarily unavailable.

Response Body Sample

{
    "customLogDefinitionId": "alcohol_test_result",
    "displayName": "Alcohol Test Result",
    "numericFields": [
        {
            "name": "value",
            "displayName": "Value",
            "unit": "mg/L"
        }
    ],
    "stringFields": [
        {
            "name": "tester_model",
            "displayName": "Alcohol tester model name"
        },
        {
            "name": "result_code",
            "displayName": "Result code",
            "enumDefinitions": [
                {
                    "name": "000",
                    "value": "Negative"
                },
                {
                    "name": "100",
                    "value": "Positive"
                },
                {
                    "name": "999",
                    "value": "Sensor Failure"
                }
            ]
        }
    ],
    "dataStoreConfiguration": {
        "moduleType": "home_app_proxy",
        "moduleInstanceId": "/alcoholTest/logs",
        "bulkDataLabel": ""
    }
}

Get custom log data

Endpoint

get /projects/{projectId}/entities/{entityId}/customLogs/{customLogDefinitionId}/data

Description

Get the custom log data.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
customLogDefinitionId
string
required
Custom log definition ID (unique within entity class)

Query Parameters

begin
string
required
The beginning time of the data entries. The format follows RFC3339.
end
string
required
The end time of the data entries. The format follows RFC3339.
skip
integer
Number of log records to skip over.
limit
integer
Maximum number of log records to return.
Default value is 1000
Minimum value is 1
sortBy
string
A comma-delimited list of sort keys. (e.g. "field1:asc,field2:desc") timestamp is the valid field. Default value is ‘timestamp:asc’.

fieldsFilter

string

A filter string starting with a conjunction. Supported conjunctions are AND() and OR(). A conjunction takes a comma-separated condition string like AND(group==="group_1",maxSpeed<5). Each condition string defines a filter for the field value. The left-hand side must be a valid field name. The right-hand side must be a value condition. For example, group==="group_1" matches any records that the group field value exactly matches "group_1". Supported operators are following:

Operator
`===`	exact match
`==`	substring match
`~==`	included in array as exact match. `name~==["john"\|"jeff"\|"jack"]` matches one of the three.
`~=`	included in array as substring match. `name~=["j"\|"e"]` matches "john", "jeff", "jack", and "ethan".
`<`	less than
`<=`	less than or equal to
`>`	greater than
`>=`	greater than or equal to

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity custom log, or a project API key.

Response

200The requested custom log records are returned.

Response Body Sample

{
    "begin": "2022-03-01T00:00:00.000Z",
    "end": "2022-03-31T23:59:59.999Z",
    "limit": 1000,
    "skip": 0,
    "total": 210,
    "records": [
        {
            "timestamp": "2022-03-17T01:23:45.678Z",
            "eventKey": "20220317012345678-1",
            "fields": {
                "value": 0.3,
                "tester_model": "MODE-123",
                "result_code": "100"
            }
        },
        {
            "timestamp": "2022-03-18T01:23:45.678Z",
            "eventKey": "20220317012345678-2",
            "fields": {
                "value": 0.0,
                "tester_model": "MODE-123",
                "result_code": "000"
            }
        }
    ]
}

Post custom log records

Endpoint

post /projects/{projectId}/entities/{entityId}/customLogs/{customLogDefinitionId}/data

Description

Post custom log records. The client can use this method to inject log records.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
customLogDefinitionId
string
required
Custom log definition ID (unique within entity class)

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to create the entity custom log, or a project API key with admin permission.

Response

204The data has been successfully processed. There is no response body.

Request Body Sample

[
    {
        "timestamp": "2022-03-17T01:23:45.678Z",
        "eventKey": "20220317012345678-1",
        "fields": {
            "value": 0.3,
            "tester_model": "MODE-123",
            "result_code": "100"
        }
    },
    {
        "timestamp": "2022-03-18T01:23:45.678Z",
        "eventKey": "20220317012345678-2",
        "fields": {
            "value": 0.0,
            "tester_model": "MODE-123",
            "result_code": "000"
        }
    }
]

Get alerts

Endpoint

get /projects/{projectId}/entities/{entityId}/alerts

Description

Get a list of alerts of the entity instance.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)

Query Parameters

state
integer
Return alerts with the specified state.
severity
integer
Return alerts with the specified severity.
skip
integer
Number of alerts to skip over.
limit
integer
Maximum number of alerts to return.
Default value is 25
Minimum value is 1

Request Headers What's this?

Authorization
required
Must contain the user API key of a user with permission to read the entity alerts, or a project API key.

Response

200Successful retrieval of alerts.

Response Body Sample

[
  {
    "id": "63ce9a3e9bc89f001b228c80",
    "projectId": 1,
    "homeId": 2,
    "alertRuleId": 5,
    "condition": {
      "conditionType": "metricsThreshold",
      "duration": "1min",
      "frequency": "1min",
      "delay": "1min",
      "aggregation": "avg",
      "thresholds": [
        {
          "severity": 1,
          "operator": "greaterThan",
          "operands": [
            0.86
          ]
        },
        {
          "severity": 2,
          "operator": "greaterThan",
          "operands": [
            0.85
          ]
        },
        {
          "severity": 3,
          "operator": "greaterThan",
          "operands": [
            0.84
          ]
        }
      ],
      "targetMetrics": [
        {
          "entityClass": "robot1",
          "metricsDefinitionId": "location",
          "metricName": "speed"
        }
      ]
    },
    "description": "Robot exceeded a speed limit",
    "severity": 1,
    "entityId": "robot1-1",
    "entityClass": "robot1",
    "metricsDefinitionId": "location",
    "metricName": "speed",
    "state": 1,
    "invocationTime": "2023-01-23T14:31:26Z"
  },
  {
    "id": "63ce9a3e9bc89f001b228c7f",
    "projectId": 1,
    "homeId": 2,
    "alertRuleId": 5,
    "condition": {
      "conditionType": "metricsThreshold",
      "duration": "1min",
      "frequency": "1min",
      "delay": "1min",
      "aggregation": "avg",
      "thresholds": [
        {
          "severity": 1,
          "operator": "greaterThan",
          "operands": [
            0.86
          ]
        },
        {
          "severity": 2,
          "operator": "greaterThan",
          "operands": [
            0.85
          ]
        },
        {
          "severity": 3,
          "operator": "greaterThan",
          "operands": [
            0.84
          ]
        }
      ],
      "metricsCondition": {
        "entityClass": "robot1",
        "metricsDefinitionId": "location",
        "metricName": "speed"
      },
      "targetMetrics": [
        {
          "entityClass": "robot1",
          "metricsDefinitionId": "location",
          "metricName": "speed"
        }
      ]
    },
    "description": "Robot exceeded a speed limit",
    "severity": 2,
    "entityId": "robot1",
    "entityClass": "robot1-1",
    "metricsDefinitionId": "metrics",
    "metricName": "speed",
    "state": 1,
    "invocationTime": "2023-01-23T14:31:26Z"
  }
]

Get alert

Endpoint

get /projects/{projectId}/entities/{entityId}/alerts/{alertId}

Description

Return the alert with the specified ID.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
alertId
string
required
Alert ID

Request Headers What's this?

Authorization
required
Must contain the user API key of a user with permission to read the entity alerts, or a project API key.

Response

200Successful retrieval of alert by specified ID.

Recover an alert

Endpoint

patch /projects/{projectId}/entities/{entityId}/alerts/{alertId}/recover

Description

Recover the alert with the specified ID.

Path Parameters

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
alertId
string
required
Alert ID

Request Headers What's this?

Authorization
required
Must contain the key of a user with permissions to update the alert or a project API key with admin permission.

Response

204Successfully recovered the alert with specified ID.

Proxy GET request to app server

Endpoint

get /projects/{projectId}/entities/{entityId}/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

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
srcPath
string
required
A path that matches one of the source paths in the project's App Proxy configuration for entities.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity instance, or a project API key.

Proxy POST request to app server

Endpoint

post /projects/{projectId}/entities/{entityId}/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

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
srcPath
string
required
A path that matches one of the source paths in the project's App Proxy configuration for entities.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity instance, or a project API key.

Proxy PUT request to app server

Endpoint

put /projects/{projectId}/entities/{entityId}/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

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
srcPath
string
required
A path that matches one of the source paths in the project's App Proxy configuration for entities.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity instance, or a project API key.

Proxy PATCH request to app server

Endpoint

patch /projects/{projectId}/entities/{entityId}/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

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
srcPath
string
required
A path that matches one of the source paths in the project's App Proxy configuration for entities.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity instance, or a project API key.

Proxy DELETE request to app server

Endpoint

delete /projects/{projectId}/entities/{entityId}/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

projectId
integer
required
The unique ID for a specified project.
entityId
string
required
Entity ID (unique within project)
srcPath
string
required
A path that matches one of the source paths in the project's App Proxy configuration for entities.

Request Headers What's this?

Authorization
required
Must contain a user API key of a user with permission to read the entity instance, or a project API key.

MODEDeveloper Central

MODE Docs

Projects

Endpoints

The Entity Class object

The Entity Class object

The Entity Instance object

The Entity Instance object

Get Project Log Entries

Endpoint

Description

Path Parameters

Query Parameters

Request Headers What's this?

Response

Proxy GET request to app server

Endpoint

Description

Path Parameters

Request Headers What's this?

Proxy POST request to app server

Endpoint

Description

Path Parameters

Request Headers What's this?

Proxy PUT request to app server

Endpoint

Description

Path Parameters

Request Headers What's this?

Proxy PATCH request to app server

Endpoint

Description

Path Parameters

Request Headers What's this?

Proxy DELETE request to app server

Endpoint

Description

Path Parameters

Request Headers What's this?

Get list of device classes

Endpoint

Description

Path Parameters

Request Headers What's this?

Response

Get device class

Endpoint

Description

Path Parameters

Response

Get list of entity classes

Endpoint

Description

Path Parameters

Request Headers What's this?

Response

Create entity class

Endpoint

Description

Path Parameters

Request Headers What's this?

Request Body

Response

Get entity class

Endpoint

Description

Path Parameters

Request Headers What's this?

Response

Update entity class

Endpoint

Description

Path Parameters

Request Headers What's this?

Response

Delete entity class

Endpoint

Description

Path Parameters