BlueCold API

This documentation 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

General information

All endpoints refer to a <base_url> parameter.

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

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.

Key concepts

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	—

Customer Hierarchy

Customer: Top-level account holder (e.g., "Logistics Corp France")
Sub-customer: Hierarchical child account (e.g., "Logistics Corp - Lyon branch")
- Sub-customers inherit permissions from parent customer
- API parameter fetchSubCustomerDevices=true includes child devices
Device: Physical BLE beacon (sensor or gateway)
Asset: Business entity containing multiple devices (e.g., shipping pallet, container)

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 4.1)	✓			Timeseries	`sensorValue`
Sensor data: server timestamp (see section 4.1)	✓			Timeseries	`sensorValue_received`
Datalogger	✓			Timeseries	`datalogger`
Asset containing the sensor	✓			Relations	—
Sensors associated with the asset		✓		Relations	—

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}"
    }
  ]
}

Key insight

Use sensorValue for timeline reconstruction (when was the temperature measured), use sensorValue_received for publication (when was the data saved in BlueCold).

API Reference

Device list (sensors and gateways)

Description

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

URL

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

Parameters

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

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
}

Asset list

Description

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

URL

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

Parameters

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

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
}

Historical data (timeseries) per device

Description

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

info

Note: There are no timeseries on the asset side. Design: This endpoint retrieves timeseries for a single device. Suitable for on-demand lookups or dashboards.

Scalability

Do not use for systematic polling of multiple devices or feeding external systems. Each device requires a separate request, leading to:

High API call volume and rate-limit exhaustion
Network overhead and latency accumulation
Inefficient resource utilization

For large-scale ingestion: Use the bulk telemetry export endpoints in section 6 instead.

URL

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

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).

Response

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

Attributes

