Flake

The flake module is the device tree: every device of the tenant, the services it exposes, and the current value of every property — served from the backend's cache of the last transmissions. Reads never wake a device. Writes are queued and confirmed by the device; the confirmation arrives as the next OBJECT_UPDATED event, and the property's pending field tracks it in the meantime.

{deviceId} accepts the device id or the IMEI throughout. Property ids are canonical hex strings (0x0800). Human-readable names, units and enums for these raw values come from the schema module; connectivity and user-defined labels from meta; live updates arrive over the websocket.

New to the API? The Application Developer Guide walks through the whole flow.

GET	List devices/api/v1/devices
GET	List services of a device/api/v1/devices/:deviceId/services
GET	Read all properties of a service/api/v1/devices/:deviceId/services/:serviceId/properties
GET	Read one property/api/v1/devices/:deviceId/services/:serviceId/properties/:propertyId
PUT	Write one property/api/v1/devices/:deviceId/services/:serviceId/properties/:propertyId
PUT	Write several properties/api/v1/devices/:deviceId/services/:serviceId/properties
POST	Open a property stream/api/v1/devices/:deviceId/services/:serviceId/properties/:propertyId/stream
DELETE	Close a property stream/api/v1/devices/:deviceId/services/:serviceId/properties/:propertyId/stream
GET	Read a property stream/api/v1/devices/:deviceId/services/:serviceId/properties/:propertyId/stream
POST	Call a device method/api/v1/devices/:deviceId/services/:serviceId/messages/:name

List devices

Lists every device the caller may read. depth adds services (1) and their current property values (2) — one call for a dashboard's whole startup state.

GET/api/v1/devices?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
instancestringoptional	Substring filter on service ids.
expandstringoptional	Comma-separated optional per-property fields to include: propertyType, modifier, transmittedAt, streamData. Accepted values: modifier, propertyType, transmittedAt, streamData

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.
servicesarrayoptionaldepth ≥ 1	The services in play: in a device listing the device's own services, added from depth 1; in a history query the service identifiers the read is narrowed to.
serviceIdstring	Service identifier (UUID) of the service on this device.
propertiesarrayoptionaldepth ≥ 2	Current values of the service's properties, added at depth 2 — the device listing sits one level further out than a service listing does.
idstring	Property id in canonical hexadecimal form, e.g. 0x0800.
value	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64.
measuredAtintegeroptional	When the device measured the value, UTC epoch milliseconds; null when the device sent no timestamp.
pendingobjectoptional	Set while a write to this property is still awaiting device confirmation; null otherwise.
value	The queued value awaiting delivery to the device.
retriesinteger	Delivery attempts remaining for the queued write. min 0
failuresarraystring	Reasons of the delivery attempts that failed so far.
streamIdstringoptional	Id minted by the write request; stream writes report their STREAM_WRITE_* progress under it.
modifierobjectoptionalexpand ∋ modifier	Flags the device transmitted with the property.
isReadOnlyboolean	The device declared the property read-only.
isActionableboolean	Writing triggers an action on the device rather than storing a value.
isVolatileboolean	Not cacheable on the wire — reads are forwarded to the device, so a stored value is only as fresh as the last transmission.
isErrorboolean	The device reported the property in an error state.
isMetaboolean	A protocol-level property of the device (such as the transmission timestamp), not application data.
isNullboolean	The property currently carries no value; value is null.
propertyTypeoptionalenumexpand ∋ propertyType	Wire type of the property (UINT16, FLOAT, STRING, …). Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM, INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
transmittedAtintegeroptionalexpand ∋ transmittedAt	When the value reached the backend, UTC epoch milliseconds.
streamobjectoptional	Present on stream properties that have been loaded at least once: a summary of the last loaded payload.
loadedAtinteger	When the content was loaded from the device, UTC epoch milliseconds.
sizeinteger	Size of the loaded content in bytes. min 0
completeboolean	Whether the stream was read to its end.
truncatedboolean	Whether the cached content was cut off at the size limit.
encodingenum	How streamData is encoded: base64 for binary streams, utf8 for string streams. Possible values: base64, utf8
streamDatastringoptionalexpand ∋ streamData	The loaded stream content; requested via expand=streamData.

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

