Log in to Bueno
API docs by Redocly

API documentation

Download OpenAPI specification:Download

API support: support@buenosystems.com.au URL: https://us.api.bueno-analytics.com

Introduction

The Bueno API is a collection of REST endpoints, used to interact with the Bueno Platform.

Getting started

The building model

The data model is hierarchical, the relationships between some of the main entities are roughly mapped out below. More information on what each of these entities represent can be found by navigating to their respective subsections of this documentation.

Organisation → Site → Group → Equipment → Point → DataStreamMapping

Organisation → Integration → Data Stream → DataStreamMapping

To fetch Site, Group, Equipment or Point data you can traverse the layers of the data model sequentially.

These entities can also be traversed in the opposite direction using the refs field which is available on each of the Site, Equipment and Point entities, providing a reference to all higher level entities.

The Organisation, Integration, and Data Stream side of the model can be traversed in a similar way, although here refs are replaced with properties that indicate the parent entity. (E.g Integration entities have an organisationId property.)

Histories data

One of the primary purposes of the Bueno Platform is to be able to ingest, store and serve up time series historical data.

In the data model, Points have a relationship with Histories. Histories can be retrieved for a single Point as raw or aggregated (rolled up) data ranging from 5 minute to yearly intervals. An individual History entity is an object containing a timestamp, in the case of raw data a val, or in the case of an aggregation, formulas e.g. avg, max, min.

Aggregated data timestamps are always aligned to the start of the period, for example, for QUARTERLY, the dates would be Jan 1st, Apr 1st etc. regardless of whether the requested time period covers all or only some of the aggregate range.

The data is aggregated to the start of the time period, for example, for hourly data, a timestamp of 10:00 includes data from 10:00 inclusive to 11:00 exclusive.

Timestamps are returned in ISO 8601 format in Coordinated Universal Time (UTC) for raw and sub daily aggregated histories and as a local date for larger aggregations.

These same histories also have a relationship with Data Streams. Data Streams represent a single source of Histories and this part of the model is leveraged when ingesting them into the platform. See Data Streams, Data Stream Mappings, and Ingestion below for more information.

Access control

Access in the API is controlled by a User's Role, which defines the permissions available to a User e.g. View Insights, and Groups, which define which Organisations and Sites the User has access to. Not all endpoints documented here are available to every Role.

If you are a Bueno user, your access can be configured in the app. Alternatively, reach out to API support if you need help in configuring your access.

Authentication

This is required to retrieve an access token to authenticate your User with the API. Use the same credentials you use to login to the Bueno app to authenticate with the API.

All requests must be authorised using your Bearer access token.

  • HTTP authorisation scheme: bearer
  • Bearer format: JWT

Retrieve access token

Allows a user to login with their email and password. This endpoint will issue an access token on success.

This token will expire after the time specified in the response and a new token will need to be requested.

Request Body schema: application/json
email
string <email>
password
string

Responses

Response Schema: application/json
token
string <JWT>

JWT string that can be used as a bearer token

expires
integer <int64>

Issued JWT token time to expire in seconds

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "S0m3@S3cr3TP4$$"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "expires": 1209599
}

Organisations

An Organisation entity represents a company or customer with 0 or more Sites.

Create Organisation

Creates a new Organisation entity.

Authorizations:
Bearer authentication
Request Body schema: application/json
key
required
string

Unique, immutable, human readable key to identify the Organisation

name
required
string

Full name of the Organisation

timezone
required
string

Timezone of the Organisation

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Organisation

key
string

Unique, immutable, human readable key to identify the Organisation

name
string

Full name of the Organisation

timezone
string

Timezone of the Organisation

Request samples

Content type
application/json
{
  • "key": "ACME",
  • "name": "Acme Corporation",
  • "timezone": "Australia/Melbourne"
}

Response samples

Content type
application/json
{
  • "id": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
  • "key": "ACME",
  • "name": "Acme Corporation",
  • "timezone": "Australia/Melbourne"
}

Update Organisation

Updates an Organisation entity.

