gwoe-antragspruefer/docs/reference/api.md

# API-Endpoints

Automatisch generierte Referenz der FastAPI-Endpoints.

## Analyse

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| POST | `/api/analyze-drucksache` | Keycloak (geplant) | Antrag aus Landtag-Portal analysieren |
| POST | `/analyze` | Keycloak (geplant) | Freitext-Upload analysieren |
| GET | `/status/{job_id}` | - | Job-Status abfragen |
| GET | `/result/{job_id}` | - | Analyse-Ergebnis (HTML) |
| GET | `/result/{job_id}/pdf` | - | Analyse-Ergebnis (PDF) |

## Assessments

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/api/assessments` | - | Alle Bewertungen (optional `?bundesland=`) |
| GET | `/api/assessment` | - | Einzelne Bewertung (`?drucksache=`) |
| GET | `/api/assessment/pdf` | - | PDF-Download einer Bewertung |

## Suche

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/api/search` | - | Interne DB-Suche (`?q=`, max 200 Zeichen) |
| GET | `/api/search-landtag` | - | Live Landtags-Suche (`?q=&bundesland=`) |

## Auswertungen

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/auswertungen` | - | Dashboard (HTML) |
| GET | `/api/auswertungen/matrix` | - | Aggregations-Matrix (JSON, `?wahlperiode=`) |
| GET | `/api/auswertungen/zeitreihe` | - | Score-Verlauf (JSON) |
| GET | `/api/auswertungen/export.csv` | - | Long-Format-CSV aller Anträge |
| GET | `/api/auswertungen/score-histogram` | - | Score-Verteilung in 11 Buckets (`?bundesland=&wahlperiode=`) |

### Stimmverhalten × GWÖ (siehe ADR 0010)

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/api/auswertungen/stimm-index` | - | Stimm-Index pro Fraktion (`Ø(GWÖ\|JA) − Ø(GWÖ\|NEIN)`) |
| GET | `/api/auswertungen/heuchelei` | - | Anteil NEIN trotz `wahlprogramm.score≥7` pro Fraktion |
| GET | `/api/auswertungen/empfehlungs-konsistenz` | - | NEIN trotz GWÖ-Empfehlung „unterstützen" |
| GET | `/api/auswertungen/stimm-index-pro-wert` | - | Heatmap Fraktion × {Würde, Solidarität, Nachhaltigkeit, Gerechtigkeit, Demokratie} |
| GET | `/api/auswertungen/stimm-index-pro-gruppe` | - | Aufschlüsselung nach Berührungsgruppe (A–E) |
| GET | `/api/auswertungen/stimm-index-cross-bl` | - | Gleiche Fraktion in mehreren Bundesländern |
| GET | `/api/auswertungen/stimm-index-zeitreihe` | - | Stimm-Index pro Quartal × Fraktion |
| GET | `/api/auswertungen/stimmverhalten.csv` | - | Long-Format-CSV Stimmverhalten |
| GET | `/api/auswertungen/vote-orphans` | - | Drucksachen mit Vote ohne Bewertung (`?bundesland=&limit=`) |
| POST | `/api/auswertungen/vote-orphans/auto-rate` | Admin | Bulk-Bewerten Top-N Vote-Orphans (rate-limited 3/min) |

**Filter-Parameter** (für die Stimmverhalten-Endpoints):

| Param | Default | Beschreibung |
|---|---|---|
| `bundesland` | alle | BL-Filter (z.B. `NRW`, `BB`, …) |
| `wahlperiode` | alle | WP-Filter (z.B. `NRW-WP18`) |
| `exclude_antragsteller` | `1` | Antragstellende Fraktion ausschließen (Default an) |
| `min_n` | `5` | Mindest-Sample-Size für „ausreichend"-Flag |