---

List services of a device

Lists the services of one device; depth=1 adds current property values. {deviceId} accepts the device id or the IMEI.

GET/api/v1/devices/Yk3pL7rWq2/services?depth=0

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]+$

Query Parameters

Name	Description
depthintegeroptional	How many levels of nested resources the response includes; 0 returns only the top level. Default: 0 min 0
instancestringoptional	Substring filter on service ids.
expandstringoptional	Comma-separated optional per-property fields to include: propertyType, modifier, transmittedAt, streamData. Accepted values: modifier, propertyType, transmittedAt, streamData

Response

Name	Description
serviceIdstring	Service identifier (UUID) of the service on this device.
propertiesarrayoptionaldepth ≥ 1	The properties in play: in a service listing their current values, added from depth 1; in a history query the ids to read — at least one, because every property is stored as its own series.
idstring	Property id in canonical hexadecimal form, e.g. 0x0800.
value	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64.
measuredAtintegeroptional	When the device measured the value, UTC epoch milliseconds; null when the device sent no timestamp.
pendingobjectoptional	Set while a write to this property is still awaiting device confirmation; null otherwise.
value	The queued value awaiting delivery to the device.
retriesinteger	Delivery attempts remaining for the queued write. min 0
failuresarraystring	Reasons of the delivery attempts that failed so far.
streamIdstringoptional	Id minted by the write request; stream writes report their STREAM_WRITE_* progress under it.
modifierobjectoptionalexpand ∋ modifier	Flags the device transmitted with the property.
isReadOnlyboolean	The device declared the property read-only.
isActionableboolean	Writing triggers an action on the device rather than storing a value.
isVolatileboolean	Not cacheable on the wire — reads are forwarded to the device, so a stored value is only as fresh as the last transmission.
isErrorboolean	The device reported the property in an error state.
isMetaboolean	A protocol-level property of the device (such as the transmission timestamp), not application data.
isNullboolean	The property currently carries no value; value is null.
propertyTypeoptionalenumexpand ∋ propertyType	Wire type of the property (UINT16, FLOAT, STRING, …). Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM, INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
transmittedAtintegeroptionalexpand ∋ transmittedAt	When the value reached the backend, UTC epoch milliseconds.
streamobjectoptional	Present on stream properties that have been loaded at least once: a summary of the last loaded payload.
loadedAtinteger	When the content was loaded from the device, UTC epoch milliseconds.
sizeinteger	Size of the loaded content in bytes. min 0
completeboolean	Whether the stream was read to its end.
truncatedboolean	Whether the cached content was cut off at the size limit.
encodingenum	How streamData is encoded: base64 for binary streams, utf8 for string streams. Possible values: base64, utf8
streamDatastringoptionalexpand ∋ streamData	The loaded stream content; requested via expand=streamData.

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 all properties of a service

Current values of every property of the service, served from the backend's cache of the last transmissions.

GET/api/v1/devices/Yk3pL7rWq2/services/string/properties

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]+$
serviceIdstring	Service identifier (UUID) of the service on this device. min length 1

Query Parameters

Name	Description
expandstringoptional	Comma-separated optional per-property fields to include: propertyType, modifier, transmittedAt, streamData. Accepted values: modifier, propertyType, transmittedAt, streamData

Response

