> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API

> Health checks and alert intake 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](https://opensre.com/docs/guides/python-api.md). 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` | Machines (alert sources, CI, schedulers) | Set `OPENSRE_ALERT_LISTENER_TOKEN` and send `Authorization: Bearer <token>`. If unset, only loopback callers are accepted. |
| `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 theme={null}
curl https://<host>/healthz
curl https://<host>/readyz
curl https://<host>/health
```

## Alert intake

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

```bash theme={null}
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`.

Queued alerts are picked up by the agent's alert inbox — the interactive shell
surfaces them with `/alerts`, and chat gateways deliver them to the paired
channel.

## Status codes

| Code | Meaning |
| - | - |
| `202` | Accepted (`POST /alerts`) |
| `400` | Malformed JSON or missing required fields |
| `401` | Missing or invalid bearer token |
| `403` | Non-loopback caller without `OPENSRE_ALERT_LISTENER_TOKEN` |
| `413` | Alert body larger than 1 MiB |
| `503` | LLM not configured (`/health`) or gateway not ready (`/readyz`) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.