## Aktuelle Themen × PM-Generator (siehe ADR 0011)

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/aktuelle-themen` | Keycloak | Dashboard (HTML, 5 Tabs) |
| GET | `/api/aktuelle-themen/top` | - | Top-News mit Antrags-Match (`?days=&top_k=&only_relevant=&date=`) |
| GET | `/api/aktuelle-themen/cluster` | - | News-Themen-Cluster (`?days=`) |
| GET | `/api/aktuelle-themen/top-antraege` | - | Hoch-bewertete Anträge mit News-Resonanz (`?min_gwoe_score=&days=`) |
| GET | `/api/aktuelle-themen/news-fuer-antrag` | - | News passend zu einem Antrag (`?drucksache=`) |
| GET | `/api/aktuelle-themen/anträge-fuer-news` | - | Anträge passend zu einer News (`?url=`) |
| GET | `/api/aktuelle-themen/zeitreihe` | - | News-Volumen pro Tag×Source (`?days=30`) |
| POST | `/api/aktuelle-themen/generate-presse` | Admin | PM-Generator (qwen-max, rate-limited 5/min, `?force=` für neue Version) |
| GET | `/api/aktuelle-themen/drafts` | - | Liste der PM-Entwürfe (`?limit=`) |
| GET | `/api/aktuelle-themen/drafts/{id}` | - | Einzelner PM-Entwurf |
| GET | `/api/aktuelle-themen/drafts-versions` | - | Alle Versionen für `(drucksache, news_url)` |

## Admin

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/v2/admin/stand` | Admin | System-Stand-Dashboard (HTML, Auto-Refresh 30s) |
| GET | `/api/admin/stand` | Admin | Datenstand-Aggregation (Counts, KPIs, pro-BL-Stats) |
| POST | `/api/batch-analyze` | Admin | Batch-Analyse (`?bundesland=&limit=`, ALL-BL-Modus) |

## Wahlprogramme

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/quellen` | - | Wahlprogramm-Übersicht (HTML) |
| GET | `/api/programme` | - | Liste aller Programme (JSON) |
| GET | `/api/programme/status` | - | Indexierungsstatus |
| POST | `/api/programme/index` | Keycloak (geplant) | Programm(e) indexieren |
| GET | `/api/wahlprogramm-cite` | - | PDF-Seite mit Zitat-Highlighting |

## Zitat-Highlighting

`GET /api/wahlprogramm-cite`

Liefert ein vollständiges Wahlprogramm-PDF mit gelb markierter Zitat-Stelle.

**Parameter:**

| Param | Typ | Beschreibung |
|---|---|---|
| `pid` | string | PROGRAMME-Key (z.B. `gruene-grundsatz`) — alternativ `pdf` |
| `pdf` | string | PDF-Dateiname (z.B. `gruene-grundsatzprogramm.pdf`) — Reverse-Lookup auf `pid` |
| `seite` | int | Ziel-Seitennummer (1-indexed) |
| `q` | string | Snippet-Text zum Highlighten (max 200 Zeichen) |
| `ds` | string | Drucksache-Nr. (optional, für Auto-Re-Analyse bei nicht-verifizierbarem Zitat) |
| `bl` | string | Bundesland-Code (optional, zusammen mit `ds` für Re-Analyse) |

**Verhalten:**

- Text gefunden → PDF mit gelber Highlight-Annotation, `X-Found-Page` Header
- Text NICHT gefunden + `ds`+`bl` vorhanden → Assessment wird automatisch neu analysiert, HTML-Warte-Seite zurück
- Unbekanntes Programm → 404
- Ungültige Seite → 400

## Bundesländer

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/api/bundeslaender` | - | Liste aller konfigurierten Bundesländer |

## Auth (Keycloak)

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/api/auth/me` | - | Auth-Status (`{"authenticated": bool, "user": {...}}`) |
| GET | `/api/auth/login-url` | - | Keycloak-Login-URL (`?redirect=`) |
| GET | `/api/auth/callback` | - | OIDC-Callback nach Login |
| POST | `/api/auth/logout` | - | Logout |

## Methodik / Transparenz

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/methodik` | - | Methodik-/Transparenz-Seite (HTML) |
| GET | `/quellen` | - | Wahlprogramm-Übersicht (HTML) |

## System

| Methode | Pfad | Auth | Beschreibung |
|---|---|---|---|
| GET | `/health` | - | Health-Check |