Developer documentation

API

Control-plane API schema and regeneration workflow.

The API is the control plane’s contract with the rest of the system. Workspace agents, edge components, deploy workers, analytics workers, and local smokes all depend on it to resolve state and report outcomes.

Because the control plane owns durable decisions, API changes should be treated as contract changes. Update tests and the checked-in schema when behavior changes.

The live FastAPI schema is available from the running control plane:

/openapi.json

The checked-in API snapshot is:

docs/api/openapi.json

Regenerate it after API changes:

python3 scripts/export_openapi.py

Docker-based equivalent:

docker compose -f dev/docker-compose.yml run --rm \
  -v "$PWD:/workspace" -w /workspace control-plane \
  python scripts/export_openapi.py

API changes should include focused control-plane tests and an updated snapshot.

That keeps the source code, generated schema, and developer documentation aligned for the components that call the control plane.