Firmware and device settings API

This page covers two families of routes: firmware updates (OTA) and remote device settings. How both work for people is in Firmware updates (OTA), Firmware rollout waves and Remote device settings. Paths are under https://<your host>/tenant/<tenantId>.

Firmware routes

Adding and revoking signing keys is an Owner permission, so an API key cannot do it.

Upload a package

POST /api/iot/ota/packages takes multipart/form-data with two parts: file (the image) and meta (JSON text). The checksum is checked before anything is stored, and the signature is verified against your registered keys.

curl -s -X POST "https://$HOST/tenant/$TENANT/api/iot/ota/packages" \
  -H "Authorization: Bearer $HERMETRY_KEY" \
  -F "file=@router-fw-2.5.0.bin" \
  -F 'meta={"title":"router-fw","version":"2.5.0","checksum":"<sha256 of the file>","signatureScheme":"usign-ed25519","signature":"<text of the .sig file>","profileId":"a1b2…","releaseNotes":"Fixes LTE reconnect."}'

The default maximum size is 64 MiB. The answer is 201 { "package": {...} }.

Assign and roll out

{
    "packageId": "f00d…",
    "targetType": "PROFILE",
    "targetId": "a1b2…",
    "waves": [
        {
            "size": {
                "percent": 5
            },
            "soakMin": 60,
            "minSuccessPct": 95,
            "maxFailurePct": 2,
            "maxDurationMin": 1440
        },
        {
            "size": {
                "percent": 100
            },
            "soakMin": 0,
            "minSuccessPct": 95,
            "maxFailurePct": 2,
            "maxDurationMin": 2880
        }
    ]
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/ota/assignments' \
  -H 'Content-Type: application/json' \
  -d '{"packageId":"f00d…","targetType":"PROFILE","targetId":"a1b2…","waves":[{"size":{"percent":5},"soakMin":60,"minSuccessPct":95,"maxFailurePct":2,"maxDurationMin":1440},{"size":{"percent":100},"soakMin":0,"minSuccessPct":95,"maxFailurePct":2,"maxDurationMin":2880}]}'

{
    "assignment": {
        "…": "…"
    },
    "preview": {
        "…": "…"
    },
    "result": {
        "…": "…"
    }
}

{
    "assignment": null,
    "preview": {
        "…": "…"
    }
}

{
    "message": "Only a ready package can be assigned.",
    "code": "CONFLICT"
}

A wave’s size is { "percent": 0–100 } or { "count": 1–100000 }; the last wave takes the rest. soakMin 0 to 10,080, minSuccessPct and maxFailurePct 0 to 100, optional maxFailures, maxDurationMin 5 to 43,200.

Rollout statuses: RUNNING, PAUSED, COMPLETED, ABORTED. A failed gate pauses the rollout; resume continues, abort ends it.

Update states

A device’s update moves through QUEUED, INITIATED, WAITING, DOWNLOADING, DOWNLOADED, VERIFIED, UPDATING and ends UPDATED, FAILED, TIMEOUT, ROLLED_BACK, SKIPPED or CANCELLED. Only FAILED, TIMEOUT and ROLLED_BACK can be retried ({ "action": "retry" }), up to the attempt limit.

OTA settings

PUT /api/iot/ota/settings/profile/{profileId} takes otaEnabled, allowMetered, allowUnsigned, downloadTimeoutMin (5 to 1,440), updateTimeoutMin (2 to 240), maxAttempts (1 to 10); null goes back to the default. For a device (/settings/device/{deviceId}) only allowMetered is taken: “A device takes only the metered-link setting.”

Webhook events: ota.update.* and ota.rollout.*, see the Webhook event reference.

Device settings routes

Remote settings are for licensed devices whose model publishes a settings manifest.

What a write may change depends on the class of each changed setting: operating settings need iot_device_settings.operate, configuration settings iot_device_settings.write, dangerous settings iot_device_settings.dangerous.write (Owner only, so never an API key) and "confirm": true.

Change a section

GET  /api/iot/devices/{deviceId}/settings/network        → ETag: "7"
PATCH /api/iot/devices/{deviceId}/settings/network
If-Match: "7"
{ "patch": { "lte": { "apn": "iot.example" } } }

• If-Match is required: without it, 428 “If-Match is required: send the rev you read.”
• A section changed since you read it: 412 “The section changed since it was read; read it again.” (rev_mismatch).
• ?dryRun=true validates and lists what would change, and stores nothing.
• A merge patch merges objects, deletes with null and replaces lists whole.
• Writes are limited to 600 per organisation per minute.
• Secrets are never returned: a secret setting reads as { "set": true }.

A device that does not take settings by section answers 409 “This device does not take settings by section.”; one whose manifest is not in the catalog yet, “The settings manifest of this device’s model and firmware is not in the catalog yet.”

Bulk jobs

POST /api/iot/device-settings/jobs with Idempotency-Key header: name (up to 80), baselineId or sections, selector (deviceIds, profileId or models), optional waves ({ "percent": [1, 10, 100] } or { "count": [...] }, up to 10), gates (minApplied, maxReverted as fractions 0 to 1), onConflict (queue or skip), offlineExpiryDays (1 to 90), waveTimeoutMin (1 to 1,440), confirm. A repeated Idempotency-Key answers the first job (200). ?dryRun=true answers the plan. Refusals: 409 too_many_jobs; 422 confirm_required, invalid_sections, no_devices, too_many_devices; 403 class_forbidden.