HTTP API

Everything the web app does is a plain HTTP API you can call from scripts or CI: submitting build/test jobs and driving your pods (power, capture, signal generation, flashing, the waveform library). All paths below are under your server's /api base (e.g. https://www.embeddedci.com/api).

Authentication

Create a personal API key and send it as an Authorization: ApiKey header. A key authenticates as you, scoped to your organization. It is not limited to job submission; it works across the whole API, including the BenchPod endpoints.

# Create a key on the API keys page, then send it on every request:
Authorization: ApiKey eci_<kid>_<secret>

Keys carry scopes, enforced per endpoint: jobs:submit for job submission, benchpod:control for the BenchPod endpoints (pods, command, capture, waveforms, DAC, and the /auth/token exchange), aivision:control for AI Vision boards (registering and driving them; it never reaches a pod, and benchpod:control never reaches a board), and emi:analyze for the EMI Analyzer (board upload and analysis runs; see EMI analysis in CI). Pick scopes when you create a key, or edit them later, on the API keys page. A key missing the required scope gets a 403. (Scopes constrain API keys only; interactive web sessions are unrestricted.)

BenchPod firmware updates (/ota, including release installs and aborts), persisted settings (Wi-Fi, cloud, Ethernet, DAC safety limits, calibration, the pod's LAN and signature policies) and every other T2/T3 command need an organization owner or admin. With an API key that means the benchpod:admin scope on top of benchpod:control, and the key's owner must still be an owner or admin; even an owner's key without the scope gets a 403. Only organization owners and admins can give a key benchpod:admin, and it is never a default. A cloud token from /auth/token keeps this only when the key or session that minted it has it; GitHub Actions OIDC tokens never do (reads and instrument control only).

Direct pod access (REST)

These accept your API key directly, with no exchange step. This is the same surface the BenchPod page uses. You address a pod by its id (from GET /benchpod/devices). Every path needs the benchpod:control scope; the ones marked benchpod:admin also need an organization owner or admin. Commands that touch the pod answer 409 when it is offline or another user or CI run holds its lease, and pass the pod's own refusal on as the error message (see the firmware command reference).

# List your pods
curl -H "Authorization: ApiKey $ECI_KEY" \
     https://www.embeddedci.com/api/benchpod/devices

# Power the target on (efuse 1 = internal 5V) via the generic command channel
curl -H "Authorization: ApiKey $ECI_KEY" -H 'Content-Type: application/json' \
     -d '{"command":{"cmd":"target_power","efuse":1,"state":1}}' \
     https://www.embeddedci.com/api/benchpod/devices/<device_id>/command

# Start an ADC (scope) capture, then poll the result
curl -H "Authorization: ApiKey $ECI_KEY" -H 'Content-Type: application/json' \
     -d '{"device_id":"<id>","samples":1024,"sample_rate_mhz":1}' \
     https://www.embeddedci.com/api/scope/captures/start
curl -H "Authorization: ApiKey $ECI_KEY" \
     https://www.embeddedci.com/api/capture/<capture_id>

SPI flash

The pod can program a 25-series SPI NOR flash on the DUT (W25Q, MX25, GD25, IS25 and similar, first 16 MB) over four LA pins. It needs a pod that announces spi_master. The pins come from the wiring profile (spi_sclk, spi_mosi, spi_miso, spi_cs); sck, mosi, miso, cs, hz (default 1 MHz), mode (0 or 3) and hold_reset (default true) override them per request. The start address must be a multiple of 4 KB. The DUT is held in reset during the job and released at the end, also on failure. Over the cloud expect about 40 KB/s (25 to 30 seconds per MB); blank (0xFF) areas are skipped. The same panel is on the Flash DUT tab.

# Read the chip ID (pins from the wiring profile's spi_* keys)
curl -X POST -H "Authorization: ApiKey $ECI_KEY" \
     https://www.embeddedci.com/api/benchpod/devices/<device_id>/spi/flash/id
# -> {"id":"ef4017","present":true,"size":8388608,"manufacturer":"Winbond",...}

# Write an image at 0x10000 (the body is the raw .bin), then poll until "live" is false
curl -H "Authorization: ApiKey $ECI_KEY" -H 'Content-Type: application/octet-stream' \
     --data-binary @app.bin \
     "https://www.embeddedci.com/api/benchpod/devices/<device_id>/spi/flash?addr=0x10000&name=app.bin"
curl -H "Authorization: ApiKey $ECI_KEY" \
     https://www.embeddedci.com/api/benchpod/devices/<device_id>/spi/flash

For the live WebSocket streams, pass the key in the ?token= query parameter (an eci_ token is recognized as an API key):

# Live capture/terminal streams take the key as a ?token= query param
# (eci_ tokens are recognised as API keys):
wss://www.embeddedci.com/api/ws/capture?device_id=<id>&token=$ECI_KEY

Capabilities gate some features per board: e.g. generate/replay require an AC waveform DAC and are rejected on DC-only boards.

Drive pods by name (cloud): token exchange

The cloud endpoints address a pod by name and add a one-consumer-at-a-time lease and a raw byte-tunnel (for flashing/captures from CI). They take a short-lived session token, not your static key, so a long-lived secret never ends up in a WebSocket URL or a CI log. Mint one from your API key with POST /auth/token (the API-key analogue of the GitHub Actions OIDC exchange).

# 1) Exchange your API key for a short-lived cloud-session token.
#    Omit the body for any pod in your org, or scope it down:
curl -H "Authorization: ApiKey $ECI_KEY" -H 'Content-Type: application/json' \
     -d '{"devices":["pod-a"],"ttl_seconds":3600}' \
     https://www.embeddedci.com/api/auth/token
# -> { "token": "<jwt>", "token_type": "bearer", "expires_at": "...", "expires_in": 3600 }

# 2) Drive a pod BY NAME with the minted token (Bearer):
curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     -H 'X-Benchpod-Device: pod-a' \
     -d '{"cmd":"status"}' \
     https://www.embeddedci.com/api/cloud/devices/command

# WebSocket byte-tunnel (flash / capture) — token in the query string is a
# short-lived JWT, never your static key:
wss://www.embeddedci.com/api/cloud/devices/ws?device=pod-a&token=$TOKEN

Not covered here

Some routes are internal to the web app, the CLI or our operations, and may change without notice: the CLI sign-in flow (/auth/device/*), guest sessions (/auth/guest*, /auth/benchpod/revoke-refresh), the trusted-repo form's repo lookup, and everything under /admin, /agent and /hw-agent.

Higher-level clients

Most users don't call these endpoints by hand. The pytest SDK, CLI, and MCP server wrap them (auth, leasing, tunnels, chunk reassembly). Reach for those first; drop to the raw API for custom integrations. The Python SDK performs the /auth/token exchange for you: set BENCHPOD_API_KEY (or pass api_key=) and connect to embeddedci:<name>.