HTTP API

The OpenSRE backend serves one HTTP API (FastAPI, gateway/web/webapp.py). All routes live on a single port (default 8000). To drive the agent in-process from your own code instead, see the Python API. In production, always call the API over HTTPS — deploy behind a TLS-terminating load balancer (the backend is Terraform-managed, separately from this repo). In production, terminate TLS at a load balancer or reverse proxy in front of the application.

Authentication

Routes	Caller	Authentication
`POST /alerts`, `POST /investigate`	Machines (alert sources, CI, schedulers)	Set `OPENSRE_ALERT_LISTENER_TOKEN` and send `Authorization: Bearer <token>`. If unset, only loopback callers are accepted.
`/api/investigations/*`	Users and web clients	Clerk JWT as `Authorization: Bearer <clerk-session-token>`. The token must include an organization; records are scoped to that organization.
`GET /`, `/health`, `/ok`, `/healthz`, `/readyz`	Health probes	None

Health

Route	Behavior
`GET /healthz`	Liveness. Always returns `{"status": "ok"}`.
`GET /readyz`	Readiness after gateway startup. Returns `503` with `{"status": "not_ready"}` until ready.
`GET /`, `/health`, `/ok`	LLM configuration check. Returns version and `llm_configured`. Status is `503` until an LLM is configured.

curl https://<host>/healthz
curl https://<host>/readyz
curl https://<host>/health

Alert intake

Enqueue an alert for background handling. Returns 202:

curl -X POST "https://<host>/alerts" \
  -H "Authorization: Bearer $OPENSRE_ALERT_LISTENER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "CPU above 90% on checkout-db", "source": "grafana"}'

Required field: text. Optional fields: alert_name, severity, source, received_at. Request bodies larger than 1 MiB return 413.

Synchronous investigation

Runs the investigation in the request and returns the report. The connection remains open for the duration of the pipeline. Prefer the asynchronous API when calling through a load balancer.

curl -X POST "https://<host>/investigate" \
  -H "Authorization: Bearer $OPENSRE_ALERT_LISTENER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"raw_alert": {"alert_name": "HighCPU", "severity": "critical"}}'

Required field: raw_alert. Optional top-level fields: alert_name, severity. Response fields: report, problem_md, root_cause, is_noise, validity_score, and optionally tool_calls.

Asynchronous investigations (Clerk)

Enqueue an investigation, then poll for status. The background worker runs only when OPENSRE_INVESTIGATION_WORKER=1. Records are stored in Postgres when DATABASE_URL is set; otherwise they are kept in process memory. Reports are written to local disk first and uploaded to S3 when OPENSRE_ARTIFACTS_BUCKET is configured.

# Enqueue (202)
curl -X POST "https://<host>/api/investigations" \
  -H "Authorization: Bearer $CLERK_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"raw_alert": {"alert_name": "HighCPU"}, "severity": "critical",
       "workspace_id": "T0123456"}'
# → {"investigation_id": "…", "status": "queued"}

workspace_id is optional. Pass a Slack team ID when the investigation originates from Slack.

# Poll
curl "https://<host>/api/investigations/<investigation_id>" \
  -H "Authorization: Bearer $CLERK_SESSION_TOKEN"
# → {"investigation_id": "…",
#    "status": "queued|running|completed|failed|cancelled",
#    "report_s3_key": null, "report_url": null, "error": null}

# Cancel a queued investigation (before the worker claims it)
curl -X POST "https://<host>/api/investigations/<investigation_id>/cancel" \
  -H "Authorization: Bearer $CLERK_SESSION_TOKEN"

Investigations are scoped to the Clerk organization in the token. An investigation belonging to another organization returns 404. A token without an organization returns 403. Canceling a non-queued investigation returns 409.

Status codes

Code	Meaning
`202`	Accepted (`/alerts`, `POST /api/investigations`)
`400`	Malformed JSON or missing required fields
`401`	Missing or invalid bearer token
`403`	Non-loopback caller without `OPENSRE_ALERT_LISTENER_TOKEN`, or Clerk token without an organization
`404`	Unknown investigation ID, or one outside your organization
`409`	Investigation is not cancellable (already claimed or finished)
`413`	Alert body larger than 1 MiB
`503`	LLM not configured (`/health`), gateway not ready (`/readyz`), or investigation pipeline failure

Deploy and APIs

Community

Authentication

Health

Alert intake

Synchronous investigation

Asynchronous investigations (Clerk)

Status codes

​Authentication

​Health

​Alert intake

​Synchronous investigation

​Asynchronous investigations (Clerk)

​Status codes

Authentication

Health

Alert intake

Synchronous investigation

Asynchronous investigations (Clerk)

Status codes