Telemetry and attributes API

Telemetry is what devices measure and send over time. Attributes are named values that describe a device: what it reports about itself (client), what you store about it (server) and what you want it to have (shared). This page lists the REST routes for both. Paths are under https://<your host>/tenant/<tenantId>.

The REST API reads telemetry but never writes it. Devices write telemetry over MQTT or HTTP; flows write derived values with Save telemetry. See Device HTTP API and Derived values.

Telemetry routes

A device you may not read answers 404, the same as a device that does not exist.

Latest values

GET /api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity

Leave out keys (at most 50) for every key.

{
  "kind": "iot_device",
  "entityId": "6f1c…",
  "latest": {
    "temperature": { "ts": 1762681200000, "value": 21.5 },
    "humidity": { "ts": 1762681200000, "value": 40 }
  }
}

History

GET /api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1762594800000&to=1762681200000&bucket=1h&agg=max

Day buckets are UTC days: for days in your own time zone, read hourly buckets and add them up. Raw values are kept at most 90 days, minute buckets at most 31 days. The full parameter rules, paging through raw values and worked examples are on The history API.

A device’s keys

GET /api/iot/devices/{deviceId}/elements

The answer lists the device’s elements with labels and the keys it has, declared in its profile or sent, at most 300. Without the permission to read device profiles, only the keys the device has sent are listed.

Attribute routes

Client attributes are written by the device only. A write to client answers 405: “Client attributes are written by the device only.”

Read

GET /api/iot/devices/{deviceId}/attributes?scope=server&keys=maxTempThreshold,site_code

scope is client, shared or server (any case); leave it out for all three. keys holds up to 100 keys.

{
  "attributes": {
    "client": { "fw_version": { "value": "2.4.1", "updatedAt": 1762594800000 } },
    "shared": { "reportInterval": { "value": 60, "updatedAt": 1762500000000 } },
    "server": { "maxTempThreshold": { "value": 8, "updatedAt": 1762400000000 } }
  }
}

Settings that a device’s Settings tab manages (cfg.* keys on devices that take settings by section) are not shown here; read them through the device settings routes, see Firmware and device settings API.

Write

{
    "maxTempThreshold": 8,
    "site_code": "IST-04"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/attributes/server' \
  -H 'Content-Type: application/json' \
  -d '{"maxTempThreshold":8,"site_code":"IST-04"}'

{
    "changed": [
        "maxTempThreshold",
        "site_code"
    ]
}

{
    "message": "One or more attribute keys are invalid or reserved.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "keys_invalid",
        "keys": [
            {
                "key": "fw_title",
                "reason": "reserved"
            }
        ]
    }
}

{
    "message": "Device not found.",
    "code": "NOT_FOUND"
}

Shared attributes are sent to the device right away if it is connected, else when it connects. A shared value must fit the device profile’s downlink limit: “An attribute value is larger than the device’s downlink limit.” (details.reason = value_too_large).

Delete

DELETE /api/iot/devices/{deviceId}/attributes/shared?keys=reportInterval,mode

The answer is { "deleted": ["mode", "reportInterval"] }, the keys that existed. A device is told about deleted shared keys.

Attribute key rules

See Attributes for what each scope is for, and Reserved keys and attributes for the full list.

Typical uses

• Per-device limits from an ERP or MES: write maxTempThreshold as a server attribute; alarm rules can compare with it. See Alarm conditions reference.
• Desired settings for a third-party device: write a shared key the device’s firmware reads, and watch its client attributes for the result.
• A nightly report: read hourly series of yesterday and store it in your warehouse.