docs/api.md

# API Documentation

## Base URL
```
http://localhost:8000/api/v1
```

## Endpoints

### Health Check
```
GET /health
```
Response:
```json
{
  "status": "ok",
  "message": "AI Code Review Agent is running"
}
```

---

### Full Analysis
```
POST /analyze
```
Request:
```json
{
  "github_url": "https://github.com/username/repository"
}
```
Response: `EngineeringReport` object

---

### Quick Analysis
```
POST /quick-analyze
```
Request:
```json
{
  "github_url": "https://github.com/username/repository"
}
```
Response: `RepositoryResponse` object

## Interactive Docs
Visit http://localhost:8000/docs for Swagger UI

## Rate limits

All limits are applied per API key (via `X-API-Key` header). Requests without
a key are limited by IP address.

| Endpoint | Limit | Reason |
|---|---|---|
| `POST /api/v1/analyze` | 5 req/min | Full pipeline — LLM calls, clone, static analysis |
| `POST /api/v1/analyze/async` | 20 req/min | Queue submission only — fast and cheap |
| `GET /api/v1/jobs/{id}` | 120 req/min | Read-only status poll |
| `GET /api/v1/health` | unlimited | Healthcheck — no limit applied |
| `GET /metrics/prometheus` | unlimited | Prometheus scrape — no limit applied |

When a limit is exceeded the API returns `429 Too Many Requests` with a
`Retry-After` header indicating when the client may retry.