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": [
                        {
                            "Value": "000",
                            "Name": "Normal"
                        },
                        {
                            "Value": "900",
                            "Name": "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.

Get Data Source Catalog Items

Endpoint
get /projects/{projectId}/dataSourceCatalogItems
Description

Get all data source catalog items available for the project. The search string may contain multiple phrases separated by whitespaces. When the search parameter is used, only items that vendor, name, or description matching exactly or partially one of the phrases will be returned.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

Query Parameters

  • search

    string

    Search for data source catalog items by keywords.

  • catalogItemType

    string

    Filter data source catalog items by catalog item type.

  • configurationType

    string

    Filter data source catalog items by configuration type.

  • skip

    integer

    Number of users to skip over.

  • limit

    integer

    Maximum number of data source catalog items to return.

    Default value is 100

    Minimum value is 1

Request Headers What's this?

  • Authorization

    required

    Must contain a user, project, or device API key.

Response
  • 200List of available data source catalog items 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 Data Source Catalog Item

Endpoint
get /projects/{projectId}/dataSourceCatalogItems/{catalogItemId}
Description

Get the specified data source catalog item.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • catalogItemId

    string

    required

    Data source catalog item ID.

Response
  • 200Data source catalog item is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested dataSourceCatalogItem does not exist or is not accessible.
  • 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 certain fields of the specified entity instance, with the matching fields in the JSON in the request body. If the field to be updated is attributes, key-value pairs that are present in the request body's attributes field will overwrite matching key-value pairs in the original attributes. To unset an attribute, use null as the value for that attribute.

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 metadata

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

Get the location metadata.

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 metadata.
  • 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.

  • searchKeyPrefixes

    string

    When searchKeyPrefixes is specified, all the geospatial data whose searchKeys is prefixed by this parameters will be returned. For example, if you specify searchKeyPrefixes as "foo::,bar::", data with searchKey such as "foo::1" and "bar::2" will be returned. Note that you can specify either the searchKeyPrefixes parameter or the searchKeys parameter.

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

  • ts

    string

    The point in time (in RFC3339) to fetch data entries from. This value can not be specified with begin and end.

  • selectAttributes

    string

    Specify keywords to project specific attributes in the geo-object. The selectAttributes parameter allows multiple values, separated by commas (",").

  • attributeQuery

    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 attribute value. The left-hand side must be a valid attribute field name. The right-hand side must be a value condition. For example, group==="group_1" matches any records where the group attribute 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

    This parameter is only supported when the latest is true in the query.

  • point

    string

    Specify this query parameter enabling to select location data whose geometry data intersects with a specified point. The format of the point is array of real numbers of longitude and latitude [longitude,latitude] e.g. [139.78186023120884, 35.689037335151994]. The geodetic of longitude and latitude must be in WGS84. This parameter is only supported when the latest is true in the query.

  • polygon

    string

    Specify this query parameter enabling to select location data whose geometry data intersects with a specified polygon. The format of the point is 3-dimensional real numbers. The longitude and latitude values in an array must be longitude first and the each last array is separated by comma e.g. [[[longitude,latitude],[longitude,latitude],[longitude,latitude]]] This parameter is only supported when the latest is true in the query.

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:00+09:00",
    "end": "2023-03-25T09:00:00.01+09:00",
    "collectionId": "tokyo",
    "data": [
        {
            "timestamp": "2023-03-25T09:00:00.01+09:00",
            "searchKey": "worker::user-1",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    139.78204030637045,
                    35.68893985910911
                ]
            },
            "floorId": 1234,
            "areas": [
                {
                    "areaId": "tyo_office"
                }
            ],
            "attributes": {
                "placeId": "tyo_office",
                "place_in": "2023-03-25T00:00:00.010Z"
            }
        },
        {
            "timestamp": "2023-03-25T09:00:00+09:00",
            "searchKey": "site::tyo_office",
            "geometry": {
                "type": "FeatureCollection",
                "features": [
                    {
                        "type": "Feature",
                        "properties": {},
                        "geometry": {
                            "coordinates": [
                                [
                                    [
                                        139.78186023120884,
                                        35.689037335151994
                                    ],
                                    [
                                        139.78207804723996,
                                        35.688811329363205
                                    ],
                                    [
                                        139.78216797128977,
                                        35.68887056972147
                                    ],
                                    [
                                        139.78194865652313,
                                        35.689095763833905
                                    ],
                                    [
                                        139.78186023120884,
                                        35.689037335151994
                                    ]
                                ]
                            ],
                            "type": "Polygon"
                        }
                    }
                ]
            },
            "floorId": 1234
        }
    ]
}

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 object counter history

Endpoint
get /projects/{projectId}/entities/{entityId}/location/objectCounters/{counterId}/data
Description

