Skip to main content
The OpenSRE backend serves one HTTP API (FastAPI, gateway/http/webapp.py). All routes live on a single port (default 8000). In production, always call the API over HTTPS — deploy behind a TLS-terminating load balancer (see the Terraform module under infra/terraform/).

​
Authentication

The API has two auth schemes, matched to the caller:
RoutesCallerAuth
POST /alerts, POST /investigateMachines (alert sources, schedulers)Static bearer token: set OPENSRE_ALERT_LISTENER_TOKEN on the server and send Authorization: Bearer <token>. Without the env var, these routes only accept loopback callers.
/api/* (investigations)Users via the web appClerk JWT: send Authorization: Bearer <clerk-session-token>. Records are scoped to the token’s organization.
GET /health, GET /healthz, GET /okProbesNone

​
Health

curl https://<host>/healthz          # liveness: {"status": "ok"}
curl https://<host>/health           # readiness: 503 until an LLM is configured

​
Alert intake

Queue an alert for background investigation (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"}'
Bodies above 1 MiB are rejected with 413.

​
Synchronous investigation

Run an investigation inline and get the report in the response (slow — the request stays open for the full pipeline; prefer the async API behind load balancers): 
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"}}'

​
Async investigations (Clerk-authenticated)

Enqueue and poll — the pattern web clients should use. Queued investigations are executed by a background worker in the web service; it is enabled by setting OPENSRE_INVESTIGATION_WORKER=1 (the Terraform deployment sets this). Records live in Postgres when DATABASE_URL is set, else 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": "3f6…", "status": "queued"}
# workspace_id is optional — pass the Slack workspace (team) id when the
# investigation originates from a Slack workspace.

# Poll
curl "https://<host>/api/investigations/<investigation_id>" \
  -H "Authorization: Bearer $CLERK_SESSION_TOKEN"
# → {"investigation_id": "3f6…", "status": "queued|running|completed|failed",
#    "report_s3_key": null, "report_url": null, "error": null}
Investigations belong to the Clerk organization in the token; reading another organization’s investigation returns 404.

​
Status codes

CodeMeaning
202Accepted and queued (/alerts, POST /api/investigations)
400Malformed JSON or missing required fields
401Missing or invalid bearer token (/api/*, or token-mode /alerts)
403Non-loopback caller and no OPENSRE_ALERT_LISTENER_TOKEN configured
404Unknown investigation id, or one outside your organization
413Alert body above 1 MiB
503LLM not configured (/health) or investigation pipeline failure