BlueCold API

1 Introduction

1.1 Purpose of this document

This document describes the technical specifications of the APIs available as output from the BlueCold solution. They allow retrieval of all raw data related to the fleet of sensors and gateways managed by the user, as well as business information that may have been entered in BlueCold:

Device characteristics
Data generated by devices
Asset characteristics
Sensor / asset associations
Gateway characteristics

2 How the API works

2.1 General

All endpoints refer to a <base_url> parameter.

The URL used is: https://bluecold.elainnovation.com

2.2 Authentication

Obtaining an authentication token

POST <base_url>/api/auth/login

Payload:

{
  "username": "user@example.com",
  "password": "password"
}

Response:

{
  "token": "<ACCESS_TOKEN>",
  "refreshToken": "<REFRESH_TOKEN>"
}

Refreshing an existing token

If the user has already authenticated and holds an active token, the refreshToken field can be used to renew it:

POST <base_url>/api/auth/token

Payload:

{
  "refreshToken": "<REFRESH_TOKEN>"
}

Response:

{
  "token": "<ACCESS_TOKEN>",
  "refreshToken": "<REFRESH_TOKEN>"
}

Default validity periods

Token	Duration
Access Token (JWT)	2.5 hours (9,000 seconds)
Refresh Token	1 week (604,800 seconds)

The token must then be included in the Authorization header of subsequent requests, with the value:

Bearer <ACCESS_TOKEN>

Note: If the user has neither reconnected nor refreshed their token for more than one week, they will be required to re-authenticate.

2.3 Storage format description

BlueCold stores data in four formats, all linked to an entity (i.e. a beacon or an asset):

Format	Description	Example
Entity Info	Core characteristic data of the entity	Name
Attribute	Secondary data of the entity	ELA order number
Timeseries	Time-stamped historical data linked to a sensor	Temperature
Relations	Associations between sensors and assets	—

2.4 List of fields available via API

The table below summarises all fields available through the API, the format in which they are stored in BlueCold, and their field name. Users can query these fields by making a generic call on the entity infos, attributes, or timeseries of an entity, specifying the desired field name (last column).

Field	Sensor	Asset	Gateway	Stored as	Field name in BlueCold
MAC address / identifier	✓	✓	✓	Entity info	`name`
bluecold_id	✓	✓	✓	Entity info	`id`
Name	✓	✓	✓	Entity info	`label`
Sensor user group	✓			Attribute	`sensorGroupMember`
Gateway user group			✓	Attribute	`gatewayGroupMember`
Firmware version	✓			Attribute	`firmwareVersion`
Status	✓		✓	Attribute	`active`
ELA order number	✓		✓	Attribute	`order`
Date added to BlueCold	✓		✓	Attribute	`added`
Battery level	✓			Timeseries	`batteryLevel`
Last calibration date	✓			Attribute	`lastCalibrationDate`
Next calibration date	✓			Attribute	`nextCalibrationDate`
Active calibration certificate URL	✓			Attribute	`calibrationReportUrl`
Gateway type			✓	Attribute	`gatewayType`
Last gateway connection date			✓	Attribute	`lastConnectTime`
Last gateway disconnection date			✓	Attribute	`lastDisconnectTime`
Last gateway activity date			✓	Attribute	`lastActivityTime`
Asset association history		✓		Attribute	`assetHistory`
Sensor position list within the asset		✓		Attribute	`assetPositions`
Sensor data: sensor timestamp (see section 2.4.1)	✓			Timeseries	`sensorValue`
Sensor data: server timestamp (see section 2.4.1)	✓			Timeseries	`sensorValue_received`
Datalogger	✓			Timeseries	`datalogger`
Asset containing the sensor	✓			Relations	—
Sensors associated with the asset		✓		Relations	—

2.4.1 Sensor data timestamps

BlueCold provides two fields to retrieve sensor data:

sensorValue: sensor data timestamped at the moment the Bluetooth frame is scanned by the gateway. This allows reconstruction of a historical data timeline for the sensor.

{
  "sensorValue": [
    {
      "ts": 1751292795758,
      "value": "{\"type\":\"temperature_live\",\"value\":-5.12}"
    }
  ]
}