Get historical data on the number of objects in an area. Use the begin and end parameters to fetch entries for a specific time range. However, if the ts parameter is set, the begin and end parameters will be ignored, and the latest data from ts will be returned.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • counterId

    string

    required

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.

  • includeDescendants

    boolean

    required

    Set this to true to include descendant entities' location. The default is false.

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 object counter 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

{
  "counterId": "people",
  "data": [
    {
      "timestamp": "2023-01-01T00:00:00Z",
      "areaId": "mt_fuji",
      "count": 30
    }
  ]
}

Delete object counter history

Endpoint
delete /projects/{projectId}/entities/{entityId}/location/objectCounters/{counterId}/data
Description

Delete object counter history data entries of a geospatial time series collection that falls 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)

  • counterId

    string

    required

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": [
                {
                    "value": "000",
                    "name": "Negative"
                },
                {
                    "value": "100",
                    "name": "Positive"
                },
                {
                    "value": "999",
                    "name": "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.

  • 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

  • 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

    The sort order of the log records in the format field:order (e.g. timestamp:desc). Currently, only the timestamp field is supported. The default order is ascending.

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.

Get alert rules

Endpoint
get /projects/{projectId}/entities/{entityId}/alertRules
Description

Get a list of alert rules of the entity.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

Query Parameters

  • skip

    integer

    Number of alert rules to skip over.

  • limit

    integer

    Maximum number of alert rules to return.

    Default value is 25

    Minimum value is 1

  • conditionType

    string

    Return alert rules of the specified condition type.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read alert rules of the entity or a project API key.

Response
  • 200Successfully retrieved the alert rules.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Create an alert rule

Endpoint
post /projects/{projectId}/entities/{entityId}/alertRules
Description

Create an alert rule for the entity.

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 the key of a user with permissions to create alert rules of the entity or a project API key with the admin operation permission.

Request Body

  • name

    string

    required

    The name of the alert rule

  • description

    string

    The description of the alert rule

  • enabled

    boolean

    Whether the alert rule is enabled

  • disableAutoRecovery

    boolean

    Whether alert based on this rule recover automatically

  • condition

    object

    required

    The condition that triggers the alert rule

  • messageTemplate

    object

    The message template to use when the alert rule is triggered

  • actions

    array

    The actions to take when the alert rule is triggered

Response
  • 201Successfully created a new alert rule.
  • 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": "The room high temperature monitor",
  "description": "The room temperature should be below 35 degrees",
  "enabled": true,
  "disableAutoRecovery": false,
  "condition": {
    "conditionType": "metricsThreshold",
    "delay": "1min",
    "duration": "1min",
    "frequency": "1min",
    "targetMetrics": [
      {
        "entityClass": "room",
        "metricsDefinitionId": "ambient",
        "metricName": "temperature"
      }
    ],
    "aggregation": "avg",
    "thresholds": [
      {
        "operator": "greaterThan",
        "operands": [30],
        "severity": 1
      },
      {
        "operator": "greaterThan",
        "operands": [25],
        "severity": 2
      },
      {
        "operator": "greaterThan",
        "operands": [20],
        "severity": 3
      }
    ]
  },
  "messageTemplate": {
    "title": "The room temperature of {{entityName}} is too high",
    "recoveryTitle": "The room temperature of {{entityName}} is back to normal",
    "increasedSeverityTitle": "[{{alertRuleName}}] {{entityName}} severity increased",
    "decreasedSeverityTitle": "[{{alertRuleName}}] {{entityName}} severity decreased",
    "message": "See the details in https://example.com/projects/{{projectId}}/view/alerts/{{alertId}}",
    "recoveryMessage": "See the details in https://example.com/projects/{{projectId}}/view/alerts/{{alertId}}",
    "increasedSeverityMessage": "[{{alertRuleName}}] {{entityName}} severity increased to {{severity}}",
    "decreasedSeverityMessage": "[{{alertRuleName}}] {{entityName}} severity decreased to {{severity}}"
  },
  "actions": [
    {
      "recipients": [
        {
          "recipientType": "email",
          "email": "recipient@example.com"
        },
        {
          "recipientType": "event",
          "eventType": "alert"
        },
        {
          "recipientType": "slack",
          "assistantId": 1,
          "workspaceId": "ABCDEFGH",
          "channelId": "ABCDEFGH"
        }
      ]
    }
  ]
}

Get an alert rule

Endpoint
get /projects/{projectId}/entities/{entityId}/alertRules/{alertRuleId}
Description

Return the alert rule with the specified ID.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • alertRuleId

    integer

    required

    The unique ID for a specified alert rule.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read alert rules of the entity or a project API key.

