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 cs_dev_a7x9k2m4p8q1w3e5r7t9y2u4i6o8a0s2

Key Format: cs_dev_ prefix followed by 32 random alphanumeric characters.

How it works:

  • API keys are generated during device provisioning and shown once to the admin
  • Only a SHA-256 hash of the key is stored on the server
  • On each request, the server hashes the provided key and looks up the matching device
  • Invalid or missing keys return 401 Unauthorized

Key Revocation: If a key is compromised, admins can regenerate it from the admin portal. The device must be factory reset and re-provisioned with the new key.

Rate Limits

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

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.

Zigbee Relay: Hubs can relay readings from paired Zigbee sensors by including the sensor's device_id in each reading. The backend validates the hub owns the sensor. GPS position (if provided) applies to all readings in the batch.

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": 3,
  • "timestamp": "2026-03-29T12:00:05Z"
}

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
Example
{
  • "reporting_interval_seconds": 300,
  • "enabled_sensors": [
    ],
  • "timezone": "America/Los_Angeles",
  • "location_override": {
    },
  • "device_location": {
    }
}

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
timezone
string
object (LocationOverride)

User-set location override. When set, this takes precedence over device-reported GPS for geofence alerts and display. Use for WiFi-only devices or fixed installations.

Responses

Request samples

Content type
application/json
Example
{
  • "location_override": {
    }
}

Response samples

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

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
Example
{
  • "command_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "status": "acked"
}

Response samples

Content type
application/json
{
  • "acknowledged": true,
  • "timestamp": "2026-03-29T15:00:00Z"
}

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.

Zigbee Sensors: Hubs can check for updates on behalf of paired Zigbee sensors by providing the sensor's device_id. The backend validates the hub owns the sensor.

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

Current firmware version on the device

device_id
string <uuid>

Device ID to check updates for. Optional - defaults to the authenticated device. Used by hubs to check OTA updates for paired Zigbee sensors.

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.

Zigbee Sensors: Hubs download firmware for paired sensors by providing the sensor's device_id. The firmware returned matches the sensor's device model.

Authorizations:
ApiKeyAuth
path Parameters
version
required
string
Example: 1.3.0

Firmware version to download

query Parameters
device_id
string <uuid>

Device ID to download firmware for. Optional - defaults to the authenticated device. Used by hubs to download firmware for paired Zigbee sensors.

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
device_id
string <uuid>

Device ID for this status report. Optional for hub's own updates (defaults to authenticated device). Required when hub reports OTA status for a paired Zigbee sensor.

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
Example
{
  • "version": "1.3.0",
  • "status": "downloading",
  • "progress_percent": 45
}

Response samples

Content type
application/json
{
  • "recorded": true,
  • "timestamp": "2026-03-29T15:00:00Z"
}

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": "cs_dev_z8y7x6w5v4u3t2s1r0q9p8o7n6m5l4k3",
  • "ieee_address": "0x00124b001cce5a7d"
}

Response samples

Content type
application/json
{
  • "registered": true,
  • "device_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "serial_number": "SN2026032900001",
  • "model_id": "zigbee_sensor_v1"
}