API docs by Redocly

ClimaSense Device API (1.0.0)

Download OpenAPI specification:

SignalIOT: support@signaliot.com License: LicenseRef-Proprietary

API for ClimaSense IoT devices to report telemetry, receive commands, and manage firmware updates.

Authentication

All endpoints require API key authentication via the Authorization header:

Authorization: Bearer <api_key>

API keys are provisioned during device manufacturing and stored hashed on the server.

Rate Limits

Endpoint Limit Window
POST /v1/telemetry 60 requests 1 minute
GET /v1/settings 10 requests 1 minute
GET /v1/commands/pending 30 requests 1 minute
GET /v1/ota/check 10 requests 1 minute
GET /v1/ota/download/* 5 requests 1 hour

Telemetry

Sensor data ingestion

Submit sensor readings

Submit one or more sensor readings from the device. Readings are stored in TimescaleDB and routed to the alert evaluation system.

Sensor Types:

  • temperature (°C)
  • humidity (%)
  • pressure (hPa)
  • power_availability (boolean as 0/1)
  • battery_level (%)
  • signal_strength (dBm)
  • iaq (Indoor Air Quality index)
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects (SensorReading) [ 1 .. 100 ] items
latitude
number [ -90 .. 90 ]

Device latitude (GPS position, optional)

longitude
number [ -180 .. 180 ]

Device longitude (GPS position, optional)

Responses

Request samples

Content type
application/json
Example
{
  • "latitude": 37.7749,
  • "longitude": -122.4194,
  • "readings": [
    ]
}

Response samples

Content type
application/json
{
  • "accepted": 0,
  • "timestamp": "2019-08-24T14:15:22Z"
}

Settings

Device configuration

Fetch device configuration

Retrieve the current configuration for this device. Configuration includes reporting intervals, enabled sensors, and other device-specific settings.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "reporting_interval_seconds": 60,
  • "enabled_sensors": [
    ],
  • "location": {
    },
  • "timezone": "America/Los_Angeles"
}

Update device configuration

Update device configuration. Supports partial updates - only include fields that should be changed.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
reporting_interval_seconds
integer [ 60 .. 3600 ]
enabled_sensors
Array of strings
object (Location)
timezone
string

Responses

Request samples

Content type
application/json
{
  • "reporting_interval_seconds": 60,
  • "enabled_sensors": [
    ],
  • "location": {
    },
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "reporting_interval_seconds": 60,
  • "enabled_sensors": [
    ],
  • "location": {
    },
  • "timezone": "America/Los_Angeles"
}

Commands

Remote command execution

Poll for pending commands

Check for pending commands that need to be executed. Commands expire after 24 hours if not acknowledged.

Command Types:

  • reboot - Graceful device restart
  • config_update - Configuration change
  • factory_reset - Full device reset (requires explicit confirmation)
  • diagnostics - Report diagnostic information
Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
Example
{
  • "commands": [
    ]
}

Acknowledge command execution

Report the result of a command execution. The device should call this after attempting to execute a command, regardless of success or failure.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
command_id
required
string <uuid>
status
required
string
Enum: "acked" "failed"
error_message
string

Error details if status is failed

object

Command result data (e.g., diagnostics output)

Responses

Request samples

Content type
application/json
{
  • "command_id": "7d510d78-7444-4252-aeac-9e473949661e",
  • "status": "acked",
  • "error_message": "string",
  • "result": { }
}

Response samples

Content type
application/json
{
  • "acknowledged": true,
  • "timestamp": "2019-08-24T14:15:22Z"
}

OTA

Over-the-air firmware updates

Check for firmware updates

Check if a firmware update is available for this device. Updates are released per-batch to enable staged rollouts.

Authorizations:
ApiKeyAuth
query Parameters
current_version
required
string
Example: current_version=1.2.3

Current firmware version on the device

Responses

Response samples

Content type
application/json
Example
{
  • "update_available": true,
  • "version": "1.3.0",
  • "checksum": "sha256:a3f8c2e1d4b5...",
  • "size_bytes": 1048576,
  • "release_notes": "Bug fixes and performance improvements"
}

Download firmware binary

Stream the firmware binary for the specified version from R2 storage. Verify the checksum after download before applying.

Authorizations:
ApiKeyAuth
path Parameters
version
required
string
Example: 1.3.0

Firmware version to download

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Invalid or missing API key"
}

Report OTA update progress

Report the status of an OTA update. The device should report progress during download and the final result after attempting to apply the update.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
version
required
string

Firmware version being updated to

status
required
string
Enum: "downloading" "downloaded" "verifying" "applying" "completed" "failed"
progress_percent
integer [ 0 .. 100 ]

Download progress (for downloading status)

error_message
string

Error details if status is failed

Responses

Request samples

Content type
application/json
{
  • "version": "string",
  • "status": "downloading",
  • "progress_percent": 100,
  • "error_message": "string"
}

Response samples

Content type
application/json
{
  • "recorded": true,
  • "timestamp": "2019-08-24T14:15:22Z"
}

Zigbee

Zigbee sensor registration (hub only)

Register a paired Zigbee sensor

Called by the hub when a new Zigbee sensor is paired. The sensor must have a pre-provisioned API key. The backend associates the sensor with the hub's namespace.

Zigbee sensors can report the same sensor types as the hub (temperature, humidity, pressure, iaq, etc.) and their telemetry is submitted by the hub on their behalf.

Note: Only hub devices can call this endpoint.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
sensor_api_key
required
string

Pre-provisioned API key of the Zigbee sensor

ieee_address
string

Zigbee IEEE address

Responses

Request samples

Content type
application/json
{
  • "sensor_api_key": "sk_sensor_abc123...",
  • "ieee_address": "0x00124b001cce5a7d"
}

Response samples

Content type
application/json
{
  • "registered": true,
  • "sensor_id": "aa8707dc-fa19-438f-a5ba-ee5518d43631",
  • "serial_number": "string"
}