# API-Referenz

Alle Endpunkte der öffentlichen API, die OpenAPI-Beschreibung und die Webhook-Verwaltung im Überblick.

## Hinweise für KI-Agenten

- API-Basisadresse: `https://api.eventwerk.eu/api/v1`
- OpenAPI 3.1: `https://api.eventwerk.eu/openapi.json` und `/api/v1/openapi.json`. Daraus lassen sich Clients und Typprüfungen generieren.
- Anmeldung: `Authorization: Bearer ew_...`
- Schlüssel: Einstellungen unter `/dashboard/einstellungen`, nur mit Eventwerk Plus und nur für Eigentümer. Der volle Schlüssel wird nur einmal angezeigt. Name und Zeitpunkt der letzten Nutzung werden geführt und ausgegeben.
- Zeiten: Alle Zeitpunkte kommen in UTC mit Suffix `Z`. Die Zeitzone des Events steht getrennt in `timezone` als IANA-Name, Standard `Europe/Vienna`. Clients rechnen selbst um.
- Paginierung: Die Event- und Anmeldelisten liefern `{items, has_more, next_cursor}` mit `limit` (Standard 50, höchstens 200), `cursor` und `updated_since`.
- Grenzen: 200 Anfragen pro Minute je Schlüssel. Der Zähler liegt im Speicher je Instanz, ist hinter mehreren Instanzen ein Vielfaches und beginnt nach einem Deploy neu. Bei Überschreitung antwortet die API mit 429, `rate_limited` und `Retry-After`.
- Gastgrenzen: Anmelde-Link 20 je Stunde je IP-Adresse, Anmeldung 60 je Stunde je IP-Adresse und 3 je Stunde je E-Mail-Adresse und Event.
- Fehler: JSON mit `code` und `message`, optional mit `details`.

Die öffentliche API liegt unter `/api/v1` und wird mit einem API-Schlüssel angesprochen. Sie gehört zu Eventwerk Plus. Die Webhook-Verwaltung liegt unter `/api/webhooks` und braucht ein Sitzungs-Token.

## OpenAPI

Die vollständige Beschreibung der API liegt als OpenAPI 3.1 unter [https://api.eventwerk.eu/openapi.json](https://api.eventwerk.eu/openapi.json) und unter `/api/v1/openapi.json` bereit. Die Datei beschreibt Endpunkte, Felder, Statuscodes und Fehlercodes.

- Aus der Beschreibung lassen sich Clients, Typprüfungen und Sammlungen für Testwerkzeuge generieren.
- Beide Adressen liefern dieselbe Fassung der Beschreibung.

```bash
curl -s https://api.eventwerk.eu/openapi.json
```

## Einstieg

- Grundlagen, Schlüssel und Grenzen: `/docs/api-grundlagen`.
- Events, Tickets, Anmeldungen, CSV und Kennzahlen: `/docs/api-ereignisse`.
- Webhooks, Signatur und Ereignisse: `/docs/api-webhooks`.
- Fehlerform und Codes: `/docs/api-fehler`.

## Endpunkte mit API-Schlüssel

| Methode | Pfad | Zweck |
| --- | --- | --- |
| GET | /me | Organisation und Rolle des Schlüssels. |
| GET | /events | Alle Events der Organisation, seitenweise und nach Beginn sortiert. |
| POST | /events | Event anlegen, optional mit `Idempotency-Key`. |
| GET | /events/{eventID} | Ein Event lesen. |
| PATCH | /events/{eventID} | Ein Event teilweise ändern. |
| DELETE | /events/{eventID} | Ein Event löschen. Ein veröffentlichtes Event mit Anmeldungen wird abgelehnt. |
| GET | /events/{eventID}/tickets | Ticketarten eines Events lesen. |
| GET | /events/{eventID}/registrations | Anmeldungen seitenweise lesen, mit Statusfilter und Suche. |
| GET | /events/{eventID}/registrations.csv | Anmeldungen als CSV exportieren. |
| GET | /events/{eventID}/stats | Kennzahlen eines Events lesen. |

> **Hinweis:** Alle Pfade dieser Tabelle sind relativ zur Basisadresse https://api.eventwerk.eu/api/v1.

## Webhooks mit Sitzungs-Token

| Methode | Pfad | Zweck |
| --- | --- | --- |
| GET | /api/webhooks | Aktive Webhooks lesen. |
| POST | /api/webhooks | Webhook mit URL anlegen. |
| DELETE | /api/webhooks/{webhookID} | Webhook widerrufen. |

Diese Endpunkte erwarten `Authorization: Bearer <Access-Token>` aus der E-Mail-Anmeldung. Sie sind nur für Eigentümer im Plus-Plan freigegeben.

## Betrieb

Diese Pfade liegen direkt an der Wurzel der Serveradresse, nicht unter `/api/v1`.

| Methode | Pfad | Zweck |
| --- | --- | --- |
| GET | /healthz | Prozess läuft. Antwort: status ok. |
| GET | /readyz | Datenbank ist erreichbar. Sonst 503 mit database_unavailable. |

## Nicht Teil der öffentlichen API

- Ticketarten anlegen, ändern oder löschen.
- Anmeldungen anlegen oder stornieren.
- Nachrichten, Umfragen und Programm lesen oder schreiben.
- Team und Einladungen verwalten.
- Webhooks mit einem API-Schlüssel verwalten.
- Serien anlegen und Events duplizieren.
- Erinnerungen, CSV-Import und Empfehlungscodes verwalten.

> **Warnung:** Zapier-Workflows und eine eigene Domain für Eventseiten sind angekündigt, aber noch nicht gebaut. Erinnerungen, CSV-Import und Empfehlungscodes laufen über die Sitzungs-API.