API-Referenz
Agon stellt eine REST-API bereit, die von der Desktop-App, der mobilen App und dem öffentlichen Website-Buchungswidget gemeinsam genutzt wird. Wenn du Entwickler bist und Agon integrieren oder darauf aufbauen möchtest, erklärt diese Seite die Grundlagen.
Basis-URL
Die API läuft lokal auf dem Computer des Studio-Managers:
http://localhost:8000
Wenn sich Kunden von außen verbinden (über die mobile App oder das Website-Widget), verwenden sie die benannte Cloudflare-Tunnel-URL des Studios, die so aussieht:
https://studio-<id>.tunnel.agon-studio.dev
Alle Endpunkte sind unter /api/v1/ versioniert. Zum Beispiel:
http://localhost:8000/api/v1/clients
Diese Seite behandelt das Backend, das lokal auf dem Computer jedes Studios läuft. Es gibt keine zentrale Agon-API: Der Lizenzserver und der gehostete KI-Proxy existieren nicht mehr, und der KI-Assistent ruft den vom Studio konfigurierten KI-Anbieter direkt auf (siehe Studio → KI-Assistent-Konfiguration).
Authentifizierung
Alle geschützten Endpunkte erfordern ein gültiges JWT-Zugriffstoken im Authorization-Header:
Authorization: Bearer <your_access_token>
Um ein Token zu erhalten, sende eine POST-Anfrage an /api/v1/auth/login mit deiner E-Mail und deinem Passwort:
{
"email": "manager@mystudio.com",
"password": "your-password"
}
Die Antwort enthält ein access_token (gültig 8 Stunden für Desktop, 30 Tage für Mobile) und ein refresh_token.
Deaktivierte Konten
Ein Zugriffstoken funktioniert nicht mehr, sobald sein Konto deaktiviert wird — es bleibt nicht
bis zum Ablauf gültig. Jede Anfrage liest das Konto neu, daher erhält ein deaktiviertes
Teammitglied oder ein Kunde, dessen Datensatz deaktiviert oder gelöscht wurde
(DELETE /api/v1/clients/{client_id}), bereits beim nächsten Aufruf 401 AUTH_TOKEN_INVALID,
an jedem Endpunkt. Auch POST /api/v1/auth/refresh weist das Refresh-Token ab, es gibt also
ohne erneute Anmeldung keinen Weg zurück.
Behandle diesen 401 wie jeden anderen: Verwende das Token nicht weiter und schicke die Person zurück zum Anmeldebildschirm. Er ist nicht wiederholbar, und ein Refresh behebt ihn nicht.
Wenn das Zugriffstoken abläuft, sende das Refresh-Token an POST /api/v1/auth/refresh, um ein neues Zugriffstoken zu erhalten, ohne dich erneut anzumelden.
Eine Passwortänderung beendet bestehende Sitzungen
Das Zurücksetzen oder Ändern eines Kontopassworts macht jedes bereits ausgestellte Token
ungültig — auch das Refresh-Token, das ein Zugriffstoken sonst um Monate überdauert. Wer noch
ein altes Token hält, erhält beim nächsten Aufruf 401 AUTH_TOKEN_INVALID, und auch
POST /api/v1/auth/refresh weist das alte Refresh-Token ab.
Das gilt für POST /api/v1/auth/reset-password,
POST /api/v1/auth/manager/recover-with-code und für ein Passwort, das über
PUT /api/v1/staff/{staff_id} gesetzt wird. Das Konto, das die Änderung auslöst, ist
eingeschlossen: Wer das eigene Passwort zurücksetzt, wird ebenfalls abgemeldet und muss sich mit
dem neuen Passwort anmelden.
Antwortformat
Alle Endpunkte liefern JSON zurück. Erfolgreiche Antworten liefern die angeforderten Daten direkt zurück.
Beispiel einer erfolgreichen Antwort:
{
"id": 42,
"full_name": "Jane Smith",
"email": "jane@example.com",
"status": "active"
}
Fehlerformat
Alle Fehlerantworten folgen dieser Struktur:
{
"error": {
"code": "BOOKING_CLASS_FULL",
"message": "This class is full. Would you like to join the waitlist?",
"details": {}
}
}
Häufige Fehlercodes:
| Code | Bedeutung |
|---|---|
AUTH_INVALID_CREDENTIALS | Falsche E-Mail oder falsches Passwort |
AUTH_TOKEN_EXPIRED | Das Zugriffstoken ist abgelaufen — erneuern |
AUTH_TOKEN_INVALID | (401) Das Token ist fehlerhaft, vom falschen Typ, oder gehört zu einem Konto, das nicht mehr existiert oder deaktiviert wurde — siehe Deaktivierte Konten. Nicht wiederholen; neu anmelden |
CLIENT_INACTIVE | (409) Ein Teammitglied wollte im Namen eines deaktivierten Kunden handeln. Ein deaktivierter Kunde, der für sich selbst handelt, erhält stattdessen AUTH_TOKEN_INVALID |
AUTH_INSUFFICIENT_PERMISSIONS | Deine Rolle erlaubt diese Aktion nicht |
BOOKING_CLASS_FULL | Keine Plätze im Kurs verfügbar |
BOOKING_ALREADY_EXISTS | Der Kunde ist für diesen Kurs bereits gebucht |
BOOKING_NO_MEMBERSHIP | Der Kunde hat keine aktive Mitgliedschaft oder Credits (wird auch für die Terminbuchung verwendet) |
BOOKING_CANCELLATION_WINDOW_PASSED | Zu kurz vor Kursbeginn, um zu stornieren |
CHECKIN_NO_BOOKING | Keine bestätigte Buchung für diesen Kunden und diesen Kurs gefunden |
CHECKIN_OUTSIDE_WINDOW | Außerhalb des Check-in-Zeitfensters |
CHECKIN_ALREADY_CHECKED_IN | Der Kunde hat bereits eingecheckt |
WAIVER_SIGNATURE_REQUIRED | Der Kunde hat eine nicht unterschriebene Pflicht-Haftungsfreistellung und kann nicht buchen |
APPOINTMENT_SERVICE_INACTIVE | Die angeforderte Termin-Dienstleistung wurde deaktiviert |
APPOINTMENT_INSTRUCTOR_INACTIVE | Das Konto des angeforderten Kursleiters ist nicht aktiv |
APPOINTMENT_IN_PAST | Die angeforderte Terminstartzeit liegt in der Vergangenheit |
APPOINTMENT_OUTSIDE_AVAILABILITY | Die angeforderte Zeit liegt außerhalb der Verfügbarkeit des Kursleiters |
APPOINTMENT_SLOT_CONFLICT | Die angeforderte Zeit überschneidet sich mit einem anderen bestätigten Termin (einschließlich Pufferzeit) |
APPOINTMENT_ALREADY_CANCELLED | Der Termin befindet sich nicht in einem bestätigten Zustand und kann nicht erneut storniert werden |
APPOINTMENT_NOT_CONFIRMED | Der Termin muss bestätigt sein, um als abgeschlossen oder nicht erschienen markiert zu werden |
CHECKOUT_INVALID_REDIRECT_URL | Eine success_url oder cancel_url des Checkouts ist kein erlaubtes Weiterleitungsziel (das agon://-Deep-Link-Schema, der Origin des Widgets, die Tunnel-URL des Studios oder eine Loopback-Adresse) |
NOT_FOUND | Die angeforderte Ressource existiert nicht |
VALIDATION_ERROR | Im Anfragetext fehlen erforderliche Felder oder er enthält ungültige Werte |
KI-Assistent-Fehlercodes:
| Code | Bedeutung |
|---|---|
AI_NOT_CONFIGURED | (409) Eine KI-Aktion wurde fortgesetzt, aber es ist kein KI-Anbieter konfiguriert — der Assistent läuft im Basismodus. Füge einen Anbieter-Schlüssel unter Einstellungen → KI-Assistent hinzu |
AI_RATE_LIMITED | (429) Der KI-Anbieter des Studios begrenzt die Anfragerate. details.docs_url verweist auf Bei erwarteter starker Nutzung |
AI_KEY_INVALID | (400) Der Anbieter hat den an POST /studio/ai gesendeten API-Schlüssel abgelehnt |
AI_INVALID_PROVIDER | (422) Der an POST /studio/ai gesendete Anbieter ist nicht unter GET /studio/ai/providers aufgeführt |
Interaktive Dokumentation (Swagger UI)
Die API von Agon enthält eine interaktive Dokumentation auf Basis von Swagger UI. Wenn Agon läuft, öffne diese URL in deinem Browser:
http://localhost:8000/docs
Die Swagger UI ermöglicht es dir, alle verfügbaren Endpunkte zu durchsuchen, ihre Parameter und Antwortformate zu sehen und Testanfragen direkt aus deinem Browser zu senden.
Eine alternative OpenAPI-Ansicht (ReDoc) ist ebenfalls verfügbar unter:
http://localhost:8000/redoc
API-Versionierung
Alle aktuellen Endpunkte liegen unter /api/v1/. Wenn in einer zukünftigen Version breaking Changes eingeführt werden, sind sie unter /api/v2/ verfügbar, während /api/v1/ für einen Übergangszeitraum aktiv bleibt.