Platform APIs

This page enumerates the HTTP endpoints the platform Host's system-gateway-http runtime exposes. HTTP is not the substrate's authority — the bus is. Per P1.43, HTTP endpoints exist only at boundaries that cannot be bus-native. Inventory, state, and command surfaces (apps, devices, runtimes, mounts, packages, AI providers, agent state) live as bus actors with declared accepts ops; substrate consumers (the platform shell, Edge, the CLI, agents, federation peers) query the bus, not HTTP.

The closed list of HTTP boundaries below is normative. Anything else is either a documented read-only projection for non-bus-aware external clients (CI smoke checks, third-party monitors) or a bug.

The closed-list HTTP boundaries

1. Browser-bootstrap credential issuance

Endpoint	Method	Purpose
/api/identity/bootstrap	GET	Returns the browser bootstrap payload (root, addressRoot, routeKey, publicNamespace, spaceId, authorityRoot, authenticated, principal, transportPlan). The browser cannot use the bus before it has credentials; this endpoint is the boundary that gives it credentials.
/api/identity/nats-creds	GET	Mints a NATS user JWT for the calling session. With ?purpose=probe, returns authorization-only (no token).

2. OAuth redirects and callbacks

Endpoint	Method	Purpose
/api/auth/login/google	GET	Start Google OIDC; redirects to provider.
/api/auth/callback/google	GET	Google OIDC callback. Sets mx_session cookie, redirects.
/api/auth/logout	POST	Revoke session, clear cookie.

OAuth providers redirect to HTTP URLs by protocol; this is unavoidable. Anthropic / Codex / GitHub providers follow the same shape.

3. Static asset serving

/apps/<appName>/<assetPath>

The browser fetches HTML/JS/CSS bundles over HTTP. Per package-authoring conventions, every webapp's matrix.json declares its appName and routePrefix; the gateway routes /apps/<appName>/<assetPath> to the runtime that owns the asset endpoint actor (system.gateway.http resolves through system.runtimes and system.registry).

Public Space-scoped form:

/<spacePath>/<appName>/<assetPath>

The gateway resolves spacePath via auth.namespace.resolve and serves the same asset bundle scoped to that Space's authority root. See Spaces.

4. NATS WebSocket upgrade

/nats-ws

Same-origin WebSocket. Browser connects with a NATS user JWT from /api/identity/nats-creds. NATS NKey challenge-response over the WebSocket. Once upgraded the browser is on the bus; this endpoint exists only for the upgrade.

5. Health endpoint

Endpoint	Method	Purpose
/healthz	GET	Liveness probe. Returns { ok: true, ... }. For external HTTP-only monitors (load balancers, uptime services, Caddy probes). External monitors cannot speak NATS; this endpoint exists for them.

6. Webhooks from external providers

/webhooks/<provider>

Third-party services (Stripe, GitHub, OAuth providers) post over HTTP. Unavoidable.

7. Federation handshake (target state)

Status: target state — ships in v2. Cross-Space discovery and leafnode setup will need HTTP boundaries; spec'd separately under WORKSTREAMS/runtime-environment-multi-instance/.

8. Pairing (Device side)

Endpoint	Method	Purpose
/api/devices/enroll/start	POST	Start device enrollment. Backed by auth.device.start / auth.pair.start.
/api/devices/enroll/complete	POST	Complete enrollment from a signed-in browser. Backed by auth.device.approve / auth.pair.approve.
/api/devices/redeem	POST	Device redeems an approved enrollment. Backed by auth.device.exchange / auth.pair.exchange.
/auth/link	GET	Browser-side device link UI entry.

Pairing is conceptually an OAuth-shaped boundary: a Device that is not yet on the bus must obtain credentials through HTTP, and HiveCast must redirect through a browser to authenticate the user. The auth.device.* and auth.pair.* ops are the bus-side authority; these HTTP endpoints are the entry points before the Device has bus credentials. After pairing, the Device speaks NATS.

9. Host-link heartbeat / refresh (Device side)

Endpoint	Method	Purpose
/_auth/host-link/heartbeat	POST	Heartbeat from a paired Device. Validates token, updates lastRefreshedAt. Bearer token.
/_auth/host-link/credentials/refresh	POST	Issue fresh device-scoped NATS JWT, revoke prior keys. Bearer token.

A Device's host.control posts these from the Device side to keep the platform's system.devices view fresh and rotate credentials. The Device may also speak directly to system.devices over its leafnode connection; the HTTP path remains for boundary cases (Device behind strict NAT with no NATS WebSocket reach).

What is NOT on the closed list (and where to find the bus authority)

These HTTP endpoints exist today as projections of bus authority. Substrate consumers (the platform shell, Edge, the CLI, agents) MUST use the bus. External non-bus-aware clients may continue to call the projection.

HTTP projection	Bus authority	Bus call
/api/apps	system.catalog	matrix invoke system.catalog list '{}'
/api/devices	system.devices	matrix invoke system.devices devices.list '{"includeOffline":true}'
/api/devices/:id	system.devices	matrix invoke system.devices devices.get '{"deviceId":"<slug>"}'
/api/devices/:id/revoke	system.auth	matrix invoke system.auth auth.hostLink.revoke '{"hostLinkId":"<id>"}'
/api/identity/runtime-summary (the runtime-data half)	system.runtimes	matrix invoke system.runtimes runtimes.list '{}'
/api/auth/me	system.auth	matrix invoke system.auth auth.session.validate '{}'

Migration is in flight per P1.43. Each of the above HTTP endpoints either retires entirely once internal consumers migrate, or remains marked in code as "projection, not authority — internal substrate consumers MUST use the bus."

App routing summary

Public app routes:

/<spacePath>/<appName>/<assetPath>          ← linked-Space route (Space-scoped)
/apps/<appName>/<assetPath>                 ← current-host route

The gateway resolves these to runtime asset endpoints via system.runtimes and system.registry. Per P1.22d, the dashboard exposes route-plan diagnostics for each route — fetched directly over the bus.

Caddyfile

The production deployment fronts the gateway with Caddy. See projects/deploy-cloud/Caddyfile.bare for the live routing config. Caddy terminates TLS and reverse-proxies the closed-list endpoints listed above.

See also

• Actor surfaces — bus ops backing the projections (and the actors that have no projection because they don't need one).
• Security: Authentication — how identity flows through these.
• Devices / Pairing — pairing endpoint usage in context.
• Operational runbooks — common HTTP debugging.

Source: projects/matrix-3/packages/system-gateway-http/src/host-platform-http-surface.ts for the route handlers. projects/matrix-3/packages/system-gateway-http/src/http-routing.ts for the routing layer. WORKSTREAMS/loose-ends/items/P1.43-http-api-reduction-bus-is-authority.md is the SSOT for the closed list of allowed HTTP boundaries.