Device API
The device API is what soc-ota-agent talks to.
It lives under /api/devices/v1/otapulse/*.
This is the documented device API.
Every operation is listed in the OTA-Pulse Device API group of the API Reference.
Endpoints
Section titled “Endpoints”All paths are relative to /api/devices/v1/otapulse.
| Method | Path | Purpose |
|---|---|---|
POST | /auth/requests | Authenticate the device and receive a token |
GET, POST | /deployments/next | Check for the next deployment |
GET | /deployments/{id}/download | Download the deployment artifact |
PUT | /deployments/{id}/status | Report deployment status |
GET | /deployments/{id}/control-map | Get the update control map |
POST, PUT | /deployments/{id}/log | Upload the deployment log |
PATCH, PUT | /inventory/attributes | Submit device inventory |
Download URL
Section titled “Download URL”The check-for-update response carries the download URL.
The server issues it, so the agent does not build it.
It points at /api/devices/v1/deployments/{id}/download and carries a signed token.
This URL is the same on both device APIs.
It is not deprecated.
How the agent finds the native API
Section titled “How the agent finds the native API”The agent tries the native endpoints first.
It falls back to the legacy endpoints only when the server answers 404.
Every response under /api/devices/v1/otapulse/* carries the header X-OTAPulse-Wire: 1.
That header lets the agent tell a real native 404 from a server that has no native routes.
Legacy endpoints (deprecated)
Section titled “Legacy endpoints (deprecated)”Older agents use the endpoints of the earlier device wire format.
They are deprecated and marked deprecated in the API Reference.
| Legacy path | Native replacement |
|---|---|
/api/devices/v1/authentication/auth_requests | /auth/requests |
/api/devices/v1/deployments/device/deployments/next | /deployments/next |
/api/devices/v2/deployments/device/deployments/next | /deployments/next |
/api/devices/v2/deployments/device/deployments/{id}/update_control_map | /deployments/{id}/control-map |
/api/devices/v1/deployments/device/deployments/{id}/status | /deployments/{id}/status |
/api/devices/v1/deployments/device/deployments/{id}/log | /deployments/{id}/log |
/api/devices/v1/inventory/device/attributes | /inventory/attributes |
Both sets of endpoints run the same handlers, so responses are the same. The legacy endpoints keep working for fielded devices. They will be removed after the fleet cutover. The removal will be announced in the release notes.
Operators can switch the legacy endpoints off with LEGACY_DEVICE_WIRE_ENABLED=false.
Legacy requests then get 410 Gone with a message that points at the native API.
The setting defaults to true.
The server counts legacy requests in the metric otapulse_legacy_device_wire_requests_total.
This shows whether any real device still uses them.