(Note: Only the Organisation's name and timezone can be updated, the id and key must remain the same.)

Authorizations:
Bearer authentication
Request Body schema: application/json
id
required
string <uuid>

Unique identifier of the Organisation

key
required
string

Unique, immutable, human readable key to identify the Organisation

name
required
string

Full name of the Organisation

timezone
required
string

Timezone of the Organisation

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Organisation

key
string

Unique, immutable, human readable key to identify the Organisation

name
string

Full name of the Organisation

timezone
string

Timezone of the Organisation

Request samples

Content type
application/json
{
  • "id": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
  • "key": "ACME",
  • "name": "Acme Corporation",
  • "timezone": "Australia/Melbourne"
}

Response samples

Content type
application/json
{
  • "id": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
  • "key": "ACME",
  • "name": "Acme Corporation",
  • "timezone": "Australia/Melbourne"
}

Retrieve Organisations

Retrieves a list of Organisation entities.

Authorizations:
Bearer authentication

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Organisation

key
string

Unique, immutable, human readable key to identify the Organisation

name
string

Full name of the Organisation

timezone
string

Timezone of the Organisation

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Organisation by ID

Retrieves a single Organisation entity by its ID.

Authorizations:
Bearer authentication
path Parameters
organisationId
required
string <uuid>
Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7

Unique identifier of an Organisation

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Organisation

key
string

Unique, immutable, human readable key to identify the Organisation

name
string

Full name of the Organisation

timezone
string

Timezone of the Organisation

Response samples

Content type
application/json
{
  • "id": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
  • "key": "ACME",
  • "name": "Acme Corporation",
  • "timezone": "Australia/Melbourne"
}

Sites

A Site entity is the equivalent of a building in the physical world. A Site always belongs to an Organisation. Each Site entity contains information related to the building location, as well as tags, props, and refs that capture some of the characteristics of the Site and its relationships to other entities.

Create Site

Creates a new Site entity. The Organisation ID must be included in the Site's refs.

Authorizations:
Bearer authentication
Request Body schema: application/json
name
required
string

Name of the Site

area
number
Default: null

Area of the Site in square meters

latitude
required
number

Latitude co-ordinates of the Site

longitude
required
number

Longitude co-ordinates of the Site

address
required
string

Address of the Site

city
required
string

City in which the Site is located

state
required
string

State in which the Site is located

country
required
string

Two letter country in which the Site is located

postcode
required
string

Postcode of the Site

timezone
required
string

Timezone of the Site

props
object
Default: null

Additional key-value typed properties associated with the Site

tags
Array of strings
Default: null

Strings applied to the Site to add context and used for analytics

refs
required
object
Default: {}

Upstream references for the Site

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Site

name
string

Name of the Site

externalId
string
Default: null

Alternative unique identifier

description
string

Description of the Site

area
number
Default: null

Area of the Site in square meters

latitude
number
Default: null

Latitude co-ordinates of the Site

longitude
number
Default: null

Longitude co-ordinates of the Site

address
string
Default: null

Address of the Site

city
string

City in which the Site is located

state
string
Default: null

State in which the Site is located

country
string

Country in which the Site is located

postcode
string
Default: null

Postcode of the Site

timezone
string

Timezone of the Site

props
object
Default: {}

Additional key-value typed properties associated with the Site

refs
object
Default: {}

Upstream references for the Site

tags
Array of strings

Strings applied to the Site to add context and used for analytics

deleted
boolean

Boolean flag indicating if the Site is deleted

Request samples

Content type
application/json
{
  • "name": "Acme Building 1",
  • "area": 42500,
  • "latitude": -37.812765,
  • "longitude": 144.973535,
  • "address": "Sugartopped Loaf, Melbourne VIC 3000",
  • "city": "Melbourne",
  • "state": "VIC",
  • "country": "AU",
  • "postcode": "3000",
  • "timezone": "Australia/Melbourne",
  • "props": {
    },
  • "tags": [
    ],
  • "refs": {
    }
}

Response samples

Content type
application/json
{
  • "id": "8a7869df-6cad-4642-a015-9fbb36d3b337",
  • "name": "Acme Building 1",
  • "externalId": "2658ee88-0788524e",
  • "description": "Acme headquarters",
  • "area": 42500,
  • "latitude": -37.812765,
  • "longitude": 144.973535,
  • "address": "Sugartopped Loaf, Melbourne VIC 3000",
  • "city": "Melbourne",
  • "state": "VIC",
  • "country": "AU",
  • "postcode": "3000",
  • "timezone": "Australia/Melbourne",
  • "props": {
    },
  • "refs": {
    },
  • "tags": [
    ],
  • "deleted": false
}

Update Site

Updates a list of Site entities.

Authorizations:
Bearer authentication
Request Body schema: application/json
Array
id
required
string <uuid>

Unique identifier of the Site

name
required
string

Name of the Site

description
required
string

Description of the Site

area
number
Default: null

Area of the Site in square meters

latitude
number
Default: null

Latitude co-ordinates of the Site

longitude
number
Default: null

Longitude co-ordinates of the Site

address
string
Default: null

Address of the Site

city
required
string

City in which the Site is located

state
string
Default: null

State in which the Site is located

country
required
string

Country in which the Site is located

postcode
string
Default: null

Postcode of the Site

timezone
required
string

Timezone of the Site

props
object
Default: {}

Additional key-value typed properties associated with the Site

refs
required
object

Upstream references for the Site

tags
Array of strings
Default: []

Strings applied to the Site to add context and used for analytics

deleted
boolean
Default: false

Boolean flag indicating if the Site is deleted

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Site

name
string

Name of the Site

externalId
string
Default: null

Alternative unique identifier

description
string

Description of the Site

area
number
Default: null

Area of the Site in square meters

latitude
number
Default: null

Latitude co-ordinates of the Site

longitude
number
Default: null

Longitude co-ordinates of the Site

address
string
Default: null

Address of the Site

city
string

City in which the Site is located

state
string
Default: null

State in which the Site is located

country
string

Country in which the Site is located

postcode
string
Default: null

Postcode of the Site

timezone
string

Timezone of the Site

props
object
Default: {}

Additional key-value typed properties associated with the Site

refs
object
Default: {}

Upstream references for the Site

tags
Array of strings

Strings applied to the Site to add context and used for analytics

deleted
boolean

Boolean flag indicating if the Site is deleted

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Sites with advanced search

Retrieve Sites using advanced search queries. See the documentation for more information on how to use advanced search.

Examples:

Find a Site by its ID:

id == "3cecf04f-0101-4f36-a3ff-d4822fa72f5b"

Find a Site by its name:

name == "222 Smith St"

Find all Sites without operating hour properties:

NOT props.startOpHrs AND NOT props.endOpHrs
Authorizations:
Bearer authentication
query Parameters
organisationId
required
string <uuid>
Example: organisationId=9f1748db-ea2b-4e9a-b035-e5757d7e97c7

Unique identifier of an Organisation

expr
string
Default: ""
Example: expr=name == "123 Market St"

Expression to search Sites with

limit
number
Default: 5000
Example: limit=50

Result set size limit

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Site

name
string

Name of the Site

externalId
string
Default: null

Alternative unique identifier

description
string

Description of the Site

area
number
Default: null

Area of the Site in square meters

latitude
number
Default: null

Latitude co-ordinates of the Site

longitude
number
Default: null

Longitude co-ordinates of the Site

address
string
Default: null

Address of the Site

city
string

City in which the Site is located

state
string
Default: null

State in which the Site is located

country
string

Country in which the Site is located

postcode
string
Default: null

Postcode of the Site

timezone
string

Timezone of the Site

props
object
Default: {}

Additional key-value typed properties associated with the Site

refs
object
Default: {}

Upstream references for the Site

tags
Array of strings

Strings applied to the Site to add context and used for analytics

deleted
boolean

Boolean flag indicating if the Site is deleted

Response samples

Content type
application/json
[
  • {
    }
]

Delete Site

Deletes a single Site entity by its ID.

Authorizations:
Bearer authentication
path Parameters
siteId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Site

Responses

Retrieve Site by ID

Retrieves a single Site entity by its ID.

Authorizations:
Bearer authentication
path Parameters
siteId
required
string <uuid>
Example: 8a7869df-6cad-4642-a015-9fbb36d3b337

Unique identifier of the Site

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Site

name
string

Name of the Site

externalId
string
Default: null

Alternative unique identifier

description
string

Description of the Site

area
number
Default: null

Area of the Site in square meters

latitude
number
Default: null

Latitude co-ordinates of the Site

longitude
number
Default: null

Longitude co-ordinates of the Site

address
string
Default: null

Address of the Site

city
string

City in which the Site is located

state
string
Default: null

State in which the Site is located

country
string

Country in which the Site is located

postcode
string
Default: null

Postcode of the Site

timezone
string

Timezone of the Site

props
object
Default: {}

Additional key-value typed properties associated with the Site

refs
object
Default: {}

Upstream references for the Site

tags
Array of strings

Strings applied to the Site to add context and used for analytics

deleted
boolean

Boolean flag indicating if the Site is deleted

Response samples

Content type
application/json
{
  • "id": "8a7869df-6cad-4642-a015-9fbb36d3b337",
  • "name": "Acme Building 1",
  • "externalId": "2658ee88-0788524e",
  • "description": "Acme headquarters",
  • "area": 42500,
  • "latitude": -37.812765,
  • "longitude": 144.973535,
  • "address": "Sugartopped Loaf, Melbourne VIC 3000",
  • "city": "Melbourne",
  • "state": "VIC",
  • "country": "AU",
  • "postcode": "3000",
  • "timezone": "Australia/Melbourne",
  • "props": {
    },
  • "refs": {
    },
  • "tags": [
    ],
  • "deleted": false
}

Retrieve Sites by Organisation ID

Retrieves a list of Site entities belonging to a specific Organisation.

Authorizations:
Bearer authentication
path Parameters
organisationId
required
string <uuid>
Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7

Unique identifier of an Organisation

query Parameters
includeDeleted
boolean
Default: false
Example: includeDeleted=false

Include deleted Sites in the response

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Site

name
string

Name of the Site

externalId
string
Default: null

Alternative unique identifier

description
string

Description of the Site

area
number
Default: null

Area of the Site in square meters

latitude
number
Default: null

Latitude co-ordinates of the Site

longitude
number
Default: null

Longitude co-ordinates of the Site

address
string
Default: null

Address of the Site

city
string

City in which the Site is located

state
string
Default: null

State in which the Site is located

country
string

Country in which the Site is located

postcode
string
Default: null

Postcode of the Site

timezone
string

Timezone of the Site

props
object
Default: {}

Additional key-value typed properties associated with the Site

refs
object
Default: {}

Upstream references for the Site

tags
Array of strings

Strings applied to the Site to add context and used for analytics

deleted
boolean

Boolean flag indicating if the Site is deleted

Response samples

Content type
application/json
[
  • {
    }
]

Groups

A Group entity belongs to a Site and is used to logically group Equipment that also belong to the Site. The entity does not normally have a physical equivalent in the real world, and is typically used as a 'grouping' entity to make modeling Sites that have large numbers of Equipment more manageable.

Create Group

Creates a new Group entity.

Authorizations:
Bearer authentication
Request Body schema: application/json
name
required
string

Name of the Group

siteId
required
string <uuid>

Unique identifier of the Site the Group belongs to

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Group

name
string

Name of the Group

siteId
string <uuid>

Unique identifier of the Site the Group belongs to

deleted
boolean

Boolean flag indicating if the Group is deleted

Request samples

Content type
application/json
{
  • "name": "CHW PLANT",
  • "siteId": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}

Response samples

Content type
application/json
{
  • "id": "38d77506-9c7a-447e-9153-b9ce23b7ceb6",
  • "name": "CHW PLANT",
  • "siteId": "8a7869df-6cad-4642-a015-9fbb36d3b337",
  • "deleted": false
}

Update Group

Updates a list of Group entities.

Authorizations:
Bearer authentication
Request Body schema: application/json
Array
id
required
string <uuid>

Unique identifier of the Group

name
required
string

Name of the Group

siteId
required
string <uuid>

Unique identifier of the Site the Group belongs to

deleted
boolean

Boolean flag indicating if the Group is deleted

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Group

name
string

Name of the Group

siteId
string <uuid>

Unique identifier of the Site the Group belongs to

deleted
boolean

Boolean flag indicating if the Group is deleted

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Groups with advanced search

Retrieve Groups using advanced search queries. See the documentation for more information on how to use advanced search.

Examples:

Find a Group by its ID:

id == "3cecf04f-0101-4f36-a3ff-d4822fa72f5b"

Find a Group by its name:

name == "CHWS"

Find all Groups belonging to a particular Site:

site.name == "222 Smith St"
Authorizations:
Bearer authentication
query Parameters
organisationId
required
string <uuid>
Example: organisationId=9f1748db-ea2b-4e9a-b035-e5757d7e97c7

Unique identifier of an Organisation

expr
string
Default: ""
Example: expr=name == "AHUs"

Expression to search Groups with

limit
number
Default: 5000
Example: limit=50

Result set size limit

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Group

name
string

Name of the Group

siteId
string <uuid>

Unique identifier of the Site the Group belongs to

deleted
boolean

Boolean flag indicating if the Group is deleted

Response samples

Content type
application/json
[
  • {
    }
]

Delete Group

Deletes a single Group entity by its ID.

Authorizations:
Bearer authentication
path Parameters
equipGroupId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Group

Responses

Retrieve Group by ID

Retrieves a Group entity by its ID.

Authorizations:
Bearer authentication
path Parameters
equipGroupId
required
string <uuid>
Example: 38d77506-9c7a-447e-9153-b9ce23b7ceb6

Unique identifier of a Group

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Group

name
string

Name of the Group

siteId
string <uuid>

Unique identifier of the Site the Group belongs to

deleted
boolean

Boolean flag indicating if the Group is deleted

Response samples

Content type
application/json
{
  • "id": "38d77506-9c7a-447e-9153-b9ce23b7ceb6",
  • "name": "CHW PLANT",
  • "siteId": "8a7869df-6cad-4642-a015-9fbb36d3b337",
  • "deleted": false
}

Retrieve Groups by Site ID

Retrieves a list of Group entities belonging to a specific Site.

Authorizations:
Bearer authentication
path Parameters
siteId
required
string <uuid>
Example: 8a7869df-6cad-4642-a015-9fbb36d3b337

Unique identifier of the Site

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Group

name
string

Name of the Group

siteId
string <uuid>

Unique identifier of the Site the Group belongs to

deleted
boolean

Boolean flag indicating if the Group is deleted

Response samples

Content type
application/json
[
  • {
    }
]

Equipment

An Equipment entity can be roughly translated to either a physical object in a building such as a fan, or a virtual object such as a level/floor of a building. An Equipment belongs to a Group. Like Sites, Equipment entities have tags, props, and refs that characterise them and map out their relationships to other entities. Equipment can also have a Class that defines the Equipment's function within the data model.

Create Equipment

Creates a new Equipment entity. The Group ID must be included in the Equipment's refs.

Authorizations:
Bearer authentication
Request Body schema: application/json
name
required
string

Name of the Equipment

tags
Array of strings
Default: []

Strings applied to the Equipment to add context and used for analytics

refs
required
object
Default: {}

Upstream references for the Equipment

props
object
Default: {}

Additional key-value typed properties associated with the Equipment

object (VirtualMeterRefs)

Contains the submeter references used to build a virtual meter

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Equipment

name
string

Name of the Equipment

externalId
string
Default: null

Alternative unique identifier

object (EquipmentClass)

Equipment Class details

tags
Array of strings

Strings applied to the Equipment to add context and used for analytics

refs
object
Default: {}

Upstream references for the Equipment

Array of objects (EquipmentType)

Equipment types that the Equipment belongs to e.g. ahu, chiller

object (VirtualMeterRefs)

Contains the submeter references used to build a virtual meter

props
object
Default: {}

Additional key-value typed properties associated with the Equipment

deleted
boolean

Boolean flag indicating if the Equipment is deleted

Request samples

Content type
application/json
{
  • "name": "Gas Meter",
  • "tags": [
    ],
  • "refs": {
    },
  • "props": {
    },
  • "virtualMeterRefs": null
}

Response samples

Content type
application/json
{
  • "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
  • "name": "Gas Meter",
  • "externalId": "3758ef98-0788524e",
  • "class": {
    },
  • "tags": [
    ],
  • "refs": {
    },
  • "types": [
    ],
  • "virtualMeterRefs": null,
  • "props": {
    },
  • "deleted": false
}

Update Equipment

Updates a list of Equipment entities.

Authorizations:
Bearer authentication
Request Body schema: application/json
Array
id
required
string <uuid>

Unique identifier of the Equipment

name
required
string

Name of the Equipment

tags
Array of strings
Default: []

Strings applied to the Equipment to add context and used for analytics

refs
required
object

Upstream references for the Equipment

Array of objects (EquipmentType)
Default: []

Equipment types that the Equipment belongs to e.g. ahu, chiller

props
object
Default: {}

Additional key-value typed properties associated with the Equipment

deleted
boolean
Default: false

Boolean flag indicating if the Equipment is deleted

object (VirtualMeterRefs)

Contains the submeter references used to build a virtual meter

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Equipment

name
string

Name of the Equipment

externalId
string
Default: null

Alternative unique identifier

object (EquipmentClass)

Equipment Class details

tags
Array of strings

Strings applied to the Equipment to add context and used for analytics

refs
object
Default: {}

Upstream references for the Equipment

Array of objects (EquipmentType)

Equipment types that the Equipment belongs to e.g. ahu, chiller

object (VirtualMeterRefs)

Contains the submeter references used to build a virtual meter

props
object
Default: {}

Additional key-value typed properties associated with the Equipment

deleted
boolean

Boolean flag indicating if the Equipment is deleted

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
  • "name": "Gas Meter",
  • "externalId": "3758ef98-0788524e",
  • "class": {
    },
  • "tags": [
    ],
  • "refs": {
    },
  • "types": [
    ],
  • "virtualMeterRefs": null,
  • "props": {
    },
  • "deleted": false
}

Retrieve Equipment with advanced search

Retrieve Equipment using advanced search queries. See the documentation for more information about how to use advanced search.

Examples:

Find an Equipment by its ID:

id == "3cecf04f-0101-4f36-a3ff-d4822fa72f5b"

Find all VAVs belonging to a particular AHU:

tags.vav AND refs.ahu == "3cecf04f-0101-4f36-a3ff-d4822fa72f5b"

Find all solar meters:

tags.meter AND (props.totalMeterType == "SOLAR" OR props.submeterType == "SOLAR")

Find all Equipment belonging to a particular Site:

site.name == "222 Smith St"

Find all Equipment belonging to certain Groups:

group.name == "Level 1" OR group.name == "Level 2"
Authorizations:
Bearer authentication
query Parameters
organisationId
required
string <uuid>
Example: organisationId=9f1748db-ea2b-4e9a-b035-e5757d7e97c7

Unique identifier of an Organisation

expr
string
Default: ""
Example: expr=name == "AHU"

Expression to search Equipment with

limit
number
Default: 5000
Example: limit=50

Result set size limit

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Equipment

name
string

Name of the Equipment

externalId
string
Default: null

Alternative unique identifier

object (EquipmentClass)

Equipment Class details

tags
Array of strings

Strings applied to the Equipment to add context and used for analytics

refs
object
Default: {}

Upstream references for the Equipment

Array of objects (EquipmentType)

Equipment types that the Equipment belongs to e.g. ahu, chiller

object (VirtualMeterRefs)

Contains the submeter references used to build a virtual meter

props
object
Default: {}

Additional key-value typed properties associated with the Equipment

deleted
boolean

Boolean flag indicating if the Equipment is deleted

Response samples

Content type
application/json
[
  • {
    }
]

Delete Equipment

Deletes a single Equipment entity by its ID.

Authorizations:
Bearer authentication
path Parameters
equipId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Equipment

Responses

Retrieve Equipment by ID

Retrieves a single Equipment entity by its ID.

Authorizations:
Bearer authentication
path Parameters
equipId
required
string <uuid>
Example: 0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d

Unique identifier of the Equipment

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Equipment

name
string

Name of the Equipment

externalId
string
Default: null

Alternative unique identifier

object (EquipmentClass)

Equipment Class details

tags
Array of strings

Strings applied to the Equipment to add context and used for analytics

refs
object
Default: {}

Upstream references for the Equipment

Array of objects (EquipmentType)

Equipment types that the Equipment belongs to e.g. ahu, chiller

object (VirtualMeterRefs)

Contains the submeter references used to build a virtual meter

props
object
Default: {}

Additional key-value typed properties associated with the Equipment

deleted
boolean

Boolean flag indicating if the Equipment is deleted

Response samples

Content type
application/json
{
  • "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
  • "name": "Gas Meter",
  • "externalId": "3758ef98-0788524e",
  • "class": {
    },
  • "tags": [
    ],
  • "refs": {
    },
  • "types": [
    ],
  • "virtualMeterRefs": null,
  • "props": {
    },
  • "deleted": false
}

Retrieve Equipment by Group ID

Retrieves a list of Equipment entities belonging to a Group.

