Skip to main content

REST-API v1

Consibio Support Team
Updated

Notice

The Consibio Rest API described in this article (https://cloud.consibio.com/rest) is going to be replaced by the Consibio Cloud REST API v2 described in this article.

We recommend all new integrations to use the REST API v2 (https://api.v2.consibio.com/api-docs/) instead of the REST-API v1.

Background

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 or cellular 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://cloud.consibio.com/, 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.

This document describes how data in Consibio Cloud can be retrieved and updated using the Consibio Cloud REST API.


Figure 1: REST API overview

Overview

The base URL of the Consibio Cloud REST API is:

https://cloud.consibio.com/rest

The following REST endpoints are exposed from this base URL:

Endpoint Type Parameters Description
/login POST Login credentials formatted as plain text:
{
  "username": "<email>",
  "password": "<pwd>"
}		 Used to retrieve the auth token used for all other requests
/list_projects GET none List projects for given user.
/list_devices_in_project GET ?project_id=<project_id> List devices for a given project ID.
/list_elements_in_project GET ?project_id=<project_id> List all elements in a project with given ID.
/get_element_value GET ?project_id<project_id>
&element_id=<element_id>		 Get the current value of an element with given ID.
/get_datalog_for_element GET ?element_id=<element_id>
&project_id=<project_id>
&from_time=<unix_timestamp>
&to_time=<unix_timestamp>
&interval=<seconds>
 Get data from the datalog associated with a given element ID in a project with given ID.
/devices/<device_id>/telemetry PUT Device with ID <device_id> can send data to Consibio Cloud, if it’s preregistered. Contact Consibio at devices@consibio.com to obtain device account.

Telemetry data as JSON:
{
"id": "<element_id>",
"dp": [
{"t": <timestamp>, "v": <float>},
{"t": <timestamp>, "v": <float>},
...
]
}		 Send array of new datapoints for element with a given element ID. Each datapoint contains a time t and a floating point value v.

All the GET endpoints uses ID tokens to allow access to the API. This token should be provided in the http header in the format:

Authorization: Bearer {BEARER_TOKEN}

The token is retrieved from the /login endpoint, when correct credentials are provided in the login POST request.

API Endpoints

/login

Type: POST

Parameters

JSON-formatted credentials in plain text:

{
   "username": "<email>",
   "password": "<pwd>"
}
Return value
{
   "payload": {
      token: <ID_token>,
      user_id: <uid>,
      email: <user email>
      expires: <seconds until token expires>     
   },
   "status": "ok"
}

/list_projects

Type: GET

Parameters

None

Return value
{
   "payload": {
      "<project_id>":
         {"name": <project.name>},

       ... <additional entries ...
   },
   "status": "ok"
}
Example

Calling

/list_projects

returns:

{
   "payload": {
      "project_id1": {
         "name": "Project 1"
      },
      "project_id2": {
         "name": "Project 2"
      },
   },
   "status": "ok"
}

/list_devices_in_project

Type: GET

Parameters
<string> project_id
Return value
{
   "payload": {
      "<gw_id>":
         {
             "project_id": <project_id>,
             "type": <type and version of hardware>,
             "channels": <key-value map of all I/O channels configured for the device>,
             "versions": {
                 "cloud": <uuid of the config version registered in the cloud>,
                 "device": <uuid of the config version registered on the device>,
             },
             "last_version_publish": <unix timestamp in seconds when device last published it's configuration>,
         },

       ... <additional entries ...
   },
   "status": "ok"
}
Example

Calling

/list_devices_in_project?project_id=project_id1

returns:

{
    "payload": {
        "device_id1": {
            "type": "Battery IoT Connector v0.5",
            "project_id": "project_id1",
            "channels": {
                "i2c::T9602": {
                    "sub_channels": {
                        "RH": {
                            "config": {},
                            "element_id": "element_id1"
                        },
                        "temp": {
                            "element_id": "element_id2",
                            "config": {}
                        }
                    }
                }
            },
            "versions": {
                "device": "e84b7e37-10fe-43e4-902a-065dc9ecbef2",
                "cloud": "e84b7e37-10fe-43e4-902a-065dc9ecbef2"
            },
            "last_version_publish": 1660633424.013
        }
              ... <additional entries ...
    },
    "status": "ok"
}

/list_elements_in_project

Type: GET

Parameters
<string> project_id
Return value
{
   "payload": {
      "<element_id>":
         {
            "name": "<element name>",
            "element_type": “<’monitor’ or ‘actuator’>",
            "unit": "<unit>",
            "type": "<type of sensor or actuator>",
            "color": "<hex color code>",
            "description": "<Description of the element>",
            "sigDigits": <integer with number of significant digits>,
            "telemetry": {
                "cur_val": {
                    "val": <current datapoint value of the element>,
                    "time": <unix timestamp in seconds for datapoint>},
                "last_val": {
                    "val": <last datapoint value of the element>,
                    "time": <unix timestamp in seconds for last datapoint>},
                }
            }
         },

              ... <additional entries ...
   },
   "status": "ok"
}
Example

Calling

/list_elements_in_project?project_id=project_id1

returns:

{
   "payload": {
      "element_id1":
         {
            "name": Temp sensor",
            "element_type": “monitor",
            "unit": "C",
            "type": "temp",
            "color": "#950000",
            "description": "The indoor air temperature",
            sigDigits: 2
         },
      "element_id2":
         {
            "name": RH sensor",
            "element_type": “monitor",
            "unit": "%",
            "type": "RH",
            "color": "#5349A8",
            "description": "The indoor relative humidity",
            sigDigits: 1
         },
              ... <additional entries ...
   },
   "status": "ok"
}

/get_element_value

Type: GET

Parameters
<string> element_id, <string> project_id
Return value
{
   "payload": {
      "val": <current output value of the element>,
      "time": <unix timestamp in seconds when latest value was recorded>
   },
   "status": "ok"
}
Example

Calling

/get_element_value?project_id=project_id1&element_id=element_id1

returns:

{
   "payload": {
      "val": 22.12,
      "time": 1588845438.102
   },
   "status": "ok"
}

/get_datalog_for_element

Type: GET


Description
Get data from the datalog associated with a given element ID in a project with given ID.

Parameters
Name Type Optional/Required Description
element_id <string> required Element ID to retrieve values from.
project_id <string> required ID of the project, that the element is associated to.
to_time <float> required A datalog will be returned with values until this UNIX timestamp (in seconds).
from_time <float> required A datalog will be returned with values from this UNIX timestamp (in seconds).
interval <float> optional

Default: 0.0		 Desired interval (in seconds) between datapoints. Returns all stored values, if interval=0.0 or if interval is lower than the logging interval set for the element (can be configured in the Consibio Web App). If the interval is larger than the log interval, then a mean of the values in the given interval will be returned.
Return value
{
   "payload": [
      {
         "val": <Recorded value of element_id at time "time">,
         "time": <unix timestamp in seconds when the value was recorded>
      },
              ... <additional entries ...
   ],
   "status": "ok"
}
Example

Calling

/get_datalog_for_element?element_id=element_id1&project_id=project_id1 &from_time=1588845438.0&to_time=1588846638.0&interval=3600.0

returns:

{
   "payload": [
      {
         "val": 22.12,
         "time": 1588845438.102
      },
      {
         "val": 23.41,
         "time": 1588849038.200
      },
      {
         "val": 24.97,
         "time": 1588852638.904
      },
   ],
   "status": "ok"
}

 

/devices/<device_id>/telemetry

Type: PUT

Description
Used by devices to publish telemetry data to Consibio Cloud via the REST API. Note that the device with ID=<device_id> for security reasons must be preregistered with a password-based device account on:
<device_id>@devices.consibio.com

It will be soon be possible to register devices in the web app, but until then you must contact Consibio at devices@consibio.com to obtain device credentials.

When the device is registered with a valid account, data can be sent, by:

  1. Obtaining a bearer token using the /login endpoint.
  2. Pushing JSON-based timestamped datapoints for each element id to the telemetry endpoint with the bearer token in the auth header.

Example
Calling:

/devices/device_id1/telemetry

with a valid auth token in the header and a JSON-formatted json payload of:

{
  "id": "element_id1",
  "dp": [
    {"t": 1588845438.15, "v": 22.12},
    {"t": 1588845442.91, "v": 23.97},
    {"t": 1588845493.41, "v": 24.15},
  ]
}

returns:

{"status": "ok"}

and the value will be available in Consibio Cloud in the datalogs, usable by automation rules, alarms in widgets etc. just like any other element.

Related articles