Firmware API

Endpoints

Method	Path	Description
`GET`	`/api/firmware`	List firmware versions
`POST`	`/api/firmware`	Upload new firmware
`GET`	`/api/firmware/:id`	Get firmware details
`DELETE`	`/api/firmware/:id`	Delete firmware version
`POST`	`/api/firmware/deploy`	Deploy to devices
`GET`	`/api/firmware/deployments`	List deployments
`GET`	`/api/firmware/deployments/:id`	Get deployment status

List Firmware Versions

GET /api/firmware?model=RC500

Query Parameters

Parameter	Type	Description
`model`	string	Filter by device model
`page`	int	Page number
`limit`	int	Items per page

Response (200)

{
  "data": [
    {
      "id": "uuid",
      "version": "1.52.1",
      "model": "RC500",
      "filename": "openwrt-rc500-1.52.1-sysupgrade.bin",
      "size": 15728640,
      "sha256": "a1b2c3d4...",
      "releaseNotes": "Bug fixes for cellular failover timing",
      "uploadedAt": "2026-05-20T10:00:00Z",
      "deviceCount": 85
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 12
  }
}

Upload Firmware

POST /api/firmware
Content-Type: multipart/form-data

version: 1.53.0
model: RC500
releaseNotes: New GPS reporting improvements
file: @firmware-1.53.0.bin

Response (201)

{
  "id": "uuid",
  "version": "1.53.0",
  "model": "RC500",
  "filename": "firmware-1.53.0.bin",
  "size": 15890432,
  "sha256": "computed-hash...",
  "uploadedAt": "2026-05-24T12:00:00Z"
}

Deploy Firmware

POST /api/firmware/deploy
Content-Type: application/json

{
  "firmwareId": "firmware-uuid",
  "targets": {
    "type": "tag",
    "filter": {"region": "us-west"}
  },
  "options": {
    "preserveConfig": true,
    "strategy": "staged",
    "stages": [
      {"percentage": 5, "waitMinutes": 60},
      {"percentage": 25, "waitMinutes": 240},
      {"percentage": 100, "waitMinutes": 0}
    ]
  }
}

Target Types

Type	Filter	Description
`all`	`{model: "RC500"}`	All devices of a model
`tag`	`{region: "us-west"}`	Devices matching tags
`devices`	`["uuid1", "uuid2"]`	Specific device IDs
`single`	`"device-uuid"`	Single device

Response (202)

{
  "deploymentId": "deploy-uuid",
  "firmwareVersion": "1.53.0",
  "targetCount": 32,
  "strategy": "staged",
  "status": "in_progress",
  "createdAt": "2026-05-24T12:00:00Z"
}

Get Deployment Status

GET /api/firmware/deployments/deploy-uuid

Response (200)

{
  "id": "deploy-uuid",
  "firmwareId": "firmware-uuid",
  "firmwareVersion": "1.53.0",
  "status": "in_progress",
  "targetCount": 32,
  "progress": {
    "succeeded": 8,
    "failed": 1,
    "pending": 23,
    "inProgress": 0
  },
  "currentStage": 2,
  "stages": [
    {"percentage": 5, "status": "completed"},
    {"percentage": 25, "status": "in_progress"},
    {"percentage": 100, "status": "pending"}
  ],
  "createdAt": "2026-05-24T12:00:00Z",
  "startedAt": "2026-05-24T12:00:05Z"
}

Deployment States

Status	Description
`pending`	Created, not yet started
`in_progress`	Actively deploying to devices
`paused`	Manually paused (can resume)
`completed`	All targets succeeded
`failed`	Too many failures, stopped
`cancelled`	Manually cancelled

Delete Firmware

DELETE /api/firmware/uuid