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

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

---