Meta

Per-device information that is not measurement data. The backend maintains status (online / offline / idle — idle means connected but quiet) and lastMessage; the data object belongs to the application — names, locations, tags. Devices carry no built-in display name, so this is where device lists get their labels.

Status changes and metadata writes are pushed as META_STATUS_CHANGE, META_SET and META_DELETE events over the websocket. The expected shape of data can be described with a meta schema for UIs to render forms from.

GET	List device metadata/api/v1/meta
GET	Read metadata of a device/api/v1/meta/:deviceId
PUT	Replace device metadata/api/v1/meta/:deviceId
PATCH	Merge device metadata/api/v1/meta/:deviceId
DELETE	Clear device metadata/api/v1/meta/:deviceId

List device metadata

Lists every readable device with its IMEI; depth=1 includes the metadata entries.

GET/api/v1/meta?depth=0

Query Parameters

Name	Description
depthintegeroptional	How many levels of nested resources the response includes; 0 returns only the top level. Default: 0 min 0

Response

Name	Description
crnstring	Unique Coldwave resource name (CRN) that identifies a resource
imeistring	The device's IMEI, the 15-digit identity of its modem.
metaobjectoptionaldepth ≥ 1	Connectivity state and user-defined data of the device; included at depth ≥ 1.
statusenum	Connectivity of the device: online, offline, or idle — idle means connected but quiet. Possible values: online, offline, idle
lastMessageintegeroptional	When the device last sent anything, UTC epoch milliseconds; null before its first message.
datadictionaryoptional	The user-defined metadata object; null when none was written.

Errors

Status	Description	Body
403	You do not have permission to perform this action
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Read metadata of a device

Connectivity state and user-defined data of one device. {deviceId} accepts the device id or the IMEI.

GET/api/v1/meta/Yk3pL7rWq2

Path Parameters

Name	Description
deviceId	The device id, or its IMEI.
Alternative 1string	Resource id: Base58 (9–10 characters) or a 16-character Crockford snowflake. Not an RFC 4122 UUID. Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$
Alternative 2string	The device id, or its IMEI. max length 16 Pattern: ^[0-9a-fA-F]+$

Response

Name	Description
statusenum	Connectivity of the device: online, offline, or idle — idle means connected but quiet. Possible values: online, offline, idle
lastMessageintegeroptional	When the device last sent anything, UTC epoch milliseconds; null before its first message.
datadictionaryoptional	Either a device's user-defined metadata object — null when none was written — or stream content, as a string in the encoding encoding names.

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No device with this id or IMEI in the tenant.	code: META_NOT_FOUND
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Replace device metadata

Replaces the user-defined data object as a whole.

PUT/api/v1/meta/Yk3pL7rWq2

Path Parameters

Name	Description
deviceId	The device id, or its IMEI.
Alternative 1string	Resource id: Base58 (9–10 characters) or a 16-character Crockford snowflake. Not an RFC 4122 UUID. Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$
Alternative 2string	The device id, or its IMEI. max length 16 Pattern: ^[0-9a-fA-F]+$

Body

Errors

Status	Description	Body
403	You do not have permission to perform this action
400	The data object uses the reserved key deviceId.	code: META_RESERVED_KEY
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Merge device metadata

Merges keys into the user-defined data object; existing keys are overwritten, others kept.

PATCH/api/v1/meta/Yk3pL7rWq2

Path Parameters

Name	Description
deviceId	The device id, or its IMEI.
Alternative 1string	Resource id: Base58 (9–10 characters) or a 16-character Crockford snowflake. Not an RFC 4122 UUID. Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$
Alternative 2string	The device id, or its IMEI. max length 16 Pattern: ^[0-9a-fA-F]+$

Body

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No device with this id or IMEI in the tenant.	code: META_NOT_FOUND
400	The data object uses the reserved key deviceId.	code: META_RESERVED_KEY
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Clear device metadata

Removes the listed keys from the data object — or, without a body, all of it.

DELETE/api/v1/meta/Yk3pL7rWq2

Path Parameters

Name	Description
deviceId	The device id, or its IMEI.
Alternative 1string	Resource id: Base58 (9–10 characters) or a 16-character Crockford snowflake. Not an RFC 4122 UUID. Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$
Alternative 2string	The device id, or its IMEI. max length 16 Pattern: ^[0-9a-fA-F]+$

Body

Name	Description
keysarraystring	Keys to remove from the data object; omit the body to clear all data.

Errors

Status	Description	Body
403	You do not have permission to perform this action
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Events

Published on the tenant's event stream and delivered over the websocket to every subscriber holding read on the resource the message names. resourceIdentifier is the resource the action changed; the payload is the shape below.

Event	Description
META_DELETE	Keys were removed from a device's metadata, or all of it was cleared.
META_SET	A device's user-defined metadata was written (replaced or merged).
META_STATUS_CHANGE	Connectivity of a device changed — online, offline, or idle — with the lastMessage timestamp.

Metadata cleared

Keys were removed from a device's metadata, or all of it was cleared.

EVENTMETA_DELETE

Payload

Name	Description

Metadata written

A device's user-defined metadata was written (replaced or merged).

EVENTMETA_SET

Payload

Name	Description
datadictionaryoptional	Either a device's user-defined metadata object — null when none was written — or stream content, as a string in the encoding encoding names.

Device status changed

Connectivity of a device changed — online, offline, or idle — with the lastMessage timestamp.

EVENTMETA_STATUS_CHANGE

Payload

Name	Description
statusenum	Connectivity of the device: online, offline, or idle — idle means connected but quiet. Possible values: online, offline, idle
lastMessageintegeroptional	When the device last sent anything, UTC epoch milliseconds; null before its first message.
connectionIdstringoptional	Identifies the live connection that announced the device online. Set on online only, and only by the wire handlers, so a stale handler can tell a foreign reconnect from its own report.