Updates

Firmware comes from one update server that serves the whole backend. It is told the product id, hardware ids and firmware versions, read from the device's cached device service in flake without waking the device. Nothing is kept afterwards: no job to poll, and a retry is another call.

A booking is held against that server's concurrent-download budget; UPDATE_SERVER_OUT_OF_RESOURCES means those slots are all taken, not that the request was wrong. An update also reboots hardware in the field, so the route needs create on the device's update resource, not the read that covers device data — see IAM.

POST	Start a firmware update/api/v1/update/legacy/:device
POST	/api/v1/update/firmware
PUT	/api/v1/update/firmware/:firmwareId/file
GET	/api/v1/update/firmware
GET	/api/v1/update/firmware/:firmwareId
PATCH	/api/v1/update/firmware/:firmwareId
DELETE	/api/v1/update/firmware/:firmwareId
POST	/api/v1/update/rollout
GET	/api/v1/update/rollout
GET	/api/v1/update/rollout/:rolloutId
PATCH	/api/v1/update/rollout/:rolloutId
POST	/api/v1/update/rollout/:rolloutId/advance
GET	/api/v1/update/rollout/:rolloutId/devices
POST	/api/v1/update/device/:device
GET	/api/v1/update/device/:device
PUT	/api/v1/update/device/:device/pin
DELETE	/api/v1/update/device/:device/pin
GET	/api/v1/update/inventory

Start a firmware update

Books a firmware download and tells the device to fetch it, all inside the one request; {device} accepts the device id, the IMEI or the SIM's ICCID. Outcomes arrive as status on a 200 — NO_UPDATE and an unreachable device included — and one call updates at most one hardware unit.

POST/api/v1/update/legacy/Yk3pL7rWq2

Path Parameters

Name	Description
devicestring	Names the device by its id, its IMEI, or the ICCID of its SIM.

Response

Name	Description
statusenum	How far the exchange got: STARTED, NO_UPDATE, DEVICE_OFFLINE, DEVICE_NOT_OK, UPDATE_SERVER_OUT_OF_RESOURCES, UPDATE_SERVER_ERROR or SERVER_ERROR — only STARTED means the device is downloading. Possible values: STARTED, NO_UPDATE, DEVICE_OFFLINE, DEVICE_NOT_OK, UPDATE_SERVER_OUT_OF_RESOURCES, UPDATE_SERVER_ERROR, SERVER_ERROR
messagestring	The status as a fixed English sentence for display; it is not localised, so code branches on status.
detailstringoptional	What the failing step reported, present only on UPDATE_SERVER_ERROR and SERVER_ERROR. Diagnostic and untranslated — meant for a log or a bug report, not for a user.

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No device in this tenant is known by that identifier. {device} is tried as device id, then IMEI, then ICCID — check the value, and that the token belongs to the tenant the device is registered in.
409	The device is known but has never reported what it runs: no PRODUCT_ID in its device service, or no firmware version on any hardware unit, so there is nothing to ask the update server about. Retry once the device has transmitted its device service.
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

---

POST /api/v1/update/firmware

POST/api/v1/update/firmware

Body

Name	Description
productNamestring	min length 1
hardwareNamestring	min length 1
versionstring	Pattern: ^\d+\.\d+\.\d+
channelenum	Possible values: dev, beta, stable
sizeinteger	> 0 · max 67108864
checksumobject
algorithmenum	Possible values: SHA256, SHA384
sumstring	Pattern: ^[0-9a-fA-F]+$
checkpointbooleanoptional
sharedbooleanoptional
releaseNotesstringoptional
tenantIdstringoptional	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}$

Response

Name	Description
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
409		code: FIRMWARE_EXISTS
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

---

PUT /api/v1/update/firmware/:firmwareId/file

PUT/api/v1/update/firmware/Yk3pL7rWq2/file

Path Parameters

Name	Description
firmwareIdstring	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}$

Query Parameters

Name	Description
sizeintegeroptional	Size of the loaded content in bytes. > 0 · max 67108864
algorithmoptionalenum	Possible values: SHA256, SHA384
sumstringoptional	Pattern: ^[0-9a-fA-F]+$
tenantIdstringoptional	Tenant identifier Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$

Response

Name	Description
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource

Errors

Status	Description	Body
400
403	You do not have permission to perform this action
404
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
409		code: FIRMWARE_EXISTS
422		reason: size, expected: string, actual: string
503
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

---

GET /api/v1/update/firmware

GET/api/v1/update/firmware

Query Parameters

