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