Download OpenAPI specification:Download
The Bueno API is a collection of REST endpoints with JSON responses, for interacting with the site data model and associated histories.
The data model is a hierarchical data structure:
Organisation → Site → Group → Equipment → Point
To fetch Site, Group, Equipment or Point data you can traverse the layers of the data model sequentially.
The data model 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.
For example a Point entity would have the following information available:
"refs": {"organisation": UUID, "site": UUID, "group": UUID, "equip": UUID}
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.
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.
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.
bearer
JWT
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.
string <email> | |
password | string |
token | string <JWT> JWT string that can be used as a bearer token |
expires | integer <int64> Issued JWT token time to expire in seconds |
{- "email": "user@example.com",
- "password": "S0m3@S3cr3TP4$$"
}
{- "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "expires": 1209599
}
An Organisation entity represents a company or customer which has 0 or more Sites.
Possible operations for an Organisation are to retrieve a list of Organisations or an individual Organisation by ID. Sites and Integrations belonging to an Organisation can also be retrieved.
Creates a new Organisation entity.
key required | string Human readable key to identify the Organisation (must be unique) |
name required | string Full name of the Organisation |
timezone required | string Timezone of the Organisation |
id | string <uuid> Unique identifier of the Organisation |
key | string Human readable key to identify the Organisation |
name | string Full name of the Organisation |
timezone | string Timezone of the Organisation |
{- "key": "ACME",
- "name": "Acme Corporation",
- "timezone": "Australia/Melbourne"
}
{- "id": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "key": "ACME",
- "name": "Acme Corporation",
- "timezone": "Australia/Melbourne"
}
Retrieves a list of Organisation entities.
id | string <uuid> Unique identifier of the Organisation |
key | string Human readable key to identify the Organisation |
name | string Full name of the Organisation |
timezone | string Timezone of the Organisation |
[- {
- "id": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "key": "ACME",
- "name": "Acme Corporation",
- "timezone": "Australia/Melbourne"
}
]
Retrieves a single Organisation entity by its ID.
organisationId required | string <uuid> Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7 Unique identifier of an Organisation |
id | string <uuid> Unique identifier of the Organisation |
key | string Human readable key to identify the Organisation |
name | string Full name of the Organisation |
timezone | string Timezone of the Organisation |
{- "id": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "key": "ACME",
- "name": "Acme Corporation",
- "timezone": "Australia/Melbourne"
}
A Site entity is the equivalent of a building in the physical world. A Site always belongs to an Organisation.
tags
and props
which are used to add extra context to the Siterefs
which specify which Organisation it belongs toPossible operations for a Site include create, update and delete as well as retrieving a Site by its ID or a list of Sites belonging to an Organisation.
Creates a new Site entity. The Organisation ID must be included in the Site's refs
.
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 |
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 |
{- "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": {
- "slowSync": {
- "type": "NUMBER",
- "value": {
- "unit": "h",
- "num": 24
}
}, - "energyAlertEmail": {
- "type": "STRING",
- "value": "user@example.com"
}, - "waterAlertsRecipients": {
- "type": "LIST",
- "value": [
- "test-user-1",
- "test-user-2"
]
}
}, - "tags": [
- "acme",
- "site",
- "officeBuilding"
], - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7"
}
}
{- "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": {
- "slowSync": {
- "type": "NUMBER",
- "value": {
- "unit": "h",
- "num": 24
}
}, - "energyAlertEmail": {
- "type": "STRING",
- "value": "user@example.com"
}, - "waterAlertsRecipients": {
- "type": "LIST",
- "value": [
- "test-user-1",
- "test-user-2"
]
}
}, - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7"
}, - "tags": [
- "acme",
- "site",
- "officeBuilding"
], - "deleted": false
}
Updates a list of Site entities.
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 |
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 |
[- {
- "id": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "name": "Acme Building 1",
- "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": {
- "slowSync": {
- "type": "NUMBER",
- "value": {
- "unit": "h",
- "num": 24
}
}, - "energyAlertEmail": {
- "type": "STRING",
- "value": "user@example.com"
}, - "waterAlertsRecipients": {
- "type": "LIST",
- "value": [
- "test-user-1",
- "test-user-2"
]
}
}, - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7"
}, - "tags": [
- "acme",
- "site",
- "officeBuilding"
], - "deleted": false
}
]
[- {
- "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": {
- "slowSync": {
- "type": "NUMBER",
- "value": {
- "unit": "h",
- "num": 24
}
}, - "energyAlertEmail": {
- "type": "STRING",
- "value": "user@example.com"
}, - "waterAlertsRecipients": {
- "type": "LIST",
- "value": [
- "test-user-1",
- "test-user-2"
]
}
}, - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7"
}, - "tags": [
- "acme",
- "site",
- "officeBuilding"
], - "deleted": false
}
]
Retrieve Sites using advanced search queries. See the documentation for more information on how to use advanced search.
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
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 |
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 |
[- {
- "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": {
- "slowSync": {
- "type": "NUMBER",
- "value": {
- "unit": "h",
- "num": 24
}
}, - "energyAlertEmail": {
- "type": "STRING",
- "value": "user@example.com"
}, - "waterAlertsRecipients": {
- "type": "LIST",
- "value": [
- "test-user-1",
- "test-user-2"
]
}
}, - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7"
}, - "tags": [
- "acme",
- "site",
- "officeBuilding"
], - "deleted": false
}
]
Retrieves a single Site entity by its ID.
siteId required | string <uuid> Example: 8a7869df-6cad-4642-a015-9fbb36d3b337 Unique identifier of the Site |
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 |
{- "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": {
- "slowSync": {
- "type": "NUMBER",
- "value": {
- "unit": "h",
- "num": 24
}
}, - "energyAlertEmail": {
- "type": "STRING",
- "value": "user@example.com"
}, - "waterAlertsRecipients": {
- "type": "LIST",
- "value": [
- "test-user-1",
- "test-user-2"
]
}
}, - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7"
}, - "tags": [
- "acme",
- "site",
- "officeBuilding"
], - "deleted": false
}
Retrieves a list of Site entities belonging to a specific Organisation.
organisationId required | string <uuid> Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7 Unique identifier of an Organisation |
includeDeleted | boolean Default: false Example: includeDeleted=false Include deleted Sites in the response |
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 |
[- {
- "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": {
- "slowSync": {
- "type": "NUMBER",
- "value": {
- "unit": "h",
- "num": 24
}
}, - "energyAlertEmail": {
- "type": "STRING",
- "value": "user@example.com"
}, - "waterAlertsRecipients": {
- "type": "LIST",
- "value": [
- "test-user-1",
- "test-user-2"
]
}
}, - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7"
}, - "tags": [
- "acme",
- "site",
- "officeBuilding"
], - "deleted": false
}
]
A Group entity belongs to a Site and is used to associate Equipment together within that Site.
name
used to uniquely label the groupsiteId
to identify the ID of the Site it belongs toPossible operations for a Group include create, update and delete as well as retrieving a Group by its ID or a list of Groups by Site ID.
Creates a new Group entity.
name required | string Name of the Group |
siteId required | string <uuid> Unique identifier of the Site the Group belongs to |
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 |
{- "name": "CHW PLANT",
- "siteId": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}
{- "id": "38d77506-9c7a-447e-9153-b9ce23b7ceb6",
- "name": "CHW PLANT",
- "siteId": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "deleted": false
}
Updates a list of Group entities.
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 |
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 |
[- {
- "id": "38d77506-9c7a-447e-9153-b9ce23b7ceb6",
- "name": "CHW PLANT",
- "siteId": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "deleted": false
}
]
[- {
- "id": "38d77506-9c7a-447e-9153-b9ce23b7ceb6",
- "name": "CHW PLANT",
- "siteId": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "deleted": false
}
]
Retrieve Groups using advanced search queries. See the documentation for more information on how to use advanced search.
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"
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 |
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 |
[- {
- "id": "38d77506-9c7a-447e-9153-b9ce23b7ceb6",
- "name": "CHW PLANT",
- "siteId": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "deleted": false
}
]
Retrieves a Group entity by its ID.
equipGroupId required | string <uuid> Example: 38d77506-9c7a-447e-9153-b9ce23b7ceb6 Unique identifier of a Group |
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 |
{- "id": "38d77506-9c7a-447e-9153-b9ce23b7ceb6",
- "name": "CHW PLANT",
- "siteId": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "deleted": false
}
Retrieves a list of Group entities belonging to a specific Site.
siteId required | string <uuid> Example: 8a7869df-6cad-4642-a015-9fbb36d3b337 Unique identifier of the Site |
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 |
[- {
- "id": "38d77506-9c7a-447e-9153-b9ce23b7ceb6",
- "name": "CHW PLANT",
- "siteId": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "deleted": false
}
]
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.
tags
which are strings used to describe the type of equipmenttypes
which are used to group particular type of equipmentprops
which provide key value meta informationrefs
to specify which Site and Organisation it belongs todeploymentId
to specify which Deployment it belongs to.Possible operations for an Equipment include create, update and delete, as well as Import and Export. It is also possible to retrieve an Equipment by its ID, a list of Equipment belonging to a Group or a list of Equipment belonging to a Site.
Creates a new Equipment entity. The Group ID must be included in the Equipment's refs
.
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 |
id | string <uuid> Unique identifier of the Equipment |
name | string Name of the Equipment |
externalId | string Default: null Alternative unique identifier |
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 |
{- "name": "Gas Meter",
- "tags": [
- "equip",
- "gas"
], - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}, - "props": {
- "station": {
- "type": "STRING",
- "value": "BUILDING_2"
}
}, - "virtualMeterRefs": null
}
{- "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
- "name": "Gas Meter",
- "externalId": "3758ef98-0788524e",
- "tags": [
- "equip",
- "gas"
], - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}, - "types": [
- {
- "name": "chw_loop",
- "group": "hvac",
- "subGroup": "plant"
}
], - "virtualMeterRefs": null,
- "props": {
- "station": {
- "type": "STRING",
- "value": "BUILDING_2"
}
}, - "deleted": false
}
Updates a list of Equipment entities.
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 |
id | string <uuid> Unique identifier of the Equipment |
name | string Name of the Equipment |
externalId | string Default: null Alternative unique identifier |
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 |
[- {
- "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
- "name": "Gas Meter",
- "tags": [
- "equip",
- "gas"
], - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}, - "types": [ ],
- "props": {
- "station": {
- "type": "STRING",
- "value": "BUILDING_2"
}
}, - "deleted": false,
- "virtualMeterRefs": null
}
]
{- "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
- "name": "Gas Meter",
- "externalId": "3758ef98-0788524e",
- "tags": [
- "equip",
- "gas"
], - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}, - "types": [
- {
- "name": "chw_loop",
- "group": "hvac",
- "subGroup": "plant"
}
], - "virtualMeterRefs": null,
- "props": {
- "station": {
- "type": "STRING",
- "value": "BUILDING_2"
}
}, - "deleted": false
}
Retrieve Equipment using advanced search queries. See the documentation for more information about how to use advanced search.
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"
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 |
id | string <uuid> Unique identifier of the Equipment |
name | string Name of the Equipment |
externalId | string Default: null Alternative unique identifier |
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 |
[- {
- "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
- "name": "Gas Meter",
- "externalId": "3758ef98-0788524e",
- "tags": [
- "equip",
- "gas"
], - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}, - "types": [
- {
- "name": "chw_loop",
- "group": "hvac",
- "subGroup": "plant"
}
], - "virtualMeterRefs": null,
- "props": {
- "station": {
- "type": "STRING",
- "value": "BUILDING_2"
}
}, - "deleted": false
}
]
Retrieves a single Equipment entity by its ID.
equipId required | string <uuid> Example: 0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d Unique identifier of the Equipment |
id | string <uuid> Unique identifier of the Equipment |
name | string Name of the Equipment |
externalId | string Default: null Alternative unique identifier |
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 |
{- "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
- "name": "Gas Meter",
- "externalId": "3758ef98-0788524e",
- "tags": [
- "equip",
- "gas"
], - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}, - "types": [
- {
- "name": "chw_loop",
- "group": "hvac",
- "subGroup": "plant"
}
], - "virtualMeterRefs": null,
- "props": {
- "station": {
- "type": "STRING",
- "value": "BUILDING_2"
}
}, - "deleted": false
}
Retrieves a list of Equipment entities belonging to a Group.
equipGroupId required | string <uuid> Example: 38d77506-9c7a-447e-9153-b9ce23b7ceb6 Unique identifier of the Group |
includeDeleted | boolean Default: false Example: includeDeleted=false Include deleted Equipment in the response |
id | string <uuid> Unique identifier of the Equipment |
name | string Name of the Equipment |
externalId | string Default: null Alternative unique identifier |
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 |
{- "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
- "name": "Gas Meter",
- "externalId": "3758ef98-0788524e",
- "tags": [
- "equip",
- "gas"
], - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}, - "types": [
- {
- "name": "chw_loop",
- "group": "hvac",
- "subGroup": "plant"
}
], - "virtualMeterRefs": null,
- "props": {
- "station": {
- "type": "STRING",
- "value": "BUILDING_2"
}
}, - "deleted": false
}
Retrieves a list of Equipment entities belonging to a specific Site.
siteId required | string <uuid> Example: 8a7869df-6cad-4642-a015-9fbb36d3b337 Unique identifier of the Site |
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 |
id | string <uuid> Unique identifier of the Equipment |
name | string Name of the Equipment |
externalId | string Default: null Alternative unique identifier |
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 |
{- "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
- "name": "Gas Meter",
- "externalId": "3758ef98-0788524e",
- "tags": [
- "equip",
- "gas"
], - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}, - "types": [
- {
- "name": "chw_loop",
- "group": "hvac",
- "subGroup": "plant"
}
], - "virtualMeterRefs": null,
- "props": {
- "station": {
- "type": "STRING",
- "value": "BUILDING_2"
}
}, - "deleted": false
}
The import feature provides a way to create and update Equipment in bulk within an Organisation (across multiple Sites and Integrations). This includes:
For detailed documentation on this feature, please contact API support.
sites | Array of arrays Equipment import stats broken down by site |
validation | json Validation data from the import including any errors |
{- "sites": [
- {
- "siteId": "ffb4a449-7056-4b41-b5d4-7e25b41aad6f",
- "siteName": "Site 123",
- "stats": {
- "create": {
- "equips": 1,
- "groups": 1
}, - "update": {
- "equips": 2
}, - "move": {
- "equips": 3
}
}
}
], - "validation": {
- "errors": [
- {
- "row": 3,
- "column": "group.id",
- "message": "Value for group.id not found",
- "data": {
- "site.id": "ffb4a449-7056-4b41-b5d4-7e25b41aad6f",
- "group.id": "01733d82-6bd8-40c6-8db2-09effee8ad87",
- "equipment.name": "Chiller-1"
}
}
]
}
}
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.
siteIds required | Array of strings <uuid> Example: siteIds=8a7869df-6cad-4642-a015-9fbb36d3b337 List of unique identifiers of the Sites to export Points for |
{- "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"
}
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).
equipId required | string <uuid> Example: 110e9ea8-d8e9-4270-a084-92c064d528da Unique identifier of the Equipment |
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 |
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 |
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. |
id | string <uuid> Unique identifier of the Equipment |
name | string Name of the Equipment |
externalId | string Default: null Alternative unique identifier |
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 |
{- "name": "Gas Meter",
- "duplicatePoints": false,
- "duplicateDataStreamMappings": false,
- "groupId": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}
{- "id": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d",
- "name": "Gas Meter",
- "externalId": "3758ef98-0788524e",
- "tags": [
- "equip",
- "gas"
], - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "38d77506-9c7a-447e-9153-b9ce23b7ceb6"
}, - "types": [
- {
- "name": "chw_loop",
- "group": "hvac",
- "subGroup": "plant"
}
], - "virtualMeterRefs": null,
- "props": {
- "station": {
- "type": "STRING",
- "value": "BUILDING_2"
}
}, - "deleted": false
}
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.
type
to describe if the point is a Number, Boolean or Multistateunit
(optional) which contains information about the Unit of a Point e.g. "kL"tags
which are strings used to describe the Point for example a ZT sensor might be described with "zone", "temp", "sensor"props
which provide key value meta informationrefs
to specify which Equipment, Site and Organisation it belongs toPossible operations for a Point include create, update and delete, as well as Import and Export. It is also possible to retrieve a Point by its ID, a list of Points belonging to an Equip as well as a Point's raw and aggregated histories over a period of time.
Creates a new Point entity. The Equipment ID must be included in the Point's refs
.
name required | string Name of the Point |
type required | string Enum: "boolean" "number" "multistate - string" "multistate - numeric" Type of the Point |
object (CreateUnitProperty) Default: null Unit | |
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 |
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 |
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 (UnitProperty) Unit | |
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 |
{- "name": "SUCTION_PRES",
- "type": "number",
- "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "tags": [
- "sensor",
- "pressure",
- "refrigerant"
], - "props": {
- "e2deviceId": {
- "type": "STRING",
- "value": "2"
}, - "pointTagRemoved": {
- "type": "DATE",
- "value": "2021-06-30"
}
}, - "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "927b9206-31b9-4933-88b3-104ed7159c65",
- "equip": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}
}
{- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "SUCTION_PRES",
- "type": "number",
- "externalId": "227556dc-0788524e",
- "tags": [
- "sensor",
- "pressure",
- "refrigerant"
], - "props": {
- "e2deviceId": {
- "type": "STRING",
- "value": "2"
}, - "pointTagRemoved": {
- "type": "DATE",
- "value": "2021-06-30"
}
}, - "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "defaultHistoryRollup": "avg",
- "deleted": false,
- "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "927b9206-31b9-4933-88b3-104ed7159c65",
- "equip": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}, - "enumValues": {
- "1.0": "Active",
- "2.0": "Stalled"
}
}
Updates a list of Point entities.
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 (UnitProperty) Unit | |
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 |
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 |
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 (UnitProperty) Unit | |
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 |
[- {
- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "SUCTION_PRES",
- "type": "number",
- "tags": [
- "sensor",
- "pressure",
- "refrigerant"
], - "props": {
- "e2deviceId": {
- "type": "STRING",
- "value": "2"
}, - "pointTagRemoved": {
- "type": "DATE",
- "value": "2021-06-30"
}
}, - "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "deleted": false,
- "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "927b9206-31b9-4933-88b3-104ed7159c65",
- "equip": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}, - "enumValues": {
- "1.0": "Active",
- "2.0": "Stalled"
}
}
]
[- {
- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "SUCTION_PRES",
- "type": "number",
- "externalId": "227556dc-0788524e",
- "tags": [
- "sensor",
- "pressure",
- "refrigerant"
], - "props": {
- "e2deviceId": {
- "type": "STRING",
- "value": "2"
}, - "pointTagRemoved": {
- "type": "DATE",
- "value": "2021-06-30"
}
}, - "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "defaultHistoryRollup": "avg",
- "deleted": false,
- "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "927b9206-31b9-4933-88b3-104ed7159c65",
- "equip": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}, - "enumValues": {
- "1.0": "Active",
- "2.0": "Stalled"
}
}
]
Retrieve Points using advanced search queries. See the documentation for more information on how to use advanced search.
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"
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 |
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 |
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 (UnitProperty) Unit | |
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 |
[- {
- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "SUCTION_PRES",
- "type": "number",
- "externalId": "227556dc-0788524e",
- "tags": [
- "sensor",
- "pressure",
- "refrigerant"
], - "props": {
- "e2deviceId": {
- "type": "STRING",
- "value": "2"
}, - "pointTagRemoved": {
- "type": "DATE",
- "value": "2021-06-30"
}
}, - "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "defaultHistoryRollup": "avg",
- "deleted": false,
- "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "927b9206-31b9-4933-88b3-104ed7159c65",
- "equip": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}, - "enumValues": {
- "1.0": "Active",
- "2.0": "Stalled"
}
}
]
Retrieves a single Point entity by its ID.
pointId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Point |
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 |
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 (UnitProperty) Unit | |
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 |
{- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "SUCTION_PRES",
- "type": "number",
- "externalId": "227556dc-0788524e",
- "tags": [
- "sensor",
- "pressure",
- "refrigerant"
], - "props": {
- "e2deviceId": {
- "type": "STRING",
- "value": "2"
}, - "pointTagRemoved": {
- "type": "DATE",
- "value": "2021-06-30"
}
}, - "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "defaultHistoryRollup": "avg",
- "deleted": false,
- "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "927b9206-31b9-4933-88b3-104ed7159c65",
- "equip": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}, - "enumValues": {
- "1.0": "Active",
- "2.0": "Stalled"
}
}
Retrieves a list of Point entities belonging to a specific Equipment.
equipId required | string <uuid> Example: 0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d Unique identifier of the Equipment |
includeDeleted | boolean Default: false Example: includeDeleted=false Include deleted Points in the response |
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 |
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 (UnitProperty) Unit | |
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 |
[- {
- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "SUCTION_PRES",
- "type": "number",
- "externalId": "227556dc-0788524e",
- "tags": [
- "sensor",
- "pressure",
- "refrigerant"
], - "props": {
- "e2deviceId": {
- "type": "STRING",
- "value": "2"
}, - "pointTagRemoved": {
- "type": "DATE",
- "value": "2021-06-30"
}
}, - "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "defaultHistoryRollup": "avg",
- "deleted": false,
- "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "927b9206-31b9-4933-88b3-104ed7159c65",
- "equip": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}, - "enumValues": {
- "1.0": "Active",
- "2.0": "Stalled"
}
}
]
The import feature provides a way to create and update Points in bulk within an Organisation (across multiple Sites and Integrations). This includes:
For detailed documentation on this feature, please contact API support.
sites | Array of arrays Point import stats broken down by site |
validation | json Validation data from the import including any errors |
{- "sites": [
- {
- "siteId": "ffb4a449-7056-4b41-b5d4-7e25b41aad6f",
- "siteName": "Site 123",
- "integrationsAffected": [
- {
- "id": "5b3ee3b1-fc1d-4a0a-86d1-350396d93bd0",
- "name": "My Company Legacy Integration"
}
], - "stats": {
- "create": {
- "points": 2,
- "equips": 1,
- "groups": 1
}, - "update": {
- "points": 2
}, - "move": {
- "points": 3
}
}
}
], - "validation": {
- "errors": [
- {
- "row": 3,
- "column": "equipment.id",
- "message": "Value for equipment.id not found",
- "data": {
- "integration.id": "5b3ee3b1-fc1d-4a0a-86d1-350396d93bd0",
- "stream.id": "/Site/Controller1/AHU/Cmd",
- "site.id": "ffb4a449-7056-4b41-b5d4-7e25b41aad6f",
- "group.id": "01733d82-6bd8-40c6-8db2-09effee8ad87",
- "equipment.id": "b0982c6b-fcb2-4699-b91c-618423cbf54d",
- "point.name": "TEST-IMPORT-POINT-3",
- "point.type": "Boolean"
}
}
]
}
}
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.
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 |
{- "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"
}
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.
pointId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Point |
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 |
ts | string <date-time> Timestamp of the History object |
val | number Value of the History object |
[- {
- "ts": "2022-10-08T04:23:00Z",
- "val": 1
}
]
Retrieves aggregated histories for a specific Point, time period and aggregation interval which must be less than daily (sub-daily).
pointId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Point |
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 |
ts | string <date-time> Start timestamp of the History aggregate |
avg | number Default: null Average value in the period starting at the |
sum | number Default: null Sum of the values in the period starting at the |
min | number Default: null Minimum value in the period starting at the |
max | number Default: null Maximum value in the period starting at the |
count | integer <int16> Default: null Count of values in the period starting at the |
[- {
- "ts": "2022-10-08T04:00:00Z",
- "avg": 1,
- "sum": 1,
- "min": 1,
- "max": 1,
- "count": 1
}
]
Retrieves aggregated histories for a specific Point, time period and aggregation interval of daily or higher.
pointId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Point |
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 |
ts | string <date> Start date of the History aggregate |
avg | number Default: null Average value in the period starting at 00:00 on the |
sum | number Default: null Sum of values in the period starting at 00:00 on the |
min | number Default: null Minimum value in the period starting at 00:00 on the |
max | number Default: null Maximum value in the period starting at 00:00 on the |
count | integer <int16> Default: null Count of values in the period starting at 00:00 on the |
[- {
- "ts": "2022-10-08",
- "avg": 1,
- "sum": 1,
- "min": 1,
- "max": 1,
- "count": 1
}
]
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).
pointId required | string <uuid> Example: 110e9ea8-d8e9-4270-a084-92c064d528da Unique identifier of the Point |
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 |
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. |
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 |
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 (UnitProperty) Unit | |
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 |
{- "name": "SUCTION_PRES",
- "duplicateDataStreamMappings": false,
- "equipId": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}
{- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "SUCTION_PRES",
- "type": "number",
- "externalId": "227556dc-0788524e",
- "tags": [
- "sensor",
- "pressure",
- "refrigerant"
], - "props": {
- "e2deviceId": {
- "type": "STRING",
- "value": "2"
}, - "pointTagRemoved": {
- "type": "DATE",
- "value": "2021-06-30"
}
}, - "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "defaultHistoryRollup": "avg",
- "deleted": false,
- "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "927b9206-31b9-4933-88b3-104ed7159c65",
- "equip": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}, - "enumValues": {
- "1.0": "Active",
- "2.0": "Stalled"
}
}
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
.
pointId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Point |
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 (UnitProperty) Unit | |
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 |
{- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "SUCTION_PRES",
- "type": "number",
- "externalId": "227556dc-0788524e",
- "etlId": "VICTarneit3029~R2MT$7cR2_MT_404A$2da2$7cSUCTION_PRES",
- "tags": [
- "sensor",
- "pressure",
- "refrigerant"
], - "props": {
- "e2deviceId": {
- "type": "STRING",
- "value": "2"
}, - "pointTagRemoved": {
- "type": "DATE",
- "value": "2021-06-30"
}
}, - "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "defaultHistoryRollup": "avg",
- "deleted": false,
- "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "927b9206-31b9-4933-88b3-104ed7159c65",
- "equip": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}, - "enumValues": {
- "1.0": "Active",
- "2.0": "Stalled"
}
}
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
.
equipId required | string <uuid> Example: 0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d Unique identifier of the Equipment |
includeDeleted | boolean Default: false Example: includeDeleted=false Include deleted Points in the response |
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 (UnitProperty) Unit | |
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 |
[- {
- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "SUCTION_PRES",
- "type": "number",
- "externalId": "227556dc-0788524e",
- "etlId": "VICTarneit3029~R2MT$7cR2_MT_404A$2da2$7cSUCTION_PRES",
- "tags": [
- "sensor",
- "pressure",
- "refrigerant"
], - "props": {
- "e2deviceId": {
- "type": "STRING",
- "value": "2"
}, - "pointTagRemoved": {
- "type": "DATE",
- "value": "2021-06-30"
}
}, - "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "defaultHistoryRollup": "avg",
- "deleted": false,
- "refs": {
- "organisation": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "site": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "group": "927b9206-31b9-4933-88b3-104ed7159c65",
- "equip": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}, - "enumValues": {
- "1.0": "Active",
- "2.0": "Stalled"
}
}
]
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:
Creates a new Integration entity.
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 |
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 |
{- "name": "1 Sesame St BMS ",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "timezone": "Australia/Melbourne"
}
{- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "1 Sesame St BMS",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "timezone": "Australia/Melbourne"
}
Updates a single Integration entity.
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 |
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 |
{- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "1 Sesame St BMS",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "timezone": "Australia/Melbourne"
}
{- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "1 Sesame St BMS",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "timezone": "Australia/Melbourne"
}
Retrieves a single Integration entity by its ID.
integrationId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Integration |
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 |
{- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "1 Sesame St BMS",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "timezone": "Australia/Melbourne"
}
Retrieves a list of Integration entities belonging an Organisation.
organisationId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Organisation |
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 |
[- {
- "id": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "name": "1 Sesame St BMS",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "timezone": "Australia/Melbourne"
}
]
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).
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 unitCreates a new Data Stream entity.
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 |
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 |
updatedAt | string <date-time> Timestamp at which the Data Stream was updated, or |
pointMappings | Array of arrays Default: null List of Point Mappings associated to this Data Stream (optional) |
{- "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "streamId": "MyConnection/Device301/Chiller-1/SAT",
- "status": "ENABLED",
- "type": "NUMBER",
- "metadata": {
- "unit": "%"
}
}
{- "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
- "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "streamId": "MyConnection/Device301/Chiller-1/SAT",
- "status": "ENABLED",
- "type": "NUMBER",
- "metadata": {
- "unit": "%"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedAt": "2022-10-08T12:00:00Z",
- "pointMappings": null
}
Updates a single Data Stream entity.
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 |
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 |
updatedAt | string <date-time> Timestamp at which the Data Stream was updated, or |
pointMappings | Array of arrays Default: null List of Point Mappings associated to this Data Stream (optional) |
{- "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
- "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "streamId": "MyConnection/Device301/Chiller-1/SAT",
- "status": "ENABLED",
- "type": "NUMBER",
- "metadata": {
- "unit": "%"
}
}
{- "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
- "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "streamId": "MyConnection/Device301/Chiller-1/SAT",
- "status": "ENABLED",
- "type": "NUMBER",
- "metadata": {
- "unit": "%"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedAt": "2022-10-08T12:00:00Z",
- "pointMappings": null
}
Retrieves a single Data Stream entity by its ID.
dataStreamId required | string <uuid> Example: 07fab9a6-d330-4efc-a198-192cbfd93eb9 Unique identifier of the Data Stream |
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 |
updatedAt | string <date-time> Timestamp at which the Data Stream was updated, or |
pointMappings | Array of arrays Default: null List of Point Mappings associated to this Data Stream (optional) |
{- "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
- "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "streamId": "MyConnection/Device301/Chiller-1/SAT",
- "status": "ENABLED",
- "type": "NUMBER",
- "metadata": {
- "unit": "%"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedAt": "2022-10-08T12:00:00Z",
- "pointMappings": null
}
Deletes a single Data Stream entity.
dataStreamId required | string <uuid> Example: 07fab9a6-d330-4efc-a198-192cbfd93eb9 Unique identifier of the Data Stream |
{- "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"
}
Retrieves a list of Data Stream entities belonging to an Integration.
integrationId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Integration |
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 |
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 |
updatedAt | string <date-time> Timestamp at which the Data Stream was updated, or |
pointMappings | Array of arrays Default: null List of Point Mappings associated to this Data Stream (optional) |
[- {
- "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
- "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "streamId": "MyConnection/Device301/Chiller-1/SAT",
- "status": "ENABLED",
- "type": "NUMBER",
- "metadata": {
- "unit": "%"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedAt": "2022-10-08T12:00:00Z",
- "pointMappings": null
}
]
Exports a list of Data Stream entities belonging an Integration.
integrationId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Integration |
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 |
Retrieves a list of Data Stream entities belonging to an Integration.
integrationId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Integration |
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 |
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 |
updatedAt | string <date-time> Timestamp at which the Data Stream was updated, or |
pointMappings | Array of arrays Default: null List of Point Mappings associated to this Data Stream (optional) |
[- {
- "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
- "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "streamId": "MyConnection/Device301/Chiller-1/SAT",
- "status": "ENABLED",
- "type": "NUMBER",
- "metadata": {
- "unit": "%"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedAt": "2022-10-08T12:00:00Z",
- "pointMappings": null
}
]
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-01T10:00:00+00:00:00". 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.
An endpoint is provided to retrieve Data Stream Mappings for a Point as well as an endpoint to set the Data Stream Mappings for a Point.
Sets the Data Stream Mapping entities for a Point.
pointId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Point |
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 |
object (DataStream) Data Stream details | |
tsStart | string <date-time> Timestamp at which the Data Stream is associated to the Point |
[- {
- "dataStream": {
- "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "streamId": "MyConnection/Device301/Chiller-1/SAT"
}, - "tsStart": "2022-10-08T12:00:00Z"
}
]
[- {
- "dataStream": {
- "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
- "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "streamId": "MyConnection/Device301/Chiller-1/SAT",
- "status": "ENABLED",
- "type": "NUMBER",
- "metadata": {
- "unit": "%"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedAt": "2022-10-08T12:00:00Z",
- "pointMappings": null
}, - "tsStart": "2022-10-08T12:00:00Z"
}
]
Retrieves a list of Data Stream Mapping entities for a Point.
pointId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Point |
object (DataStream) Data Stream details | |
tsStart | string <date-time> Timestamp at which the Data Stream is associated to the Point |
[- {
- "dataStream": {
- "id": "07fab9a6-d330-4efc-a198-192cbfd93eb9",
- "integrationId": "5c198552-51dd-4214-994f-dd089ba0e1dc",
- "streamId": "MyConnection/Device301/Chiller-1/SAT",
- "status": "ENABLED",
- "type": "NUMBER",
- "metadata": {
- "unit": "%"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedAt": "2022-10-08T12:00:00Z",
- "pointMappings": null
}, - "tsStart": "2022-10-08T12:00:00Z"
}
]
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.
Writes history to Data Streams belonging to an Integration.
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 |
{- "data": {
- "2020-01-01T12:00:00": [
- {
- "streamId": "stream-id-1",
- "val": 1
}, - {
- "streamId": "stream-id-2",
- "val": "On"
}
], - "2021-01-01T12:00:00": [
- {
- "streamId": "stream-id-1",
- "val": 2.5
}, - {
- "streamId": "stream-id-2",
- "val": "Off"
}
]
}, - "tz": "Australia/Sydney",
- "source": "My first ingestion"
}
{- "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"
}
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.
Retrieves a list of Occurrences for a specific Equipment.
equipId required | string <uuid> Example: 0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d Unique identifier of the Equipment |
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 |
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 |
[- {
- "occurredOn": "2022-10-08",
- "times": [
- {
- "duration": 54000,
- "time": "12:00"
}
], - "description": "Bakery oven left on for 15h",
- "ruleId": "7404f7e2-4a5a-4362-bc6c-fcbaa792c546",
- "equipId": "0e366a9c-3b7c-4e4f-8da1-ad0fdfd40c3d"
}
]
Retrieves a list of Actions belonging to an Organisation, optionally filtered by the specified parameters.
organisationId required | string <uuid> Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7 Unique identifier of an Organisation |
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 |
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) |
[- {
- "id": 1234,
- "siteId": "8a7869df-6cad-4642-a015-9fbb36d3b337",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "summary": "Turn off the unit after hours",
- "description": "This unit should not run during after hours periods. The operating schedule of this unit should be adjusted accordingly.",
- "status": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "name": "To Be Quoted",
- "statusType": {
- "id": 2,
- "name": "In Progress"
}
}, - "severity": "Blocker",
- "type": "Maintenance",
- "team": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "name": "Bueno"
}, - "assignee": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "updatedAt": "2022-10-08T12:00:00Z",
- "closedAt": "2022-10-08T12:00:00Z",
- "attachments": [
- {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "name": "attachment.pdf",
- "actionId": 1234,
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "commentId": "9f1648db-ea2b-4e9a-b035-e5656d6e96c6",
- "createdBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "updatedAt": "2022-10-08T12:00:00Z"
}
], - "links": [
- {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "actionId": 1234,
- "name": "Link to a resource",
- "createdBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "updatedAt": "2022-10-08T12:00:00Z"
}
], - "targetRules": [
- {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "actionId": 1234,
- "targetId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "ruleId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "createdBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdAt": "2022-10-08T12:00:00Z"
}
], - "savings": [
- {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "actionId": 1234,
- "savingType": {
- "id": 12,
- "resource": "GAS",
- "unit": {
- "name": "kWh",
- "symbol": "kWh"
}
}, - "amount": 100,
- "createdBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "updatedAt": "2022-10-08T12:00:00Z"
}
]
}
]
Retrieves a list of Comments belonging to an Action.
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 |
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 |
[- {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "actionId": 1234,
- "comment": "This is a comment",
- "createdBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "updatedAt": "2022-10-08T12:00:00Z"
}
]
Retrieves a list of Attachments belonging to an Action.
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 |
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 |
[- {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "name": "attachment.pdf",
- "actionId": 1234,
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "commentId": "9f1648db-ea2b-4e9a-b035-e5656d6e96c6",
- "createdBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "updatedAt": "2022-10-08T12:00:00Z"
}
]
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.
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 |
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 |
[- {
- "id": 0,
- "actionId": 0,
- "organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
- "type": "string",
- "oldValue": "string",
- "newValue": "string",
- "updatedAt": "2019-08-24T14:15:22Z",
- "updatedBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "commentId": "ee0469af-2fa1-4b7e-b5f1-8e711a95821b",
- "linkId": "009f739c-6620-43b0-978e-b245e723c57a",
- "attachmentId": "96b9bbac-86d3-4497-9e0c-1f8e3803eddb",
- "savingId": "a6ba414f-b3ac-4e4f-906d-1ad38bc66a2e",
- "targetRuleId": "b4a0e2e0-e8ec-4a71-bf90-576736366e75",
- "oldStatusId": "12d45024-6365-40c8-a45a-b62efe613240",
- "newStatusId": "e0b462d6-c960-4b03-ab2f-720d9b15c039",
- "oldAssignee": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "newAssignee": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}
}
]
Retrieves a list of Status entities belonging to an Organisation. This list represents the Status that an Action can potentially have.
organisationId required | string <uuid> Example: 9f1748db-ea2b-4e9a-b035-e5757d7e97c7 Unique identifier of an Organisation |
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 |
[- {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "name": "To Be Quoted",
- "statusType": {
- "id": 2,
- "name": "In Progress"
}
}
]
Retrieves a list of Attachments belonging to an Action.
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 |
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 |
[- {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "name": "attachment.pdf",
- "actionId": 1234,
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "commentId": "9f1648db-ea2b-4e9a-b035-e5656d6e96c6",
- "createdBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "updatedAt": "2022-10-08T12:00:00Z"
}
]
Creates a new Attachment entity and saves the associated File.
file required | string <binary> The file to be uploaded as an attachment |
required | object |
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 |
{- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "name": "attachment.pdf",
- "actionId": 1234,
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "commentId": "9f1648db-ea2b-4e9a-b035-e5656d6e96c6",
- "createdBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "updatedAt": "2022-10-08T12:00:00Z"
}
Retrieves a single Attachment entity by its ID.
attachmentId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Attachment |
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 |
{- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "name": "attachment.pdf",
- "actionId": 1234,
- "organisationId": "9f1748db-ea2b-4e9a-b035-e5757d7e97c7",
- "commentId": "9f1648db-ea2b-4e9a-b035-e5656d6e96c6",
- "createdBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "createdAt": "2022-10-08T12:00:00Z",
- "updatedBy": {
- "id": "81b69082-bd4d-41e3-9fa2-a20d9f418599",
- "fullName": "John Doe"
}, - "updatedAt": "2022-10-08T12:00:00Z"
}
Retrieves the file of a single Attachment entity by its ID.
attachmentId required | string <uuid> Example: 5c198552-51dd-4214-994f-dd089ba0e1dc Unique identifier of the Attachment |
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 a list of supported weather metrics and their corresponding Unit and Unit System.
id | number Unique identifier of the Weather Metric |
name | string Name of the metric |
object (UnitProperty) Unit | |
unitSystem | string (UnitSystem) Enum: "METRIC" "USC" Unit system applied to response data |
[- {
- "id": 1,
- "name": "sea_level_pressure",
- "unit": {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0,
- "dimension": "kg1*m-1*sec-2"
}, - "unitSystem": "METRIC"
}
]
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.
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 |
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) |
ts | string <date-time> Timestamp of the History object |
val | number Value of the History object |
[- {
- "ts": "2022-10-08T04:23:00Z",
- "val": 1
}
]
Retrieves aggregated Weather Histories for a specific Weather Metric, Site, time period and aggregation interval which must be less than daily (sub-daily).
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 |
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 |
ts | string <date-time> Start timestamp of the History aggregate |
avg | number Default: null Average value in the period starting at the |
sum | number Default: null Sum of the values in the period starting at the |
min | number Default: null Minimum value in the period starting at the |
max | number Default: null Maximum value in the period starting at the |
count | integer <int16> Default: null Count of values in the period starting at the |
[- {
- "ts": "2022-10-08T04:00:00Z",
- "avg": 1,
- "sum": 1,
- "min": 1,
- "max": 1,
- "count": 1
}
]
Retrieves aggregated histories for a specific Weather Metric, Site, time period and aggregation interval of daily or higher.
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 |
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 |
ts | string <date> Start date of the History aggregate |
avg | number Default: null Average value in the period starting at 00:00 on the |
sum | number Default: null Sum of values in the period starting at 00:00 on the |
min | number Default: null Minimum value in the period starting at 00:00 on the |
max | number Default: null Maximum value in the period starting at 00:00 on the |
count | integer <int16> Default: null Count of values in the period starting at 00:00 on the |
[- {
- "ts": "2022-10-08",
- "avg": 1,
- "sum": 1,
- "min": 1,
- "max": 1,
- "count": 1
}
]
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).
siteId required | string <uuid> Example: 8a7869df-6cad-4642-a015-9fbb36d3b337 Unique identifier of the Site |
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 |
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.
|
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 ) |
[ ]
Units are attached to Points when required, to define the Unit of the History associated with that Point.
Units have the following properties:
name
symbol
type
scale
offset
Retrieve a list of supported Units.
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 |
[- {
- "id": 212,
- "name": "kilopascal",
- "symbol": "kPa",
- "type": "pressure",
- "scale": 1000,
- "offset": 0
}
]
Retrieves the currently logged in user's details.
id | string <uuid> Unique identifier of the User |
fullName | string Full name of the User |
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 |
{- "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
}
Where supported, Advanced Search provides a flexible way of searching for entities using expressions. The following is a comprehensive description of the fields and operators supported.
There are currently four supported searchable entities: Point, Equipment, Group and Site. Each entity type is searched for separately and has its own set of fields (called top-level fields) that can be used directly in the expression.
The following expression, for example, matches all points with the name equal to Zone Temp Sensor
, assuming it has
been applied in the context of points: name == "Zone Temp Sensor"
.
Here is the list of the supported top-level fields for each entity:
Entity | Top-level fields |
---|---|
Point | id, name, type, unit, unit.name, unit.symbol, stream |
Equipment | id, name |
Group | id, name |
Site | id, name, timezone, address, state, city, country, postcode, area, longitude, latitude |
These are the values defined in tags
, refs
or props
. They must be prefixed with the field name followed by a
dot (.
) and the key name. Some examples are: tags.zone
, refs.ahu
or props.maxFlow
.
Here are the supported dynamic fields for each entity:
Entity | Dynamic fields |
---|---|
Point | tags, refs, props |
Equipment | tags, refs, props |
Group | |
Site | tags, props |
These are the fields that exist on parent entities and are accessible via the entity prefix. Each entity has access
to all of its parents (for example, a point search can access its parent equip id via equip.id
).
Here are the supported parent reference groups for each entity:
Entity | Parent fields |
---|---|
Point | equip, group, site |
Equipment | group, site |
Group | site |
Site |
These are the fields that exist on linked entities and are accessible via the entity prefix.
When searching for Points, the stream
field can be used to find Points that have a currently mapped Data Stream with particular properties.
Note: Only the Data Stream that is the current mapping is supported. Older mappings are not supported.
Here are the supported Data Stream fields:
Field name | Description |
---|---|
streamId | Id of the Stream |
createdAt | Timestamp when the Stream was created |
updatedAt | Timestamp when the Stream was last updated |
tsStart | Timestamp at which the Stream mapping to the Point starts |
integration.name | Name of the Integration to which the Stream is attached to |
Writing a field on its own will check for the presence of that property if it is a dynamic field (tags
, refs
or props
), or will check if the field value is not null
for a top-level field. For example, the query tags.ahu
will check for the presence of the ahu
tag, whereas the query equip.name
will check that the name
field of the
parent equip exists and is not null
.
Operators can be used with top-level fields: props
and refs
(tags
can only be used on its own).
Here are the supported operators:
Operator | Symbol | Example |
---|---|---|
Equality | == | name == "AHU1" |
Regex Match | *= | name *= "AHU[0-9]{1}" |
Regex Case-insensitive Match | ~= | name ~= "ahu_f(.)+t" |
Greater than | > | props.maxFlow > 30 |
Greater than or equal | >= | props.maxFlow >= 30 |
Less than | < | props.maxFlow < 30 |
Less than or equal | <= | props.maxFlow <= 30 |
The regex operators *=
and ~=
allow matching fields against regular expressions. *=
performs a case-sensitive
regex match, while ~=
performs a case-insensitive match.
The regular expression syntax used is based on PCRE.
Some common regex syntax:
.
matches any single character*
matches zero or more of the preceding character or group+
matches one or more of the preceding character or group?
matches zero or one of the preceding character or group^
matches the start of the string$
matches the end of the string[...]
defines a character set, e.g. [aeiou]
matches any vowel(...)
defines a capturing groupa|b
matches either a
or b
For more help with the supported regular expression syntax, see the following Regular Expression tutorial and use Regex 101 (select flavour "PCRE2") to test your expressions.
The following Boolean operators are supported, all of which are case-insensitive:
Operator | Symbol | Example |
---|---|---|
And | AND | name == "AHU1" AND props.maxFlow > 30 |
Or | OR | name == "AHU1" OR props.maxFlow > 30 |
Not | NOT | NOT tags.ahu , NOT address == "1 Main St" |
Expressions can be enclosed in parentheses ( )
to enforce precedence.
e.g. (name == "AHU-1" AND props.ratedPower > 10) OR (tags.ahu AND NOT tags.fcu)
There are currently two types of literals supported: string and numeric.
String literals are expressed with double-quotes.
e.g. props.meterType == "Light and Power"
Ids are also expressed with double quotes.
e.g. id == "3cecf04f-0101-4f36-a3ff-d4822fa72f5b"
Numeric literals are expressed without quotes and can be either integer or decimal point numbers.
e.g. latitude > 35 AND latitude < 37.5
Find all Sites where name is equal to 123 Main St
or where postcode is 2000
and area is greater than 1000
:
name == "123 Main St" OR (postcode == "2000" AND area > 1000)
Find all Groups with the name CHWS
belonging to Sites in NSW
:
name == "CHWS" AND site.state == "NSW"
Find all Equipment which have an ahu
tag, a startOpHrs
property of 9am
and are referenced to a particular chilled
water loop:
tags.ahu AND props.startOpHrs == "9:00:00" AND refs.chilledLoops == "3cecf04f-0101-4f36-a3ff-d4822fa72f5b"
Find all Points with zone
but not sp
tags belonging to Equipment with an ahu
tag on the Site 100 High St
:
tags.zone AND NOT tags.sp AND equip.tags.ahu and site.name = "100 High St"
Find all Points with an Equip name that contains AHU
and a unit symbol of °C
:
equip.name *= "AHU" AND unit.symbol == "°C"
Find all Points with a name that contains temp
(case-insensitive) and a unit symbol of °C
or °F
:
name ~= "temp" AND (unit.symbol == "°C" OR unit.symbol == "°F")
Find all Points where the currently mapped Data Stream has a stream id containing Connector-123
:
stream.streamId ~= "Connector-123"
Find all Points where the Stream Integration name contains Default
:
stream.integration.name ~= "Default"
Find all Points where the current Data Stream Mapping starts on 2020-01-01
:
stream.tsStart ~= "2020-01-01"