Consentium IoT Sensor Data API — Developer Documentation v2

The Consentium IoT API enables IoT devices to send telemetry (sensor readings, firmware/device status) to the cloud and allows applications to retrieve historical and real-time data for monitoring, analytics, or automation.

Base URL


https://api.consentiumiot.com

Authentication & Access Control

Every request requires authentication keys provided at board registration:

sendKey → Used for write operations (sending or updating sensor data).
receiveKey → Used for read operations (retrieving sensor data).
boardKey → Unique identifier for a virtual board.

⚠️ Important:

Keep your keys secret. Treat them like passwords.
Use HTTPS at all times to avoid exposing credentials.

Quickstart Guide

1. Submit Data (POST)

cURL Example

curl -X POST "https://api.consentiumiot.com/v2/updateData?sendKey=<YOUR-SEND-KEY>&boardKey=<YOUR-BOARD-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "sensors": {
      "sensorData": [
        { "info": "Temperature", "data": "40.00" },
        { "info": "Humidity", "data": "90.00" }
      ]
    },
    "boardInfo": {
      "firmwareVersion": "0.0",
      "architecture": "ESP32",
      "statusOTA": false,
      "deviceMAC": "DD:DA:0C:20:E1:41",
      "signalStrength": -30
    }
  }'

Postman Example

Method: POST

URL:

https://api.consentiumiot.com/v2/updateData?sendKey=<YOUR-SEND-KEY>&boardKey=<YOUR-BOARD-KEY>

Headers: Content-Type: application/json

Body (raw JSON):

{
  "sensors": {
    "sensorData": [
      { "info": "Temperature", "data": "40.00" },
      { "info": "Humidity", "data": "90.00" }
    ]
  },
  "boardInfo": {
    "firmwareVersion": "0.0",
    "architecture": "ESP32",
    "statusOTA": false,
    "deviceMAC": "DD:DA:0C:20:E1:41",
    "signalStrength": -30
  }
}

2. Get Historical Data (GET)

cURL Example

curl "https://api.consentiumiot.com/getData?receiveKey=<YOUR-RECEIVE-KEY>&boardKey=<YOUR-BOARD-KEY>"

Postman Example

Method: GET

URL:

https://api.consentiumiot.com/getData?receiveKey=<YOUR-RECEIVE-KEY>&boardKey=<YOUR-BOARD-KEY>

3. Get Most Recent Data (GET)

cURL Example

curl "https://api.consentiumiot.com/getData?recents=true&receiveKey=<YOUR-RECEIVE-KEY>&boardKey=<YOUR-BOARD-KEY>"

Postman Example

Method: GET

URL:

https://api.consentiumiot.com/getData?recents=true&receiveKey=<YOUR-RECEIVE-KEY>&boardKey=<YOUR-BOARD-KEY>

Endpoints Overview

HTTP Method

Endpoint

Purpose

POST

/v2/updateData

Submit or update telemetry data for a board.

GET

/getData

Retrieve all historical data feeds for a board.

GET

/getData?recents=true

Retrieve only the most recent feed(s).

1. Submit / Update Sensor Data

Endpoint

POST /v2/updateData?sendKey=<YOUR-SEND-KEY>&boardKey=<YOUR-BOARD-KEY>

Description

Used by IoT boards or edge devices to push telemetry data to the Consentium IoT platform.

Each update includes:

Sensor readings → flexible key-value structure.
Board metadata (boardInfo) → mandatory information about the device’s state and identity.

Request Body

{
  "sensors": {
    "sensorData": [
      {
        "info": "Temperature",
        "data": "40.00"
      },
      {
        "info": "Humidity",
        "data": "90.00"
      }
    ]
  },
  "boardInfo": {
    "firmwareVersion": "0.0",
    "architecture": "ESP32",
    "statusOTA": false,
    "deviceMAC": "DD:DA:0C:20:E1:41",
    "signalStrength": -30
  }
}

Response

200 OK

{
  "status": "success",
  "message": "Sensor data updated successfully"
}

Error Codes

422 Unprocessable Entity → Missing required boardInfo fields.
429 Too Many Requests → MAC address mismatch (board vs. physical device).
400 Bad Request → Malformed JSON or missing parameters.
401 Unauthorized → Invalid sendKey.

2. Get Historical Data

Endpoint

GET /getData?receiveKey=<YOUR-RECEIVE-KEY>&boardKey=<YOUR-BOARD-KEY>

Description

Fetch all stored feeds for a board. Each feed entry maps infoN (sensor name) to valueN (sensor reading).

Response

{
  "board": {
    "info1": "Temperature",
    "info2": "Humidity",
    "name": "Test board2"
  },
  "feeds": [
    {
      "updated_at": "2025-09-05T14:20:56.914801Z",
      "value1": 40.0,
      "value2": 90.0
    },
    {
      "updated_at": "2025-09-05T13:59:22.101432Z",
      "value1": 39.5,
      "value2": 88.0
    }
  ]
}

3. Get Most Recent Data

Endpoint

GET /getData?recents=true&receiveKey=<YOUR-RECEIVE-KEY>&boardKey=<YOUR-BOARD-KEY>

Description

Returns only the most recent feed entry for a board.

Response

