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.
curlcurl -sS https://api.{{DOMAIN}}/v1/product-lines \
-H "Authorization: Bearer $EW_TOKEN" \
-H "Accept: application/json"
| Scope | Grants | Typical holder |
|---|---|---|
| image:write | Upload images, read image metadata. | CI build job |
| release:write | Create and sign releases, edit selectors. | Release job |
| wave:control | Start, pause, resume and halt waves. | On-call operator |
| device:read | Query device state and history. | Support tooling |
| audit:export | Export 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-lines | List product lines and their current recommended build. | device:read |
| POST | /v1/images | Start 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}/finalize | Close the upload; server verifies the whole-image digest. | image:write |
| POST | /v1/releases | Create a release: image, selector, wave plan. | release:write |
| GET | /v1/releases/{id}/manifest | Fetch the signed manifest as devices receive it. | device:read |
| POST | /v1/releases/{id}/sign | Submit a detached signature produced by your own HSM. | release:write |
| POST | /v1/waves/{id}/start | Begin the first cohort. | wave:control |
| POST | /v1/waves/{id}/pause | Stop advancing. In-flight transfers finish. | wave:control |
| POST | /v1/waves/{id}/halt | Stop 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/devices | Query devices by selector. Cursor-paginated. | device:read |
| GET | /v1/devices/{id}/history | Full transition history for one device. | device:read |
| POST | /v1/devices/{id}/tags | Add or remove tags used by selectors. | release:write |
| POST | /v1/exports/audit | Request a signed JSONL export for a date range. | audit:export |
| GET | /v1/nodes | Delivery 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_AUTH | 401 | Token missing, expired or revoked. Re-issue; do not retry. |
| E_SCOPE | 403 | Token is valid but lacks the scope for this call. |
| E_NOTFOUND | 404 | Unknown identifier, or one belonging to another namespace. |
| E_CONFLICT | 409 | That version already exists for the product line. Versions are immutable. |
| E_HALTED | 409 | The wave is frozen. Acknowledge the halt before any advance call. |
| E_DIGEST | 422 | Uploaded bytes do not match the declared digest. The upload is discarded. |
| E_UNSIGNED | 422 | Release has no valid manifest signature. It cannot be started. |
| E_SELECTOR | 422 | Selector matches zero devices, or more than the plan's device ceiling. |
| E_RATE | 429 | Rate limited. Honour Retry-After; it is always present. |
| E_INTERNAL | 500 | Our fault. Safe to retry with the same idempotency key. |
Device-reported codes
| Code | Reported when | Counts toward halt |
|---|---|---|
| E_CHAIN | Signature does not chain to the device trust anchor. | freezes the release |
| E_DIGEST | Staged image does not match the manifest digest. | yes |
| E_PATCH | Delta could not be applied to the reported base. | yes |
| E_NOSPACE | Not enough room to stage. Includes free-byte count. | no — device excluded |
| E_SLOT | Flash write or erase failed on the inactive slot. | yes |
| E_TIMEOUT | No ew_confirm() within the watchdog window. | yes |
| E_POWER | Power was lost mid-transfer; resumed on the next check-in. | no |
| E_HWREV | Manifest 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 requests | 600 / min / token | Burst of 60. Retry-After on every 429. |
| Concurrent block uploads | 20 | Per organisation, not per token. |
| Maximum image size | 4 GB | Above this, split the image or talk to us. |
| Blocks kept hot for deltas | 12 builds | Older bases receive the full image. |
| Selector evaluation | on every check-in | Not rate limited; it is part of the device protocol. |
| Webhook retry window | 24 h | Exponential backoff, then dropped with a record. |
| Audit export range | 92 days per request | Longer ranges are split automatically by the CLI. |
| Device check-ins | not rate limited | They 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.