API-Dokumentation

Öffentliche REST-API für Episodendaten von Kack & Sachgeschichten.

https://kack.li JSON 300 REQ / MIN (default) CORS ENABLED

BREAKING CHANGE · 2026-04-13

Das Feld episode_num wurde als nicht verlässlich eingestuft und ist ab sofort aus den API-Responses entfernt.

RATE LIMITS & 429-VERHALTEN

Alle öffentlichen API-Requests unter /api/* sind standardmässig auf 300 Requests pro Minute limitiert. Die Antwort enthält zur Steuerung immer diese Header. Limits sind per ENV konfigurierbar.

RateLimit-Policy – aktives Limitfenster (z. B. 300;w=60)
RateLimit-Limit – maximale Requests im Fenster
RateLimit-Remaining – verbleibende Requests
RateLimit-Reset – Sekunden bis Reset

Beispiel (200):
RateLimit-Policy: 300;w=60
RateLimit-Limit: 300
RateLimit-Remaining: 298
RateLimit-Reset: 42

Beispiel (429):
HTTP 429 Too Many Requests
{ "error": "Zu viele Anfragen, bitte später erneut versuchen." }

Öffentliche Endpunkte

GET /api/status Systemstatus & Statistiken public ▶

Gibt den aktuellen Status der Datenbank zurück: Episodenanzahl, Parse-Stand, letzter Sync.

— bereit

Klicke „Ausführen" um die API live abzufragen.

GET /api/episodes Episodenliste mit Suche & Filter public ▶

Paginierte Episodenliste mit Discovery-Funktionen (Sortierung, Facetten, Mehrfachfilter).

Validierung: limit muss eine Ganzzahl von 1–100 sein, offset eine Ganzzahl ≥ 0. Ungültige Parameter liefern 400 mit { code, message, details }.

Beispiele:
/api/episodes?sort=relevance&q=star%20wars&has_guest=1
/api/episodes?topic[]=Psychologie&topic[]=Philosophie&sort=duration

Parameter	Typ	Beschreibung
q optional	string	Volltextsuche in Titel & Beschreibung
guest optional	string	Filter nach Gastname
topic optional	string	Filter nach Thema (einzeln)
topic[] optional	repeatable	Mehrfachfilter, z. B. `topic[]=A&topic[]=B`
sort optional	string	`pub_date` (default), `relevance`, `duration`
has_guest optional	boolean	`1/0`, `true/false`, `yes/no`
has_chapters optional	boolean	Nur Episoden mit/ohne Kapitel
has_film_title optional	boolean	Nur Episoden mit/ohne Werkbezug
limit optional	integer	Anzahl Ergebnisse (1–100)
offset optional	integer	Offset für Paginierung (≥ 0)

— bereit

Klicke „Ausführen" um die API live abzufragen.

GET /api/episodes/:id Einzelne Episode public ▶

Gibt eine einzelne Episode mit allen Feldern zurück (inkl. Kapitel, Gäste, Themen, Film-Titel).

Parameter	Typ	Beschreibung	Wert
:id required	integer	Episoden-ID

— bereit

Klicke „Ausführen" um die API live abzufragen.

GET /api/guests Alle Gäste mit Auftrittsanzahl public ▶

Liste aller Gäste, sortiert nach Anzahl der Auftritte.

— bereit

Klicke „Ausführen" um die API live abzufragen.

GET /api/topics Alle Themen mit Häufigkeit public ▶

Liste aller Themen, sortiert nach Häufigkeit über alle Episoden.

— bereit

Klicke „Ausführen" um die API live abzufragen.

Admin-Endpunkte (Bearer-Token erforderlich)

ADMIN TOKEN Wird nur lokal im Browser gespeichert und ausschließlich für Anfragen an diese API verwendet.

GET /api/suggestions Community-Vorschläge mit Status admin ▶

Gibt eingereichte Community-Vorschläge zurück. Standardmäßig siehst du pending. Mit Filtern kannst du auch bereits freigegebene oder abgelehnte Vorschläge ansehen.

Parameter	Typ	Beschreibung
status optional	string	`pending`, `approved` oder `rejected`
type optional	string	`guest`, `topic` oder `film`
episode_id optional	integer	Nur Vorschläge für eine bestimmte Episode
limit optional	integer	Anzahl Einträge (max. 500)

— bereit