Name	Description
idstring	Property id in canonical hexadecimal form, e.g. 0x0800.
value	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64.
measuredAtintegeroptional	When the device measured the value, UTC epoch milliseconds; null when the device sent no timestamp.
pendingobjectoptional	Set while a write to this property is still awaiting device confirmation; null otherwise.
value	The queued value awaiting delivery to the device.
retriesinteger	Delivery attempts remaining for the queued write. min 0
failuresarraystring	Reasons of the delivery attempts that failed so far.
streamIdstringoptional	Id minted by the write request; stream writes report their STREAM_WRITE_* progress under it.
modifierobjectoptionalexpand ∋ modifier	Flags the device transmitted with the property.
isReadOnlyboolean	The device declared the property read-only.
isActionableboolean	Writing triggers an action on the device rather than storing a value.
isVolatileboolean	Not cacheable on the wire — reads are forwarded to the device, so a stored value is only as fresh as the last transmission.
isErrorboolean	The device reported the property in an error state.
isMetaboolean	A protocol-level property of the device (such as the transmission timestamp), not application data.
isNullboolean	The property currently carries no value; value is null.
propertyTypeoptionalenumexpand ∋ propertyType	Wire type of the property (UINT16, FLOAT, STRING, …). Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM, INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
transmittedAtintegeroptionalexpand ∋ transmittedAt	When the value reached the backend, UTC epoch milliseconds.
streamobjectoptional	Present on stream properties that have been loaded at least once: a summary of the last loaded payload.
loadedAtinteger	When the content was loaded from the device, UTC epoch milliseconds.
sizeinteger	Size of the loaded content in bytes. min 0
completeboolean	Whether the stream was read to its end.
truncatedboolean	Whether the cached content was cut off at the size limit.
encodingenum	How streamData is encoded: base64 for binary streams, utf8 for string streams. Possible values: base64, utf8
streamDatastringoptionalexpand ∋ streamData	The loaded stream content; requested via expand=streamData.

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	The device, service or property does not exist in this tenant.	code: FLAKE_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

---

Read one property

Current value of a single property, addressed by its hexadecimal id.

GET/api/v1/devices/Yk3pL7rWq2/services/string/properties/string

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]+$
serviceIdstring	Service identifier (UUID) of the service on this device. min length 1
propertyIdstring	Property id in canonical hexadecimal form, e.g. 0x0800. Pattern: ^0x[0-9A-Fa-f]+$

Query Parameters

Name	Description
expandstringoptional	Comma-separated optional per-property fields to include: propertyType, modifier, transmittedAt, streamData. Accepted values: modifier, propertyType, transmittedAt, streamData

Response

Name	Description
idstring	Property id in canonical hexadecimal form, e.g. 0x0800.
value	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64.
measuredAtintegeroptional	When the device measured the value, UTC epoch milliseconds; null when the device sent no timestamp.
pendingobjectoptional	Set while a write to this property is still awaiting device confirmation; null otherwise.
value	The queued value awaiting delivery to the device.
retriesinteger	Delivery attempts remaining for the queued write. min 0
failuresarraystring	Reasons of the delivery attempts that failed so far.
streamIdstringoptional	Id minted by the write request; stream writes report their STREAM_WRITE_* progress under it.
modifierobjectoptionalexpand ∋ modifier	Flags the device transmitted with the property.
isReadOnlyboolean	The device declared the property read-only.
isActionableboolean	Writing triggers an action on the device rather than storing a value.
isVolatileboolean	Not cacheable on the wire — reads are forwarded to the device, so a stored value is only as fresh as the last transmission.
isErrorboolean	The device reported the property in an error state.
isMetaboolean	A protocol-level property of the device (such as the transmission timestamp), not application data.
isNullboolean	The property currently carries no value; value is null.
propertyTypeoptionalenumexpand ∋ propertyType	Wire type of the property (UINT16, FLOAT, STRING, …). Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM, INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
transmittedAtintegeroptionalexpand ∋ transmittedAt	When the value reached the backend, UTC epoch milliseconds.
streamobjectoptional	Present on stream properties that have been loaded at least once: a summary of the last loaded payload.
loadedAtinteger	When the content was loaded from the device, UTC epoch milliseconds.
sizeinteger	Size of the loaded content in bytes. min 0
completeboolean	Whether the stream was read to its end.
truncatedboolean	Whether the cached content was cut off at the size limit.
encodingenum	How streamData is encoded: base64 for binary streams, utf8 for string streams. Possible values: base64, utf8
streamDatastringoptionalexpand ∋ streamData	The loaded stream content; requested via expand=streamData.

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	The device, service or property does not exist in this tenant.	code: FLAKE_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

---

Write one property

Queues the value for delivery to the device. The property's pending field tracks confirmation, which arrives as the next OBJECT_UPDATED event; immediate=true fails instead of queueing while the device is offline.