Name	Description
productNamestringoptional
hardwareNamestringoptional
channeloptionalenum	Possible values: dev, beta, stable
tenantIdstringoptional	Tenant identifier Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$

Response

Name	Description
firmwareIdstring
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
productNamestring	min length 1
hardwareNamestring	min length 1
versionobject
printablestring
majorinteger	min 0
minorinteger	min 0
patchinteger	min 0
channelenum	Possible values: dev, beta, stable
stateenum	Possible values: draft, published, deprecated, withdrawn
revisioninteger	min 0
checkpointboolean
sharedboolean
fileKeystringoptional
sizeinteger	> 0
checksumobject
algorithmenum	Possible values: SHA256, SHA384
sumstring	Pattern: ^[0-9a-fA-F]+$
headerCheckoptionalenum	Possible values: ok, mismatch, not-checked
releasedAtintegeroptional	Unix timestamp in milliseconds since epoch.
releaseNotesstringoptional
createdBystring	Resource identifier of the entity that created this resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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

---

GET /api/v1/update/firmware/:firmwareId

GET/api/v1/update/firmware/Yk3pL7rWq2

Path Parameters

Name	Description
firmwareIdstring	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}$

Query Parameters

Name	Description
tenantIdstringoptional	Tenant identifier Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$

Response

Name	Description
firmwareIdstring
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
productNamestring	min length 1
hardwareNamestring	min length 1
versionobject
printablestring
majorinteger	min 0
minorinteger	min 0
patchinteger	min 0
channelenum	Possible values: dev, beta, stable
stateenum	Possible values: draft, published, deprecated, withdrawn
revisioninteger	min 0
checkpointboolean
sharedboolean
fileKeystringoptional
sizeinteger	> 0
checksumobject
algorithmenum	Possible values: SHA256, SHA384
sumstring	Pattern: ^[0-9a-fA-F]+$
headerCheckoptionalenum	Possible values: ok, mismatch, not-checked
releasedAtintegeroptional	Unix timestamp in milliseconds since epoch.
releaseNotesstringoptional
createdBystring	Resource identifier of the entity that created this resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
404
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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

---

PATCH /api/v1/update/firmware/:firmwareId

PATCH/api/v1/update/firmware/Yk3pL7rWq2

Path Parameters

Name	Description
firmwareIdstring	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}$

Query Parameters

Name	Description
tenantIdstringoptional	Tenant identifier Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$

Body

Name	Description
channeloptionalenum	Possible values: dev, beta, stable
stateoptionalenum	Possible values: published, deprecated
checkpointbooleanoptional
sharedbooleanoptional
releaseNotesstringoptional

Errors

Status	Description	Body
403	You do not have permission to perform this action
404
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
409		code: FIRMWARE_EXISTS
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

---

DELETE /api/v1/update/firmware/:firmwareId

DELETE/api/v1/update/firmware/Yk3pL7rWq2

Path Parameters

Name	Description
firmwareIdstring	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}$

Query Parameters

Name	Description
tenantIdstringoptional	Tenant identifier Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$

Errors

Status	Description	Body
403	You do not have permission to perform this action
404
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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

---

POST /api/v1/update/rollout

POST/api/v1/update/rollout

Body

Name	Description
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource
target
Alternative 1object
type
Alternative 2object
type
groupRistring	Unique Coldwave resource name (CRN) that identifies a resource
percentageinteger	min 0 · max 100
triggersarrayoptional
pauseAfterFailedInstallsintegeroptional	min 1
tenantIdstringoptional	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}$

Response

Name	Description
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
404
409		code: FIRMWARE_EXISTS
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

---

GET /api/v1/update/rollout

GET/api/v1/update/rollout

Response

Name	Description
rolloutIdstring
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource
stateenum	Possible values: draft, running, paused, done
pauseReasonoptionalenum	Possible values: manual, self-paused, firmware-withdrawn
target
Alternative 1object
type
Alternative 2object
type
groupRistring	Unique Coldwave resource name (CRN) that identifies a resource
percentageinteger	min 0 · max 100
admissionobject
seeninteger	min 0
admittedinteger	min 0
triggersarray
pauseAfterFailedInstallsinteger	min 1
startedAtintegeroptional	Unix timestamp in milliseconds since epoch.
countersobject
eligibleinteger	min 0
startedinteger	min 0
succeededinteger	min 0
failedinteger	min 0
createdBystring	Resource identifier of the entity that created this resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_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

---

GET /api/v1/update/rollout/:rolloutId

GET/api/v1/update/rollout/Yk3pL7rWq2

