The Bueno API is a collection of REST endpoints with JSON responses, for interacting with the site data model and associated histories.

Getting started

The building model

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, "equip": UUID}

Histories data

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 a 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 control

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

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

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

All requests must be authorised using your Bearer access token.

• HTTP authorisation scheme: bearer
• Bearer format: JWT

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.

A Site entity is the equivalent of a building in the physical world. A Site always belongs to an Organisation.

Each Site entity contains:

• Information related to the building location
• tags and props which are used to add extra context to the Site
• refs which specify which Organisation it belongs to

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

A Group entity belongs to a Site and is used to associate Equipment together within that Site.

A Group contains:

• name used to uniquely label the group
• siteId to identify the ID of the Site it belongs to

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

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.

The Equipment entity contains:

• tags which are strings used to describe the type of equipment
• types which are used to group particular type of equipment
• props which provide key value meta information
• refs to specify which Site and Organisation it belongs to
• deploymentId 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.

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.

The Point entity contains:

• type to describe if the point is a Number, Boolean or String
• unit (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 information
• refs to specify which Equipment, Site and Organisation it belongs to

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