Zum Inhalt springen

Entwickler-Portal

Teams-API

Die öffentliche Schnittstelle für eigene Integrationen rund um dein Team: Spieltage, Verfügbarkeiten und Terminabstimmungen lesen, Stimmen und die eigene Verfügbarkeit schreiben. Ein API-Token hat genau die Berechtigungen seines Inhabers — es sieht die Teams, in denen du Mitglied bist, nicht mehr.

openapi.jsonZurück zum Portal

Schnellstart

  1. In den Kontoeinstellungen unter „API-Token“ einen Token anlegen. Für den Anfang genügt „Nur lesen“. Der Klartext erscheint genau einmal — sicher speichern.
  2. Den ersten Aufruf machen:
curl -H "Authorization: Bearer tma_pat_DEIN_TOKEN" \
  https://teammanagerapp.de/api/v1/me/teams

Die Antwort ist eine Liste deiner Teams mit deren IDs — der Einstieg für alle weiteren Endpunkte. Dasselbe in TypeScript und Python:

const BASE = "https://teammanagerapp.de/api/v1";
const headers = { Authorization: `Bearer ${process.env.TM_API_TOKEN}` };

const res = await fetch(`${BASE}/me/teams`, { headers });
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const { results } = await res.json();

for (const team of results) {
  console.log(`${team.name} — ${team.role}, ${team.memberCount} Mitglieder`);
}
import os
import requests

BASE = "https://teammanagerapp.de/api/v1"
headers = {"Authorization": f"Bearer {os.environ['TM_API_TOKEN']}"}

res = requests.get(f"{BASE}/me/teams", headers=headers)
res.raise_for_status()

for team in res.json()["results"]:
    print(f"{team['name']} — {team['role']}, {team['memberCount']} Mitglieder")

Grundlagen

Basis-URL
https://teammanagerapp.de/api/v1
Authentifizierung
Authorization: Bearer tma_pat_…
Content-Type
application/json
Zeichensatz
UTF-8
Zeitangaben
UTC, ISO 8601 — reine Daten als YYYY-MM-DD
Version
v1 · jede Antwort trägt X-Api-Version

Token legst du in den Kontoeinstellungen an (maximal 5 aktive) und kannst sie dort jederzeit widerrufen. Ein widerrufener Token verliert sofort den Zugriff.

Tragende Regeln

Deine Berechtigungen, live geprüft. Der Token trägt keine eigenen Rechte. Jede Anfrage wird gegen deine aktuellen Team-Mitgliedschaften geprüft: Verlässt du ein Team, sieht der Token es ab sofort nicht mehr. Teams ohne eigene Mitgliedschaft antworten 404 — auch wenn es sie gibt.

Scopes. Beim Anlegen wählst du „Nur lesen“ oder „Lesen und Schreiben“. Schreibende Endpunkte (Stimme abgeben, Verfügbarkeit setzen) verlangen einen Token mit Schreibzugriff und folgen denselben Regeln wie die App: Inaktive Mitglieder können nicht abstimmen, Stimmen nur bei laufender Abstimmung.

Pagination. Listen liefern { results, nextCursor }. Solange nextCursor nicht null ist, gibt es eine weitere Seite:

let cursor: string | null = null;
do {
  const url = new URL(`${BASE}/teams/${teamId}/members`);
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers });
  const page = await res.json();
  // … page.results verarbeiten …
  cursor = page.nextCursor;
} while (cursor);

Kein CORS. Die API ist für serverseitige Integrationen gedacht. Aufrufe aus dem Browser von einer fremden Origin funktionieren nicht — und ein API-Token gehört ohnehin nie in Client-Code.

Unbekannte Felder ignorieren. Additive Änderungen (neue Felder, neue Endpunkte) kommen ohne Ankündigung; brechende Änderungen erscheinen als /api/v2.

Rezepte

Abstimmen per API. Spieltage liefern während einer Abstimmung die Terminoptionen samt Stimmenstand und eigener Stimme; mit der pollOptionId stimmst du ab:

# Spieltage samt Abstimmung lesen …
curl -H "Authorization: Bearer tma_pat_DEIN_TOKEN" \
  "https://teammanagerapp.de/api/v1/teams/TEAM_ID/matchdays"

# … und für eine Terminoption stimmen (Token mit „Lesen und Schreiben“)
curl -X POST \
  -H "Authorization: Bearer tma_pat_DEIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pollOptionId": "OPTION_ID", "canPlay": true}' \
  https://teammanagerapp.de/api/v1/polls/vote

Eigene Verfügbarkeit pflegen. Etwa aus dem eigenen Kalender heraus:

curl -X POST \
  -H "Authorization: Bearer tma_pat_DEIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"date": "2026-08-15", "available": true}' \
  https://teammanagerapp.de/api/v1/teams/TEAM_ID/availability

Endpunkte

get/meEigenes Konto abrufen
get/me/teamsEigene Teams auflisten
get/teams/{teamId}/membersMitglieder eines Teams auflisten
get/teams/{teamId}/matchdaysSpieltage eines Teams auflisten
get/teams/{teamId}/availabilityVerfügbarkeiten eines Monats abrufen
post/teams/{teamId}/availabilityEigene Verfügbarkeit setzen
post/polls/voteStimme in einer Terminabstimmung abgeben
get/openapi.jsonDieses Dokument abrufen
get/me

Eigenes Konto abrufen

Identität des Token-Inhabers — der schnellste Weg, einen Token zu prüfen.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Antworten

  • 200 Das Konto hinter dem Token.
  • 401 Kein oder ungültiger API-Token.
  • 403 Token widerrufen, ohne Schreibzugriff oder Aktion nicht erlaubt.
  • 404 Nicht gefunden — auch für Teams, in denen der Token-Inhaber kein Mitglied ist.
  • 429 Rate-Limit erreicht. Retry-After nennt die Wartezeit in Sekunden.
get/me/teams

Eigene Teams auflisten

Alle Teams, in denen der Token-Inhaber Mitglied ist, mit Rolle und Status. Ohne Pagination — die Menge ist durch das Tarif-Limit klein; nextCursor ist immer null.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Antworten

  • 200 Teams des Token-Inhabers.
  • 401 Kein oder ungültiger API-Token.
  • 403 Token widerrufen, ohne Schreibzugriff oder Aktion nicht erlaubt.
  • 404 Nicht gefunden — auch für Teams, in denen der Token-Inhaber kein Mitglied ist.
  • 429 Rate-Limit erreicht. Retry-After nennt die Wartezeit in Sekunden.
get/teams/{teamId}/members

Mitglieder eines Teams auflisten

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

  • teamId (path, Pflicht) ID des Teams (aus /me/teams). Teams ohne eigene Mitgliedschaft antworten 404.
  • limit (query) Seitengröße. Standard 50, Maximum 200.
  • cursor (query) Interne ID des letzten Datensatzes der Vorseite (nextCursor).

Antworten

  • 200 Mitglieder des Teams.
  • 401 Kein oder ungültiger API-Token.
  • 403 Token widerrufen, ohne Schreibzugriff oder Aktion nicht erlaubt.
  • 404 Nicht gefunden — auch für Teams, in denen der Token-Inhaber kein Mitglied ist.
  • 429 Rate-Limit erreicht. Retry-After nennt die Wartezeit in Sekunden.
get/teams/{teamId}/matchdays

Spieltage eines Teams auflisten

Spieltage mit Terminfindung: Status, Zeitraum, bestätigter Termin und — während einer Abstimmung — die Terminoptionen samt Stimmenstand und eigener Stimme.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

  • teamId (path, Pflicht) ID des Teams (aus /me/teams). Teams ohne eigene Mitgliedschaft antworten 404.
  • limit (query) Seitengröße. Standard 50, Maximum 200.
  • cursor (query) Interne ID des letzten Datensatzes der Vorseite (nextCursor).

Antworten

  • 200 Spieltage des Teams.
  • 401 Kein oder ungültiger API-Token.
  • 403 Token widerrufen, ohne Schreibzugriff oder Aktion nicht erlaubt.
  • 404 Nicht gefunden — auch für Teams, in denen der Token-Inhaber kein Mitglied ist.
  • 429 Rate-Limit erreicht. Retry-After nennt die Wartezeit in Sekunden.
get/teams/{teamId}/availability

Verfügbarkeiten eines Monats abrufen

Kalenderdaten des Teams für einen Monat, wie in der Team-Kalenderansicht.

Rate-Limit: 60 Anfragen pro 60 Sekunden.

Parameter

  • teamId (path, Pflicht) ID des Teams (aus /me/teams). Teams ohne eigene Mitgliedschaft antworten 404.
  • month (query, Pflicht) Monat im Format YYYY-MM.

Antworten

  • 200 Verfügbarkeiten des Monats.
  • 400 Ungültige Anfrage — der Fehlertext benennt das Feld.
  • 401 Kein oder ungültiger API-Token.
  • 403 Token widerrufen, ohne Schreibzugriff oder Aktion nicht erlaubt.
  • 404 Nicht gefunden — auch für Teams, in denen der Token-Inhaber kein Mitglied ist.
  • 429 Rate-Limit erreicht. Retry-After nennt die Wartezeit in Sekunden.
