http-api.md

warren HTTP API

This page enumerates every HTTP route registered by warren's Bun.serve router. It's derived directly from the ROUTE_TABLE array in src/server/handlers/route-table.ts so it can't drift from the running server.

To refresh: bun run gen:docs. To check (CI mode): bun run gen:docs:check.

Total routes: 50.

/agents

Method	Pattern	Handler	Notes
GET	/agents	listAgentsHandler
GET	/agents/:name	getAgentHandler

/alerts

Method	Pattern	Handler	Notes
POST	/alerts/heal	healAlertHandler	warren-3db0: closed-loop alert intake. Token-gated via the standard bearer gate (not auth-exempt); webhook senders carry the bearer.

/analytics

Method	Pattern	Handler	Notes
GET	/analytics/cost	listCostAnalyticsHandler
GET	/analytics/runs	listRunAnalyticsHandler
GET	/analytics/behavior	listBehaviorAnalyticsHandler
GET	/analytics/dispatch	listDispatchAnalyticsHandler

/events

Method	Pattern	Handler	Notes
GET	/events	listEventsHandler	pl-7e38 step 15 (warren-5eec): cross-run Event explorer query, readPublic with the same per-row projectEvent reduction as /runs/:id/events.
GET	/events/stream	streamLifecycleEventsHandler	warren-f566: the global lifecycle notification stream (NDJSON, one {runId, hook, state, ts} line per lifecycle transition). The list pages hold ONE connection per tab and debounce-invalidate their list queries instead of polling /runs every 5s. ?follow=0 is a probe shorthand (immediate clean close, empty body). Operator-gated — a public spectator never gets a held-open feed of every run id on the instance (scenario 39); it stays on the fallback poll.

/github-app

Method	Pattern	Handler	Notes
GET	/github-app/register	registerGitHubAppHandler	warren-a647: App manifest registration; anonymous — see ./github-app.ts.
GET	/github-app/callback	gitHubAppCallbackHandler
GET	/github-app/installed	gitHubAppInstalledHandler	warren-54c7: the manifest setup_url target — GitHub's post-install redirect lands here carrying the installation id.

/healthz

Method	Pattern	Handler	Notes
GET	/healthz	healthzHandler

/instance

Method	Pattern	Handler	Notes
GET	/instance	instanceFactsHandler	warren-2eec: read-only instance facts for the operator console. The body is a boot facts allowlist; spectators get the reduced projection (src/instance/facts.ts). Never secrets or connection strings.

/metrics

Method	Pattern	Handler	Notes
GET	/metrics	metricsHandler

/ops

Method	Pattern	Handler	Notes
GET	/ops/overview	opsOverviewHandler	pl-7e38 step 12 (warren-d850): one-poll control-plane snapshot for the Operations dashboard. readPublic with a reduced projection — a spectator sees run counts only (see ./ops-overview.ts).

/plan-runs

Method	Pattern	Handler	Notes
GET	/plan-runs	listPlanRunsHandler
POST	/plan-runs	createPlanRunHandler
GET	/plan-runs/:id	getPlanRunHandler
POST	/plan-runs/:id/cancel	cancelPlanRunHandler
POST	/plan-runs/:id/resume	resumePlanRunHandler
GET	/plan-runs/:id/events	streamPlanRunEventsHandler

/preview

Method	Pattern	Handler	Notes
GET	/preview/config	previewConfigHandler

/projects

Method	Pattern	Handler	Notes
GET	/projects	listProjectsHandler
POST	/projects	createProjectHandler
GET	/projects/:id	getProjectHandler
GET	/projects/:id/warren-config	getProjectWarrenConfigHandler
GET	/projects/:id/triggers	getProjectTriggersHandler
GET	/projects/:id/seeds/plans	listProjectSeedPlansHandler	Static path — must precede /projects/:id/seeds/:seedId so the param route doesn't swallow plans as a seed id.
GET	/projects/:id/ready-plans	listReadyPlansHandler
GET	/projects/:id/seeds/:seedId	getProjectSeedHandler
POST	/projects/:id/triggers/:triggerId/run	runProjectTriggerHandler
POST	/projects/:id/refresh	refreshProjectHandler
DELETE	/projects/:id	deleteProjectHandler

/readyz

Method	Pattern	Handler	Notes
GET	/readyz	readyzHandler

/runs

Method	Pattern	Handler	Notes
GET	/runs	listRunsHandler
POST	/runs	createRunHandler
GET	/runs/:id	getRunHandler
GET	/runs/:id/events	streamRunEventsHandler	NDJSON event tail. ?follow=1 live-tails (the default while the run is non-terminal); ?limit=N requests a bounded non-streaming read of at most N events and implies follow=false — the response closes after the page, so agents can poll for liveness without holding a stream open (warren-17c1). ?since=<seq> pages forward from a prior read.
GET	/runs/:id/inbox	pollRunInboxHandler	warren-3d0b: the in-pod steering poll for the K8s backend. Bearer-gated like every /runs route; the pod carries its per-run SCOPED token (warren-57fd). Destructive on read (it claims unread messages), so for a non-run caller it is operator-only (warren-b875). ?peek=1 lists the unread queue WITHOUT claiming (warren-3305) — the only safe way for an operator or the UI to inspect it; a bare poll steals the message from the pod's steering poll.
GET	/runs/:id/finalize-intent	getRunFinalizeIntentHandler	warren-0d35: the in-pod finalize callback for the K8s backend — the pod fetches the reap intent, runs the workspace-dependent half in place, and POSTs the FinalizeResult back. Bearer-gated; the pod carries its per-run scoped token (warren-57fd).
POST	/runs/:id/finalize-result	postRunFinalizeResultHandler
POST	/runs/:id/salvage	postRunSalvageHandler	warren-cd3b: the in-pod salvage intake — the pod POSTs the work it captured (rescue ref + git bundle) when the finalize branch push failed or no reap intent ever arrived, BEFORE its emptyDir dies with the pod.
POST	/runs/:id/git-credential	postRunGitCredentialHandler	warren-c9ac: the in-pod credential re-mint (forge-contract.md §4.1 window 3) — the pod requests a freshly-minted push credential over the same authenticated callback channel instead of trusting the mounted Secret.
POST	/runs/:id/steer	steerRunHandler
POST	/runs/:id/cancel	cancelRunHandler
POST	/runs/:id/preview/login	previewLoginHandler	warren-e1b0: POST, not GET — the bearer rides the Authorization header like every other /runs route instead of a ?token= query string that would land in history / Referer / proxy logs.
POST	/runs/:id/preview/teardown	previewTeardownHandler

/version

Method	Pattern	Handler	Notes
GET	/version	versionHandler

/whoami

Method	Pattern	Handler	Notes
GET	/whoami	whoamiHandler	warren-e195: readPublic, not anonymous — an exempt route gets no actor to name.