docs/API.md

# HTTP API

All backend routes live under `/api/` and are served by FastAPI. In
production, the browser hits them same-origin via a Next.js rewrite; in
dev they're at `http://localhost:8000/api/...`. Full auto-generated docs
are always at `http://localhost:8000/docs` (Swagger UI).

## Public endpoints (no auth)

### Health / readiness

| Method | Path | Response |
|---|---|---|
| GET | `/api/health` | `{status, data_dir, data_dir_exists}` — always 200 if process is up |
| GET | `/api/ready` | `{ready, checks, bills_count}` — 200 if data is loaded, 503 otherwise |

### Bills

| Method | Path | Notes |
|---|---|---|
| GET | `/api/bills` | List bills. Query: `state`, `status`, `session_year`, `category`, `search`, `limit`, `offset` |
| GET | `/api/bills/stats` | Totals: `{total_bills, federal_bills, state_bills, most_active_state, last_updated_at}` |
| GET | `/api/bills/filters` | Dropdown data: `{states, statuses, years, categories}` |
| GET | `/api/bills/{bill_id}` | Full bill detail (used by the row-detail modal) |
| GET | `/api/bills/by-state` | `{STATE: count}` for the choropleth. Optional `?year=YYYY` |
| GET | `/api/bills/export.csv` | Filtered CSV download (same filters as `/api/bills`) |

### Insights

| Method | Path |
|---|---|
| GET | `/api/insights/by-state?limit=N` |
| GET | `/api/insights/by-category?limit=N` |
| GET | `/api/insights/over-time` |

### Calendar

| Method | Path | Notes |
|---|---|---|
| GET | `/api/calendar` | Month view. Query: `year`, `month`, `types[]` |
| GET | `/api/calendar/upcoming` | Next N days. Query: `days` (default 7, max 30) |

### Newsletter

| Method | Path | Notes |
|---|---|---|
| GET | `/api/newsletters` | List available dates |
| GET | `/api/newsletters/{date}` | Markdown of one newsletter |
| GET | `/api/newsletters/{date}/changes` | Weekly changes CSV rows for that date |
| GET | `/api/newsletters/{date}/digest` | Stats + in-motion bills for the hero + Bills in Motion sections |
| GET | `/api/newsletters/{date}/featured-bill` | "Bill of the Week" — scored pick from the week's changes |
| GET | `/api/newsletters/{date}/category-trends` | Top IAPP categories affected this week |

### States

| Method | Path |
|---|---|
| GET | `/api/states/featured` |
| GET | `/api/states/{state}/spotlight?key_bills=N` |

### Feedback / subscribe

| Method | Path | Body |
|---|---|---|
| POST | `/api/feedback` | `{name?, email?, type, description}` |
| POST | `/api/newsletter/subscribe` | `{email}` |
| POST | `/api/newsletter/unsubscribe` | `{email}` |

### AI tools

| Method | Path | Body |
|---|---|---|
| GET | `/api/ai/bills/list` | Bills available in the AI tools dropdown |
| GET | `/api/ai/bill/{state}/{bill_number}` | Bill + summary + suggested questions + has_report flag |
| GET | `/api/ai/report/{state}/{bill_number}` | Pre-generated report markdown |
| POST | `/api/ai/qa` | `{state, bill_number, question}` |
| POST | `/api/ai/compare` | `{focus_state, focus_bill_number, compare[], question}` |
| POST | `/api/ai/eu-compare` | `{state, bill_number, question}` |

## Auth

| Method | Path | Notes |
|---|---|---|
| POST | `/api/auth/login` | `{username, password}` → `{token, username, name}` |
| GET | `/api/auth/me` | Current user; requires `Authorization: Bearer <token>` |
| POST | `/api/auth/logout` | Client discards the token |

## Admin endpoints

All under `/api/admin/*`. Require `Authorization: Bearer <jwt>` where the
JWT was issued by `/api/auth/login`. Enforced by the `require_admin`
dependency in every admin route.

### Overview

| Method | Path | Notes |
|---|---|---|
| GET | `/api/admin/overview` | Card counts, including `new_feedback_count` (fed to the nav badge) |

### Users

| Method | Path | Body |
|---|---|---|
| GET | `/api/admin/users` | List |
| POST | `/api/admin/users` | `{username, name, email, password}` |
| PATCH | `/api/admin/users/{username}` | `{name?, email?, password?}` (any subset) |
| DELETE | `/api/admin/users/{username}` | |

### Subscribers

| Method | Path |
|---|---|
| GET | `/api/admin/subscribers` |
| DELETE | `/api/admin/subscribers/{email}` |

### Feedback

| Method | Path | Body |
|---|---|---|
| GET | `/api/admin/feedback` | |
| PATCH | `/api/admin/feedback/{id}` | `{status}` — one of `new`, `read`, `resolved` |
| DELETE | `/api/admin/feedback/{id}` | |

### Pipeline

| Method | Path | Body / Notes |
|---|---|---|
| GET | `/api/admin/pipeline/status` | Current or last run |
| GET | `/api/admin/pipeline/history?limit=N` | Last N runs |
| GET | `/api/admin/pipeline/scripts` | The 14 step list with names + indices |
| GET | `/api/admin/pipeline/log?tail=N` | Last N lines of the pipeline log |
| POST | `/api/admin/pipeline/run` | `{pull?, test?, test_count?, start_from?, stop_after?, reset_vectorstore?, upload_to_hf?}` (all optional) |
| POST | `/api/admin/pipeline/cancel` | Kills the running subprocess group |
| POST | `/api/admin/pipeline/rebuild-manifest` | Standalone `rebuild_vectorstore_manifest.py` run |

### Weekly changes

| Method | Path |
|---|---|
| GET | `/api/admin/weekly-changes` |
| GET | `/api/admin/weekly-changes/{week_of}` |

## Error format

Errors follow FastAPI's default `{"detail": "..."}` shape. Server-side
5xx errors also include a `request_id` — a short hex string echoed in
the `X-Request-ID` response header. When a user reports an error, ask
for the request ID and grep the backend logs for `rid=<id>`.

## Rate limiting

None currently. Add one at the ingress layer (HF's edge) if traffic ever
warrants it.