---
title: "REST-API – Überblick"
description: "Für wen die REST-API ist, wie Rechte und API-Schlüssel zusammenspielen, was v1 kann und wo die interaktive Doku liegt"
---

Mit der **REST-API** binden Owner, Admins und Plattform-Admins eigene Programme an QuickTribe an – zum Beispiel ein CRM, eine Vereinsverwaltung, ein Ticket- oder Einlass-System oder eine Auswertung in einer Tabellenkalkulation. Die API liefert **Mitglieder**, **Events**, **Kurse** und **geleistete Dienste** einer Community als JSON und kann ausgewählte Verwaltungsaktionen ausführen – mit denselben Prüfungen wie die Oberfläche.

Die Anmeldung erfolgt mit einem **API-Schlüssel**, den du auf deiner Konto-Seite erzeugst (siehe [API-Schlüssel](/rest-api/api-schluessel)). Alle Endpunkte mit Beispielen stehen in der [API-Referenz](#api-referenz) und in der interaktiven Doku deiner Installation.

## Für wen

| Konto | Erreicht über die API |
| --- | --- |
| **Owner und Admins** einer Community | nur die eigenen Communities, in denen das Konto gerade Owner oder Admin ist (gesperrte Communities nicht) |
| **Plattform-Admins** | alle Communities der Installation, auch gesperrte – wie im Admin-Bereich |
| Moderatoren und Mitglieder | keine – sie können keine API-Schlüssel erzeugen |

## Rechte: immer die aktuellen des Kontos

Ein API-Schlüssel hat **keine eigenen Rechte**. Bei **jedem** Aufruf prüft QuickTribe die Rechte des Kontos, zu dem der Schlüssel gehört – so, als würde die Person selbst in der Oberfläche klicken:

- Wird ein Admin zum Moderator oder Mitglied, wirkt sein Schlüssel in dieser Community **sofort** nicht mehr (Antwort `403`). Bekommt er die Rolle zurück, funktioniert der Schlüssel wieder.
- Verliert ein Plattform-Admin dieses Recht, erreicht sein Schlüssel nur noch die Communities, in denen er selbst Owner oder Admin ist.
- Wird das Konto gelöscht, werden seine Schlüssel entfernt.
- Gesperrte Communities erreichen nur Plattform-Admins, gelöschte niemand (`404`).

Alles, was die Oberfläche prüft, gilt auch über die API: die Rangfolge bei Beitrittsanfragen, Plan- und Formular-Bindungen, Teilnehmerzahl und Warteliste bei Events, Altersgruppen. Benachrichtigungen, E-Mail-Serien, Integrationen und das **Protokoll** der Community laufen genauso – im Protokoll steht zusätzlich, über welchen API-Schlüssel die Änderung kam.

### Communities anlegen und Admins benennen

Für Betreiber, die Communities automatisiert einrichten (etwa nach einer Bestellung im eigenen Shop):

1. `POST /api/rest/v1/communities` mit `name`, optional `description`, `visibility` (`public`/`private`) `slug` und `template` – nur mit dem Schlüssel eines **Plattform-Admins**. Die Community entsteht wie über **Community anlegen**; das Konto des Schlüssels wird Owner. `template` wählt die [Vorlage](/handbuch/owner/community-anlegen#vorlagen): `standard` (Standard, wenn das Feld fehlt) oder `verein`; eine unbekannte Vorlage wird mit `422` am Feld `template` abgelehnt, die Vorlage wirkt nur beim Anlegen.
2. `POST /api/rest/v1/communities/{slug}/admins` mit `email` – gibt dem Konto mit dieser Adresse die Rolle **Admin**. Plattform-Admins dürfen auch Konten benennen, die noch nicht Mitglied sind: Sie werden direkt aktive Admins, ohne Beitrittsformular oder Freigabe. Das Konto muss es bereits geben (sonst `404`).

Owner können über denselben Aufruf nur bestehende aktive Mitglieder zu Admins machen; für alle anderen Adressen antwortet die API mit `404` – so lässt sich nicht prüfen, ob es zu einer Adresse ein Konto gibt. Wer schon Admin ist, bleibt unverändert; Owner, gesperrte Mitglieder und offene Beitrittsanfragen ergeben `409`. Eine Übergabe der Owner-Rolle gibt es über die API nicht.

## Lesen oder lesen und schreiben

Beim Erzeugen wählst du den Zugriff des Schlüssels:

- **Nur lesen** – alle `GET`-Aufrufe. Jeder schreibende Aufruf (`POST`, `PUT`, `DELETE`) wird mit `403` abgelehnt, auch wenn das Konto ihn dürfte. Für Auswertungen und Abgleiche die sichere Wahl.
- **Lesen und schreiben** – zusätzlich die Verwaltungsaktionen unten.

## Was v1 kann

| Bereich | Lesen | Schreiben |
| --- | --- | --- |
| **Communities** | Communities, die der Schlüssel erreicht | Community anlegen (nur Plattform-Admins; das Konto des Schlüssels wird Owner) |
| **Mitglieder** | Verzeichnis mit Suche, Filtern (Status, Level, online, Altersgruppe) und Seiten; einzelnes Mitglied mit Community-Profil, eigenen Rollen (auch internen), Abzeichen und laufenden Plänen; Vor- und Nachname sowie Anschrift (`firstName`, `lastName`, `address` mit Firma und USt-IdNr.), wenn die Community sie abfragt – sonst `null`; eigene Rollen der Community; wartende Beitrittsanfragen mit Antworten | Beitrittsanfrage freigeben oder ablehnen; eigene Rollen eines Mitglieds setzen; Admin benennen (Owner und Plattform-Admins, per E-Mail-Adresse) |
| **Events** | Termine im Zeitraum (Serien aufgelöst) mit Zusagen, freien Plätzen und Warteliste, Mindestteilnehmerzahl mit Stichtag des Termins (`minAttendees`, `minAttendeesDeadlineAt`, `minAttendeesState`, `minAttendeesMissing`) und Absage (`cancelled`, `cancellationKind`, `cancellationReason`, `cancelledAt`); ein Termin mit Teilnehmenden, Ticketnummer, Check-in-Stand und Warteliste | Event anlegen, ändern (auch Mindestteilnehmerzahl und Stichtag: `minAttendees`, `minAttendeesDeadline`), löschen; einen Termin absagen (`POST …/events/{eventId}/cancel` mit `occurrence` und optional `reason`) und die Absage zurücknehmen (`POST …/events/{eventId}/reinstate` mit `occurrence`) – siehe [Termine absagen](#termine-absagen) |
| **Kurse** | Kurse (auch Entwürfe) mit Modulen und Lektionen (ohne Inhalte); Freischaltungen; Fortschritt eines Mitglieds in allen Kursen | Kurs für ein Mitglied freischalten (optional befristet) und Freischaltung entziehen |
| **Dienste** | Geleistete [Dienste](/handbuch/owner/dienste) mit Zustand (`pending` = wartet auf Bestätigung, `confirmed` = zählt als geleistet, `rejected` = abgelehnt) – als Liste in Seiten mit Filtern (Zustand, Jahr, Dienst-Art, Event, Termin, Mitglied) und einzeln; je Eintrag Dienst-Art, Event und Termin, Mitglied in Kurzform, Zeitpunkt der Entscheidung und Begründung einer Ablehnung | Geleisteten Dienst bestätigen oder mit Begründung ablehnen; mehrere Dienste oder alle wartenden eines Termins auf einmal bestätigen |

Nicht in v1: Beiträge, Kommentare, Nachrichten, Zahlungen und Rechnungen, Einstellungen (auch Dienst-Arten, Dienst-Slots und deren Buchung), Plattform-Verwaltung, Webhooks. Für Benachrichtigungen bei Ereignissen gibt es die [Integrationen](/handbuch/owner/integrationen/uebersicht) mit dem allgemeinen Webhook.

### Geleistete Dienste bestätigen

Ab QuickTribe 2.37 kann eine Community festlegen, dass ein Dienst erst zählt, wenn das Team ihn [bestätigt hat](/handbuch/owner/dienste#geleistete-dienste-bestätigen). Über die API erledigt das zum Beispiel ein Einlass- oder Zeiterfassungs-System, das weiß, wer wirklich da war:

```bash
# Dienste, die auf Bestätigung warten (Seiten wie beim Mitgliederverzeichnis)
curl -s -H "Authorization: Bearer $QT_KEY" \
  "$QT_URL/api/rest/v1/communities/mein-verein/duty-completions?status=pending"

# Einen Dienst bestätigen – er zählt ab jetzt als geleistet
curl -s -X POST -H "Authorization: Bearer $QT_KEY" \
  "$QT_URL/api/rest/v1/communities/mein-verein/duty-completions/0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b/confirm"

# Einen Dienst ablehnen – die Begründung ist Pflicht (bis 300 Zeichen) und geht an das Mitglied
curl -s -X POST -H "Authorization: Bearer $QT_KEY" -H "Content-Type: application/json" \
  -d '{"reason":"Nicht erschienen."}' \
  "$QT_URL/api/rest/v1/communities/mein-verein/duty-completions/0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b/reject"

# Alle wartenden Dienste eines Termins bestätigen (occurrenceKey steht in jedem Eintrag)
curl -s -X POST -H "Authorization: Bearer $QT_KEY" -H "Content-Type: application/json" \
  -d '{"occurrenceKey":"5f0c2a9e-1b7d-5c3e-9f4a-0d1e2f3a4b5c"}' \
  "$QT_URL/api/rest/v1/communities/mein-verein/duty-completions/confirm"
```

Es gelten dieselben Regeln wie in der Oberfläche: Bestätigen geht für wartende und – als Korrektur – für abgelehnte Dienste, Ablehnen nur für wartende (sonst `409`); ein bestätigter Dienst ist endgültig. Wer einen schon bestätigten Dienst noch einmal bestätigt, bekommt ihn unverändert zurück (`200`). Das Mitglied wird wie sonst benachrichtigt, und jede Entscheidung steht im Protokoll.

Zwei Unterschiede zur Oberfläche: Dort bestätigen auch **Moderatoren** – ein API-Schlüssel braucht wie überall ein Konto, das **Owner oder Admin** ist (oder Plattform-Admin). Und ohne den Filter `status` liefert die Liste **alle** Zustände; als geleistet zählen nur Einträge mit `counted: true`.

### Termine absagen

`POST /api/rest/v1/communities/{slug}/events/{eventId}/cancel` sagt einen Termin ab, `…/reinstate` nimmt die Absage zurück – mit denselben Regeln und Folgen wie [in der Oberfläche](/handbuch/owner/events#termin-absagen): Zusagen bleiben gespeichert, die Angemeldeten werden benachrichtigt, der Eintrag im Protokoll nennt den API-Schlüssel.

```bash
curl -s -X POST -H "Authorization: Bearer $QT_KEY" -H "Content-Type: application/json" \
  "$QT_URL/api/rest/v1/communities/mein-verein/events/$EVENT_ID/cancel" \
  -d '{"occurrence": "2027-03-11T18:00:00+00:00", "reason": "Die Halle ist gesperrt."}'
```

- `occurrence` ist Pflicht: der Beginn des Termins, wie ihn die Terminliste als `occurrenceStart` liefert. Bei Serien betrifft der Aufruf nur diesen einen Termin.
- `reason` (nur beim Absagen, optional): reiner Text bis 300 Zeichen – ihn lesen die Angemeldeten in Benachrichtigung und E-Mail.
- Antwort ist der Termin (`cancelled`, `cancellationKind`, `cancellationReason`, `cancelledAt`). **404** bei unbekanntem Event oder Termin, **409** bei einer Vorschau, einem beendeten Termin, einem schon abgesagten bzw. nicht abgesagten Termin, **422** ohne `occurrence`.
- Auch automatische Absagen (Mindestteilnehmerzahl nicht erreicht) nimmst du so zurück; die Mindestzahl wird für diesen Termin danach nicht noch einmal geprüft.

## Datenschutz

Die API liefert nur, was Owner und Admins auch in der Oberfläche sehen. Geleistete Dienste nennen das Mitglied nur mit Anzeigename, Profilbild und Rolle – und die Begründung einer Ablehnung, die das Team selbst eingegeben hat. **Nicht** enthalten sind E-Mail-Adressen (das Mitgliederverzeichnis zeigt sie dem Team nicht), Geburtsdaten (höchstens die Altersgruppen-Abzeichen, die das Team sieht), Name und Anschrift von Communities, die sie nicht abfragen, Passwörter, Tokens und Zahlungsdaten. Über die API greift die Community selbst als Verantwortliche auf ihre Daten zu – sie ersetzt das Abrufen in der Oberfläche und gibt nichts an Dritte weiter. Wer die Daten an ein anderes System überträgt, ist dafür selbst verantwortlich (z. B. Auftragsverarbeitung mit dem CRM-Anbieter).

## Interaktive Doku

Jede Installation bringt ihre eigene, interaktive Beschreibung mit:

- **Swagger UI:** `https://<deine-installation>/api/rest/docs` – mit „Authorize“ trägst du deinen Schlüssel ein und probierst Aufrufe direkt im Browser aus (der Schlüssel bleibt nur in diesem Browser-Tab).
- **OpenAPI-Datei:** `https://<deine-installation>/api/rest/docs.json` – für Code-Generatoren, Postman, Insomnia oder Bruno.

Beide sind ohne Schlüssel lesbar; sie beschreiben nur die Schnittstelle, keine Daten.

<Tip>
Die Seiten dieser Doku zur API: [API-Schlüssel](/rest-api/api-schluessel), [Authentifizierung und Beispiele](/rest-api/authentifizierung), [Seiten, Filter, Fehler und Limits](/rest-api/konventionen). Hinweise für Betreiber (Proxy, Wartungsmodus) stehen unter [Betrieb → REST-API](/betrieb#rest-api).
</Tip>

## API-Referenz

Die Referenz in der Navigation links (Gruppe **API-Referenz**) entsteht aus derselben OpenAPI-Beschreibung wie die interaktive Doku. Trage im Feld für den Server die Adresse deiner Installation ein (ohne `https://`), um Beispiele direkt auszuprobieren.
