The Consibio Cloud REST API v2 enables easy access to data stored in Consibio Cloud. Typically, our users interact with the data provided by Consibio Equipment through our user interface at consibio.cloud. However, if the users want to extract the data into their own systems, we've that possible through our Consibio Cloud REST API v2.
The point of such an API is to provide a way for developers to retrieve, manipulate, and utilize data programmatically. Ou API can facilitate seamless communication and integration between different software systems and platforms, regardless of the underlying technologies, enabling interoperability and data exchange.
In this article, you will find relevant links to our documentation and an introduction to our terminology related to the data that is available from our REST endpoints.
Link to Swagger Documentation
For easy integration of data to your services, we've made the documentation compliant with the latest OAS version 3.1. A link to the API documentation in a Swagger type development environment can be found here:
https://api.v2.consibio.cloud/api-docs/
Parameter description / terminology
The basic structure of the Consibio system is depicted in Figure 1. We work with IoT devices, that are deployed on site – these are interchangeably referred to as devices or gateways. A device communicates with sensors or actuators (like relays, pumps and valves) over a wired connection and relays all relevant data to the Consibio Cloud through either a WiFi, cellular or Satelite connection. All signal processing and interfacing electronics required for interfacing the sensors or actuators are embedded in the devices.
In Consibio Cloud, all sensors and actuators are collectively referred to as elements. Thus, one device/gateway can provide values for several elements to the Cloud. Furthermore, devices and elements are grouped into projects in the Cloud. User management and authorization works on the project level.
Users login to the Consibio Cloud web app via https://consibio.cloud/, where they have access to real-time visualizations of current state of data, datalogs over time, possibility to setup control rules, alarm systems, real-time analytics and more. Whenever a control rule is defined in the Cloud, it is automatically synced to the relevant device, which in turn effectuates the control logic between the appropriate sensor and actuators.
For an overview of how data is transferred to the user and via. the REST API v2, see Figure 1:
Figure 1: REST API v2 overview
Example usage: Pull datalogs from Consibio Cloud
Often, the REST API is used to pull historical datalogs from Consibio Cloud to save it in another system. The steps below outline how to achieve that on a per-location basis.
One-time steps during setup
First, you need to register a service account and get the Consibio Cloud project ID. This should only be done once.
Register a service account
When calling the API, you need to make the call from a user that has access to the requested ressources. It is possible to use your personal Consibio Cloud account with the API but we only recommend doing that for testing purposes.
For a real integration, you should register a service account by going to:
and registering a new account.
Service accounts are usually called service-account@your-domain.com or similar.
Note that you need to verify the account to get access, so it should be an email address, where you can access the verification email sent to it after signup (either directly or by a catch-all setup on your domain).
Grant the service account access to the desired Consibio Cloud projects
While logged into a user, that already has access to the desired project, go to the project and click on the "Users" tab (1) in the main menu:
Then click "Add user to project" (2). In the dialog, type the service account email (3) and select an appropriate role (4). If the service account is only used to pull out data, it should be "viewer". The role can also be changed later. Finally, click "Send invite" (5).
The service account now has read access to the given Consibio Cloud project.
Grab the Consibio Cloud project id
When calling the API, you request data from the desired project based on the Project ID. If you open a project in Consibio Cloud, the project id is listed in the URL of the browser, for example:
https://consibio.cloud/projects/<project_id>/devices
Save this project ID for use in each API call.
Steps to perform for each datalog request
Now you are ready to make a request to Consibio Cloud's REST API. As outlinted in the Swagger Docs: https://api.v2.consibio.cloud/api-docs/ there are many endpoints and multiple ways to extract the data you want.
The most common approach is to extract data for each location created in Consibio Cloud. That approach is outlined below
1. Authentication: Request new token (if expired)
First, you need to authenticate. To do that, you make a POST request to the https://api.v2.consibio.cloud/login endpoint with the username and password in the body:
{
"username": "service-account@your-domain.com",
"password": "secret123"
}
On success, this returns a payload, that contains a bearer token:
{
"payload": {
"token": "your_access_token_here",
"user_id": "your_user_id_here",
"email": "service-account@your-domain.com",
"expires": 1679003040
},
"status": "ok"
}
This bearer token should be included in the Authorization header of all subsequent requests as such:
| Key | Value |
Authorization |
Bearer <your_bearer_token> |
2. List locations in the project
Next, you list all the locations in the Consibio Cloud project with a GET request to this endpoint (where you replace project_id with your Project ID:
https://api.v2.consibio.cloud/projects/<project_id>/locations
This will only succeed, if you includede the Bearer token and remembered to grant the service account access to the given project.
On success, this returns a JSON payload with all the locations in this project:
{
"status": "ok",
"payload": {
"<location_id_1>": {
"name": "Consibio Headquarter",
"location": {
"latitude": 56.20832571382255,
"longitude": 10.217640774628872
},
"type": "sewer-manhole",
"parameters": {
"<parameter_type_1>": "<element_id_1>",
"<parameter_type_2>": "<element_id_2>"
},
},
"<location_id_2>": {
"location": {
"latitude": 56.20832571382255,
"longitude": 10.217640774628872
},
"type": "manhole",
"parameters": {
"<parameter_type_1>": "<element_id_1>",
"<parameter_type_2>": "<element_id_2>"
},
"name": "Another Location"
}
}
}
There are 2 location IDs in the returned payload in this example:
location_id_1 and location_id_2
We use these in the step 3.
3. Request datalogs for a specified duration for each location
For each of the returned Location IDs, we then call this endpoint to get all information and data related to that location:
Note that this call includes two timestamps: from_time and to_time (UNIX timestamps in seconds) which define for which period, the datalogs will be queried.
This returns a payload with info on:
- The location itself.
- All devices at that location.
- All elements (ie. data tags) on that location
- Datalogs for each element in the requested period
- Any alarms
- Any Virtual Sensors (ie. calculation rules)
The payload is of the form:
{
"status": "ok",
"payload": {
"devices": {
"device_id_1": {<device_details>}
},
"location": {<location_details>},
"elements": {
"element_id_1": {<element_details>}
},
"datalogs": {
"element_id1": [
{"t": 1751650800, "v": 10.2},
{"t": 1751651100, "v": 15.1},
{"t": 1751651400, "v": 22.0},
{"t": 1751651700, "v": 9.4}
]
},
"alarms": {
"alarm_id_1": {<alarm_details>},
"alarm_id_2": {<alarm_details>}
},
"virtual_sensors": {
"virtual_sensor_id_1": {<virtual_sensor_details>}
}
}
}
If you are only interested in the historical data in the requested period, you can look at the "datalogs" object. If you want the most recent measurements, they are listed under the "elements" object.
The full payload is shown in the Swagger Docs for the endpoint.