PUT/api/v1/devices/Yk3pL7rWq2/services/string/properties/string?immediate=false&retries=3

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]+$
serviceIdstring	Service identifier (UUID) of the service on this device. min length 1
propertyIdstring	Property id in canonical hexadecimal form, e.g. 0x0800. Pattern: ^0x[0-9A-Fa-f]+$

Query Parameters

Name	Description
immediatebooleanoptional	Deliver now or fail: when the device is offline the write is rejected instead of queued. Default: false
retriesintegeroptional	How many delivery attempts the backend makes for the queued write (default 3). Default: 3 min 0

Body

Name	Description
value	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64.

Response

Name	Description
streamIdstring	Correlates the write with the STREAM_WRITE_* actions it emits if the property turns out to be a stream; meaningless for scalar writes.

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	The device is offline and the request required immediate delivery — an immediate=true write, a stream operation, or a method call.	code: FLAKE_DEVICE_OFFLINE
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

---

Write several properties

Queues values for several properties of one service in a single request.

PUT/api/v1/devices/Yk3pL7rWq2/services/string/properties?immediate=false&retries=3

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]+$
serviceIdstring	Service identifier (UUID) of the service on this device. min length 1

Query Parameters

Name	Description
immediatebooleanoptional	Deliver now or fail: when the device is offline the write is rejected instead of queued. Default: false
retriesintegeroptional	How many delivery attempts the backend makes for the queued write (default 3). Default: 3 min 0

Body

Name	Description
idstring	Property id in canonical hexadecimal form, e.g. 0x0800. Pattern: ^0x[0-9A-Fa-f]+$
value	The value as last transmitted. Encoding follows the property type: INT64/UINT64 as decimal strings, BIN/UUID as base64.

Response

Name	Description
streamIdstring	Correlates the write with the STREAM_WRITE_* actions it emits if the property turns out to be a stream; meaningless for scalar writes.

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	The device is offline and the request required immediate delivery — an immediate=true write, a stream operation, or a method call.	code: FLAKE_DEVICE_OFFLINE
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

---

Open a property stream

Loads a stream property's content from the device (mode=load) or follows it live (mode=live). Re-opening a running stream refreshes its expiry rather than starting a second one.

POST/api/v1/devices/Yk3pL7rWq2/services/string/properties/string/stream?mode=load&expiresIn=60000

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]+$
serviceIdstring	Service identifier (UUID) of the service on this device. min length 1
propertyIdstring	Property id in canonical hexadecimal form, e.g. 0x0800. Pattern: ^0x[0-9A-Fa-f]+$

Query Parameters

Name	Description
modeoptionalenum	load pulls the stream until EOF and caches it so it stays readable while the device is offline; live only forwards chunks and stores nothing. Default: load Possible values: load, live
expiresInintegeroptional	Time until expiry, in seconds Default: 60000 > 0

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	The device is offline and the request required immediate delivery — an immediate=true write, a stream operation, or a method call.	code: FLAKE_DEVICE_OFFLINE
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

---

Close a property stream

Closes a running stream on the device.

DELETE/api/v1/devices/Yk3pL7rWq2/services/string/properties/string/stream

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]+$
serviceIdstring	Service identifier (UUID) of the service on this device. min length 1
propertyIdstring	Property id in canonical hexadecimal form, e.g. 0x0800. Pattern: ^0x[0-9A-Fa-f]+$

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 a property stream

Returns the loaded stream content and its summary.

GET/api/v1/devices/Yk3pL7rWq2/services/string/properties/string/stream

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]+$
serviceIdstring	Service identifier (UUID) of the service on this device. min length 1
propertyIdstring	Property id in canonical hexadecimal form, e.g. 0x0800. Pattern: ^0x[0-9A-Fa-f]+$

Response

Name	Description
loadedAtinteger	When the content was loaded from the device, UTC epoch milliseconds.
sizeinteger	Size of the loaded content in bytes. min 0
completeboolean	Whether the stream was read to its end.
truncatedboolean	Whether the cached content was cut off at the size limit.
encodingenum	How streamData is encoded: base64 for binary streams, utf8 for string streams. Possible values: base64, utf8
idstring	Property id in canonical hexadecimal form, e.g. 0x0800.
datastring	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	The device, service or property does not exist in this tenant.	code: FLAKE_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

