API compatibility routes

/api/* paths are served directly by the gateway. They split into two classes:

1. Boundary endpoints — on the substrate's closed list of allowed HTTP boundaries (P1.43). Permanent. The browser cannot use the bus without these, or OAuth providers redirect to HTTP URLs by protocol.
2. Compatibility projections — read-only views of bus actors retained for non-bus-aware external clients. Internal substrate consumers MUST migrate off these; they are being retired or relabelled.

Status: bus-is-authority migration in progress (P1.43). The gateway is not the authority for app inventory, runtime inventory, status, or config. Those live as bus actors. Any internal consumer (matrix-web, Edge, agents, proof scripts) that still calls /api/apps, /api/runtimes, or /api/status is on the migration list.

Boundary endpoints (closed list)

Method	Path	Purpose
GET, HEAD	/api/identity/bootstrap	Browser session bootstrap (see App bootstrap). Issues the credentials the browser needs to join the bus.
GET, HEAD	/api/identity/nats-creds	Mints NATS user JWTs scoped to the authenticated principal.
GET	/oauth/<provider>/callback	OAuth callback redirect target. Required by the OAuth protocol.
GET	/healthz	Liveness for external HTTP-only monitors (load balancers, uptime services).

These are kept forever. They exist because the boundary exists.

Compatibility projections (migrating)

Method	Path	Bus authority	Migration status
GET, HEAD	/api/apps	system.catalog	Internal consumers being migrated; endpoint either retired or retained as a documented external projection (P1.43 step 7).
GET, HEAD	/api/config	system.gateway.http.config	Projection only.
GET	/api/status	system.runtimes	Projection only.
GET	/api/runtimes	system.runtimes	Projection of runtimes.list.
POST	/api/runtimes/register	host.control	Control half; migrating to host.control invocations.
POST	/api/runtimes/start	host.control	Control half; migrating.
POST	/api/runtimes/stop	host.control	Control half; migrating.
POST	/api/host/stop	host.control	Migrating; hivecast stop will use the bus.

How to call the bus authority instead

# What apps are deployed?
matrix invoke system.catalog catalog.list '{}'

# What runtimes are alive?
matrix invoke system.runtimes runtimes.list '{}'

# Host status snapshot
matrix invoke system.runtimes runtimes.summary '{}'

# Stop a runtime via host.control (the supervised path)
matrix invoke host.control host.runtime.stop '{"runtimeId":"RUNTIME-..."}'

For browser code, the same calls go through MatrixDSLHost / MatrixActorHtmlElement.request(); for headless code, through MatrixRuntime.request(). There is no Matrix-specific HTTP shape these clients should hit.

/api/identity/bootstrap

Covered in detail at App bootstrap. Returns the JSON the browser needs to begin its session: identity, NATS WebSocket URL, transport plan. The browser cannot speak the bus before it has this response.

Method enforcement

Each route enforces specific methods. Sending POST to /api/identity/bootstrap returns 405. There is no method override (X-HTTP-Method-Override) support.

Authorization

Endpoint	Auth requirement
/api/identity/*	Optional (returns anonymous shape if no session). The session, if present, comes from the __Host--prefixed cookie set after OAuth completes.
/oauth/*/callback	Validates state token; otherwise no caller auth.
/healthz	None. Public liveness.
/api/apps, /api/config, /api/status	Today: optional. Projection routes inherit authority-root scoping from session if present.
/api/host/stop, /api/runtimes/*	Today: no gateway-side enforcement (local-mode trust). Cloud deployments gate via Caddy / system-auth middleware.

Caution: A locally-running gateway exposed to the network without further protection is a critical security misconfiguration. The control-plane projection endpoints (/api/host/stop, /api/runtimes/*) assume local-mode trust today. The migration to bus-side host.control invocations (P1.43 step 8) closes this gap because authentication is enforced at NATS subject-permission level.

See also

• App bootstrap
• Operations / Health
• Reference / Gateway actor ops
• P1.43 — HTTP-API reduction: bus is authority

Source: projects/matrix-3/packages/system-gateway-http/src/http-listener.ts:117-208.