Response
  • 200Successfully retrieved the alert rule with specified ID.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested alertRule does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": 951,
  "name": "The room high temperature monitor",
  "description": "The room temperature should be below 35 degrees",
  "enabled": true,
  "disableAutoRecovery": false,
  "condition": {
    "conditionType": "metricsThreshold",
    "delay": "1min",
    "duration": "1min",
    "frequency": "1min",
    "targetMetrics": [
      {
        "entityClass": "room",
        "metricsDefinitionId": "ambient",
        "metricName": "temperature"
      }
    ],
    "aggregation": "avg",
    "thresholds": [
      {
        "operator": "greaterThan",
        "operands": [30],
        "severity": 1
      },
      {
        "operator": "greaterThan",
        "operands": [25],
        "severity": 2
      },
      {
        "operator": "greaterThan",
        "operands": [20],
        "severity": 3
      }
    ]
  },
  "messageTemplate": {
    "title": "The room temperature of {{entityName}} is too high",
    "recoveryTitle": "The room temperature of {{entityName}} is back to normal",
    "increasedSeverityTitle": "[{{alertRuleName}}] {{entityName}} severity increased",
    "decreasedSeverityTitle": "[{{alertRuleName}}] {{entityName}} severity decreased",
    "message": "See the details in https://example.com/projects/{{projectId}}/view/alerts/{{alertId}}",
    "recoveryMessage": "See the details in https://example.com/projects/{{projectId}}/view/alerts/{{alertId}}",
    "increasedSeverityMessage": "[{{alertRuleName}}] {{entityName}} severity increased to {{severity}}",
    "decreasedSeverityMessage": "[{{alertRuleName}}] {{entityName}} severity decreased to {{severity}}"
  },
  "actions": [
    {
      "recipients": [
        {
          "recipientType": "email",
          "email": "recipient@example.com"
        },
        {
          "recipientType": "event",
          "eventType": "alert"
        },
        {
          "recipientType": "slack",
          "assistantId": 1,
          "workspaceId": "ABCDEFGH",
          "channelId": "ABCDEFGH"
        }
      ]
    }
  ],
  "creationTime": "2023-01-03T00:05:00.000Z",
  "updateTime": "2023-01-04T00:10:00.000Z"
}

Update an alert rule

Endpoint
patch /projects/{projectId}/entities/{entityId}/alertRules/{alertRuleId}
Description

Update the alert rule with the specified ID. Note if you change the any sub fields of the "condition" field, all the active alerts state will become obsolete state.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • alertRuleId

    integer

    required

    The unique ID for a specified alert rule.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to update alert rules of the entity or a project API key with the admin operation permission.

Request Body

  • name

    string

    The name of the alert rule

  • description

    string

    The description of the alert rule

  • enabled

    boolean

    Whether the alert rule is enabled

  • disableAutoRecovery

    boolean

    Whether alert based on this rule recover automatically

  • condition

    object

    The condition that triggers the alert rule

  • messageTemplate

    object

    The message template to use when the alert rule is triggered

  • actions

    array

    The actions to take when the alert rule is triggered

Response
  • 204Successfully updated the alert rule 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 alertRule does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Delete an alert rule

Endpoint
delete /projects/{projectId}/entities/{entityId}/alertRules/{alertRuleId}
Description

Delete the alert rule with the specified ID.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • alertRuleId

    integer

    required

    The unique ID for a specified alert rule.

Request Headers What's this?

  • Authorization

    required

    Must contain either a key of a user with permissions for alert rule deletion of the entity or a project API key with admin operation privileges. Note that you cannot delete an alert rule if any entity has active 'suspendAlertRuleEvaluationConditions' referencing it. You must first remove all 'suspendAlertRuleEvaluationConditions' associated with entities that reference the alert rule before deletion can proceed if you want to delete the alert rule.

Response
  • 204Successfully deleted the alert rule with the specified ID. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required alertRule does not exist or is not accessible.
  • 409Some entities have references to the alert rule.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

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 Entity App Proxy read permission for 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 Entity App Proxy create permission for 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 Entity App Proxy create permission for 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 Entity App Proxy update permission for 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 Entity App Proxy delete permission for the entity instance, or a project API key.

Upload a file

Endpoint
post /projects/{projectId}/entities/{entityId}/uploadFile
Description

Upload a file associated with an entity instance. To upload a file, the client must first acquire (an) upload URL(s) by using the open-upload action in the request body. After completing the upload (by making a PUT request to the upload URL(s)), 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 device API key of a device belonging to the same home, a user API key of a user with permission to create entity files, or a project API key with admin permissions.

Request Body

  • action

    string

    required

    Action to be taken.

    Options are open-upload, close-upload

  • metadata

    object

    Metadata for the file. Required for the open-upload action.

  • numberOfParts

    integer

    Optional number of parts to split the upload into. Defaults to 1.

  • uploadId

    string

    Upload ID returned from the open-upload action. Required for the close-upload action.

