Engineering Runtime API

Provider & capability catalog

What the runtime supports, published as a versioned contract with the commit it was built from.

Providers are the platforms the runtime can operate — GitHub, files, and whatever ships next. Capabilities are packaged Markdown workflows the runtime executes. Together they are the answer to "what can Engineering Runtime actually do?", and this host publishes that answer as a versioned contract.

curl -s https://api.engineeringruntime.com/metadata/catalog

No token, no organisation, no database. Just what the runtime supports.

Two views of the same data — pick the right one

There are two ways to ask about providers and capabilities, and they answer different questions. Choosing the wrong one is the main mistake this page exists to prevent.

Contract view Tenant view
Path /metadata/providers · /metadata/capabilities {prefix}/providers · {prefix}/capabilities
Answers What does the runtime support? What is my organisation doing with it?
Auth None, ever Organisation-scoped
Database Not touched Read for status and history
Adds — status, last_used, scope
Use for Docs, agents, client generation, automation Dashboards and UIs

The tenant view merges live status derived from audit activity, so its answer changes as your fleet runs commands. The contract view does not: it changes only when a new catalog is deployed.

If you are building a dashboard, use the tenant view. If you are asking what the product can do, use the contract view — it needs no credentials and gives the same answer to everyone.

The envelope

Every contract response carries the same header block, so one request tells you what you are holding:

{
  "contract_version": "1.0",
  "generated_at": "2026-08-05T15:46:57Z",
  "source": "embed",
  "runtime": {
    "repo": "engineering-runtime",
    "commit": "38eec00c62b1584a9a1d074a37d99521ab387440",
    "short_commit": "38eec00",
    "ref": "main",
    "known": true
  },
  "counts": { "providers": 2, "capabilities": 45 }
}

runtime.commit is the field that makes this auditable. Without it you can see when a catalog was built but not what from — and you cannot tell a contract that is merely old from one that has drifted from the runtime it claims to describe. If a catalog is ever generated without a runtime checkout, known is false and the commit is absent rather than guessed.

Compatibility

contract_version is a promise, not a build number:

Change Version
Adding a field, provider or capability minor — 1.0 → 1.1
Removing or renaming a field major — 1.x → 2.0

Pin to the major. A catalog generated before versioning existed reports "0", which is honest rather than a claim to satisfy 1.0.

Endpoints

GET /metadata/catalog

The envelope alone — version, provenance, counts, and links to the rest. The cheapest way to check whether the catalog you have is current.

GET /metadata/providers

Provider inventory: id, name, auth model, operation count, operation names, and how many capabilities target it.

curl -s https://api.engineeringruntime.com/metadata/providers

GET /metadata/capabilities

Capability inventory: id, name, provider, description, and source path.

# every capability
curl -s https://api.engineeringruntime.com/metadata/capabilities

# one provider
curl -s "https://api.engineeringruntime.com/metadata/capabilities?provider=github"

# free-text across name, description, id and provider
curl -s "https://api.engineeringruntime.com/metadata/capabilities?q=secret"

provider and q behave exactly as they do on {prefix}/capabilities. Two endpoints filtering the same data differently would be a trap.

Where the catalog comes from

The runtime repository is the source of truth. This API never runs the runtime binary and never calls GitHub to answer a request.

engineering-runtime/providers/**        ─┐
engineering-runtime/capabilities/**/*.md ┴─→ CI (deploy-cloud-run)
                                              → catalog.json (+ runtime commit)
                                              → embedded in this binary
                                              → served here

It refreshes when app-api deploys, not when the runtime changes. A runtime release without an app-api deploy leaves this contract behind — which is exactly why generated_at and runtime.commit are published. Staleness that you can see is a manageable problem; staleness you cannot see is not.

Machine-readable everything else