Engineering Runtime API

Getting started

Make your first call, point a runtime at this API, and understand which prefix you want.

Everything below works against the live host — no account and no API key.

1. Check you can reach the API

curl -s https://api.engineeringruntime.com/api/public/health
# {"status":"ok","edition":"enterprise"}

/health (no prefix) answers the same thing and is what uptime checks should poll. /version tells you which build responded.

2. Choose your prefix

You are Use Why
Building against the demo, or shipping Community runtimes /api/public Always open, no credential distribution
Building the enterprise app, or running authenticated runtimes /api/v1 Carries login, org management, API keys

Shared routes behave identically on both. Changing prefix does not change a request body or a response shape — only who is allowed to send it.

3. Read the active policy

This is the call a runtime makes on every runtime portal sync:

curl -s 'https://api.engineeringruntime.com/api/public/policies?active=true' \
  -H 'X-Runtime-Client: engineering-runtime'

You get the single active policy document, including its yaml body. The runtime writes that YAML to a local file and evaluates every subsequent command against the local copy — it does not call this API per command.

Sending X-Runtime-Client has the same effect as ?active=true. That is deliberate: a runtime that forgets the query parameter still gets one policy rather than a list it would have to filter.

4. Send an audit event

curl -s -X POST https://api.engineeringruntime.com/api/public/audit \
  -H 'Content-Type: application/json' \
  -d '{
    "executor": "kishore",
    "consumer": "human",
    "command": "github repo list",
    "provider": "github",
    "policy_decision": "ALLOWED",
    "status": "success",
    "duration_ms": 100
  }'

202 Accepted comes back with the stored event. Post {"events":[…]} to ingest a batch in one request.

The ingest endpoint accepts camelCase aliases (user, tool, decision, policyVersion, durationMs, ai) alongside the canonical snake_case fields, so older runtime builds keep reporting without a migration. Missing fields are filled in: consumer defaults to human, status is derived from policy_decision, provider falls back to the first word of command, and an absent timestamp becomes now.

5. Point a runtime at this API

export RUNTIME_PORTAL_ENABLED=true
export RUNTIME_PORTAL_BASE_URL=https://api.engineeringruntime.com
export RUNTIME_PORTAL_PATH_PREFIX=/api/public   # or /api/v1

runtime portal status
runtime portal sync

runtime portal sync pulls the active policy and caches it locally. From then on the runtime evaluates policy without touching the network; audit uplink and fleet heartbeats are best-effort and never block a command.

6. Generate a client

The contract at /openapi.yaml is the supported way to build against this API.

curl -sO https://api.engineeringruntime.com/openapi.yaml

# any OpenAPI 3.1 generator, e.g.
openapi-generator-cli generate -i openapi.yaml -g go -o ./client

Prefer generated clients over hand-written ones, and prefer both over reading this repository. The contract is the integration point.

Running your own Control Plane API

The Control Plane API source repository is private. Public visitors cannot clone or start it, and this portal does not publish seed passwords or local bootstrap steps.

You want Do this
Try the live API The /api/public calls above, or the demo UI at demo.engineeringruntime.com
Enterprise UI / keys Request access via app.engineeringruntime.com — credentials are issued on request
Local development (collaborators only) Use RUN.md inside the private engineering-runtime-app-api repo — not this public site

Where to go next