Response
  • 200For the `open-upload` action, this represents a successful start of the upload for a file. The response body is a JSON object that contains an array of pre-signed upload URLs. The client shoould divide up the file in the same number of parts as the number of URLs, and upload each part to its corresponding URL with a PUT request.
  • 204For the `close-upload` action, this represents a successful completion of entity file upload.
  • 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",
  "metadata": {
    "timestamp": "2023-11-01T12:17:56Z",
    "contentType": "video/mp4",
    "tags": [
      "camera1",
      "eventId:20231101",
      "eventType:crash"
    ],
    "expirationDate": "2024-11-01T12:17:56Z",
    "fileName": "video.mp4",
    "attributes": {
      "eventId": "20231101",
      "eventType": "crash",
      "errorCode": 42
    }
  },
  "numberOfParts": 2
}

Get entity files

Endpoint
get /projects/{projectId}/entities/{entityId}/files
Description

Look up files associated with an entity instance. Use the begin and end query parameters to fetch only files with timestamps that fall within the time range. Use the tag parameter to fetch files with a matching tag. And use the contentType paramter to fetch only files that match the given content type.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

Query Parameters

  • begin

    string

    The beginning time to search for entity files in RFC3339 format.

  • end

    string

    The end time to search for entity files in RFC3339 format.

  • tag

    string

    If specified, return files that contain the specified tag. If this paramter is repeated, files matching at least one of the tags will be returned.

  • contentType

    string

    MIME type of the entity file to search for.

  • limit

    integer

    The maximum number of entity files to return.

  • skip

    integer

    The number of entity files to skip.

  • sortBy

    string

    A sort key. timestamp is the valid field. (e.g. "timestamp:asc" or "timestamp:desc")

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key of a user with permission to read entity files, or a project API key.

Response
  • 200Successful query for files associated with an entity instance.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get entity file metadata

Endpoint
get /projects/{projectId}/entities/{entityId}/files/{fileId}
Description

Get the metadata of ther specified entity file.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • fileId

    string

    required

    Entity file ID.

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key of a user with permission to read entity files, or a project API key.

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

Response Body Sample

{
  "fileId": "3a0b1b2b4d4e5f6a0a1b2a1a",
  "projectId": 1,
  "entityId": "vehicle123",
  "timestamp": "2023-11-01T12:17:56Z",
  "contentType": "video/mp4",
  "tags": [
    "camera1",
    "eventId:20231101",
    "eventType:crash"
  ],
  "fileName": "video.mp4",
  "attributes": {
    "eventId": "20231101",
    "eventType": "crash",
    "errorCode": 42
  },
  "url": "https://download.tinkermode.com/download/v1.eyJzIjoiZW50aXR5ZmlsZXMiLCJrIjoiQS9lbnRpdGllcy91YXJlaG91c2VfZnJlZXplcl8wMDEvZmlsZXMvM2EwYjFiMmM1ZDRlNWY2YTBhMWIyYzNhIiwiZiI6ImluY2lkZW50Lm1wNCJ9.1702687298.91445ff477f6ca1568569bce48b077febaf78d1a5f584dfdaa894013"
}

Update entity file metadata

Endpoint
patch /projects/{projectId}/entities/{entityId}/files/{fileId}
Description

Update the metadata of the specified entity file.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • fileId

    string

    required

    Entity file ID.

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key of a user with permission to update entity files, or a project API key with admin permissions.

Request Body

  • tags

    array

    A collection of unique string identifiers associated with the entity file.

  • expirationDate

    string

    Timestamp indicating when the entity file should expire.

  • attributes

    object

    Attributes associated with the entity file, separated as key-value pairs.

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

Request Body Sample

{
  "tags": [
    "camera1",
    "eventId:20231101",
    "eventType:crash"
  ],
  "expirationDate": "2024-11-01T12:17:56Z",
  "attributes": {
    "eventId": "20231101",
    "eventType": "crash",
    "errorCode": 42
  }
}

Delete an entity file

Endpoint
delete /projects/{projectId}/entities/{entityId}/files/{fileId}
Description

Delete the specified entity file. This includes both the metadata and the actual file object in storage.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • fileId

    string

    required

    Entity file ID.

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key of a user with permission to delete entity file, or a project API key with admin permissions.

Response
  • 204Successful deletion of entity file.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required file does not exist or is not accessible.
  • 409The file 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 video feeds

Endpoint
get /projects/{projectId}/entities/{entityId}/videoFeeds
Description

Get a list of video feeds of the entity.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

Query Parameters

  • skip

    integer

    Number of video feeds to skip over.

  • limit

    integer

    Maximum number of video feeds to return.

    Default value is 25

    Minimum value is 1

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read video feeds of the entity or a project API key.

