Pulling datalogs with the REST API

This walks through the most common REST API integration: pulling historical datalogs out of Consibio Cloud on a per-location basis, so you can save them into another system.

For the full endpoint reference, see the interactive API documentation: https://api.v2.consibio.cloud/api-docs/.

Terminology

• Device (also called a gateway) — the physical IoT hardware deployed on site. It communicates with sensors or actuators (like relays, pumps and valves) over a wired connection, and relays data to Consibio Cloud over Wi-Fi, cellular or satellite.
• Element — a sensor or actuator value. One device can provide values for several elements.
• Location — a group of devices and elements at a physical site.
• Project — the top-level container for devices, elements and locations. User access and authorization is managed at the project level.

One-time setup

Register a service account

To call the API, you need a user account with access to the resources you want to read. You can use your personal Consibio Cloud account for testing, but for a real integration you should register a dedicated service account — for example service-account@your-domain.com — by signing up at https://v3.consibio.cloud/signup. You’ll need to verify the account, so use an email address you can receive the verification email at.

Grant the service account access to the project

While logged in as a user who already has access to the project:

1. Open the Users view from the main menu.
2. Select Add user to project.
3. Enter the service account’s email and choose a role — Viewer is enough if the account will only read data.
4. Select Send invite.

The service account now has access to the project at the chosen role.

Get the project ID

Open the project in Consibio Cloud — the project ID is in the browser’s address bar:

https://v3.consibio.cloud/projects/<project_id>/devices

Save this ID; you’ll use it in every API call for this project.

Pulling a datalog

1. Authenticate

Request a token from the login endpoint with the service account’s credentials:

curl -s -X POST https://api.v2.consibio.cloud/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"service-account@your-domain.com","password":"secret123"}'

This returns:

{
    "status": "ok",
    "payload": {
        "token": "your_access_token_here",
        "user_id": "your_user_id_here",
        "email": "service-account@your-domain.com",
        "expires": 1679003040
    }
}

Include the token in the Authorization header of every subsequent request:

Authorization: Bearer <your_access_token>

2. List locations in the project

curl -s https://api.v2.consibio.cloud/projects/<project_id>/locations \
  -H 'Authorization: Bearer <your_access_token>'

This returns the locations in the project, keyed by location ID:

{
    "status": "ok",
    "payload": {
        "<location_id_1>": {
            "name": "Consibio Headquarter",
            "location": {"latitude": 56.208, "longitude": 10.217},
            "type": "sewer-manhole",
            "parameters": {"<parameter_type_1>": "<element_id_1>"}
        }
    }
}

3. Request datalogs for a location

For each location ID, request everything related to that location over a time range:

curl -s "https://api.v2.consibio.cloud/projects/<project_id>/locations/<location_id>/all?from_time=<unix_timestamp>&to_time=<unix_timestamp>" \
  -H 'Authorization: Bearer <your_access_token>'

from_time and to_time are Unix timestamps in seconds. The response includes the location’s devices, elements, alarms, virtual sensors, and a datalogs object keyed by element ID:

{
    "status": "ok",
    "payload": {
        "datalogs": {
            "element_id_1": [
                {"t": 1751650800, "v": 10.2},
                {"t": 1751651100, "v": 15.1}
            ]
        }
    }
}

Use the datalogs object for historical data over the requested period, or the elements object for each element’s most recent measurement.

Next steps

For an overview of authentication options and the full endpoint list, see Consibio Cloud API. To try this out without real hardware, see Testing the REST API with a demo project.

Support

Questions about the REST API? Contact support@consibio.com.