Authorizations:
Bearer authentication
path Parameters
equipGroupId
required
string <uuid>
Example: 38d77506-9c7a-447e-9153-b9ce23b7ceb6

Unique identifier of the Group

query Parameters
includeDeleted
boolean
Default: false
Example: includeDeleted=false

Include deleted Equipment in the response

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Equipment

name
string

Name of the Equipment

externalId
string
Default: null

Alternative unique identifier

object (EquipmentClass)

Equipment Class details

tags
Array of strings

Strings applied to the Equipment to add context and used for analytics

refs
object
Default: {}

Upstream references for the Equipment

Array of objects (EquipmentType)

Equipment types that the Equipment belongs to e.g. ahu, chiller

object (VirtualMeterRefs)

Contains the submeter references used to build a virtual meter

props
object
Default: {}

Additional key-value typed properties associated with the Equipment

deleted
boolean

Boolean flag indicating if the Equipment is deleted

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Equipment by Site ID

Retrieves a list of Equipment entities belonging to a specific Site.

Authorizations:
Bearer authentication
path Parameters
siteId
required
string <uuid>
Example: 8a7869df-6cad-4642-a015-9fbb36d3b337

Unique identifier of the Site

query Parameters
includeDeleted
boolean
Default: false
Example: includeDeleted=false

Include deleted Equipment in the response

equipGroupId
string <uuid>
Default: null
Example: equipGroupId=f11b46d2-f569-41a3-b0f2-5f95edc0bf94

Unique identifier of a Group

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Equipment

name
string

Name of the Equipment

externalId
string
Default: null

Alternative unique identifier

object (EquipmentClass)

Equipment Class details

tags
Array of strings

Strings applied to the Equipment to add context and used for analytics

refs
object
Default: {}

Upstream references for the Equipment

Array of objects (EquipmentType)

Equipment types that the Equipment belongs to e.g. ahu, chiller

object (VirtualMeterRefs)

Contains the submeter references used to build a virtual meter

props
object
Default: {}

Additional key-value typed properties associated with the Equipment

deleted
boolean

Boolean flag indicating if the Equipment is deleted

Response samples

Content type
application/json
[
  • {
    }
]

Import Equipment

The import feature provides a way to create and update Equipment in bulk within an Organisation (across multiple Sites and Integrations). This includes:

  • Creating Equipment and Groups
  • Updating the properties of existing Equipment, including moving Equipment to a new Group

For detailed documentation on this feature, please contact API support.

Authorizations:
Bearer authentication
Request Body schema: text/csv
Schema not provided

Responses

Response Schema: application/json
sites
Array of arrays

Equipment import stats broken down by site

validation
json

Validation data from the import including any errors

Response samples

Content type
application/json
{
  • "sites": [
    ],
  • "validation": {
    }
}

Export Equipment

The export feature provides a way to export a CSV of Equipment for one or more Sites. The CSV is formatted in a way that it can be directly used in the Equipment import, making it easy to bulk update Equipment.

Authorizations:
Bearer authentication
query Parameters
siteIds
required
Array of strings <uuid>
Example: siteIds=8a7869df-6cad-4642-a015-9fbb36d3b337

List of unique identifiers of the Sites to export Points for

Responses

Response Schema: text/csv
string

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "Failed to convert value of type 'java.lang.String' to required type 'java.util.UUID'; nested exception is java.lang.IllegalArgumentException: Invalid UUID string: invalid"
}

Duplicate Equipment

Duplicates an existing Equipment entity, resulting in a new Equipment entity with the same properties (excluding its id, which must be different, and name, which can be optionally set).

Authorizations:
Bearer authentication
path Parameters
equipId
required
string <uuid>
Example: 110e9ea8-d8e9-4270-a084-92c064d528da

Unique identifier of the Equipment

Request Body schema: application/json
name
string
Default: null

Name of the new duplicated Equipment. If not provided, the name will be the same as the original Equipment with a (copy) suffix appended.

duplicatePoints
boolean
Default: true

Boolean flag indicating if the original Equipment's Points should be duplicated.

duplicateDataStreamMappings
boolean
Default: true

Boolean flag indicating if the original Point's Data Stream Mappings should be duplicated. (Irrelevant if duplicatePoints is false.)

groupId
string <uuid>
Default: null

Unique identifier of the Group the duplicated Equipment will belong to. If not provided, the duplicated Equipment will belong to the same Group as the original Equipment.

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Equipment

name
string

Name of the Equipment

externalId
string
Default: null

Alternative unique identifier

object (EquipmentClass)

Equipment Class details

tags
Array of strings

Strings applied to the Equipment to add context and used for analytics

refs
object
Default: {}

Upstream references for the Equipment

Array of objects (EquipmentType)

Equipment types that the Equipment belongs to e.g. ahu, chiller

object (VirtualMeterRefs)

Contains the submeter references used to build a virtual meter

props
object
Default: {}

Additional key-value typed properties associated with the Equipment

deleted
boolean

Boolean flag indicating if the Equipment is deleted

Request samples

Content type
application/json
{
  • "name": "Gas Meter",
  • "duplicatePoints": false,
  • "duplicateDataStreamMappings": false,
  • "groupId": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}

Response samples

Content type
application/json
{
  • "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
  • "name": "Gas Meter",
  • "externalId": "3758ef98-0788524e",
  • "class": {
    },
  • "tags": [
    ],
  • "refs": {
    },
  • "types": [
    ],
  • "virtualMeterRefs": null,
  • "props": {
    },
  • "deleted": false
}

Points

A Point entity refers to a data point in a building such as a sensor or a set point. A Point always belongs to an Equipment and as with Equipment, the properties of Points and their relationships to other entities are characterised by tags, props, and refs. Also like Equipment, Points can have a Class defining its function within the data model.

Points have a relationship with Histories, and as such they also have type and unit properties to describe what these Histories are (numeric, boolean, or multistate) and whether they have a specific Unit.

Create Point

Creates a new Point entity. The Equipment ID must be included in the Point's refs.

Authorizations:
Bearer authentication
Request Body schema: application/json
name
required
string

Name of the Point

type
required
string
Enum: "boolean" "number" "multistate - string" "multistate - numeric"

Type of the Point

object (CreateLegacyUnit)
Default: null
tags
Array of strings
Default: []

Strings applied to the Point to add context and used for analytics

props
object
Default: {}

Additional key-value typed properties associated with the Point

refs
required
object
Default: {}

Upstream references for the Point

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Point

name
string

Name of the Point

type
string
Enum: "boolean" "number" "multistate - string" "multistate - numeric"

Type of the Point

externalId
string
Default: null

Alternative unique identifier

object (PointClass)

Point Class details

tags
Array of strings

Strings applied to the Point to add context and used for analytics

props
object
Default: {}

Additional key-value typed properties associated with the Point

object (LegacyUnit)
defaultHistoryRollup
string
Default: "avg"

Default formula used when aggregating Histories for the Point

deleted
boolean

Boolean flag indicating if the Point is deleted

refs
object
Default: {}

Upstream references for the Point

enumValues
object
Default: {}

The enumerated values of a Point's History, only present if the Point type is string

Request samples

Content type
application/json
{
  • "name": "SUCTION_PRES",
  • "type": "number",
  • "unit": {
    },
  • "tags": [
    ],
  • "props": {
    },
  • "refs": {
    }
}

Response samples

Content type
application/json
{
  • "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
  • "name": "SUCTION_PRES",
  • "type": "number",
  • "externalId": "227556dc-0788524e",
  • "class": {
    },
  • "tags": [
    ],
  • "props": {
    },
  • "unit": {
    },
  • "defaultHistoryRollup": "avg",
  • "deleted": false,
  • "refs": {
    },
  • "enumValues": {
    }
}

Update Point

Updates a list of Point entities.

Authorizations:
Bearer authentication
Request Body schema: application/json
Array
id
required
string <uuid>

Unique identifier of the Point

name
required
string

Name of the Point

type
required
string
Enum: "boolean" "number" "multistate - string" "multistate - numeric"

Type of the Point

tags
Array of strings
Default: []

Strings applied to the Point to add context and used for analytics

props
object
Default: {}

Additional key-value typed properties associated with the Point

object (LegacyUnit)
deleted
boolean
Default: false

Boolean flag indicating if the Point is deleted

refs
required
object

Upstream references for the Point

enumValues
object
Default: {}

The enumerated values of a Point's History, only present if the Point type is string

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Point

name
string

Name of the Point

type
string
Enum: "boolean" "number" "multistate - string" "multistate - numeric"

Type of the Point

externalId
string
Default: null

Alternative unique identifier

object (PointClass)

Point Class details

tags
Array of strings

Strings applied to the Point to add context and used for analytics

props
object
Default: {}

Additional key-value typed properties associated with the Point

object (LegacyUnit)
defaultHistoryRollup
string
Default: "avg"

Default formula used when aggregating Histories for the Point

deleted
boolean

Boolean flag indicating if the Point is deleted

refs
object
Default: {}

Upstream references for the Point

enumValues
object
Default: {}

The enumerated values of a Point's History, only present if the Point type is string

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Points with advanced search

Retrieve Points using advanced search queries. See the documentation for more information on how to use advanced search.

Examples:

Find a Point by its ID:

id == "3cecf04f-0101-4f36-a3ff-d4822fa72f5b"

Find a Point by its name:

name == "Zone Temp Sensor"

Find all outside temperature sensors at a particular Site:

tags.outside AND tags.temp AND tags.sensor AND site.name == "222 Smith St"

Find all boolean Points without a hisMode prop:

type == "boolean" AND NOT props.hisMode

Find all Points tagged with temp but without a degrees celsius unit:

tags.temp AND NOT unit == "degree_celsius"

Find all Points belonging to a particular Equipment:

equip.id == "3cecf04f-0101-4f36-a3ff-d4822fa72f5b"

Find all CHWV Points on Equipment referenced to a particular chilled water loop:

tags.cool AND tags.cmd AND equip.refs.chilledLoop == "3cecf04f-0101-4f36-a3ff-d4822fa72f5b"
Authorizations:
Bearer authentication
query Parameters
organisationId
required
string <uuid>
Example: organisationId=9f1748db-ea2b-4e9a-b035-e5757d7e97c7

Unique identifier of an Organisation

expr
string
Default: ""
Example: expr=name == "Zone Temp Sensor"

Expression to search Points with

limit
number
Default: 5000
Example: limit=50

Result set size limit

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Point

name
string

Name of the Point

type
string
Enum: "boolean" "number" "multistate - string" "multistate - numeric"

Type of the Point

externalId
string
Default: null

Alternative unique identifier

object (PointClass)

Point Class details

tags
Array of strings

Strings applied to the Point to add context and used for analytics

props
object
Default: {}

Additional key-value typed properties associated with the Point

object (LegacyUnit)
defaultHistoryRollup
string
Default: "avg"

Default formula used when aggregating Histories for the Point

deleted
boolean

Boolean flag indicating if the Point is deleted

refs
object
Default: {}

Upstream references for the Point

enumValues
object
Default: {}

The enumerated values of a Point's History, only present if the Point type is string

Response samples

Content type
application/json
[
  • {
    }
]

Delete Point

Deletes a single Point entity by its ID.

Authorizations:
Bearer authentication
path Parameters
pointId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Point

Responses

Retrieve Point by ID

Retrieves a single Point entity by its ID.

Authorizations:
Bearer authentication
path Parameters
pointId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Point

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Point

name
string

Name of the Point

type
string
Enum: "boolean" "number" "multistate - string" "multistate - numeric"

Type of the Point

externalId
string
Default: null

Alternative unique identifier

object (PointClass)

Point Class details

tags
Array of strings

Strings applied to the Point to add context and used for analytics

props
object
Default: {}

Additional key-value typed properties associated with the Point

object (LegacyUnit)
defaultHistoryRollup
string
Default: "avg"

Default formula used when aggregating Histories for the Point

deleted
boolean

Boolean flag indicating if the Point is deleted

refs
object
Default: {}

Upstream references for the Point

enumValues
object
Default: {}

The enumerated values of a Point's History, only present if the Point type is string

Response samples

Content type
application/json
{
  • "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
  • "name": "SUCTION_PRES",
  • "type": "number",
  • "externalId": "227556dc-0788524e",
  • "class": {
    },
  • "tags": [
    ],
  • "props": {
    },
  • "unit": {
    },
  • "defaultHistoryRollup": "avg",
  • "deleted": false,
  • "refs": {
    },
  • "enumValues": {
    }
}

Retrieve Points by Equipment ID

Retrieves a list of Point entities belonging to a specific Equipment.

Authorizations:
Bearer authentication
path Parameters
equipId
required
string <uuid>
Example: 0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d

