Zum Hauptinhalt springen

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:

CodeBedeutung
AUTH_INVALID_CREDENTIALSFalsche E-Mail oder falsches Passwort
AUTH_TOKEN_EXPIREDDas 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_PERMISSIONSDeine Rolle erlaubt diese Aktion nicht
BOOKING_CLASS_FULLKeine Plätze im Kurs verfügbar
BOOKING_ALREADY_EXISTSDer Kunde ist für diesen Kurs bereits gebucht
BOOKING_NO_MEMBERSHIPDer Kunde hat keine aktive Mitgliedschaft oder Credits (wird auch für die Terminbuchung verwendet)
BOOKING_CANCELLATION_WINDOW_PASSEDZu kurz vor Kursbeginn, um zu stornieren
CHECKIN_NO_BOOKINGKeine bestätigte Buchung für diesen Kunden und diesen Kurs gefunden
CHECKIN_OUTSIDE_WINDOWAußerhalb des Check-in-Zeitfensters
CHECKIN_ALREADY_CHECKED_INDer Kunde hat bereits eingecheckt
WAIVER_SIGNATURE_REQUIREDDer Kunde hat eine nicht unterschriebene Pflicht-Haftungsfreistellung und kann nicht buchen
APPOINTMENT_SERVICE_INACTIVEDie angeforderte Termin-Dienstleistung wurde deaktiviert
APPOINTMENT_INSTRUCTOR_INACTIVEDas Konto des angeforderten Kursleiters ist nicht aktiv
APPOINTMENT_IN_PASTDie angeforderte Terminstartzeit liegt in der Vergangenheit
APPOINTMENT_OUTSIDE_AVAILABILITYDie angeforderte Zeit liegt außerhalb der Verfügbarkeit des Kursleiters
APPOINTMENT_SLOT_CONFLICTDie angeforderte Zeit überschneidet sich mit einem anderen bestätigten Termin (einschließlich Pufferzeit)
APPOINTMENT_ALREADY_CANCELLEDDer Termin befindet sich nicht in einem bestätigten Zustand und kann nicht erneut storniert werden
APPOINTMENT_NOT_CONFIRMEDDer Termin muss bestätigt sein, um als abgeschlossen oder nicht erschienen markiert zu werden
CHECKOUT_INVALID_REDIRECT_URLEine 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_FOUNDDie angeforderte Ressource existiert nicht
VALIDATION_ERRORIm Anfragetext fehlen erforderliche Felder oder er enthält ungültige Werte

KI-Assistent-Fehlercodes:

CodeBedeutung
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.


Verwandte Seiten​