Description

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

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>

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`

Response

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

Relations

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

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

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.

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
    }
  }
]

Historical data (timeseries) per client / per asset

Description

Note: Use these endpoints for large scale data ingestion

The process operates asynchronously: you initiate an export request, periodically check its status, then download the generated CSV file.

Flow Architecture

Export request                       Status polling               Download
(per client or per asset)  ──────→  (5→15 min poll)  ───────→  (CSV downloadUri)
      ↓                                   ↓                           ↓
   Job created                      Awaits COMPLETED              File retrieved
   → jobId + statusUrl                 or FAILED                  → Parse + Ingest

Complete cycle:

Initiate an export (customer or asset)
Wait for the job to complete (status = COMPLETED or FAILED)
Download and process the CSV file

Initiate an export for all devices of a customer

Endpoint: POST /api/custom/customer/{customerId}/devices/telemetry/export

Query Parameters:

Parameter	Type	Required	Description
`telemetryKey`	string	✅	Telemetry key to export (one per request)
`startTs`	number	✅	Start timestamp, in milliseconds
`endTs`	number	✅	End timestamp, in milliseconds
`fetchSubCustomerDevices`	boolean	❌	If `true`, includes devices from sub-customers (default: `false`)

Constraints:

The time window (endTs - startTs) cannot exceed 30 minutes
Only one telemetryKey per request (e.g., sensorValue_received)

Response (200 OK):

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "statusUrl": "https://<base_url>/api/custom/telemetry/export/550e8400-e29b-41d4-a716-446655440000"
}

cURL Example:

curl -X POST "https://<base_url>/api/custom/customer/bfd9c220-ad9c-4649-8063-c1c612f8bd60/devices/telemetry/export?telemetryKey=sensorValue_received&startTs=1234567890000&endTs=1234568490000"

Initiate an export for all devices contained in an asset

Endpoint: POST /api/custom/asset/{assetId}/devices/telemetry/export

Query Parameters:

Parameter	Type	Required	Description
`telemetryKey`	string	✅	Telemetry key to export
`startTs`	number	✅	Start timestamp, in milliseconds
`endTs`	number	✅	End timestamp, in milliseconds

Constraints:

The asset must be owned by the current customer or one of its sub-customers
Only devices with a Contains (To) relation to the asset will be included
Same 30-minute maximum window

Response (200 OK):

{
  "jobId": "550e8400-e29b-41d4-a716-446655440001",
  "statusUrl": "https://<base_url>/api/custom/telemetry/export/550e8400-e29b-41d4-a716-446655440001"
}

cURL Example:

curl -X POST "https://<base_url>/api/custom/asset/6b26482f-04bd-476d-8b7c-bf138cd483d5/devices/telemetry/export?telemetryKey=sensorValue_received&startTs=1234567890000&endTs=1234568490000"

Check export job status

Endpoint: GET /api/custom/telemetry/export/{jobId}

Parameters:

Parameter	Type	Description
`jobId`	string	UUID returned during initialization

Response (200 OK):

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "createdAt": 1783497112000,
  "completedAt": null,
  "rowCount": null,
  "error": null,
  "telemetryKey": "sensorValue_received",
  "downloadUrl": "https://<base_url>/api/custom/telemetry/export/550e8400-e29b-41d4-a716-446655440000/file"
}

Possible status values:

PENDING – Job is processing
COMPLETED – Export completed successfully, rowCount contains the number of data points
FAILED – Error during export, error contains the error message

cURL Example:

curl -X GET "https://<base_url>/api/custom/telemetry/export/550e8400-e29b-41d4-a716-446655440000"

Download export file

Endpoint: GET /api/custom/telemetry/export/{jobId}/file

Parameters:

Parameter	Type	Description
`jobId`	string	UUID of the export job (from status response)

Response:

Content-Type: text/csv
Body: CSV file with columns deviceId;ts;value

⚠️ Important: Only download if status == "COMPLETED"

cURL Example:

curl -X GET "https://<base_url>/api/custom/telemetry/export/550e8400-e29b-41d4-a716-446655440000/file" \
  -o telemetry_export.csv

Exported CSV File Format

The file uses semicolon ; as separator (default).

Structure:

deviceId;ts;value

Columns:

Column	Type	Description
`deviceId`	string	Internal device ID in BlueCold
`ts`	number	UNIX timestamp in milliseconds
`value`	mixed	Scalar value or JSON object (e.g., `{"type":"temp","value":15.17}`)

Example:

deviceId;ts;value
dde95d0-752c-11f1-8ba9-137c6080ee3d;1783410434081;"{""type"":""temperature_minidatalogger"",""value"":15.17}"
dde95d0-752c-11f1-8ba9-137c6080ee3d;1783410448838;"{""type"":""temperature_minidatalogger"",""value"":15.21}"

Notes:

Complex JSON values are serialized as strings
Timestamps are always in milliseconds (multiply by 1000 if seconds are needed)

General information​

Authentication​

Obtaining an authentication token​

Refreshing an existing token​

Default validity periods​

Key concepts​

Storage format description​

Customer Hierarchy​

List of fields available via API​

Sensor data timestamps​

API Reference​

Device list (sensors and gateways)​

Description​

URL​

Parameters​

Response​

Asset list​

Description​

URL​

Parameters​

Response​

Historical data (timeseries) per device​

Description​

URL​

Parameters​

Response​

Attributes​

Description​

URL​

Parameters​

Response​

Relations​

URL​

Parameters​

Response​

Historical data (timeseries) per client / per asset​

Description​

Flow Architecture​

Initiate an export for all devices of a customer​

Initiate an export for all devices contained in an asset​

Check export job status​

Download export file​

Exported CSV File Format​

General information

Authentication

Obtaining an authentication token

Refreshing an existing token

Default validity periods

Key concepts

Storage format description

Customer Hierarchy

List of fields available via API

Sensor data timestamps

API Reference

Device list (sensors and gateways)

Description

URL

Parameters

Response

Asset list

Description

URL

Parameters

Response

Historical data (timeseries) per device

Description

URL

Parameters

Response

Attributes

Description

URL

Parameters

Response

Relations

URL

Parameters

Response

Historical data (timeseries) per client / per asset

Description

Flow Architecture

Initiate an export for all devices of a customer

Initiate an export for all devices contained in an asset

Check export job status

Download export file

Exported CSV File Format