Unique identifier of the Equipment

query Parameters
includeDeleted
boolean
Default: false
Example: includeDeleted=false

Include deleted Points in the response

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Point

name
string

Name of the Point

type
string
Enum: "boolean" "number" "multistate - string" "multistate - numeric"

Type of the Point

externalId
string
Default: null

Alternative unique identifier

object (PointClass)

Point Class details

tags
Array of strings

Strings applied to the Point to add context and used for analytics

props
object
Default: {}

Additional key-value typed properties associated with the Point

object (LegacyUnit)
defaultHistoryRollup
string
Default: "avg"

Default formula used when aggregating Histories for the Point

deleted
boolean

Boolean flag indicating if the Point is deleted

refs
object
Default: {}

Upstream references for the Point

enumValues
object
Default: {}

The enumerated values of a Point's History, only present if the Point type is string

Response samples

Content type
application/json
[
  • {
    }
]

Import Points

The import feature provides a way to create and update Points in bulk within an Organisation (across multiple Sites and Integrations). This includes:

  • Creating Points, Equipment and Groups
  • Creating Data Streams and Point Data Stream Mappings
  • Updating the properties of existing Points, including moving Points to a new Equipment

For detailed documentation on this feature, please contact API support.

Authorizations:
Bearer authentication
Request Body schema: text/csv
Schema not provided

Responses

Response Schema: application/json
sites
Array of arrays

Point import stats broken down by site

validation
json

Validation data from the import including any errors

Response samples

Content type
application/json
{
  • "sites": [
    ],
  • "validation": {
    }
}

Export Points

The export feature provides a way to export a CSV of Points for one or more Sites. The CSV is formatted in a way that it can be directly used in the Points import, making it easy to bulk update Points.

Authorizations:
Bearer authentication
query Parameters
siteIds
required
Array of strings <uuid>
Example: siteIds=8a7869df-6cad-4642-a015-9fbb36d3b337

List of unique identifiers of the Sites to export Points for

includeDataStreamMappings
boolean
Default: false
Example: includeDataStreamMappings=true

Boolean parameter to determine whether the Point Data Stream Mappings will be included in the CSV export

Responses

Response Schema: text/csv
string

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "Failed to convert value of type 'java.lang.String' to required type 'java.util.UUID'; nested exception is java.lang.IllegalArgumentException: Invalid UUID string: invalid"
}

Retrieve raw Histories by Point ID

Retrieves a list of raw Histories for a Point for a given time period.

Units: By default the histories are returned in the original (RAW) unit however can be converted to a standardised unit by passing in STANDARD to the convertTo field. The standard unit for example will convert all Histories with a Unit of type pressure to kPa.

LOCF: It may be desirable to include in the response, the value of the last observation (history) directly before the requested time range, carried forward to the start of that time range. (E.g if histories from 6am to 7am were requested, the history at 5:55am would be carried forward to 6am and included in the response.) This can be useful for change of value (COV) points where that last observation is assumed to be valid up until a new one is received. By default this last observation carried forward (LOCF) is not included but it can be added by passing in INCLUDE_LOCF to the lastObservation field. Please note that the last observation will only be carried forward to the start of the requested time range if an observation (history) does not already exist at the start of that time range.

Authorizations:
Bearer authentication
path Parameters
pointId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Point

query Parameters
from
required
string <date-time>
Example: from=2022-10-08T04:23:00.000Z

Start timestamp of the duration for which the Point Histories are requested

to
required
string <date-time>
Example: to=2022-10-12T04:23:00.000Z

End timestamp of the duration for which the Point Histories are requested

lastObservation
string
Default: "EXCLUDE"
Enum: "INCLUDE_LOCF" "EXCLUDE"
Example: lastObservation=INCLUDE_LOCF

Include the last observation carried forward (INCLUDE_LOCF) or only return the histories within the requested time range (EXCLUDE)

convertTo
string
Enum: "RAW" "STANDARD"
Example: convertTo=RAW

Convert Point Histories to either their original (RAW) or standardised (STANDARD) unit

Responses

Response Schema: application/json
Array
ts
string <date-time>

Timestamp of the History object

val
number

Value of the History object

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve sub-daily aggregated Histories by Point ID

Retrieves aggregated histories for a specific Point, time period and aggregation interval which must be less than daily (sub-daily).

Authorizations:
Bearer authentication
path Parameters
pointId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Point

query Parameters
from
required
string <date-time>
Example: from=2022-10-08T04:23:00.000Z

Start timestamp of the duration for which the Point Histories are requested

to
required
string <date-time>
Example: to=2022-10-12T04:23:00.000Z

End timestamp of the duration for which the Point Histories are requested

type
required
string
Enum: "FIVE_MINUTE" "QUARTER_HOURLY" "HALF_HOURLY" "HOURLY"
Example: type=FIVE_MINUTE

The interval to which the histories are aggregated to e.g. an interval of HOURLY will rollup all timestamps into a single timestamp per hour on the hour

Responses

Response Schema: application/json
Array
ts
string <date-time>

Start timestamp of the History aggregate

avg
number
Default: null

Average value in the period starting at the ts (inclusive) till the ts of the next History (exclusive)

sum
number
Default: null

Sum of the values in the period starting at the ts (inclusive) till the ts of the next History (exclusive)

min
number
Default: null

Minimum value in the period starting at the ts (inclusive) till the ts of the next History (exclusive)

max
number
Default: null

Maximum value in the period starting at the ts (inclusive) till the ts of the next History (exclusive)

count
integer <int16>
Default: null

Count of values in the period starting at the ts (inclusive) till the ts of the next History (exclusive)

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve aggregated Point histories by Point ID

Retrieves aggregated histories for a specific Point, time period and aggregation interval of daily or higher.

Authorizations:
Bearer authentication
path Parameters
pointId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Point

query Parameters
from
required
string <date>
Default: null
Example: from=2022-10-08

Start date of the duration for which Point histories are requested

to
required
string <date>
Default: null
Example: to=2022-10-12

End date of the duration for which Point histories are requested

type
required
string
Enum: "DAILY" "MONTHLY" "QUARTERLY" "YEARLY"
Example: type=MONTHLY

Interval

Responses

Response Schema: application/json
Array
ts
string <date>

Start date of the History aggregate

avg
number
Default: null

Average value in the period starting at 00:00 on the ts (inclusive) till 00:00 on the ts of the next History (exclusive)

sum
number
Default: null

Sum of values in the period starting at 00:00 on the ts (inclusive) till 00:00 on the ts of the next History (exclusive)

min
number
Default: null

Minimum value in the period starting at 00:00 on the ts (inclusive) till 00:00 on the ts of the next History (exclusive)

max
number
Default: null

Maximum value in the period starting at 00:00 on the ts (inclusive) till 00:00 on the ts of the next History (exclusive)

count
integer <int16>
Default: null

Count of values in the period starting at 00:00 on the ts (inclusive) till 00:00 on the ts of the next History (exclusive)

Response samples

Content type
application/json
[
  • {
    }
]

Duplicate Point

Duplicates an existing Point entity, resulting in a new Point entity with the same properties (excluding its id, which must be different, and name, which can be optionally set).

Authorizations:
Bearer authentication
path Parameters
pointId
required
string <uuid>
Example: 110e9ea8-d8e9-4270-a084-92c064d528da

Unique identifier of the Point

Request Body schema: application/json
name
string
Default: null

Name of the new duplicated Point. If not provided, the name will be the same as the original Point with a (copy) suffix appended.

duplicateDataStreamMappings
boolean
Default: true

Boolean flag indicating if the original Point's Data Stream Mappings should be duplicated.

equipId
string <uuid>
Default: null

Unique identifier of the Equipment the duplicated Point will belong to. If not provided, the duplicated Point will belong to the same Equipment as the original Point.

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Point

name
string

Name of the Point

type
string
Enum: "boolean" "number" "multistate - string" "multistate - numeric"

Type of the Point

externalId
string
Default: null

Alternative unique identifier

object (PointClass)

Point Class details

tags
Array of strings

Strings applied to the Point to add context and used for analytics

props
object
Default: {}

Additional key-value typed properties associated with the Point

object (LegacyUnit)
defaultHistoryRollup
string
Default: "avg"

Default formula used when aggregating Histories for the Point

deleted
boolean

Boolean flag indicating if the Point is deleted

refs
object
Default: {}

Upstream references for the Point

enumValues
object
Default: {}

The enumerated values of a Point's History, only present if the Point type is string

Request samples

Content type
application/json
{
  • "name": "SUCTION_PRES",
  • "duplicateDataStreamMappings": false,
  • "equipId": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}

Response samples

Content type
application/json
{
  • "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
  • "name": "SUCTION_PRES",
  • "type": "number",
  • "externalId": "227556dc-0788524e",
  • "class": {
    },
  • "tags": [
    ],
  • "props": {
    },
  • "unit": {
    },
  • "defaultHistoryRollup": "avg",
  • "deleted": false,
  • "refs": {
    },
  • "enumValues": {
    }
}

Retrieve Legacy Point by ID Deprecated

Retrieves a single legacy Point entity by its ID. This endpoint has been replaced by /v3/points/{pointId} as it contains the legacy field etlId.

Authorizations:
Bearer authentication
path Parameters
pointId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Point

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Point

name
string

Name of the Point

type
string
Enum: "boolean" "number" "multistate - string" "multistate - numeric"

Type of the Point

externalId
string
Default: null

Alternative unique identifier

etlId
string
Default: null

ETL ID used to extract, transform and load historic data for the Point

tags
Array of strings

Strings applied to the Point to add context and used for analytics

props
object
Default: {}

Additional key-value typed properties associated with the Point

object (LegacyUnit)
defaultHistoryRollup
string
Default: "avg"

Default formula used when aggregating Histories for the Point

deleted
boolean

Boolean flag indicating if the Point is deleted

refs
object
Default: {}

Upstream references for the Point

enumValues
object
Default: {}

The enumerated values of a Point's History, only present if the Point type is string

Response samples

Content type
application/json
{
  • "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
  • "name": "SUCTION_PRES",
  • "type": "number",
  • "externalId": "227556dc-0788524e",
  • "etlId": "VICTarneit3029~R2MT$7cR2_MT_404A$2da2$7cSUCTION_PRES",
  • "tags": [
    ],
  • "props": {
    },
  • "unit": {
    },
  • "defaultHistoryRollup": "avg",
  • "deleted": false,
  • "refs": {
    },
  • "enumValues": {
    }
}

Retrieve Legacy Points by Equipment ID Deprecated

Retrieves a list of legacy Point entities belonging to a specific Equipment. This endpoint has been replaced by /v3/equips/{equipId}/points as it returns a list of legacy Points entities which contains the legacy field etlId.

Authorizations:
Bearer authentication
path Parameters
equipId
required
string <uuid>
Example: 0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d

Unique identifier of the Equipment

query Parameters
includeDeleted
boolean
Default: false
Example: includeDeleted=false

Include deleted Points in the response

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Point

name
string

Name of the Point

type
string
Enum: "boolean" "number" "multistate - string" "multistate - numeric"

Type of the Point

externalId
string
Default: null

Alternative unique identifier

etlId
string
Default: null

ETL ID used to extract, transform and load historic data for the Point

tags
Array of strings

Strings applied to the Point to add context and used for analytics

props
object
Default: {}

Additional key-value typed properties associated with the Point

object (LegacyUnit)
defaultHistoryRollup
string
Default: "avg"

Default formula used when aggregating Histories for the Point

deleted
boolean

Boolean flag indicating if the Point is deleted

refs
object
Default: {}

Upstream references for the Point

enumValues
object
Default: {}

The enumerated values of a Point's History, only present if the Point type is string

Response samples

Content type
application/json
[
  • {
    }
]

Integrations

An Integration represents a connection to a source of multiple Data Streams, typically from a single device or data connection. There can be one or more Integrations per building, such as:

  • A Niagara Integration for a BMS
  • An MQTT Integration from an IoT sensor network
  • An ETL Integration from a vertical transport system

Create Integration

Creates a new Integration entity.

Authorizations:
Bearer authentication
Request Body schema: application/json
name
required
string

Name of the Integration

organisationId
required
string <uuid>

Unique identifier of the Organisation the Integration belongs to

timezone
required
string

Timezone of the Integration

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Integration

name
string

Name of the Integration

organisationId
string <uuid>

Unique identifier of the Organisation the Integration belongs to

timezone
string

Timezone of the Integration

Request samples

Content type
application/json
{
  • "name": "1 Sesame St BMS ",
  • "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
  • "timezone": "Australia/Melbourne"
}

Response samples