Path Parameters

Name	Description
rolloutIdstring	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}$

Response

Name	Description
rolloutIdstring
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource
stateenum	Possible values: draft, running, paused, done
pauseReasonoptionalenum	Possible values: manual, self-paused, firmware-withdrawn
target
Alternative 1object
type
Alternative 2object
type
groupRistring	Unique Coldwave resource name (CRN) that identifies a resource
percentageinteger	min 0 · max 100
admissionobject
seeninteger	min 0
admittedinteger	min 0
triggersarray
pauseAfterFailedInstallsinteger	min 1
startedAtintegeroptional	Unix timestamp in milliseconds since epoch.
countersobject
eligibleinteger	min 0
startedinteger	min 0
succeededinteger	min 0
failedinteger	min 0
createdBystring	Resource identifier of the entity that created this resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
404
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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

---

PATCH /api/v1/update/rollout/:rolloutId

PATCH/api/v1/update/rollout/Yk3pL7rWq2

Path Parameters

Name	Description
rolloutIdstring	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}$

Body

Name	Description
stateoptionalenum	Possible values: running, paused, done
percentageintegeroptional	min 0 · max 100
triggersarrayoptional
pauseAfterFailedInstallsintegeroptional	min 1

Errors

Status	Description	Body
403	You do not have permission to perform this action
404
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
409		code: FIRMWARE_EXISTS
503
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

---

POST /api/v1/update/rollout/:rolloutId/advance

POST/api/v1/update/rollout/Yk3pL7rWq2/advance

Path Parameters

Name	Description
rolloutIdstring	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}$

Body

Name	Description
limitintegeroptional	min 1 · max 10000

Response

Name	Description
devicesinteger

Errors

Status	Description	Body
403	You do not have permission to perform this action
404
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
409		code: FIRMWARE_EXISTS
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

---

GET /api/v1/update/rollout/:rolloutId/devices

GET/api/v1/update/rollout/Yk3pL7rWq2/devices

Path Parameters

Name	Description
rolloutIdstring	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}$

Response

Name	Description
deviceIdstring
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
versionstringoptional
decisionoptionalenum	Possible values: admitted, declined, released
reasonoptionalenum	Possible values: rollout-not-running, firmware-not-published, incompatible, unknown-version, checkpoint-withdrawn, pinned, transfer-running, covered, auto-update-off, up-to-date, failed-install, retries-exhausted, backoff, awaiting-report, offline, node-busy, declined, batch-full, refused
nextHopstringoptional	Unique Coldwave resource name (CRN) that identifies a resource
nextBatchboolean
warningsarray
outcomeoptionalenum	Possible values: started, transfer-failed, refused, failed-install, unexpected-version, lost, aborted, installed

Errors

Status	Description	Body
403	You do not have permission to perform this action
404
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
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

---

POST /api/v1/update/device/:device

POST/api/v1/update/device/Yk3pL7rWq2

Path Parameters

Name	Description
devicestring	Names the device by its id, its IMEI, or the ICCID of its SIM.

Body

Name	Description
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource

Response

Name	Description
startedboolean
reasonoptionalenum	Possible values: rollout-not-running, firmware-not-published, incompatible, unknown-version, checkpoint-withdrawn, pinned, transfer-running, covered, auto-update-off, up-to-date, failed-install, retries-exhausted, backoff, awaiting-report, offline, node-busy, declined, batch-full, refused
detailstringoptional
firmwareRistringoptional	Unique Coldwave resource name (CRN) that identifies a resource
warningsarray

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No device in this tenant is known by that identifier. {device} is tried as device id, then IMEI, then ICCID — check the value, and that the token belongs to the tenant the device is registered in.
409		code: FIRMWARE_EXISTS
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

---

GET /api/v1/update/device/:device

GET/api/v1/update/device/Yk3pL7rWq2

Path Parameters

Name	Description
devicestring	Names the device by its id, its IMEI, or the ICCID of its SIM.

Response