Response
  • 200Successful query for video feeds associated with an entity instance.
  • 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": "63ce9a3e9bc89f001b228c80",
    "projectId": 1,
    "entityId": "robot1-1",
    "displayName": "Robot 1 - Camera 1"
  },
  {
    "id": "63ce9a3e9bc89f001b228c7f",
    "projectId": 1,
    "entityId": "robot1-1",
    "displayName": "Robot 1 - Camera 2"
  }
]

Create an video feed

Endpoint
post /projects/{projectId}/entities/{entityId}/videoFeeds
Description

Create a video feed for the entity.

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 the key of a user with permissions to create video feeds of the entity or a project API key with the admin operation permission.

Response
  • 201Successfully created a new video feed.
  • 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

{
  "displayName": "Robot 1 - Camera 1"
}

Get a video feed

Endpoint
get /projects/{projectId}/entities/{entityId}/videoFeeds/{videoFeedId}
Description

Return the video feed with the specified ID.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • videoFeedId

    string

    required

    The unique ID for a specified video feed.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read video feeds of the entity or a project API key.

Response
  • 200Successfully retrieved the video feed with specified ID.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested videoFeed does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": "63ce9a3e9bc89f001b228c80",
  "projectId": 1,
  "entityId": "robot1-1",
  "displayName": "Robot 1 - Camera 1"
}

Update a video feed

Endpoint
patch /projects/{projectId}/entities/{entityId}/videoFeeds/{videoFeedId}
Description

Update the video feed with the specified ID.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • videoFeedId

    string

    required

    The unique ID for a specified video feed.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to update video feeds of the entity or a project API key with the admin operation permission.

Response
  • 204Successfully updated the video feed 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 videoFeed does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "displayName": "Robot 1 - new Camera"
}

Delete a video feed

Endpoint
delete /projects/{projectId}/entities/{entityId}/videoFeeds/{videoFeedId}
Description

Delete the video feed with the specified ID.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • videoFeedId

    string

    required

    The unique ID for a specified video feed.

Request Headers What's this?

  • Authorization

    required

    Must contain either a key of a user with permissions for video feed deletion of the entity or a project API key with admin operation privileges

Response
  • 204Successfully deleted the video feed with the specified ID. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required videoFeed does not exist or is not accessible.
  • 409The videoFeed 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 a live stream data of a video feed

Endpoint
get /projects/{projectId}/entities/{entityId}/videoFeeds/{videoFeedId}/live
Description

Return the live stream data of video feed with the specified ID.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • entityId

    string

    required

    Entity ID (unique within project)

  • videoFeedId

    string

    required

    The unique ID for a specified video feed.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read video feeds of the entity or a project API key.

Response
  • 200Successfully retrieved the video feed with specified ID.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested live does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "url": "https://videostream.tinkermode.com/stream/v1.eyJzIjoiZW50aXR5ZmlsZXMiLCJrIjoiQS9lbnRpdGllcy91YXJlaG91c2VfZnJlZXplcl8wMDEvZmlsZXMvM2EwYjFiMmM1ZDRlNWY2YTBhMWIyYzNhIiwiZiI6ImluY2lkZW50Lm1wNCJ9.1702687298.91445ff477f6ca1568569bce48b077febaf78d1a5f584dfdaa894013"
}

Get list of data filters

Endpoint
get /projects/{projectId}/dataFilters
Description

Get all data filters 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.

  • dataType

    Returns data filters of the specified data type.

  • skip

    Number of data filters to skip over.

  • limit

    Maximum number of data filters to return.

Response
  • 200Successful retrieval of data filters.
  • 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

[
    {
        "projectId": 1234,
        "name": "Data Filter 1",
        "filterId": "filter1",
        "filterType": "conversion",
        "dataType": "metrics",
        "catalogId": "bu01",
        "conversionRules": {
            "values": [
                {
                    "name": "relative_humidity",
                    "metricName": "humidity"
                }
            ]
        }
    },
    {
        "projectId": 1234,
        "name": "Data Filter 2",
        "filterId": "filter2",
        "filterType": "conversion",
        "dataType": "metrics",
        "catalogId": "custom1",
        "conversionRules": {
            "tags": [
                {
                    "name": "statusCode",
                    "metricName": "status",
                    "replacement": [
                        {
                            "old": "001",
                            "new": "success"
                        },
                        {
                            "old": "002",
                            "new": "failure"
                        }
                    ]
                }
            ]
        }
    }
]

Create data filters

Endpoint
post /projects/{projectId}/dataFilters
Description

Create a new data filters 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 data filters of a project, or a Project API Key with admin permission.

Request Body

  • filterType

    string

    required

    Filter type of the data filter.

    Options are conversion, area_determination, ellipsoid_to_orthometric_conversion

  • name

    string

    required

    Display name of data filter.

  • catalogId

    string

    required

    Data Source Catalog ID of data filter.

  • conversionRules

    object

    The configuration of conversion type of data filter.

  • areaDeterminationRules

    object

    The configuration of area determination type of data filter.

