REST API

The dashboard is a client of this API and nothing more, so anything it can do is scriptable. It is served on the same address as the UI — :8088 by default, --ui-addr to change it.

Endpoints

An unmatched path under /api/ returns a JSON 404 rather than falling through to the dashboard's HTML shell — handing a script a page of HTML where it expected JSON is a miserable thing to debug.

Starting a run

curl -X POST --data-binary @test.yaml http://localhost:8088/api/v1/runs

The body is a LoadWave configuration in either YAML or JSON. Both go through the same parser, because JSON is a subset of YAML — which lets the browser post the object it already has while a CI script sends the very file it keeps in the repository.

202 Accepted
{ "runId": "r-3f8a91" }

Reading and saving a run's configuration

curl http://localhost:8088/api/v1/runs/r-3f8a91/config

200 OK
{
  "yaml": "name: checkout\nbaseURL: https://staging.example.com\n...",
  "sourcePath": "/home/ci/test.yaml",
  "draft": { "name": "checkout", "baseURL": "https://staging.example.com", "...": "..." }
}

Saving an edit is only meaningful when sourcePath is non-empty:

curl -X PUT --data-binary @test.yaml http://localhost:8088/api/v1/runs/r-3f8a91/config

Stopping a run

curl -X POST http://localhost:8088/api/v1/runs/r-3f8a91/stop \
  -H 'Content-Type: application/json' \
  -d '{"graceful": true, "reason": "canary rolled back"}'

The body is optional; omitting it stops gracefully.

graceful defaults to true because an abrupt stop manufactures a cliff of cancelled requests that then show up as failures in the very results you are about to read.

Stopping a run does not stop the process. The coordinator keeps serving, still holding the results.

Rescaling a run

curl -X POST http://localhost:8088/api/v1/runs/r-3f8a91/scale \
  -H 'Content-Type: application/json' \
  -d '{"vus": 500, "rampSeconds": 30}'

Both must be non-negative; a negative value is a 400. Prefer a ramp — a step change in concurrency measures the step rather than the service.

The snapshot

GET /api/v1/snapshot returns the coordinator's whole state, and it is the same object --out results.json writes.

{
  "build": { ... },
  "run": { ... },
  "runs": [ ... ],
  "agents": [ ... ],
  "ticks": [ ... ],
  "series": [ ... ],
  "totals": { ... },
  "endpoints": [ ... ],
  "failures": [ ... ],
  "events": [ ... ],
  "resolutionSeconds": 1
}

The run summary

Under run, and in each element of runs:

An agent

Elements of agents, and the body of GET /api/v1/agents:

A worker

Elements of an agent's workers:

A threshold result

A tick

Elements of ticks, one per resolutionSeconds of the run — this is what the live charts plot:

Fetching a report

curl -O http://localhost:8088/api/v1/runs/r-3f8a91/report.html

Served as a download with a generated filename, rather than as a page: this is an artefact to keep, attach to a ticket or archive alongside a release, not another view of the live dashboard. It is one self-contained HTML file with the charts as inline SVG.

A 409 means the run has no results to report yet.

The live stream

GET /api/v1/stream        (WebSocket)

One envelope with a discriminating type, so a client has a single message handler rather than a connection state machine.

The first frame is always {"type": "snapshot", "snapshot": {...}} — a client connecting mid-run sees the history it missed rather than starting its charts from wherever the next tick happens to land. After that come incremental updates carrying whichever of run, agents, ticks, thresholds and events changed.

The connection is pinged every 25 seconds so intermediaries do not close it during the quiet stretch between runs.

loadwave serve --allowed-origin https://loadwave.internal.example.com

Shutting the process down

curl -X POST http://localhost:8088/api/v1/shutdown

Only available when the server was started with --allow-shutdown; this is also what puts the Power off control in the dashboard.

Stopping a run and stopping the process are deliberately different actions — a run ending leaves the coordinator serving, still holding its results.

See also