---

Call a device method

Invokes a schema-defined method by name and waits for the device's answer — the device must be online; there is no queueing. Parameters state their own id, type and value.

POST/api/v1/devices/Yk3pL7rWq2/services/string/messages/string

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]+$
serviceIdstring	Service identifier (UUID) of the service on this device. min length 1
namestring	Name of the addressed item — a block or template, a device method, a recorded event. A method name is limited to letters, digits, _ and -, because it becomes a segment of the message CRN. Pattern: ^[A-Za-z0-9_-]{1,64}$

Body

Name	Description
paramsarrayoptional	Parameters of the call: a device method takes one entry per parameter, each stating its own type; a mail template takes its parameter values keyed by name. Default: []
idstring	Property id of the parameter, hexadecimal (0x0800). Pattern: ^0x[0-9A-Fa-f]+$
typeenum	Wire type of the parameter — stated by the caller, since method parameters have no object-table entry on the device to read it from. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM, INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
value	Parameter value; INT64/UINT64 as decimal strings, BIN/UUID as base64.

Response

Name	Description

Errors

Status	Description	Body
403	You do not have permission to perform this action
400	A method parameter cannot be serialized for the wire — wrong JSON type for the declared property type. id names the parameter, reason says what is wrong.	code: FLAKE_INVALID_PARAM, id: string, reason: string
409	The device is offline and the request required immediate delivery — an immediate=true write, a stream operation, or a method call.	code: FLAKE_DEVICE_OFFLINE
502	The instance holding the device connection could not complete the call; reason is what it reported.	code: FLAKE_CALL_FAILED, reason: string
504	The device did not answer in time — it disconnected mid-call, or the answer is still in flight.	code: FLAKE_CALL_TIMEOUT
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
CUSTOM_MESSAGE_REQUEST	A schema-defined method call was dispatched to the device.
CUSTOM_MESSAGE_RESULT	The device answered a method call; carries the outcome.
OBJECT_UPDATE_REQUEST	A write toward a device was requested over the API — the echo of a PUT, carrying the requested updates, the retry budget and the immediate flag.
OBJECT_UPDATED	A device transmitted property values. updates carries one entry per property with per-property timestamps; history holds older samples overwritten in the same transmission.
STREAM_CHUNK	A chunk of stream content arrived from the device.
STREAM_CLOSE_REQUEST	A client asked to close a running stream.
STREAM_CLOSED	A stream ended: completed, expired, closed, failed, or the device disconnected.
STREAM_OPEN_REQUEST	A client asked to load or follow a stream property.
STREAM_WRITE_CLOSED	A stream write toward the device ended — completed or failed.
STREAM_WRITE_PROGRESS	A running stream write reported progress.
STREAM_WRITE_STARTED	A stream write toward the device began; correlated to its PUT via streamId.

Method call sent

A schema-defined method call was dispatched to the device.

EVENTCUSTOM_MESSAGE_REQUEST

Payload

Name	Description
requestIdstring	Ties a method call to its answer across instances: whichever instance holds the device connection runs the call, and the one still holding the HTTP request matches the result by this id. Every other instance drops both.
namestring	Name of the addressed item — a block or template, a device method, a recorded event. A method name is limited to letters, digits, _ and -, because it becomes a segment of the message CRN.
paramsarray	Parameters of the call: a device method takes one entry per parameter, each stating its own type; a mail template takes its parameter values keyed by name.
idstring	Property id of the parameter, hexadecimal (0x0800). Pattern: ^0x[0-9A-Fa-f]+$
typeenum	Wire type of the parameter — stated by the caller, since method parameters have no object-table entry on the device to read it from. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM, INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
value	Parameter value; INT64/UINT64 as decimal strings, BIN/UUID as base64.

Method call answered

The device answered a method call; carries the outcome.

EVENTCUSTOM_MESSAGE_RESULT