{
  "board": {
    "info1": "Temperature",
    "info2": "Humidity",
    "name": "Test board2"
  },
  "feeds": [
    {
      "updated_at": "2025-09-05T14:20:56.914801Z",
      "value1": 40.0,
      "value2": 90.0
    }
  ]
}

Base Endpoint

GET /getData?receiveKey=<RECEIVE_KEY>&boardKey=<BOARD_KEY>

5. Time-Range Slicing (Grafana Compatible)

Consentium API supports proper ISO-8601 UTC format:

YYYY-MM-DDTHH:mm:ss.SSSZ

Example

https://api.consentiumiot.com/getData?recents=false&receiveKey=<KEY>&boardKey=<KEY>&from=2025-11-18T08:30:21.000Z&to=2025-11-18T10:00:21.000Z

Grafana Integration Guide

Using the Infinity Plugin

1. Install Infinity Plugin

Go to Connections → Plugins
Search "Infinity"
Install & enable

2. Add Data Source

Data Sources → Add New
Select Infinity
Set:
- Access: Server
- Method: GET

3. Use Time-Range Query URL

https://api.consentiumiot.com/getData?recents=false&receiveKey=<YOUR_RECEIVE_KEY>&boardKey=<YOUR_BOARD_KEY>&from=${__from:date:YYYY-MM-DDTHH:mm:ss.SSSZ}&to=${__to:date:YYYY-MM-DDTHH:mm:ss.SSSZ}

Why Z? This ensures Grafana formats timestamps in pure UTC, avoiding timezone issues.

4. Recommended Infinity Settings

Setting

Value

Query Type

URL

Parse As

JSON

Format

Table / Time Series

Method

GET

5. Field Mapping in Grafana

Column

JSON Path

Time

feeds[].updated_at

Value 1

feeds[].value1

Value 2

feeds[].value2

…

Additional sensor indexes

Suggested transforms:

Extract Fields
Organize Fields
Convert to Time Series (Wide)
Rename Fields to match sensor names

Timestamp Specification

All timestamps returned by the Consentium API are:

UTC
ISO-8601 format
Always end with Z

Examples:

2025-09-05T14:20:56.914801Z
2025-10-01T06:12:30.000Z

Error Handling

The API uses standard HTTP status codes:

Status Code

Meaning

Example Scenario

200 OK

Success

Data retrieved or updated successfully.

400 Bad Request

Invalid request

Malformed JSON, missing params.

401 Unauthorized

Invalid/missing key

Wrong sendKey or receiveKey.

404 Not Found

Board not found

Invalid boardKey.

422 Unprocessable Entity

Validation error

Missing required boardInfo field.

429 Too Many Requests

MAC mismatch

Board’s virtual key doesn’t match reported MAC.

Best Practices

Rate limiting: Avoid excessive calls. Implement exponential backoff for retries.
Secure your keys: Never expose sendKey or receiveKey in client-side code.
Validate data locally: Ensure correct sensor units, numeric ranges, and field consistency.
Use device MAC correctly: Each virtual board is tagged with its physical MAC. Mismatches will be rejected.
Timestamp awareness: All timestamps are returned in UTC (ISO 8601 format).

Changelog

v2 (Current)
- Introduced boardInfo block (mandatory).
- MAC address validation enforced.
- Unified getData responses into board + feeds structure.
v1 (Deprecated)
- Sensor data posted without boardInfo.
- Simple array responses instead of structured board metadata.

PreviousConsentium IoT Platform usage NextConsentium IoT Sensor Data API — Developer Documentation v1 (depricated)

Last updated 2 months ago

hashtagBase URL

hashtagAuthentication & Access Control

hashtagQuickstart Guide

hashtag1. Submit Data (POST)

hashtag2. Get Historical Data (GET)

hashtag3. Get Most Recent Data (GET)

hashtagEndpoints Overview

hashtag1. Submit / Update Sensor Data

hashtagEndpoint

hashtagDescription

hashtagRequest Body

hashtagResponse

hashtagError Codes

hashtag2. Get Historical Data

hashtagEndpoint

hashtagDescription

hashtagResponse

hashtag3. Get Most Recent Data

hashtagEndpoint

hashtagDescription

hashtagResponse

hashtag5. Time-Range Slicing (Grafana Compatible)

hashtagExample

hashtagGrafana Integration Guide

hashtag1. Install Infinity Plugin

hashtag2. Add Data Source

hashtag3. Use Time-Range Query URL

hashtag4. Recommended Infinity Settings

hashtag5. Field Mapping in Grafana

hashtagTimestamp Specification

hashtagError Handling

hashtagBest Practices

hashtagChangelog

Base URL

Authentication & Access Control

Quickstart Guide

1. Submit Data (POST)

2. Get Historical Data (GET)

3. Get Most Recent Data (GET)

Endpoints Overview

1. Submit / Update Sensor Data

Endpoint

Description

Request Body

Response

Error Codes

2. Get Historical Data

Endpoint

Description

Response

3. Get Most Recent Data

Endpoint

Description

Response

5. Time-Range Slicing (Grafana Compatible)

Example

Grafana Integration Guide

1. Install Infinity Plugin

2. Add Data Source

3. Use Time-Range Query URL

4. Recommended Infinity Settings

5. Field Mapping in Grafana

Timestamp Specification

Error Handling

Best Practices

Changelog