Content type
application/json
{
  • "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
  • "name": "1 Sesame St BMS",
  • "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
  • "timezone": "Australia/Melbourne"
}

Update Integration

Updates a single Integration entity.

Authorizations:
Bearer authentication
Request Body schema: application/json
id
string <uuid>

Unique identifier of the Integration

name
string

Name of the Integration

organisationId
string <uuid>

Unique identifier of the Organisation the Integration belongs to

timezone
string

Timezone of the Integration

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Integration

name
string

Name of the Integration

organisationId
string <uuid>

Unique identifier of the Organisation the Integration belongs to

timezone
string

Timezone of the Integration

Request samples

Content type
application/json
{
  • "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
  • "name": "1 Sesame St BMS",
  • "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
  • "timezone": "Australia/Melbourne"
}

Response samples

Content type
application/json
{
  • "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
  • "name": "1 Sesame St BMS",
  • "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
  • "timezone": "Australia/Melbourne"
}

Delete Integration

Deletes a single Integration entity by its ID.

Authorizations:
Bearer authentication
path Parameters
integrationId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Integration

Responses

Retrieve Integration by ID

Retrieves a single Integration entity by its ID.

Authorizations:
Bearer authentication
path Parameters
integrationId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Integration

Responses

Response Schema: application/json
id
string <uuid>

Unique identifier of the Integration

name
string

Name of the Integration

organisationId
string <uuid>

Unique identifier of the Organisation the Integration belongs to

timezone
string

Timezone of the Integration

Response samples

Content type
application/json
{
  • "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
  • "name": "1 Sesame St BMS",
  • "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
  • "timezone": "Australia/Melbourne"
}

Retrieve Integrations by Organisation ID

Retrieves a list of Integration entities belonging an Organisation.

Authorizations:
Bearer authentication
path Parameters
organisationId
required
string <uuid>
Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

Unique identifier of the Organisation

Responses

Response Schema: application/json
Array
id
string <uuid>

Unique identifier of the Integration

name
string

Name of the Integration

organisationId
string <uuid>

Unique identifier of the Organisation the Integration belongs to

timezone
string

Timezone of the Integration

Response samples

Content type
application/json
[
  • {
    }
]

Data Streams

Data Streams represent a single source of data i.e. they have time series history attached to them. Data Streams belong to an Integration, logically grouped with other Data Streams based on some common characteristic (typically, Data Streams from the same Integration represent data sourced from a single device or connection).