Response
  • 201Successful creation of data filter.
  • 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,
    "name": "Data Filter 2",
    "filterId": "filter2",
    "filterType": "conversion",
    "dataType": "metrics",
    "catalogId": "custom1",
    "conversionRules": {
        "excludes": [
            "debug_code"
        ],
        "values": [
            {
                "name": "relative_humidity",
                "metricName": "humidity"
            }
        ],
        "tags": [
            {
                "name": "statusCode",
                "metricName": "status",
                "replacement": [
                    {
                        "old": "001",
                        "new": "success"
                    },
                    {
                        "old": "002",
                        "new": "failure"
                    }
                ]
            }
        ]
    }
}

Response Body Sample

{
    "projectId": 1234,
    "name": "Data Filter 2",
    "filterId": "filter2",
    "filterType": "conversion",
    "dataType": "metrics",
    "catalogId": "custom1",
    "conversionRules": {
        "excludes": [
            "debug_code"
        ],
        "values": [
            {
                "name": "relative_humidity",
                "metricName": "humidity"
            }
        ],
        "tags": [
            {
                "name": "statusCode",
                "metricName": "status",
                "replacement": [
                    {
                        "old": "001",
                        "new": "success"
                    },
                    {
                        "old": "002",
                        "new": "failure"
                    }
                ]
            }
        ]
    }
}

Get data filter

Endpoint
get /projects/{projectId}/dataFilters/{filterId}
Description

Get the specified data filter

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • filterId

    string

    required

    Data Filter ID

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

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

Response Body Sample

{
    "projectId": 1234,
    "name": "Data Filter 2",
    "filterId": "filter2",
    "filterType": "conversion",
    "dataType": "metrics",
    "catalogId": "custom1",
    "conversionRules": {
        "excludes": [
            "debug_code"
        ],
        "values": [
            {
                "name": "relative_humidity",
                "metricName": "humidity"
            }
        ],
        "tags": [
            {
                "name": "statusCode",
                "metricName": "status",
                "replacement": [
                    {
                        "old": "001",
                        "new": "success"
                    },
                    {
                        "old": "002",
                        "new": "failure"
                    }
                ]
            }
        ]
    }
}

Update data filter

Endpoint
patch /projects/{projectId}/dataFilters/{filterId}
Description

Update specified data filter

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • filterId

    string

    required

    Data Filter ID

Request Headers What's this?

  • Authorization

    required

    Must contain the API key of a user who has the permission to update all data filters of a project, or a Project API Key with admin permission.

Request Body

  • filterType

    string

    required

    Filter type of the data filter.

    Options are conversion, area_determination, ellipsoid_to_orthometric_conversion

  • name

    string

    required

    Display name of data filter.

  • catalogId

    string

    required

    Data Source Catalog ID of data filter.

  • conversionRules

    object

    The configuration of conversion type of data filter.

  • areaDeterminationRules

    object

    The configuration of area determination type of data filter.

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

Request Body Sample

{
    "projectId": 1234,
    "name": "Data Filter 2",
    "filterId": "filter2",
    "filterType": "conversion",
    "dataType": "metrics",
    "catalogId": "custom1",
    "conversionRules": {
        "excludes": [
            "debug_code"
        ],
        "values": [
            {
                "name": "relative_humidity",
                "metricName": "humidity"
            }
        ],
        "tags": [
            {
                "name": "statusCode",
                "metricName": "status",
                "replacement": [
                    {
                        "old": "001",
                        "new": "success"
                    },
                    {
                        "old": "002",
                        "new": "failure"
                    }
                ]
            }
        ]
    }
}

Delete data filter

Endpoint
delete /projects/{projectId}/dataFilters/{filterId}
Description

Delete specified data filter

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • filterId

    string

    required

    Data Filter ID

Request Headers What's this?

  • Authorization

    required

    Must contain the API key of a user who has the permission to delete all data filters of a project, or a Project API Key with admin permission.

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

Create TSDBv2 Schema

Endpoint
post /projects/{projectId}/tsdb/v2/schemas
Description

Creates a new schema.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Request Body

  • name

    string

    required

    Name of the schema to be created.

  • metrics

    array

    required

    One or more metrics to be included in the schema.

Response
  • 201Successfully created the schema.

Request Body Sample

{
    "name": "foo_schema",
    "metrics": [
        {
            "name": "foo_metric",
            "tags": [
                {
                    "key": "location",
                    "value": "inside"
                }
            ]
        }
    ]
}

Response Body Sample

{
    "name": "foo_schema",
    "metrics": [
        {
            "name": "foo_metric",
            "tags": [
                {
                    "key": "unit",
                    "value": "blah"
                }
            ]
        }
    ],
    "totalMetrics": 1
}

List TSDBv2 schemas