Name	Description
productNamestringoptional
hardwareNamestringoptional
versionstringoptional
autoUpdatebooleanoptional
pinobjectoptional
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource
deliveriesarray
deviceIdstring
deviceRistring	Unique Coldwave resource name (CRN) that identifies a resource
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource
targetRistring	Unique Coldwave resource name (CRN) that identifies a resource
revisioninteger	min 1
rolloutRistringoptional	Unique Coldwave resource name (CRN) that identifies a resource
startedAtinteger	Unix timestamp in milliseconds since epoch.
sentinteger	min 0
acceptedinteger	min 0
acceptedAtintegeroptional	Unix timestamp in milliseconds since epoch.
offsetinteger	min 0
retriesinteger	min 0
nextAttemptAtintegeroptional	Unix timestamp in milliseconds since epoch.
failedAtintegeroptional	Unix timestamp in milliseconds since epoch.
resumedboolean
cleanRetryUsedboolean
outcomeenum	Possible values: started, transfer-failed, refused, failed-install, unexpected-version, lost, aborted, installed
transferredAtintegeroptional	Unix timestamp in milliseconds since epoch.
finishedAtintegeroptional	Unix timestamp in milliseconds since epoch.
versionBeforestring
versionAfterstringoptional
lastErrorstringoptional
detailstringoptional

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No device in this tenant is known by that identifier. {device} is tried as device id, then IMEI, then ICCID — check the value, and that the token belongs to the tenant the device is registered in.
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

---

PUT /api/v1/update/device/:device/pin

PUT/api/v1/update/device/Yk3pL7rWq2/pin

Path Parameters

Name	Description
devicestring	Names the device by its id, its IMEI, or the ICCID of its SIM.

Body

Name	Description
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No device in this tenant is known by that identifier. {device} is tried as device id, then IMEI, then ICCID — check the value, and that the token belongs to the tenant the device is registered in.
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

---

DELETE /api/v1/update/device/:device/pin

DELETE/api/v1/update/device/Yk3pL7rWq2/pin

Path Parameters

Name	Description
devicestring	Names the device by its id, its IMEI, or the ICCID of its SIM.

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No device in this tenant is known by that identifier. {device} is tried as device id, then IMEI, then ICCID — check the value, and that the token belongs to the tenant the device is registered in.
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

---

GET /api/v1/update/inventory

GET/api/v1/update/inventory

Response

Name	Description
productNamestring
hardwareNamestring
versionstring
devicesinteger	min 0

Errors

Status	Description	Body
403	You do not have permission to perform this action
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
UPDATES_DELIVERY_SET
UPDATES_EVALUATE_REQUEST
UPDATES_EVALUATE_RESULT
UPDATES_FIRMWARE_CREATE
UPDATES_FIRMWARE_PUBLISH
UPDATES_FIRMWARE_UPDATE
UPDATES_FIRMWARE_WITHDRAW
UPDATES_PIN_CLEAR
UPDATES_PIN_SET
UPDATES_ROLLOUT_CREATE
UPDATES_ROLLOUT_DECISION
UPDATES_ROLLOUT_UPDATE

UPDATES_DELIVERY_SET

EVENTUPDATES_DELIVERY_SET

Payload

Name	Description
deviceIdstring
deviceRistring	Unique Coldwave resource name (CRN) that identifies a resource
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource
targetRistring	Unique Coldwave resource name (CRN) that identifies a resource
revisioninteger	min 1
rolloutRistringoptional	Unique Coldwave resource name (CRN) that identifies a resource
startedAtinteger	Unix timestamp in milliseconds since epoch.
sentinteger	min 0
acceptedinteger	min 0
acceptedAtintegeroptional	Unix timestamp in milliseconds since epoch.
offsetinteger	min 0
retriesinteger	min 0
nextAttemptAtintegeroptional	Unix timestamp in milliseconds since epoch.
failedAtintegeroptional	Unix timestamp in milliseconds since epoch.
resumedboolean
cleanRetryUsedboolean
outcomeenum	Possible values: started, transfer-failed, refused, failed-install, unexpected-version, lost, aborted, installed
transferredAtintegeroptional	Unix timestamp in milliseconds since epoch.
finishedAtintegeroptional	Unix timestamp in milliseconds since epoch.
versionBeforestring
versionAfterstringoptional
lastErrorstringoptional
detailstringoptional

UPDATES_EVALUATE_REQUEST

EVENTUPDATES_EVALUATE_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.
deviceRisarraystring
rolloutRistringoptional	Unique Coldwave resource name (CRN) that identifies a resource
firmwareRistringoptional	Unique Coldwave resource name (CRN) that identifies a resource
batchKeystringoptional
limitintegeroptional	Maximum points per series. min 1

UPDATES_EVALUATE_RESULT

EVENTUPDATES_EVALUATE_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.
resultobject
startedboolean
reasonoptionalenum	Possible values: rollout-not-running, firmware-not-published, incompatible, unknown-version, checkpoint-withdrawn, pinned, transfer-running, covered, auto-update-off, up-to-date, failed-install, retries-exhausted, backoff, awaiting-report, offline, node-busy, declined, batch-full, refused
detailstringoptional
firmwareRistringoptional	Unique Coldwave resource name (CRN) that identifies a resource
warningsarray

