API reference

The authoritative machine-readable version of this page is /openapi.yaml. To call anything here from the browser, use the explorer.

{prefix} below is either /api/public or /api/v1. Routes shown with {prefix} exist on both and use the same handler; only the middleware in front differs.

Policy

The Control Plane stores versioned policy documents. Runtimes fetch the active one and evaluate locally.

POST requires yaml in the body; version, name, description, and updated_by are optional. An omitted version is generated from the UTC timestamp. The YAML is validated before it is stored — invalid policy is rejected with 400 rather than shipped to runtimes.

Versions are immutable. Re-publishing an existing version returns 409. Audit records reference the policy version that decided them, so a version that could be edited would make historical decisions unexplainable. Publishing deactivates the previous version in the same transaction, so there is always exactly one active policy per organisation.

Audit

Query parameters on GET: q (substring across command, executor, resource, provider, capability), decision, provider, consumer, limit (default 100, max 1000), offset. The response carries events, total, returned, limit, and offset — page with offset, and trust total for the count.

The runtime writes its own local audit record first and treats this endpoint as a best-effort mirror. A failed uplink loses nothing that matters: the local record is the system of record.

Catalog

Providers and capabilities are generated from the engineering-runtime repository at deploy time and embedded in the image. This API never executes the runtime binary, and never calls GitHub to answer a request.

These are the tenant view. They need an organisation and read the database to merge status and history. For what the runtime supports — no auth, no tenant, with the runtime commit it was built from — use the contract view on /metadata/providers and /metadata/capabilities. The Catalog page explains which to pick.

Provider status is not stored in the catalog: it is derived per request. A provider seen in audit within the last 24 hours reads connected, otherwise offline, unless a stored row overrides it. last_used comes from the most recent audit event naming that provider.

Fleet

Fleet status is derived from last_seen at read time: online within 15 minutes, idle within 24 hours, offline after that. Nothing marks a runtime offline on a schedule — a runtime that stops reporting simply ages out, which is the correct answer when the network, not the runtime, is what failed.

Dashboard

Returns fleet counts, catalog counts, active policy version, 24-hour command totals split by decision, AI-attributed operations, a per-provider breakdown, and the ten most recent audit events.

Auth and management (/api/v1 only)

These have no /api/public equivalent — the public surface has no accounts.

See Authentication for how credentials are checked.

Health and version

Portal and contracts

Errors

Errors are JSON with an error string.

POST /audit answers 202 Accepted, not 200: the event is stored, and the runtime's local record was already the authoritative one.