The Data Stream entity contains:

  • type describes the type of history either NUMBER or STRING
  • status defines if data is being ingested for this Data Stream, either ENABLED or DISABLED
  • metadata a free json field to store any extra information for the data stream, for example the unit

    • Create Data Stream

    Creates a new Data Stream entity.

    Authorizations:
    Bearer authentication
    Request Body schema: application/json
    integrationId
    required
    string <uuid>

    Unique identifier of the Integration

    streamId
    required
    string

    Identifier of the Data Stream (unique within the Organisation)

    status
    required
    string
    Enum: "ENABLED" "DISABLED"

    Whether the Data Stream is enabled or disabled (no longer ingesting data)

    type
    required
    string
    Enum: "NUMBER" "STRING"

    The data type of the history

    metadata
    required
    json

    Json field to store any useful information, for example the unit

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier of the Data Stream

    integrationId
    string <uuid>

    Unique identifier of the Integration

    streamId
    string

    Identifier of the Data Stream (unique within the Organisation)

    status
    string
    Enum: "ENABLED" "DISABLED"

    Whether the Data Stream is enabled or disabled (no longer ingesting data)

    type
    string
    Enum: "NUMBER" "STRING"

    The data type of the history

    metadata
    json

    Json field to store any useful information, for example the unit

    createdAt
    string <date-time>

    Timestamp at which the Data Stream was created, or 0001-01-01T00:00:00Z if the created date is not available

    updatedAt
    string <date-time>

    Timestamp at which the Data Stream was updated, or 0001-01-01T00:00:00Z if the updated date is not available

    pointMappings
    Array of arrays
    Default: null

    List of Point Mappings associated to this Data Stream (optional)

    Request samples

    Content type
    application/json
    {
    • "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
    • "streamId": "MyConnection/Device301/Chiller-1/SAT",
    • "status": "ENABLED",
    • "type": "NUMBER",
    • "metadata": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
    • "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
    • "streamId": "MyConnection/Device301/Chiller-1/SAT",
    • "status": "ENABLED",
    • "type": "NUMBER",
    • "metadata": {
      },
    • "createdAt": "2022-10-08T12:00:00Z",
    • "updatedAt": "2022-10-08T12:00:00Z",
    • "pointMappings": null
    }

    Update Data Stream

    Updates a single Data Stream entity.

    Authorizations:
    Bearer authentication
    Request Body schema: application/json
    id
    required
    string <uuid>

    Unique identifier of the Data Stream

    integrationId
    required
    string <uuid>

    Unique identifier of the Integration

    streamId
    required
    string

    Identifier of the Data Stream (unique within the Organisation)

    status
    required
    string
    Enum: "ENABLED" "DISABLED"

    Whether the Data Stream is enabled or disabled (no longer ingesting data)

    type
    required
    string
    Enum: "NUMBER" "STRING"

    The data type of the history

    metadata
    required
    json

    Json field to store any useful information, for example the unit

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier of the Data Stream

    integrationId
    string <uuid>

    Unique identifier of the Integration

    streamId
    string

    Identifier of the Data Stream (unique within the Organisation)

    status
    string
    Enum: "ENABLED" "DISABLED"

    Whether the Data Stream is enabled or disabled (no longer ingesting data)

    type
    string
    Enum: "NUMBER" "STRING"

    The data type of the history

    metadata
    json

    Json field to store any useful information, for example the unit

    createdAt
    string <date-time>

    Timestamp at which the Data Stream was created, or 0001-01-01T00:00:00Z if the created date is not available

    updatedAt
    string <date-time>

    Timestamp at which the Data Stream was updated, or 0001-01-01T00:00:00Z if the updated date is not available

    pointMappings
    Array of arrays
    Default: null

    List of Point Mappings associated to this Data Stream (optional)

    Request samples

    Content type
    application/json
    {
    • "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
    • "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
    • "streamId": "MyConnection/Device301/Chiller-1/SAT",
    • "status": "ENABLED",
    • "type": "NUMBER",
    • "metadata": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
    • "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
    • "streamId": "MyConnection/Device301/Chiller-1/SAT",
    • "status": "ENABLED",
    • "type": "NUMBER",
    • "metadata": {
      },
    • "createdAt": "2022-10-08T12:00:00Z",
    • "updatedAt": "2022-10-08T12:00:00Z",
    • "pointMappings": null
    }

    Retrieve Data Stream by ID

    Retrieves a single Data Stream entity by its ID.

    Authorizations:
    Bearer authentication
    path Parameters
    dataStreamId
    required
    string <uuid>
    Example: 07fab9a6-d330-4efc-a198-192cbfd93eb9

    Unique identifier of the Data Stream

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier of the Data Stream

    integrationId
    string <uuid>

    Unique identifier of the Integration

    streamId
    string

    Identifier of the Data Stream (unique within the Organisation)

    status
    string
    Enum: "ENABLED" "DISABLED"

    Whether the Data Stream is enabled or disabled (no longer ingesting data)

    type
    string
    Enum: "NUMBER" "STRING"

    The data type of the history

    metadata
    json

    Json field to store any useful information, for example the unit

    createdAt
    string <date-time>

    Timestamp at which the Data Stream was created, or 0001-01-01T00:00:00Z if the created date is not available

    updatedAt
    string <date-time>

    Timestamp at which the Data Stream was updated, or 0001-01-01T00:00:00Z if the updated date is not available

    pointMappings
    Array of arrays
    Default: null

    List of Point Mappings associated to this Data Stream (optional)

    Response samples

    Content type
    application/json
    {
    • "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
    • "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
    • "streamId": "MyConnection/Device301/Chiller-1/SAT",
    • "status": "ENABLED",
    • "type": "NUMBER",
    • "metadata": {
      },
    • "createdAt": "2022-10-08T12:00:00Z",
    • "updatedAt": "2022-10-08T12:00:00Z",
    • "pointMappings": null
    }

    Delete Data Stream

    Deletes a single Data Stream entity.

    Authorizations:
    Bearer authentication
    path Parameters
    dataStreamId
    required
    string <uuid>
    Example: 07fab9a6-d330-4efc-a198-192cbfd93eb9

    Unique identifier of the Data Stream

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Bad Request",
    • "message": "Failed to convert value of type 'java.lang.String' to required type 'java.util.UUID'; nested exception is java.lang.IllegalArgumentException: Invalid UUID string: invalid"
    }

    Retrieve Data Streams by Integration ID

    Retrieves a list of Data Stream entities belonging to an Integration.

    Authorizations:
    Bearer authentication
    path Parameters
    integrationId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Integration

    query Parameters
    sortBy
    string
    Enum: "STREAM_ID" "STATUS" "TYPE" "POINT_MAPPINGS_COUNT" "CREATED_AT" "UPDATED_AT"
    Example: sortBy=STREAM_ID

    Property to sort the results by

    sortDir
    string
    Enum: "ASC" "DESC"
    Example: sortDir=ASC

    Direction to sort the results by

    streamId
    string
    Example: streamId=/Chiller-1

    Used to filter the Data Streams on the streamId field (only exact matches are returned)

    streamIdRegex
    string
    Example: streamIdRegex=.*Chiller-[0-9]+

    Used to filter the Data Streams on the streamId field, (regex matches with any part of the streamId are returned)

    limit
    number
    Example: limit=500

    Maximum number data streams to retrieve, when left unset, all Data Streams will be returned

    offset
    number
    Example: offset=100

    Offset to begin returning Data Streams from, to be used along with limit to paginate results

    includePointMappings
    boolean
    Example: includePointMappings=true

    When set to true, Point Mappings associated to each Data Stream will also be included in the response

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier of the Data Stream

    integrationId
    string <uuid>

    Unique identifier of the Integration

    streamId
    string

    Identifier of the Data Stream (unique within the Organisation)

    status
    string
    Enum: "ENABLED" "DISABLED"

    Whether the Data Stream is enabled or disabled (no longer ingesting data)

    type
    string
    Enum: "NUMBER" "STRING"

    The data type of the history

    metadata
    json

    Json field to store any useful information, for example the unit

    createdAt
    string <date-time>

    Timestamp at which the Data Stream was created, or 0001-01-01T00:00:00Z if the created date is not available

    updatedAt
    string <date-time>

    Timestamp at which the Data Stream was updated, or 0001-01-01T00:00:00Z if the updated date is not available

    pointMappings
    Array of arrays
    Default: null

    List of Point Mappings associated to this Data Stream (optional)

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Export Data Streams by Integration ID

    Exports a list of Data Stream entities belonging an Integration.

    Authorizations:
    Bearer authentication
    path Parameters
    integrationId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Integration

    query Parameters
    sortBy
    string
    Enum: "STREAM_ID" "STATUS" "TYPE" "POINT_MAPPINGS_COUNT" "CREATED_AT" "UPDATED_AT"
    Example: sortBy=STREAM_ID

    Property to sort the results by

    sortDir
    string
    Enum: "ASC" "DESC"
    Example: sortDir=ASC

    Direction to sort the results by

    streamId
    string
    Example: streamId=/Chiller-1

    Used to filter the Data Streams on the streamId field, (any case insensitive substring match will be returned)

    limit
    number
    Example: limit=500

    Maximum number data streams to retrieve, when left unset, all Data Streams will be returned

    offset
    number
    Example: offset=100

    Offset to begin returning Data Streams from, to be used along with limit to paginate results

    includePointMappings
    boolean
    Example: includePointMappings=true

    When set to true, Point Mappings associated to each Data Stream will also be included in the response

    Responses

    Response Schema: text/csv
    string

    Retrieve Data Streams by Integration ID (Legacy) Deprecated

    Retrieves a list of Data Stream entities belonging to an Integration.

    Authorizations:
    Bearer authentication
    path Parameters
    integrationId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Integration

    query Parameters
    sortBy
    string
    Enum: "STREAM_ID" "STATUS" "TYPE" "POINT_MAPPINGS_COUNT" "CREATED_AT" "UPDATED_AT"
    Example: sortBy=STREAM_ID

    Property to sort the results by

    sortDir
    string
    Enum: "ASC" "DESC"
    Example: sortDir=ASC

    Direction to sort the results by

    streamId
    string
    Example: streamId=/Chiller-1

    Used to filter the Data Streams on the streamId field, (any case insensitive substring match will be returned)

    limit
    number
    Example: limit=500

    Maximum number data streams to retrieve, when left unset, all Data Streams will be returned

    offset
    number
    Example: offset=100

    Offset to begin returning Data Streams from, to be used along with limit to paginate results

    includePointMappings
    boolean
    Example: includePointMappings=true

    When set to true, Point Mappings associated to each Data Stream will also be included in the response

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier of the Data Stream

    integrationId
    string <uuid>

    Unique identifier of the Integration

    streamId
    string

    Identifier of the Data Stream (unique within the Organisation)

    status
    string
    Enum: "ENABLED" "DISABLED"

    Whether the Data Stream is enabled or disabled (no longer ingesting data)

    type
    string
    Enum: "NUMBER" "STRING"

    The data type of the history

    metadata
    json

    Json field to store any useful information, for example the unit

    createdAt
    string <date-time>

    Timestamp at which the Data Stream was created, or 0001-01-01T00:00:00Z if the created date is not available

    updatedAt
    string <date-time>

    Timestamp at which the Data Stream was updated, or 0001-01-01T00:00:00Z if the updated date is not available

    pointMappings
    Array of arrays
    Default: null

    List of Point Mappings associated to this Data Stream (optional)

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Data Stream Mappings

    Data Stream Mappings link a Point to a Data Stream and, therefore, its history. The mapping specifies at what time this relationship starts, using the tsStart property. For a typical 1:1 Point to Data Stream Mapping this will likely be set to the default value of earliest available or "0001-01-01T00:00:00.000Z". This means the Point will be mapped to the Data Stream from its first timestamp until its latest.

    A Point can also be mapped to multiple Data Streams. In this case, the tsStart of the next mapping is also the end timestamp of the previous mapping.

    The last Data Stream Mapping has no end timestamp and so the Point is mapped to the Data Stream until its latest history, which is continuing to be updated.

    A Data Stream can be mapped to multiple Points, allowing them to share the same history.

    Create / Update / Delete Data Stream Mappings by Point ID

    Sets the Data Stream Mapping entities for a Point.

    Authorizations:
    Bearer authentication
    path Parameters
    pointId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Point

    Request Body schema: application/json
    Array
    required
    object (DataStreamForDataStreamMappingsRequest)

    Data Stream details required to uniquely identify it

    tsStart
    required
    string <date-time>

    Timestamp at which the Data Stream is associated to the Point. (If you wish to set this to the earliest available time, use the timestamp "0001-01-01T00:00:00.000Z")

    Responses

    Response Schema: application/json
    Array
    object (DataStream)

    Data Stream details

    tsStart
    string <date-time>

    Timestamp at which the Data Stream is associated to the Point

    Request samples

    Content type
    application/json
    [
    • {
      }
    ]

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Data Stream Mappings by Point ID

    Retrieves a list of Data Stream Mapping entities for a Point.

    Authorizations:
    Bearer authentication
    path Parameters
    pointId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Point

    Responses

    Response Schema: application/json
    Array
    object (DataStream)

    Data Stream details

    tsStart
    string <date-time>

    Timestamp at which the Data Stream is associated to the Point

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Ingestion

    Historical data can be ingested for Data Streams belonging to an Integration. The request includes: the data to ingest - a map of local timestamps to a list of Histories and a single timezone that is specified for the whole request. Each History item contains the streamId of the relevant Data Stream and val, the value being written to that Data Stream for that timestamp. The historical data is then processed in a queue based system.

    Ingest history for an Integration

    Writes history to Data Streams belonging to an Integration.

    Authorizations:
    Bearer authentication
    Request Body schema: application/json
    required
    object

    A map of ISO 8601 formatted local timestamp keys to a list of ingestion History objects. The zone should not be included in the timestamp as it will be taken from the timezone specified in the request or the Integration's default

    tz
    string

    An optional timezone database name, when not provided the Integration's default will be used

    source
    string

    An optional custom label that will show up in logs, can be used to debug when there are any issues with messages

    Responses

    Request samples

    Content type
    application/json
    {
    • "data": {
      },
    • "tz": "Australia/Sydney",
    • "source": "My first ingestion"
    }

    Response samples

    Content type
    application/json
    {
    • "error": "Bad Request",
    • "message": "JSON parse error: Instantiation of value failed for JSON property name due to missing (therefore NULL) value for creator parameter name which is a non-nullable type"
    }

    Actions

    An Action entity represents a real world task or job. Actions are typically focused on optimising the operation of, or rectifying problems identified in, the built environment at a particular Site.

    The Action entity contains:

    • Information about what the Action is and its current status
    • Information about who is responsible for this Action
    • Links, Attachments, Savings and Target Rules related to the Action
    Additionally, it is possible to retrieve Comments for an Action.

    Retrieve Actions by Organisation ID and Optional Filters

    Retrieves a list of Actions belonging to an Organisation, optionally filtered by the specified parameters.

    Authorizations:
    Bearer authentication
    path Parameters
    organisationId
    required
    string <uuid>
    Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7

    Unique identifier of an Organisation

    query Parameters
    ids
    Array of integers <int64> [ items <int64 > ]
    Default: null
    Example: ids=1234

    Numeric identifier of an Action

    siteIds
    Array of strings <uuid>
    Default: null
    Example: siteIds=8a7869df-6cad-4642-a015-9fbb36d3b337

    List of unique Site Ids the Actions pertain to

    statusIds
    Array of integers <uuid> [ items <uuid > ]
    Default: null
    Example: statusIds=2f4da57d-0c81-4087-bc23-caeb773e26f8

    List of unique Status Ids the Actions have

    updatedBefore
    string <date-time>
    Example: updatedBefore=2021-10-08T12:00:00Z

    Latest timestamp at which the Actions were last updated

    updatedAfter
    string <date-time>
    Example: updatedAfter=2021-10-08T12:00:00Z

    Earliest timestamp at which the Actions were last updated

    createdBefore
    string <date-time>
    Example: createdBefore=2021-10-08T12:00:00Z

    Latest timestamp at which the Actions were created

    createdAfter
    string <date-time>
    Example: createdAfter=2021-10-08T12:00:00Z

    Earliest timestamp at which the Actions were created

    closedBefore
    string <date-time>
    Example: closedBefore=2021-10-08T12:00:00Z

    Latest timestamp at which the Actions were closed

    closedAfter
    string <date-time>
    Example: closedAfter=2021-10-08T12:00:00Z

    Earliest timestamp at which the Actions were closed

    Responses

    Response Schema: application/json
    Array
    id
    integer <int64>

    Numeric identifier of the Action

    siteId
    string <uuid>

    Unique identifier of the Site to which Action belongs

    organisationId
    string <uuid>

    Unique identifier of the Organisation to which Action belongs

    summary
    string

    Summary of the Action

    description
    string

    Description of the Action

    object (Status)

    Status of the Action

    severity
    string
    Enum: "Blocker" "Critical" "Major" "Moderate" "Minor" "Trivial"

    Severity of the Action

    type
    string
    Enum: "Maintenance" "DLP" "Optimisation" "Other"

    Type of the Action

    object

    Team to which the Action is assigned

    object (User)

    Details of the User assigned to the Action

    object (User)

    Details of the user who created the Action

    createdAt
    string <date-time>

    Timestamp at which the Action was created

    object (User)

    Details of the user who last updated the Action

    updatedAt
    string <date-time>

    Timestamp at which the Action was last updated

    closedAt
    string <date-time>

    Timestamp at which the Action was closed

    Array of objects (Attachment)
    Array of objects (Link)
    Array of objects (TargetRule)
    Array of objects (Saving)

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Comments by Organisation ID and Action ID

    Retrieves a list of Comments belonging to an Action.

    Authorizations:
    Bearer authentication
    path Parameters
    organisationId
    required
    string <uuid>
    Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7

    Unique identifier of an Organisation

    actionId
    required
    integer <int64>
    Example: 1234

    Numeric identifier of an Action within an Organisation

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier of the Comment

    organisationId
    string <uuid>

    Unique identifier of the Organisation to which the Comment belongs

    actionId
    integer <int64>

    Numeric identifier of the Action to which the Comment belongs

    comment
    string

    Content of the Comment

    object (User)

    Details of the user who created the Comment

    createdAt
    string <date-time>

    Timestamp at which the Comment was created

    object (User)

    Details of the user who last updated the Comment

    updatedAt
    string <date-time>

    Timestamp at which the Comment was last updated

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Attachments by Organisation ID and Action ID

    Retrieves a list of Attachments belonging to an Action.

    Authorizations:
    Bearer authentication
    path Parameters
    organisationId
    required
    string <uuid>
    Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7

    Unique identifier of an Organisation

    actionId
    required
    integer <int64>
    Example: 1234

    Numeric identifier of an Action within an Organisation

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier of the Attachment

    name
    string

    Name of the Attachment

    actionId
    integer <int64>

    Numeric identifier of the Action

    organisationId
    string <uuid>

    Unique identifier of the Organisation to which the Attachment belongs

    commentId
    string <uuid>
    Default: null

    Unique identifier of the Comment to which the Attachment belongs

    object (User)

    Details of the user who created the Attachment

    createdAt
    string <date-time>

    Timestamp at which the Attachment was created

    object (User)

    Details of the user who last updated the Attachment

    updatedAt
    string <date-time>

    Timestamp at which the Attachment was last updated

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Activity Logs by Organisation ID and Action ID

    Retrieves a list of Activity Logs belonging to an Action. Activity log entries are generated when an Action is updated, and contain information about the type of change and the user who made the change.

    Authorizations:
    Bearer authentication
    path Parameters
    organisationId
    required
    string <uuid>
    Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7

    Unique identifier of an Organisation

    actionId
    required
    integer <int64>
    Example: 1234

    Numeric identifier of an Action within an Organisation

    Responses

    Response Schema: application/json
    Array
    id
    integer <int32>

    Numeric identifier of the Activity Log

    actionId
    integer <int32>

    Numeric identifier of the associated Action

    organisationId
    string <uuid>

    Unique identifier of the Organisation to which the Activity Log belongs

    type
    string

    The type of change that this Activity Log entry represents. This can be one of the following values: 'STATUS', 'SUMMARY', 'DESCRIPTION', 'SEVERITY', 'ASSIGNEE', 'COMMENT', 'LINK', 'ATTACHMENT', 'SAVING', 'TARGET_RULE', 'ORGANISATION', 'TEAM'

    oldValue
    string or null

    The old value of the field that was changed. Can be null if the field was previously not populated.

    newValue
    string or null

    The new value of the field that was changed. Can be null if the field is now empty.

    updatedAt
    string <date-time>

    Timestamp at which the Activity Log was generated

    object (User)

    Details of the user who performed the change

    commentId
    string or null <uuid>

    If the Activity Log type is 'COMMENT', this field will contain the unique identifier of the associated Comment

    linkId
    string or null <uuid>

    If the Activity Log type is 'LINK', this field will contain the unique identifier of the associated Link

    attachmentId
    string or null <uuid>

    If the Activity Log type is 'ATTACHMENT', this field will contain the unique identifier of the associated Attachment

    savingId
    string or null <uuid>

    If the Activity Log type is 'SAVING', this field will contain the unique identifier of the associated Saving

    targetRuleId
    string or null <uuid>

    If the Activity Log type is 'TARGET_RULE', this field will contain the unique identifier of the associated Target Rule

    oldStatusId
    string or null <uuid>

    If the Activity Log type is 'STATUS', this field will contain the unique identifier of the old status of the Action

    newStatusId
    string or null <uuid>

    If the Activity Log type is 'STATUS', this field will contain the unique identifier of the new status of the Action

    object or null (User)

    If the Activity Log type is 'ASSIGNEE', this field will contain the details of the old assignee of the Action

    object or null (User)

    If the Activity Log type is 'ASSIGNEE', this field will contain the details of the new assignee of the Action

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Statuses by Organisation ID

    Retrieves a list of Status entities belonging to an Organisation. This list represents the Status that an Action can potentially have.

    Authorizations:
    Bearer authentication
    path Parameters
    organisationId
    required
    string <uuid>
    Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7

    Unique identifier of an Organisation

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier of the Status

    name
    string
    Enum: "Triage" "New Action" "Work In Progress" "Scope Required" "To Be Quoted" "Pending PO" "In Review" "Parked" "Closed" "Rejected"

    Name of the Status

    object

    Type of the Status

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Occurrences by Equipment ID Deprecated

    DEPRECATED - this will be removed 01-05-2025

    Retrieves a list of Occurrences for a specific Equipment.

    Authorizations:
    Bearer authentication
    path Parameters
    equipId
    required
    string <uuid>
    Example: 0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d

    Unique identifier of the Equipment

    query Parameters
    from
    required
    string <date>
    Example: from=2023-09-08

    Start date of the Occurrence for which Equipment Occurrences are requested

    to
    string <date>
    Default: "9999-12-31"

    End date of the Occurrence for which Equipment Occurrences are requested

    ruleIds
    Array of strings <uuid>
    Example: ruleIds=7404f7e2-4a5a-4362-bc6c-fcbaa792c546

    List of unique Rule IDs for which Equipment Occurrences are requested

    Responses

    Response Schema: application/json
    Array
    occurredOn
    string <date>

    Date on which the Occurrence was triggered

    Array of objects (Times)

    A list of starting times and durations for each individual hit in the Occurrence

    description
    string
    Default: null

    A description of the Occurrence including any relevant meta data

    ruleId
    string <uuid>

    Unique identifier of the Rule that triggered the Occurrence

    equipId
    string <uuid>

    Unique identifier of the Equipment on which the Occurrence was triggered

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Attachments

    An Attachment entity represents a file that is attached to an Action or a Comment.

    The Attachment entity contains:

    • Information about the file such as its name
    • Information about the user who uploaded the file and when it was uploaded
    • Information about the Action or Comment the file is attached to

    Retrieve Attachments by Organisation ID and Action ID

    Retrieves a list of Attachments belonging to an Action.

    Authorizations:
    Bearer authentication
    path Parameters
    organisationId
    required
    string <uuid>
    Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7

    Unique identifier of an Organisation

    actionId
    required
    integer <int64>
    Example: 1234

    Numeric identifier of an Action within an Organisation

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier of the Attachment

    name
    string

    Name of the Attachment

    actionId
    integer <int64>

    Numeric identifier of the Action

    organisationId
    string <uuid>

    Unique identifier of the Organisation to which the Attachment belongs

    commentId
    string <uuid>
    Default: null

    Unique identifier of the Comment to which the Attachment belongs

    object (User)

    Details of the user who created the Attachment

    createdAt
    string <date-time>

    Timestamp at which the Attachment was created

    object (User)

    Details of the user who last updated the Attachment

    updatedAt
    string <date-time>

    Timestamp at which the Attachment was last updated

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Attachment

    Creates a new Attachment entity and saves the associated File.

    Authorizations:
    Bearer authentication
    Request Body schema: multipart/form-data
    file
    required
    string <binary>

    The file to be uploaded as an attachment

    required
    object

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier of the Attachment

    name
    string

    Name of the Attachment

    actionId
    integer <int64>

    Numeric identifier of the Action

    organisationId
    string <uuid>

    Unique identifier of the Organisation to which the Attachment belongs

    commentId
    string <uuid>
    Default: null

    Unique identifier of the Comment to which the Attachment belongs

    object (User)

    Details of the user who created the Attachment

    createdAt
    string <date-time>

    Timestamp at which the Attachment was created

    object (User)

    Details of the user who last updated the Attachment

    updatedAt
    string <date-time>

    Timestamp at which the Attachment was last updated

    Response samples

    Content type
    application/json
    {
    • "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
    • "name": "attachment.pdf",
    • "actionId": 1234,
    • "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
    • "commentId": "9f1648db-ea2b-4e9a-b035-e5656d6e96c6",
    • "createdBy": {
      },
    • "createdAt": "2022-10-08T12:00:00Z",
    • "updatedBy": {
      },
    • "updatedAt": "2022-10-08T12:00:00Z"
    }

    Retrieve Attachment by ID

    Retrieves a single Attachment entity by its ID.

    Authorizations:
    Bearer authentication
    path Parameters
    attachmentId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Attachment

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier of the Attachment

    name
    string

    Name of the Attachment

    actionId
    integer <int64>

    Numeric identifier of the Action

    organisationId
    string <uuid>

    Unique identifier of the Organisation to which the Attachment belongs

    commentId
    string <uuid>
    Default: null

    Unique identifier of the Comment to which the Attachment belongs

    object (User)

    Details of the user who created the Attachment

    createdAt
    string <date-time>

    Timestamp at which the Attachment was created

    object (User)

    Details of the user who last updated the Attachment

    updatedAt
    string <date-time>

    Timestamp at which the Attachment was last updated

    Response samples

    Content type
    application/json
    {
    • "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
    • "name": "attachment.pdf",
    • "actionId": 1234,
    • "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
    • "commentId": "9f1648db-ea2b-4e9a-b035-e5656d6e96c6",
    • "createdBy": {
      },
    • "createdAt": "2022-10-08T12:00:00Z",
    • "updatedBy": {
      },
    • "updatedAt": "2022-10-08T12:00:00Z"
    }

    Delete Attachment

    Deletes a single Attachment entity by its ID.

    Authorizations:
    Bearer authentication
    path Parameters
    attachmentId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Attachment

    Responses

    Retrieve Attachment File by ID

    Retrieves the file of a single Attachment entity by its ID.

    Authorizations:
    Bearer authentication
    path Parameters
    attachmentId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Attachment

    Responses

    Response Schema: application/octet-stream
    string <binary>

    Weather

    Hourly weather data is available for each Site from its closest weather station for a variety of Weather Metrics. The weather data is available in either Metric or US customary (USC) units.

    A list of supported Weather Metrics can be retrieved as well as as the raw, sub-daily or daily Histories for each Weather Metric.

    Retrieve weather metrics

    Retrieve a list of supported weather metrics and their corresponding Unit and Unit System.

    Authorizations:
    Bearer authentication

    Responses

    Response Schema: application/json
    Array
    id
    number

    Unique identifier of the Weather Metric

    name
    string

    Name of the metric

    object (LegacyUnit)
    unitSystem
    string (UnitSystem)
    Enum: "METRIC" "USC"

    Unit system applied to response data

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve raw Weather Histories by Weather Metric and Site ID

    Retrieves a list of raw Weather Histories for a Site for a given Weather Metric and time period.

    LOCF: It may be desirable to include in the response, the value of the last observation (history) directly before the requested time range, carried forward to the start of that time range. (E.g if histories from 6am to 7am were requested, the history at 5:55am would be carried forward to 6am and included in the response.) This can be useful for change of value (COV) points where that last observation is assumed to be valid up until a new one is received. By default this last observation carried forward (LOCF) is not included but it can be added by passing in INCLUDE_LOCF to the lastObservation field. Please note that the last observation will only be carried forward to the start of the requested time range if an observation (history) does not already exist at the start of that time range.

    Authorizations:
    Bearer authentication
    path Parameters
    siteId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Site

    metricId
    required
    number <int>
    Example: 1

    Unique identifier of the Weather Metric

    query Parameters
    from
    required
    string <date-time>
    Example: from=2022-10-08T04:23:00.000Z

    Start timestamp of the duration for which the Weather Histories are requested

    to
    required
    string <date-time>
    Example: to=2022-10-12T04:23:00.000Z

    End timestamp of the duration for which the Weather Histories are requested

    lastObservation
    string
    Default: "EXCLUDE"
    Enum: "INCLUDE_LOCF" "EXCLUDE"
    Example: lastObservation=INCLUDE_LOCF

    Include the last observation carried forward (INCLUDE_LOCF) or only return the histories within the requested time range (EXCLUDE)

    Responses

    Response Schema: application/json
    Array
    ts
    string <date-time>

    Timestamp of the History object

    val
    number

    Value of the History object

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve sub-daily aggregated Weather Histories by Weather Metric and Site ID

    Retrieves aggregated Weather Histories for a specific Weather Metric, Site, time period and aggregation interval which must be less than daily (sub-daily).

    Authorizations:
    Bearer authentication
    path Parameters
    siteId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Site

    metricId
    required
    number <int>
    Example: 1

    Unique identifier of the Weather Metric

    query Parameters
    from
    required
    string <date-time>
    Example: from=2022-10-08T04:23:00.000Z

    Start timestamp of the duration for which the Weather Histories are requested

    to
    required
    string <date-time>
    Example: to=2022-10-12T04:23:00.000Z

    End timestamp of the duration for which the Weather Histories are requested

    type
    required
    string
    Enum: "FIVE_MINUTE" "QUARTER_HOURLY" "HALF_HOURLY" "HOURLY"
    Example: type=FIVE_MINUTE

    The interval to which the Histories are aggregated to e.g. an interval of HOURLY will rollup all timestamps into a single timestamp per hour on the hour

    Responses

    Response Schema: application/json
    Array
    ts
    string <date-time>

    Start timestamp of the History aggregate

    avg
    number
    Default: null

    Average value in the period starting at the ts (inclusive) till the ts of the next History (exclusive)

    sum
    number
    Default: null

    Sum of the values in the period starting at the ts (inclusive) till the ts of the next History (exclusive)

    min
    number
    Default: null

    Minimum value in the period starting at the ts (inclusive) till the ts of the next History (exclusive)

    max
    number
    Default: null

    Maximum value in the period starting at the ts (inclusive) till the ts of the next History (exclusive)

    count
    integer <int16>
    Default: null

    Count of values in the period starting at the ts (inclusive) till the ts of the next History (exclusive)

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve aggregated Point histories by Weather Metric and Site ID

    Retrieves aggregated histories for a specific Weather Metric, Site, time period and aggregation interval of daily or higher.

    Authorizations:
    Bearer authentication
    path Parameters
    siteId
    required
    string <uuid>
    Example: 5c198552-51dd-4214-994f-dd089ba0e1dc

    Unique identifier of the Site

    metricId
    required
    number <int>
    Example: 1

    Unique identifier of the Weather Metric

    query Parameters
    from
    required
    string <date>
    Default: null
    Example: from=2022-10-08

    Start date of the duration for which Weather histories are requested

    to
    required
    string <date>
    Default: null
    Example: to=2022-10-12

    End date of the duration for which Weather histories are requested

    type
    required
    string
    Enum: "DAILY" "MONTHLY" "QUARTERLY" "YEARLY"
    Example: type=MONTHLY

    The interval to which the Histories are aggregated to e.g. an interval of MONTHLY will rollup all timestamps into a single timestamp per month, from the first to the last day of the month inclusive

    Responses

    Response Schema: application/json
    Array
    ts
    string <date>

    Start date of the History aggregate

    avg
    number
    Default: null

    Average value in the period starting at 00:00 on the ts (inclusive) till 00:00 on the ts of the next History (exclusive)

    sum
    number
    Default: null

    Sum of values in the period starting at 00:00 on the ts (inclusive) till 00:00 on the ts of the next History (exclusive)

    min
    number
    Default: null

    Minimum value in the period starting at 00:00 on the ts (inclusive) till 00:00 on the ts of the next History (exclusive)

    max
    number
    Default: null

    Maximum value in the period starting at 00:00 on the ts (inclusive) till 00:00 on the ts of the next History (exclusive)

    count
    integer <int16>
    Default: null

    Count of values in the period starting at 00:00 on the ts (inclusive) till 00:00 on the ts of the next History (exclusive)

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Weather Observations by Site ID Deprecated

    Retrieves a list of weather observations for a specific Site and optional time period (returns all weather observations if both to and from are not provided).

    Authorizations:
    Bearer authentication
    path Parameters
    siteId
    required
    string <uuid>
    Example: 8a7869df-6cad-4642-a015-9fbb36d3b337

    Unique identifier of the Site

    query Parameters
    from
    string <date-time>
    Default: null
    Example: from=2022-10-08T04:23:00.000Z

    Start timestamp of the period requested

    to
    string <date-time>
    Default: null
    Example: to=2022-10-12T04:23:00.000Z

    End timestamp of the period requested

    aggregateType
    string (WeatherAggregateType)
    Default: "RAW"
    Enum: "RAW" "FIVE_MINUTE" "QUARTER_HOURLY" "HALF_HOURLY" "HOURLY" "DAILY" "MONTHLY" "QUARTERLY" "YEARLY"
    Example: aggregateType=RAW

    The interval to which the observations are aggregated to e.g. an interval of HOURLY will rollup all timestamps into a single timestamp per hour on the hour

    unitSystem
    string (UnitSystem)
    Default: "METRIC"
    Enum: "METRIC" "USC"
    Example: unitSystem=METRIC

    Unit system applied to the weather observations

    Responses

    Response Schema: application/json
    One of
    Array
    observationTs
    string <date-time>

    Timestamp at which the observation was recorded at the weather station

    requestTs
    string <date-time>

    Timestamp at which the observation was requested from the weather station

    airQualityIndex
    integer <int16>
    Default: null

    Air quality index (range: 0 to 500+)

    apparentTemperature
    number

    Apparent temperature (˚C when unitSystem = METRIC, or ˚F when unitSystem = USC )

    cloudCoverage
    number

    Cloud coverage (%)

    dewPoint
    number

    Dew point (˚C when unitSystem = METRIC, or ˚F when unitSystem = USC )

    diffuseHorizontalSolarIrradiance
    number

    Diffuse horizontal solar irradiance (W/m²)

    directNormalSolarIrradiance
    number

    Direct normal solar irradiance (W/m²)

    globalHorizontalSolarIrradiance
    number

    Global horizontal solar irradiance (W/m²)

    precipitation
    number

    Precipitation (mm/h when unitSystem = METRIC, or in/h when unitSystem = USC )

    pressure
    number

    Pressure (mbar)

    relativeHumidity
    number

    Relative humidity (%)

    seaLevelPressure
    number

    Sea level pressure (mbar)

    snow
    number

    Snowfall (mm/h when unitSystem = METRIC, or in/h when unitSystem = USC )

    solarElevationAngle
    number

    Solar elevation angle (˚)

    solarHourAngle
    number

    Solar hour angle (˚)

    solarRadiation
    number

    Solar Radiation (W/m²)

    sunrise
    string
    Default: null

    Local time (hh:mm:ss) at which sun rises

    sunset
    string
    Default: null

    Local time (hh:mm:ss) at which sun sets

    temperature
    number

    Temperature (˚C when unitSystem = METRIC, or ˚F when unitSystem = USC )

    uvIndex
    integer <int16>

    UV Index (range: 0 to 11+)

    visibility
    number

    Visibility (km when unitSystem = METRIC, or mi when unitSystem = USC )

    weatherCode
    integer
    Enum: 200 201 202 230 231 232 233 300 301 500 501 502 511 520 521 522 600 601 602 610 611 612 621 622 623 700 711 721 731 741 751 800 801 802 803 804 900

    Weather code that indicates what the weather is like.

    • 200 - Thunderstorm with light rain

    • 201 - Thunderstorm with rain

    • 202 - Thunderstorm with heavy rain

    • 230 - Thunderstorm with light drizzle

    • 231 - Thunderstorm with drizzle

    • 232 - Thunderstorm with heavy drizzle

    • 233 - Thunderstorm with hail

    • 300 - Light drizzle

    • 301 - Heavy drizzle

    • 500 - Light rain

    • 501 - Moderate rain

    • 502 - Heavy rain

    • 511 - Freezing rain

    • 520 - Light shower rain

    • 521 - Shower rain

    • 522 - Heavy shower rain

    • 600 - Light snow

    • 601 - Snow

    • 602 - Heavy snow

    • 610 - Mix snow/rain

    • 611 - Sleet

    • 612 - Heavy sleet

    • 621 - Snow shower

    • 622 - Heavy snow shower

    • 623 - Flurries

    • 700 - Mist

    • 711 - Smoke

    • 721 - Haze

    • 731 - Sand/dust

    • 741 - Fog

    • 751 - Freezing fog

    • 800 - Clear sky

    • 801 - Few clouds

    • 802 - Scattered clouds

    • 803 - Broken clouds

    • 804 - Overcast clouds

    • 900 - Unknown precipitation

    wetBulb
    number

    Wet bulb temperature (˚C when unitSystem = METRIC, or ˚F when unitSystem = USC )

    windDirection
    number

    Wind direction (˚)

    windSpeed
    number

    Wind speed (m/s when unitSystem = METRIC, or mi/h when unitSystem = USC )

    Response samples

    Content type
    application/json
    Example
    [ ]

    Classes

    Classes are applied to Points and Equipment to effectively define these entities within the Data Model. Classes for Points and Equipment are slightly different but both contain:

    • A long and a short name
    • A description of what the class represents within the Data Model
    • A list of tags which are strings that indicate characteristics of the class (leveraged heavily for analytics)

    Retrieve Point Classes

    Retrieve a list of all the Point Classes within the Data Model (optionally filtered).

    Authorizations:
    Bearer authentication
    query Parameters
    equipClassId
    string <uuid>
    Example: equipClassId=f1d37b44-1f68-4267-afb0-51ba7f9d04cc

    The unique identifier of the Equipment Class the returned Point Classes must be a child of

    unitTypeId
    string <uuid>
    Example: unitTypeId=8190096a-1275-4fc6-b70e-69154647ce93

    The unique identifier of the Unit Type the returned Point Classes must have

    pointType
    string
    Enum: "boolean" "number" "multistate - string" "multistate - numeric"
    Example: pointType=number

    The Point Type the returned Point Classes can be applied to

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier of the Point Class

    shortName
    string

    Short name of the Point Class

    longName
    string

    Long name of the Point Class

    pointType
    string
    Enum: "boolean" "number" "multistate - string" "multistate - numeric"

    Type of Point the Point Class is can be applied to

    tags
    Array of strings

    Strings applied to the Point Class to add context and used for analytics

    description
    string

    Description of the function or characteristics of the Point the Point Class represents

    object (UnitType)

    Unit Type details

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Equipment Classes

    Retrieve a list of all the Equipment Classes within the Data Model.

    Authorizations:
    Bearer authentication
    query Parameters
    includePointClasses
    boolean
    Default: false
    Example: includePointClasses=true

    When true, the returned Equipment Classes will include a list of their child Point Classes

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier of the Equipment Class

    shortName
    string

    Short name of the Equipment Class

    longName
    string

    Long name of the Equipment Class

    tags
    Array of strings

    Strings applied to the Equipment Class to add context and used for analytics

    description
    string

    Description of the function or characteristics of the Equipment the Equipment Class represents

    equipType
    string

    The (higher level) category of Equipment the Equipment Class belongs to

    system
    string

    The system the Equipment Class belongs to

    Array of objects (PointClass)

    Child Point Classes of the Equipment Class

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Tags, Refs & Props

    Tags, Refs and Props are used to characterise Points, Equipment and Sites. Each of those entities can have one or more Tags, Refs or Props applied to them. Tags, Refs and Props form part of the Data Model and can define a characteristic of a Point, Equipment or Site within the model. Given their significance within the Data Model, they also have relationships with Classes, characterising them and their relationships to each other.

    Tags

    Tags are descriptive strings indicative of a characteristic the entity they are applied to has. (e.g a Tag with a name of temp indicates that the entity is related to temperature in some way. Such a tag might be found on a temperature sensor Point)

    Refs

    Refs are used to describe the relationship between entities. For example, a Site entity might have an organisation Ref to an Organisation entity, indicating that the Site belongs to that Organisation. When applied to an entity the ref will have a name (key) to indicate what it is (e.g organisation) and a value which will be the id of the other entity it is a reference to.

    Props

    Props are key-value pairs that provide additional information about an entity. For example, a Point entity for a 3 phase meter might have a Prop with a name (key) of phase and a value of A, indicating that the Point's data represents the A phase.

    Information on the Tags, Refs, and Props that form part of the Data Model is available from this API. This information varies for each, however at at a minimum it includes the name and the nodeType (entity) that the Tag, Ref or Prop can be applied to, to be considered valid within the Data Model.

    Retrieve Tags

    Retrieve a list of all the Tags valid within the Data Model (optionally filtered).

    Authorizations:
    Bearer authentication
    query Parameters
    nodeType
    string
    Enum: "SITE" "EQUIP" "POINT"
    Example: nodeType=POINT

    The node (entity) type the returned Tags can be applied to

    type
    string
    Enum: "CORE" "OPTIONAL"
    Example: type=CORE

    The type of the Tag returned. CORE tags are 'core' to classifying the entity within the Data Model, while OPTIONAL tags supply extra information about the classified entity and do not affect the classification

    classId
    string <uuid|any>
    Example: classId=e71ee5bf-6481-4031-931d-aabf67a4292a

    The unique identifier of the Point or Equip Class the returned Tags must be associated with. Set to "NONE" to retrieve Tags that are not associated with any class.

    Responses

    Response Schema: application/json
    Array
    name
    string

    Name of the Tag

    nodeType
    string
    Enum: "SITE" "EQUIP" "POINT"

    The type of node (entity) the Tag can be applied to (and be valid within the Data Model)

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Refs

    Retrieve a list of all the Refs valid within the Data Model (optionally filtered).

    Authorizations:
    Bearer authentication
    query Parameters
    nodeType
    string
    Enum: "SITE" "EQUIP" "POINT"
    Example: nodeType=POINT

    The node (entity) type the returned Refs can be applied to

    classId
    string <uuid|any>
    Example: classId=e71ee5bf-6481-4031-931d-aabf67a4292a

    The unique identifier of the Point or Equip Class the returned Refs must be associated with. Set to "NONE" to retrieve Refs that are not associated with any class.

    Responses

    Response Schema: application/json
    Array
    name
    string

    Name of the Ref

    nodeType
    string
    Enum: "SITE" "EQUIP" "POINT"

    The type of node (entity) the Ref can be applied to (and be valid within the Data Model)

    targetNodeType
    string
    Enum: "SITE" "EQUIP" "POINT"

    The type of node (entity) the Ref can target (and be valid within the Data Model)

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Props

    Retrieve a list of all the Props valid within the Data Model (optionally filtered).

    Authorizations:
    Bearer authentication
    query Parameters
    nodeType
    string
    Enum: "SITE" "EQUIP" "POINT"
    Example: nodeType=POINT

    The node (entity) type the returned Props can be applied to

    propType
    string
    Enum: "HOUR" "DATE" "NUMBER" "JSON" "STRING" "LIST" "TIMESTAMP" "FUNCTION"
    Example: propType=STRING

    The type of the Prop returned

    unitTypeId
    string <uuid>
    Example: unitTypeId=8190096a-1275-4fc6-b70e-69154647ce93

    The unique identifier of the Unit Type the returned Props must have

    classId
    string <uuid|any>
    Example: classId=e71ee5bf-6481-4031-931d-aabf67a4292a

    The unique identifier of the Point or Equip Class the returned Props must be associated with. Set to "NONE" to retrieve Props that are not associated with any class.

    Responses

    Response Schema: application/json
    Array
    name
    string

    Name (key) of the Prop

    nodeType
    string
    Enum: "SITE" "EQUIP" "POINT"

    The type of node (entity) the Prop can be applied to (and be valid within the Data Model)

    propType
    string
    Enum: "HOUR" "DATE" "NUMBER" "JSON" "STRING" "LIST" "TIMESTAMP" "FUNCTION"

    The type of the the Prop's value

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Units

    Units are attached to Points when required, to define the Unit of the History associated with that Point. The Unit entity contains all the information necessary to define the characteristics of the Unit.

    Retrieve Units

    Retrieve a list of supported Units.

    Authorizations:
    Bearer authentication

    Responses

    Response Schema: application/json
    Array
    id
    integer <int16>

    Unique identifier of the Unit

    name
    string

    Name of the Unit, e.g. kilopascals

    symbol
    string

    Symbol of the Unit, e.g. kPa

    object (UnitType)

    Unit Type details

    scale
    number

    Scale of the Unit, used when converting between Units, e.g. 1000

    offset
    number

    Offset of unit, used when converting between Units, e.g. 0

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Legacy Units Deprecated

    Retrieve a list of legacy Units.

    Authorizations:
    Bearer authentication

    Responses

    Response Schema: application/json
    Array
    id
    integer <int16>

    Unique identifier of the Unit

    name
    string

    Name of the Unit, e.g. kilopascals

    symbol
    string

    Symbol of the Unit, e.g. kPa

    type
    string

    Type of the Unit e.g. pressure

    scale
    number

    Scale of the Unit, used when converting between Units, e.g. 1000

    offset
    number

    Offset of unit, used when converting between Units, e.g. 0

    dimension
    string
    Default: null

    Dimension of unit, e.g. kg1m-1sec-2

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Users

    Retrieve your user details.

    Retrieve current user details

    Retrieves the currently logged in user's details.

    Authorizations:
    Bearer authentication

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier of the User

    fullName
    string

    Full name of the User

    email
    string <email>

    Email of the User

    status
    string

    Status of the User, possible options are active or deleted

    createdAt
    string <date-time>

    Timestamp when the User was created in LocalDateTime (YYYY-MM-DDThh:mm:ss)

    updatedAt
    string <date-time>

    Timestamp when the User was last updated in LocalDateTime (YYYY-MM-DDThh:mm:ss)

    optOutUserTracking
    boolean

    Boolean to indicate whether the User has opted out from user tracking

    Response samples

    Content type
    application/json
    {
    • "id": "346f074a-25fb-4c98-8871-3aa8a4c12854",
    • "fullName": "Bob Dylan",
    • "email": "user@example.com",
    • "status": "active",
    • "createdAt": "2017-05-30T01:17:07",
    • "updatedAt": "2022-10-04T05:45:07",
    • "optOutUserTracking": false
    }