tracer-cloud--opensre/docs/api.mdx

---
title: "HTTP API"
slug: "api"
description: "Health checks, alert intake, and investigations over HTTP."
---

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](/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. |

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

## Alert intake

Enqueue an alert for background handling. Returns `202`:

```bash
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.

```bash
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.

```bash
# 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.

```bash
# 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}
```

```bash
# 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 |