UPDATES_FIRMWARE_CREATE

EVENTUPDATES_FIRMWARE_CREATE

Payload

Name	Description
firmwareIdstring
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
productNamestring	min length 1
hardwareNamestring	min length 1
versionobject
printablestring
majorinteger	min 0
minorinteger	min 0
patchinteger	min 0
channelenum	Possible values: dev, beta, stable
stateenum	Possible values: draft, published, deprecated, withdrawn
revisioninteger	min 0
checkpointboolean
sharedboolean
fileKeystringoptional
sizeinteger	> 0
checksumobject
algorithmenum	Possible values: SHA256, SHA384
sumstring	Pattern: ^[0-9a-fA-F]+$
headerCheckoptionalenum	Possible values: ok, mismatch, not-checked
releasedAtintegeroptional	Unix timestamp in milliseconds since epoch.
releaseNotesstringoptional
createdBystring	Resource identifier of the entity that created this resource

UPDATES_FIRMWARE_PUBLISH

EVENTUPDATES_FIRMWARE_PUBLISH

Payload

Name	Description
revisioninteger	min 1
fileKeystring
sizeinteger	Size of the loaded content in bytes. > 0
checksumobject
algorithmenum	Possible values: SHA256, SHA384
sumstring	Pattern: ^[0-9a-fA-F]+$
headerCheckenum	Possible values: ok, mismatch, not-checked
releasedAtinteger

UPDATES_FIRMWARE_UPDATE

EVENTUPDATES_FIRMWARE_UPDATE

Payload

Name	Description
channeloptionalenum	Possible values: dev, beta, stable
stateoptionalenum	Possible values: published, deprecated
checkpointbooleanoptional
sharedbooleanoptional
releaseNotesstringoptional

UPDATES_FIRMWARE_WITHDRAW

EVENTUPDATES_FIRMWARE_WITHDRAW

Payload

Name	Description

UPDATES_PIN_CLEAR

EVENTUPDATES_PIN_CLEAR

Payload

Name	Description

UPDATES_PIN_SET

EVENTUPDATES_PIN_SET

Payload

Name	Description
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource

UPDATES_ROLLOUT_CREATE

EVENTUPDATES_ROLLOUT_CREATE

Payload

Name	Description
rolloutIdstring
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource
stateenum	Possible values: draft, running, paused, done
pauseReasonoptionalenum	Possible values: manual, self-paused, firmware-withdrawn
target
Alternative 1object
type
Alternative 2object
type
groupRistring	Unique Coldwave resource name (CRN) that identifies a resource
percentageinteger	min 0 · max 100
admissionobject
seeninteger	min 0
admittedinteger	min 0
triggersarray
pauseAfterFailedInstallsinteger	min 1
startedAtintegeroptional	Unix timestamp in milliseconds since epoch.
countersobject
eligibleinteger	min 0
startedinteger	min 0
succeededinteger	min 0
failedinteger	min 0
createdBystring	Resource identifier of the entity that created this resource

UPDATES_ROLLOUT_DECISION

EVENTUPDATES_ROLLOUT_DECISION

Payload

Name	Description
deviceRistring	Unique Coldwave resource name (CRN) that identifies a resource
decisionenum	Possible values: admitted, declined, released
decidedAtinteger	Unix timestamp in milliseconds since epoch.
startedbooleanoptional
finishedoptionalenum	Possible values: succeeded, failed

UPDATES_ROLLOUT_UPDATE

EVENTUPDATES_ROLLOUT_UPDATE

Payload

Name	Description
rolloutIdstring
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
firmwareRistring	Unique Coldwave resource name (CRN) that identifies a resource
stateenum	Possible values: draft, running, paused, done
pauseReasonoptionalenum	Possible values: manual, self-paused, firmware-withdrawn
target
Alternative 1object
type
Alternative 2object
type
groupRistring	Unique Coldwave resource name (CRN) that identifies a resource
percentageinteger	min 0 · max 100
admissionobject
seeninteger	min 0
admittedinteger	min 0
triggersarray
pauseAfterFailedInstallsinteger	min 1
startedAtintegeroptional	Unix timestamp in milliseconds since epoch.
countersobject
eligibleinteger	min 0
startedinteger	min 0
succeededinteger	min 0
failedinteger	min 0
createdBystring	Resource identifier of the entity that created this resource