Payload

Name	Description
requestIdstring	Ties a method call to its answer across instances: whichever instance holds the device connection runs the call, and the one still holding the HTTP request matches the result by this id. Every other instance drops both.
outcome	What came of the call: the device's answer — ok, not_implemented or error — or failed when no answer was ever reached.
Alternative 1object	What came of the call: the device's answer — ok, not_implemented or error — or failed when no answer was ever reached.
type	Which of the four outcomes this is; it decides which of the fields beside it are present.
responsearray	The properties the device returned. Present on ok only.
idstring	Property id of the returned value, hexadecimal.
typeenum	Wire type of the returned property, as the device stated it. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM, INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
value	The value, encoded as a method parameter is: INT64/UINT64 as decimal strings, BIN/UUID as base64. Null for a null property.
errorCodestringoptional	Stands in place of a value when the device answered this parameter with an error property.
Alternative 2object	What came of the call: the device's answer — ok, not_implemented or error — or failed when no answer was ever reached.
type	Which of the four outcomes this is; it decides which of the fields beside it are present.
Alternative 3object	What came of the call: the device's answer — ok, not_implemented or error — or failed when no answer was ever reached.
type	Which of the four outcomes this is; it decides which of the fields beside it are present.
codeinteger	The device's own error code. The call itself ran — this is not an HTTP status and does not map to one.
messagestringoptional	The device's own wording of the error, when it sent one.
detailsarray	Properties the device sent alongside its error code, in the same encoding as a returned value.
idstring	Property id of the returned value, hexadecimal.
typeenum	Wire type of the returned property, as the device stated it. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM, INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
value	The value, encoded as a method parameter is: INT64/UINT64 as decimal strings, BIN/UUID as base64. Null for a null property.
errorCodestringoptional	Stands in place of a value when the device answered this parameter with an error property.
Alternative 4object	What came of the call: the device's answer — ok, not_implemented or error — or failed when no answer was ever reached.
type	Which of the four outcomes this is; it decides which of the fields beside it are present.
reasonstring	Why the call never reached an answer. On failed only, which the HTTP route turns into a 502.

Property write queued

A write toward a device was requested over the API — the echo of a PUT, carrying the requested updates, the retry budget and the immediate flag.

EVENTOBJECT_UPDATE_REQUEST

Payload

Name	Description
updatesarray	One entry per property the message carries: what the device reported on OBJECT_UPDATED, what a caller asked to be written on OBJECT_UPDATE_REQUEST.
idstring	Property id in canonical hexadecimal form, e.g. 0x0800; requested writes carry this form, values reported by a device carry the decimal propId instead.
value	The value, encoded by property type: INT64/UINT64 as decimal strings, BIN/UUID as base64. On a reported update it is present only when tag is value.
retriesinteger	How many delivery attempts the backend makes for the queued write (default 3). min 0
immediateboolean	Deliver now or fail: when the device is offline the write is rejected instead of queued.

Property values reported

A device transmitted property values. updates carries one entry per property with per-property timestamps; history holds older samples overwritten in the same transmission.

EVENTOBJECT_UPDATED

Payload

Name	Description
updatesarray	One entry per property the message carries: what the device reported on OBJECT_UPDATED, what a caller asked to be written on OBJECT_UPDATE_REQUEST.
transmittedAtinteger	When the value reached the backend, UTC epoch milliseconds.
measuredAtintegeroptional	When the device measured the value, UTC epoch milliseconds; null when the device sent no timestamp.
historyarrayoptional	Older samples the device overwrote inside the same transmission, reconstructed from its history block. Omitted when it sent none; the newest value travels in updates.
idstring	Property id the samples belong to, hexadecimal.
typeenum	Wire type the device stated for these samples. It is carried rather than inferred from the value — nothing in the JSON tells a uint16 from a float. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM, INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
samplesarray	The recovered samples of this property.
measuredAtintegeroptional	When the device measured the sample, UTC epoch milliseconds; null when it sent no timestamp.
value	The value, encoded as a live update's is.

Stream data received

A chunk of stream content arrived from the device.

