Skip to content
Emberwire OTA firmware delivery

API reference · v1

Documentation

Everything the platform does is reachable over one REST API at https://api.{{DOMAIN}}/v1. The dashboard is a client of it, the CLI is a client of it, and there is nothing in either that you cannot do from CI.

Quickstart

From an artifact on disk to a canary cohort. Five commands.

shell
$ ew login --token "$EW_TOKEN"
  authenticated · org_northwind · scopes: image:write release:write wave:control

$ ew image push --line pl_meter_g4 \
                --version 4.19.2 \
                build/meter-4.19.2.bin
  uploading 3,355,443 bytes · 27 of 52 blocks are new
  img_8f3a21c9 · sha256:4c1b9e77a0d5f382c6be41d09ab7255ef8c3410d6b9a7f2e5c8d1049ab3e77c2

$ ew release create --line pl_meter_g4 \
                    --image img_8f3a21c9 \
                    --wave default \
                    --sign-with rk_meter_2026q3
  rel_2026_09_16_a · manifest signed · 12 deltas precomputed (4m 11s)
  matched 478,214 devices of 480,000 in product line

$ ew wave start rel_2026_09_16_a
  cohort 1 (canary) · 0.1% · 478 devices · soak 4h

$ ew wave status rel_2026_09_16_a --watch
  cohort 1 · offered 478 · downloaded 471 · confirmed 468 · rolled back 0
  next cohort in 3h 14m

Authentication

A bearer token in the Authorization header. Tokens are scoped, expire on a schedule you set, and are never accepted as a query parameter.

curl
curl -sS https://api.{{DOMAIN}}/v1/product-lines \
  -H "Authorization: Bearer $EW_TOKEN" \
  -H "Accept: application/json"
Scope Grants Typical holder
image:writeUpload images, read image metadata.CI build job
release:writeCreate and sign releases, edit selectors.Release job
wave:controlStart, pause, resume and halt waves.On-call operator
device:readQuery device state and history.Support tooling
audit:exportExport signed per-device transition logs.Compliance

A token with wave:control can stop a rollout but cannot create one. That separation is the point: the person woken at 03:00 needs the ability to halt, not to publish.

Endpoints

Method Path Does Scope
GET/v1/product-linesList product lines and their current recommended build.device:read
POST/v1/imagesStart a chunked upload. Returns the block list to send.image:write
PUT/v1/images/{id}/blocks/{n}Upload one block. Idempotent; re-sending a block is free.image:write
POST/v1/images/{id}/finalizeClose the upload; server verifies the whole-image digest.image:write
POST/v1/releasesCreate a release: image, selector, wave plan.release:write
GET/v1/releases/{id}/manifestFetch the signed manifest as devices receive it.device:read
POST/v1/releases/{id}/signSubmit a detached signature produced by your own HSM.release:write
POST/v1/waves/{id}/startBegin the first cohort.wave:control
POST/v1/waves/{id}/pauseStop advancing. In-flight transfers finish.wave:control
POST/v1/waves/{id}/haltStop and freeze. Requires a reason string; it is kept.wave:control
GET/v1/waves/{id}Cohort state, counters, error-code histogram.device:read
GET/v1/devicesQuery devices by selector. Cursor-paginated.device:read
GET/v1/devices/{id}/historyFull transition history for one device.device:read
POST/v1/devices/{id}/tagsAdd or remove tags used by selectors.release:write
POST/v1/exports/auditRequest a signed JSONL export for a date range.audit:export
GET/v1/nodesDelivery node inventory and health as devices see it.device:read

Webhooks

Emberwire posts to your endpoint on cohort transitions, halts and device-level failures. Payloads are signed with an Ed25519 key you fetch once from /v1/webhooks/key; verify the X-Emberwire-Signature header before acting on anything.

POST to your endpoint — wave.halted
{
  "event": "wave.halted",
  "sent_at": "2026-09-17T02:14:38Z",
  "release": "rel_2026_09_16_a",
  "product_line": "pl_meter_g4",
  "cohort": 2,
  "reason": "fail_ratio",
  "counters": {
    "offered": 4812,
    "downloaded": 4796,
    "confirmed": 4753,
    "rolled_back": 43,
    "fail_ratio": 0.0089
  },
  "errors": { "E_TIMEOUT": 39, "E_PATCH": 3, "E_NOSPACE": 1 },
  "advance_blocked": true
}

