Platform & deployment

API reference

The Halo incident API — create, list, run, approve, and inspect incidents. Served by the FastAPI workflow engine.

In local development the API runs at http://127.0.0.1:8000. Interactive OpenAPI docs are at /docs (Swagger UI) and /openapi.json. All incident endpoints are under the /incidents prefix.

Health

GET /health and GET /readiness — liveness and readiness probes, return 200 when the service is up.

Create an incident

POST /incidents → 201 Created

{
  "title": "Jaguar worker offline after recent deploy",
  "severity": "sev1",
  "environment": "production",
  "product": "jaguar",
  "summary": "Worker heartbeat dropped after deploy; ingestion stalled."
}

Field	Type	Notes
`title`	string	Required, 3–160 chars.
`severity`	enum	`sev1` \| `sev2` \| `sev3`. Defaults to `sev2`.
`environment`	string	Defaults to the configured environment.
`product`	string	Defaults to the configured product.
`summary`	string \| null	Optional.

List & get

GET /incidents returns { "incidents": [ ... ] }.
GET /incidents/{incident_id} returns a single incident with its events, approvals, checkpoints, and trace links (404 if not found).

Run the next step

POST /incidents/{incident_id}/run advances the incident one stage, invoking the agent via the gateway.

{ "scenario": null, "force_mode": null, "demo_run": false }

force_mode accepts normal | degraded | blackout to pin a mode.

Approve an action

POST /incidents/{incident_id}/approve resolves a pending approval. On approval, the gated write executes through jaguar-act and the incident advances to verification.

{ "approval_id": "apr_...", "approved": true, "note": "Approved — restart the worker." }

Returns { "incident": { ... }, "approval": { ... } }. There is also POST /incidents/{incident_id}/sync-approvals to reconcile approval state against the recommendation text and trace spans.

Trace evidence

GET /incidents/{incident_id}/traces returns the trace summary surfaced in the war room — model resolved, span count, guardrails that fired, and the tools the agent called. See TrueFoundry + Bedrock.