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 defintiions that are applicable to this class of entities.

  • attributeSchemaarray

    A schema used for validating the attributes of an entity instance.

  • createdAtstring| format is date-time

    Timestamp of entity class creation.

  • updatedAtstring| format is date-time

    Timestamp of the last update on the entity class.

The Entity Class object

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

The Entity Instance object

  • entityIdstring

    Unique entity ID.

  • projectIdinteger

    Project that this entity belongs to.

  • homeIdinteger

    Home that this entity belongs to.

  • parentIdstring

    The ID of the entity instance that is a parent of the instance.

  • entityClassstring

    The entity class that the entity was instantiated from.

  • displaySettingsobject

    Various user interface settings used for display of the entity instance.

  • attributesobject

    The attributes that belong to the entity instance, separated as key-value pairs.

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

  • 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"
}

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

    Project ID

  • 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

    Project ID

  • 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

    Project ID

  • 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

    Project ID

  • 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

    Project ID

  • 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 entity classes

Endpoint
get /projects/{projectId}/entityClasses
Description

Get all entity classes defined for a project.

Path Parameters

  • projectId

    integer

    required

    Project ID

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.

Get entity class

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

Get the specified entity class.

Path Parameters

  • projectId

    integer

    required

    Project ID

  • entityClassId

    string

    required

    Entity Class ID (unique within project)

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.

Get list of entity instances

Endpoint
get /projects/{projectId}/entities
Description

Get entity instances of a project.

Path Parameters

  • projectId

    integer

    required

    Project ID

Query Parameters

  • homeId

    integer

    Return entity instances in a specific home. If the caller accesses this endpoint with a user session token, a valid home ID must be provided.

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

  • 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

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. Only a caller with a valid user session in a given home, or a project API key with admin permission belonging to the same project can create an entity instance.

Path Parameters

  • projectId

    integer

    required

    Project ID

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

Request Body

  • homeId

    uint64

    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.

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

    Project ID

  • entityId

    string

    required

    Entity ID (unique within project)

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

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

Update entity instance

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

Update attributes of the specified entity instance.

Path Parameters

  • projectId

    integer

    required

    Project ID

  • entityId

    string

    required

    Entity ID (unique within project)

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

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.

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

    Project ID

  • entityId

    string

    required

    Entity ID (unique within project)

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

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

    Project ID

  • entityId

    string

    required

    Entity ID (unique within project)

Request Headers What's this?

  • Authorization

    required

    Must contain a user or project API key.

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"
}