Deliveries are retried for 24 hours with exponential backoff. A webhook that never succeeds never changes platform behaviour — the halt has already happened; the webhook only tells you about it.

Error codes

API errors

Code HTTP Meaning and what to do
E_AUTH401Token missing, expired or revoked. Re-issue; do not retry.
E_SCOPE403Token is valid but lacks the scope for this call.
E_NOTFOUND404Unknown identifier, or one belonging to another namespace.
E_CONFLICT409That version already exists for the product line. Versions are immutable.
E_HALTED409The wave is frozen. Acknowledge the halt before any advance call.
E_DIGEST422Uploaded bytes do not match the declared digest. The upload is discarded.
E_UNSIGNED422Release has no valid manifest signature. It cannot be started.
E_SELECTOR422Selector matches zero devices, or more than the plan's device ceiling.
E_RATE429Rate limited. Honour Retry-After; it is always present.
E_INTERNAL500Our fault. Safe to retry with the same idempotency key.

Device-reported codes

Code Reported when Counts toward halt
E_CHAINSignature does not chain to the device trust anchor.freezes the release
E_DIGESTStaged image does not match the manifest digest.yes
E_PATCHDelta could not be applied to the reported base.yes
E_NOSPACENot enough room to stage. Includes free-byte count.no — device excluded
E_SLOTFlash write or erase failed on the inactive slot.yes
E_TIMEOUTNo ew_confirm() within the watchdog window.yes
E_POWERPower was lost mid-transfer; resumed on the next check-in.no
E_HWREVManifest does not apply to this hardware revision.no — device excluded

Conventions

Idempotency

Every POST accepts an Idempotency-Key header. Repeating a request with the same key returns the original result rather than creating a second release. Keys are kept for 24 hours.

Pagination

Cursor-based. Responses carry next_cursor until exhausted. Offsets are not offered, because a device list changes while you are reading it.

Times

RFC 3339, always UTC, always with an explicit Z. Device-local scheduling is expressed in windows, never in timestamps.

Immutability

Images, versions and manifests never change after they are finalised. To fix a bad build you publish a new version; there is no in-place edit and no way to make a device's history inconsistent with what it actually ran.

Sizes

All byte counts in the API are exact integers. Human-readable sizes on this site use KB = 1024 bytes, consistently, including in the tables on the overview.

Deprecation

A field is marked deprecated in the specification for at least two quarters before it is removed, and removals are listed in the changelog with the date they take effect.

Limits

Limit Value Notes
Control-plane requests600 / min / tokenBurst of 60. Retry-After on every 429.
Concurrent block uploads20Per organisation, not per token.
Maximum image size4 GBAbove this, split the image or talk to us.
Blocks kept hot for deltas12 buildsOlder bases receive the full image.
Selector evaluationon every check-inNot rate limited; it is part of the device protocol.
Webhook retry window24 hExponential backoff, then dropped with a record.
Audit export range92 days per requestLonger ranges are split automatically by the CLI.
Device check-insnot rate limitedThey are the product. They do not consume API quota.

Common questions

Can I sign releases without giving Emberwire the private key?

Yes, and it is the default recommendation. Create the release, fetch the canonical manifest bytes, sign them in your own HSM, and submit the detached signature to /v1/releases/{id}/sign. The release cannot start without a signature that validates against the chain your devices carry.

What happens to a wave if the API is unreachable?

A running wave continues; cohort advancement is driven inside the platform, not by your client. What you lose is the ability to change it. If the control plane itself is degraded, the wave scheduler holds at its current cohort rather than advancing blind — the safe direction is always to stop. See Status for how that has behaved in practice.

Can I target a single device?

Yes, through a tag selector. It is the normal way to run a field trial: tag the units, target the tag, and exclude that tag from the general release with tag_not.

How do I test without real devices?

The CLI ships a simulator: ew sim --line pl_meter_g4 --devices 500 --fail-ratio 0.02 runs virtual agents through the real device protocol against your organisation, including failures and rollbacks. Simulated devices are billed as devices while they exist and are excluded from audit exports.

Is there a hard dependency on the Emberwire CLI?

No. The CLI is a convenience over the same REST calls, and the OpenAPI document is published at /v1/openapi.json. Several customers drive the whole thing from curl in a pipeline and never install it.

What does a delivery node see?

Content-addressed blocks and the device identity presenting a valid manifest reference. It does not hold your signing keys, cannot mint a manifest, and cannot serve a block that no signed manifest commits to. Details in Security.