EVENTSTREAM_CHUNK

Payload

Name	Description
propIdinteger	The property the stream belongs to, as a decimal number — event payloads carry property ids in decimal, not in the 0x0800 form the REST routes use. > 0
seqinteger	Chunk counter within one stream, starting at 0. A reader orders by it and spots a gap with it; the byte position is offset. min 0
offsetinteger	Byte position of this chunk within the stream. It counts everything delivered, so it keeps running even after the cached copy has hit its size limit. min 0
encodingenum	How streamData is encoded: base64 for binary streams, utf8 for string streams. Possible values: base64, utf8
datastring	Either a device's user-defined metadata object — null when none was written — or stream content, as a string in the encoding encoding names.

Stream close requested

A client asked to close a running stream.

EVENTSTREAM_CLOSE_REQUEST

Payload

Name	Description
propIdinteger	The property the stream belongs to, as a decimal number — event payloads carry property ids in decimal, not in the 0x0800 form the REST routes use. > 0

Stream ended

A stream ended: completed, expired, closed, failed, or the device disconnected.

EVENTSTREAM_CLOSED

Payload

Name	Description
propIdinteger	The property the stream belongs to, as a decimal number — event payloads carry property ids in decimal, not in the 0x0800 form the REST routes use. > 0
reasonenum	Why it did not go through — a rejected parameter, a call the device's instance could not complete, a contract that does not hold up. On a stream it is instead the enumerated close reason. Possible values: completed, expired, closed, failed, disconnected
sizeinteger	Size of the loaded content in bytes. min 0
truncatedboolean	Whether the cached content was cut off at the size limit.
errorstringoptional	The failure message from the side that gave up. Present only when the stream closed as failed.

Stream open requested

A client asked to load or follow a stream property.

EVENTSTREAM_OPEN_REQUEST

Payload

Name	Description
propIdinteger	The property the stream belongs to, as a decimal number — event payloads carry property ids in decimal, not in the 0x0800 form the REST routes use. > 0
modeenum	load pulls the stream until EOF and caches it so it stays readable while the device is offline; live only forwards chunks and stores nothing. Possible values: load, live
expiresIninteger	Time until expiry, in seconds > 0

Stream write ended

A stream write toward the device ended — completed or failed.

EVENTSTREAM_WRITE_CLOSED

Payload

Name	Description
propIdinteger	The property the stream belongs to, as a decimal number — event payloads carry property ids in decimal, not in the 0x0800 form the REST routes use. > 0
streamIdstringoptional	Correlates the write with the STREAM_WRITE_* actions it emits if the property turns out to be a stream; meaningless for scalar writes.
reasonenum	Why it did not go through — a rejected parameter, a call the device's instance could not complete, a contract that does not hold up. On a stream it is instead the enumerated close reason. Possible values: completed, failed
writteninteger	Bytes of the payload the device has acknowledged so far, against the total in size. min 0
sizeinteger	Size of the loaded content in bytes. min 0
errorstringoptional	The failure message from the side that gave up. Present only when the stream closed as failed.

Stream write progressing

A running stream write reported progress.

EVENTSTREAM_WRITE_PROGRESS

Payload

Name	Description
propIdinteger	The property the stream belongs to, as a decimal number — event payloads carry property ids in decimal, not in the 0x0800 form the REST routes use. > 0
streamIdstringoptional	Correlates the write with the STREAM_WRITE_* actions it emits if the property turns out to be a stream; meaningless for scalar writes.
writteninteger	Bytes of the payload the device has acknowledged so far, against the total in size. min 0
sizeinteger	Size of the loaded content in bytes. min 0

Stream write started

A stream write toward the device began; correlated to its PUT via streamId.

EVENTSTREAM_WRITE_STARTED

Payload

Name	Description
propIdinteger	The property the stream belongs to, as a decimal number — event payloads carry property ids in decimal, not in the 0x0800 form the REST routes use. > 0
streamIdstringoptional	Correlates the write with the STREAM_WRITE_* actions it emits if the property turns out to be a stream; meaningless for scalar writes.
sizeinteger	Size of the loaded content in bytes. min 0