post/teams/{teamId}/availability

Eigene Verfügbarkeit setzen

Setzt oder ändert die eigene Verfügbarkeit für einen Tag (±2 Jahre) — dieselbe Wirkung wie ein Klick im Team-Kalender. Verlangt Scope READ_WRITE.

Rate-Limit: 60 Anfragen pro 60 Sekunden. Verlangt einen Token mit Schreibzugriff.

Parameter

  • teamId (path, Pflicht) ID des Teams (aus /me/teams). Teams ohne eigene Mitgliedschaft antworten 404.

Rumpf

FeldTypBeschreibung
date*stringDer Tag, für den die eigene Verfügbarkeit gesetzt wird (YYYY-MM-DD). (Muster ^\d{4}-\d{2}-\d{2}$)
available*booleantrue = verfügbar, false = nicht verfügbar.

Antworten

  • 200 Verfügbarkeit gespeichert.
  • 400 Ungültige Anfrage — der Fehlertext benennt das Feld.
  • 401 Kein oder ungültiger API-Token.
  • 403 Token widerrufen, ohne Schreibzugriff oder Aktion nicht erlaubt.
  • 404 Nicht gefunden — auch für Teams, in denen der Token-Inhaber kein Mitglied ist.
  • 429 Rate-Limit erreicht. Retry-After nennt die Wartezeit in Sekunden.
post/polls/vote

Stimme in einer Terminabstimmung abgeben

Gibt die eigene Stimme zu einer Terminoption ab oder ändert sie, solange die Abstimmung läuft. Verlangt Scope READ_WRITE; inaktive Mitglieder können nicht abstimmen.

Rate-Limit: 60 Anfragen pro 60 Sekunden. Verlangt einen Token mit Schreibzugriff.

Rumpf

FeldTypBeschreibung
pollOptionId*stringID der Terminoption aus dem Spieltag (matchdays-Endpunkt, poll.options[].id). (min. 1 Zeichen)
canPlay*booleantrue = Kann spielen, false = Kann nicht.

Antworten

  • 200 Stimme gespeichert.
  • 400 Ungültige Anfrage — der Fehlertext benennt das Feld.
  • 401 Kein oder ungültiger API-Token.
  • 403 Token widerrufen, ohne Schreibzugriff oder Aktion nicht erlaubt.
  • 404 Nicht gefunden — auch für Teams, in denen der Token-Inhaber kein Mitglied ist.
  • 429 Rate-Limit erreicht. Retry-After nennt die Wartezeit in Sekunden.
get/openapi.json

Dieses Dokument abrufen

Maschinenlesbarer Vertrag der Teams-API. Ohne API-Token erreichbar.

Rate-Limit: 30 Anfragen pro 60 Sekunden. Ohne API-Token erreichbar.

Antworten

  • 200 Das OpenAPI-3.0-Dokument.
  • 429 Rate-Limit erreicht. Retry-After nennt die Wartezeit in Sekunden.

Fehler und Rate-Limits

Fehler folgen dem Format der App: ein einziger error-Schlüssel, etwa { "error": "Token hat keinen Schreibzugriff." }.

400Ungültige Anfrage — der Fehlertext benennt das Feld.
401Kein oder ungültiger API-Token.
403Token widerrufen, ohne Schreibzugriff oder Aktion nicht erlaubt.
404Nicht gefunden — auch für Teams, in denen der Token-Inhaber kein Mitglied ist.
429Rate-Limit erreicht. Retry-After nennt die Wartezeit in Sekunden.

60 Anfragen pro Minute und Token, getrennt für Lesen und Schreiben. Das Limit gilt über alle Server-Instanzen hinweg. Bei Überschreitung 429 mit Retry-After in Sekunden.

Support und Vorgangsnummer

Jede Antwort trägt den Header x-correlation-id — die Vorgangsnummer dieses Aufrufs. Bei Supportanfragen diese Nummer angeben: Damit lässt sich der konkrete Aufruf samt Status und Dauer nachschlagen. Du kannst auch selbst eine x-correlation-id (max. 64 Zeichen) mitschicken; sie wird übernommen und erscheint in der Antwort.

Versionierung

/api/v1/… ist der stabile Vertrag. Additive Änderungen sind jederzeit ohne Ankündigung möglich: neue Endpunkte, neue optionale Felder im Request, neue Felder in der Antwort. Clients müssen unbekannte Antwortfelder ignorieren. Brechende Änderungen erscheinen unter /api/v2/…; v1 bleibt danach mindestens 12 Monate bedienbar.