Metadata

The meta module keeps per-device information that is not measurement data:

• Maintained by the backend: connectivity status (online / offline / idle — idle means connected but quiet) and the lastMessage timestamp.
• Maintained by you: a free-form data object for names, locations, tags — anything your application wants to attach.

Devices carry no built-in display name, so this is where device lists get their labels.

Reading metadata

const response = await client.fetch("GET", "https://<<URL>>/api/v1/meta?depth=1", { accessToken });
const meta = await response.json();

[
  {
    "crn": "crn#tenant:Ba9mN3pQ.device:A1B2C3D4",
    "imei": "350000000000001",
    "meta": {
      "status": "online",
      "lastMessage": 1756800000123,
      "data": { "name": "Rooftop HVAC 1", "site": "Berlin", "floor": 4 }
    }
  }
]

Use data to show "Rooftop HVAC 1 – Berlin" instead of a CRN.

Writing metadata

{deviceId} accepts the device id or the IMEI:

• PUT /meta/{deviceId} replaces the data object as a whole.
• PATCH /meta/{deviceId} merges keys — existing keys are overwritten, others kept.
• DELETE /meta/{deviceId} removes the listed keys, or all data without a body.

The key deviceId is reserved and rejected inside data. A meta schema can describe the expected shape of data, so UIs can render forms for it.

Staying current

Status changes and metadata writes are pushed over the websocket as META_STATUS_CHANGE, META_SET and META_DELETE events.