sensorValue_received: sensor data timestamped at the moment it is saved in the BlueCold platform. This allows retrieval of historical data as it becomes available. The value additionally contains the measuredTs field, which provides the original sensor measurement timestamp.

{
  "sensorValue_received": [
    {
      "ts": 1751292795758,
      "value": "{\"type\":\"temperature\",\"value\":26.87,\"measuredTs\":1751292785750}"
    }
  ]
}

2.5 Workflow example: initialising a third-party system

Authentication → Retrieve the JWT token for subsequent requests
List client devices
- Read bluecold ids, names and labels
List client assets
- Read bluecold ids, names and labels
For each device
- Read the bluecold id, name and label
- Read attributes
- Retrieve telemetry
- Resolve relation to the asset containing the device (if any)
For each asset
- Read the bluecold id, name and label
- Read attributes

3 API Reference

3.1 Device list (sensors and gateways)

3.1.1 Description

Lists all client devices and provides their bluecold_id, used for queries on a specific device.

3.1.2 URL

GET <base_url>/api/user/devices?pageSize=<page_size>&page=<page_num>

3.1.3 Parameters

Parameter	Description
`page_size`	Number of devices per page. Example: 100
`page_num`	Requested page number, starting at 0. Example: 0 (first page)

3.1.4 Response

{
  "data": [
    {
      "id": {
        "entityType": "DEVICE",
        "id": "<bluecold_id>"
      },
      "createdTime": 1751289432568,
      "tenantId": {
        "entityType": "TENANT",
        "id": "<tenant_id>"
      },
      "customerId": {
        "entityType": "CUSTOMER",
        "id": "<customer_id>"
      },
      "name": "<device_name>",
      "type": "default",
      "label": "",
      "deviceProfileId": null,
      "firmwareId": null,
      "softwareId": null,
      "externalId": null,
      "version": null,
      "ownerId": {
        "entityType": "CUSTOMER",
        "id": "<customer_id>"
      },
      "additionalInfo": {
        "gateway": false,
        "overwriteActivityTime": false,
        "description": ""
      },
      "deviceData": null
    }
  ],
  "totalPages": 15,
  "totalElements": 30,
  "hasNext": true
}

3.2 Asset list

3.2.1 Description

Lists all client assets and provides their bluecold_id, used for queries on a specific asset.

3.2.2 URL

GET <base_url>/api/user/assets?pageSize=<page_size>&page=<page_num>

3.2.3 Parameters

Parameter	Description
`page_size`	Number of assets per page. Example: 100
`page_num`	Requested page number, starting at 0. Example: 0 (first page)

3.2.4 Response

{
  "data": [
    {
      "id": {
        "entityType": "ASSET",
        "id": "<bluecold_id>"
      },
      "createdTime": 1751293508556,
      "tenantId": {
        "entityType": "TENANT",
        "id": "<tenant_id>"
      },
      "customerId": {
        "entityType": "CUSTOMER",
        "id": "<customer_id>"
      },
      "name": "<asset_name>",
      "type": "default",
      "label": null,
      "assetProfileId": null,
      "externalId": null,
      "version": null,
      "ownerId": {
        "entityType": "CUSTOMER",
        "id": "<customer_id>"
      },
      "additionalInfo": {
        "description": ""
      }
    }
  ],
  "totalPages": 1,
  "totalElements": 1,
  "hasNext": false
}

3.3 Historical data (timeseries)

3.3.1 Description

Provides access to the historical data of each device in BlueCold.

Note: There are no timeseries on the asset side.

3.3.2 URL

GET <base_url>/api/plugins/telemetry/DEVICE/<bluecold_id>/values/timeseries?keys=<telemetry_keys>&startTs=<start_ts>&endTs=<end_ts>

3.3.3 Parameters

Parameter	Description
`bluecold_id`	Unique internal device identifier, specific to BlueCold. See section 3.1. Note: this id is neither the NAME nor the MAC ADDRESS.
`telemetry_keys`	Names of the fields to retrieve, comma-separated. Example for a temperature sensor: `sensorValue` or `sensorValue_received`
`start_ts`	Start boundary of the time range. Format: UNIX milliseconds
`end_ts`	End boundary of the time range. Format: UNIX milliseconds
`limit`	(Optional) Maximum number of time-series data points to retrieve. Maximum: 50,000.
`orderBy`	(Optional) Sort order: `ASC` (ascending) or `DESC` (descending).