Endpoint
get /projects/{projectId}/tsdb/v2/schemas
Description

Get the list of all TSDBv2 schemas of a project.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Response
  • 200Successfully retrieved list of schemas.

Get TSDBv2 Schema

Endpoint
get /projects/{projectId}/tsdb/v2/schemas/{schemaName}
Description

Retrieves a schema.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • schemaName

    string

    required

    Name of the schema.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Response
  • 200Successfully retrieved the schema.

Response Body Sample

{
    "name": "foo_schema",
    "metrics": [
        {
            "name": "foo_metric",
            "tags": [
                {
                    "key": "unit",
                    "value": "blah"
                }
            ]
        }
    ],
    "totalMetrics": 1
}

Delete TSDBv2 Schema

Endpoint
delete /projects/{projectId}/tsdb/v2/schemas/{schemaName}
Description

Deletes a schema.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • schemaName

    string

    required

    Name of the schema.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Response
  • 204Successfully deleted the schema.

Create TSDBv2 Metric

Endpoint
post /projects/{projectId}/tsdb/v2/schemas/{schemaName}/metrics
Description

Creates an additional metric in a schema.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • schemaName

    string

    required

    Name of the schema.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Request Body

  • tags

    array

Response
  • 201Successfully created the metric.

Request Body Sample

{
    "name": "bar_metric",
    "tags": [
        {
            "key": "location",
            "value": "outside"
        }
    ]
}

Response Body Sample

{
    "name": "bar_metric",
    "tags": [
        {
            "key": "location",
            "value": "outside"
        }
    ]
}

Get TSDBv2 Metrics

Endpoint
get /projects/{projectId}/tsdb/v2/schemas/{schemaName}/metrics
Description

Retrieves metrics from a schema, optionally using a filter.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • schemaName

    string

    required

    Name of the schema.

Query Parameters

  • filter

    string

    Filters metrics using tag.{key}:"{value}" syntax with each tag delimited by a space (e.g. tag.location:"inside" tag.location:"outside").

  • nextToken

    string

    Token for retrieving additional metrics. A non-empty token indicates additional metrics are available and can be used to retrieve the next set of metrics by reissuing the request with this token. An empty token means there are no more metrics to retrieve.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Response
  • 200Successfully retrieved the metrics.

Response Body Sample

{
    "entries": [
        {
            "name": "foo_metric",
            "tags": [
                {
                    "key": "location",
                    "value": "inside"
                }
            ]
        },
        {
            "name": "bar_metric",
            "tags": [
                {
                    "key": "location",
                    "value": "outside"
                }
            ]
        }
    ],
    "nextToken": ""
}

Update TSDBv2 Metric Tags

Endpoint
patch /projects/{projectId}/tsdb/v2/schemas/{schemaName}/metrics/{metricName}
Description

Replaces the metric tags of a metric. Empty tags will remove all tags.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • schemaName

    string

    required

    Name of the schema.

  • metricName

    string

    required

    Name of the metric.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Response
  • 204Successfully updated the metric's tags.

Request Body Sample

{
    "tags": [
        {
            "key": "location",
            "value": "basement"
        },
        {
            "key": "unit",
            "value": "kWh"
        }
    ]
}

Create Log Collection

Endpoint
post /projects/{projectId}/customLogs
Description

Creates a new Log Collection

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Request Body

  • name

    string

    required

    Name of the Log Collection to be created. Must be unique per Project.

Response
  • 204Successfully created the Log Collection.

Delete a Log Collection

Endpoint
delete /projects/{projectId}/customLogs/{logCollectionName}
Description

Deletes a Log Collection

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • logCollectionName

    string

    required

    The name of the Log Collection.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Response
  • 204Successfully deleted the Log Collection.

Get Log Entries

Endpoint
get /projects/{projectId}/customLogs/{logCollectionName}/data
Description

Retrieves Log Entries of a given Log Collection using the provided filters.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • logCollectionName

    string

    required

    The name of the Log Collection.

Query Parameters

  • begin

    string

    required

    The begin time of the search range.

  • end

    string

    required

    The end time of the search range.

  • searchKeys

    array

    required

    One or more search keys used to filter the result. Multiple search keys can be delimited with a comma.

  • 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

  • skip

    integer

    The number of Log Entries to skip. If unspecified, the default value is 0.

  • limit

    integer

    The maximum number of Log Entries to return. If unspecified, the default value is 1000.

  • sortBy

    string

    The sort order of the Log Entries in the format field:order (e.g. timestamp:desc). Currently, only the timestamp field is supported. The default order is ascending.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Response
  • 200Successfully retrieved Log Entries.

Create or Update Log Entries

Endpoint
put /projects/{projectId}/customLogs/{logCollectionName}/data
Description

Creates or updates Log Entries.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • logCollectionName

    string

    required

    The name of the Log Collection.

Request Headers What's this?

  • Authorization

    required

    Must contain a project API key.

Response
  • 204Successfully created the Log Entry.

Upload a file

Endpoint
post /projects/{projectId}/uploadFile
Description

Under the hood, Project Files are basically Entity Files that belong to the root entity. To upload a file to a project, the client must first acquire (an) upload URL(s) by using the open-upload action in the request body. After completing the upload (by making a PUT request to the upload URL(s)), 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.

Request Headers What's this?

  • Authorization

    required

    Must contain a device API key of a device belonging to the same home, a user API key of a user with permission to create project files, or a project API key with admin permissions.

Request Body

  • action

    string

    required

    Action to be taken.

    Options are open-upload, close-upload

  • metadata

    object

    Metadata for the file. Required for the open-upload action.

  • numberOfParts

    integer

    Optional number of parts to split the upload into. Defaults to 1.

  • uploadId

    string

    Upload ID returned from the open-upload action. Required for the close-upload action.

Response
  • 200For the `open-upload` action, this represents a successful start of the upload for a file. The response body is a JSON object that contains an array of pre-signed upload URLs. The client should divide up the file in the same number of parts as the number of URLs, and upload each part to its corresponding URL with a PUT request.
  • 204For the `close-upload` action, this represents a successful completion of file upload.
  • 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",
  "metadata": {
    "timestamp": "2023-11-01T12:17:56Z",
    "contentType": "video/mp4",
    "tags": [
      "camera1",
      "eventId:20231101",
      "eventType:crash"
    ],
    "expirationDate": "2024-11-01T12:17:56Z",
    "fileName": "video.mp4",
    "attributes": {
      "eventId": "20231101",
      "eventType": "crash",
      "errorCode": 42
    }
  },
  "numberOfParts": 2
}

Get project files

Endpoint
get /projects/{projectId}/files
Description

Look up files associated with a project. Use the begin and end query parameters to fetch only files with timestamps that fall within the time range. Use the tag parameter to fetch files with a matching tag. And use the contentType paramter to fetch only files that match the given content type.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

Query Parameters

  • begin

    string

    The beginning time to search for files in RFC3339 format.

  • end

    string

    The end time to search for files in RFC3339 format.

  • tag

    string

    If specified, return files that contain the specified tag. If this paramter is repeated, files matching at least one of the tags will be returned.

  • contentType

    string

    MIME type of the project file to search for.

  • limit

    integer

    The maximum number of project files to return.

  • skip

    integer

    The number of project files to skip.

  • sortBy

    string

    A sort key. timestamp is the valid field. (e.g. "timestamp:asc" or "timestamp:desc")

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key of a user with permission to read project files, or a project API key.

Response
  • 200Successful query for project files.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get project file metadata

Endpoint
get /projects/{projectId}/files/{fileId}
Description

Get the metadata of ther specified project file.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • fileId

    string

    required

    Project file ID.

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key of a user with permission to read project files, or a project API key.

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

Response Body Sample

{
  "fileId": "3a0b1b2b4d4e5f6a0a1b2a1a",
  "projectId": 111,
  "entityId": "root",
  "timestamp": "2023-11-01T12:17:56Z",
  "contentType": "video/mp4",
  "tags": [
    "camera1",
    "eventId:20231101",
    "eventType:crash"
  ],
  "fileName": "video.mp4",
  "attributes": {
    "eventId": "20231101",
    "eventType": "crash",
    "errorCode": 42
  },
  "url": "https://download.tinkermode.com/download/XXXXXXXXXXXXXX"
}

Update project file metadata

Endpoint
patch /projects/{projectId}/files/{fileId}
Description

Update the metadata of the specified project file.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • fileId

    string

    required

    Project file ID.

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key of a user with permission to update project files, or a project API key with admin permissions.

Request Body

  • tags

    array

    A collection of unique string identifiers associated with the entity file.

  • expirationDate

    string

    Timestamp indicating when the entity file should expire.

  • attributes

    object

    Attributes associated with the entity file, separated as key-value pairs.

Response
  • 204Successful update of project file metadata.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested file does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "tags": [
    "camera1",
    "eventId:20231101",
    "eventType:crash"
  ],
  "expirationDate": "2024-11-01T12:17:56Z",
  "attributes": {
    "eventId": "20231101",
    "eventType": "crash",
    "errorCode": 42
  }
}

Delete a project file

Endpoint
delete /projects/{projectId}/files/{fileId}
Description

Delete the specified project file. This includes both the metadata and the actual file object in storage.

Path Parameters

  • projectId

    integer

    required

    The unique ID for a specified project.

  • fileId

    string

    required

    Project file ID.

Request Headers What's this?

  • Authorization

    required

    Must contain a user API key of a user with permission to delete project file, or a project API key with admin permissions.

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