3.3.4 Response

{
  "sensorValue_received": [
    {
      "ts": 1751292795758,
      "value": "{\"type\":\"temperature\",\"value\":26.87,\"measuredTs\":1751292785750}"
    }
  ]
}

3.4 Attributes

3.4.1 Description

Provides access to the secondary characteristics (attributes) of each device in BlueCold.

3.4.2 URL

To retrieve attributes for a device:

GET <base_url>/api/plugins/telemetry/DEVICE/<bluecold_id>/values/attributes?keys=<attribute_keys>

A gateway is treated as a device. For example, to retrieve the user groups of a gateway:
GET <base_url>/api/plugins/telemetry/DEVICE/<bluecold_id>/values/attributes?keys=gatewayGroupMember

To retrieve attributes for an asset:

GET <base_url>/api/plugins/telemetry/ASSET/<bluecold_id>/values/attributes?keys=<attribute_keys>

3.4.3 Parameters

Parameter	Description
`bluecold_id`	Unique internal device identifier, specific to BlueCold. See section 3.1. Note: this id is neither the NAME nor the MAC ADDRESS.
`attribute_keys`	Names of the fields to retrieve, comma-separated. Example: `lastCalibrationDate,nextCalibrationDate`

3.4.4 Response

[
  {
    "lastUpdateTs": 1750668601047,
    "key": "lastCalibrationDate",
    "value": "2025-05-12"
  }
]

3.5 Relations

This API allows retrieval of the asset containing the current device (see workflow example).

3.5.1 URL

Query to retrieve the asset containing the current device:

GET <base_url>/api/relations?fromId=<bluecold_id_sensor>&fromType=DEVICE

Query to list the sensors contained within an asset:

GET <base_url>/api/relations?toId=<bluecold_id_asset>&toType=ASSET

3.5.2 Parameters

Parameter	Description
`bluecold_id_sensor`	Unique internal identifier of the device whose associated asset is being looked up. Note: this id is neither the NAME nor the MAC ADDRESS.
`bluecold_id_asset`	Unique internal identifier of the asset whose associated devices are being listed. Note: this id is neither the NAME nor the MAC ADDRESS.

3.5.3 Response

Response for fromType=DEVICE (asset containing the device):

[
  {
    "from": {
      "entityType": "ASSET",
      "id": "<bluecold_id_asset>"
    },
    "to": {
      "entityType": "DEVICE",
      "id": "<bluecold_id_sensor>"
    },
    "type": "Contains",
    "typeGroup": "COMMON",
    "version": 791355646,
    "additionalInfo": {
      "created": 123456789
    }
  }
]

Response for toType=ASSET (devices contained within the asset):

[
  {
    "from": {
      "entityType": "ASSET",
      "id": "<bluecold_id_asset>"
    },
    "to": {
      "entityType": "DEVICE",
      "id": "<bluecold_id_sensor>"
    },
    "type": "Contains",
    "typeGroup": "COMMON",
    "version": 791355646,
    "additionalInfo": {
      "created": 123456789
    }
  }
]

1 Introduction​

1.1 Purpose of this document​

2 How the API works​

2.1 General​

2.2 Authentication​

Obtaining an authentication token​

Refreshing an existing token​

Default validity periods​

2.3 Storage format description​

2.4 List of fields available via API​

2.4.1 Sensor data timestamps​

2.5 Workflow example: initialising a third-party system​

3 API Reference​

3.1 Device list (sensors and gateways)​

3.1.1 Description​

3.1.2 URL​

3.1.3 Parameters​

3.1.4 Response​

3.2 Asset list​

3.2.1 Description​

3.2.2 URL​

3.2.3 Parameters​

3.2.4 Response​

3.3 Historical data (timeseries)​

3.3.1 Description​

3.3.2 URL​

3.3.3 Parameters​

3.3.4 Response​

3.4 Attributes​

3.4.1 Description​

3.4.2 URL​

3.4.3 Parameters​

3.4.4 Response​

3.5 Relations​

3.5.1 URL​

3.5.2 Parameters​

3.5.3 Response​