Öffentliche API für KI-Buchungen
Über die öffentliche Kunden-API kannst du Playrooms durchsuchen und Buchungen bis zu
einer gehosteten Zahlungssitzung erstellen – auch direkt über KI-Assistenten. Alle
Pfade liegen unter /v1/ und sind in Kleinbuchstaben gehalten.
Öffentliche Endpunkte
Zum Suchen und Lesen ist kein API-Schlüssel nötig:
| Methode | Pfad | Beschreibung |
|---|---|---|
GET | /v1/playrooms | Playroom-Katalog durchsuchen (20 Einträge pro Seite) |
GET | /v1/playrooms/{urlPath} | Details zu einem Playroom |
GET | /v1/playrooms/{urlPath}/booking-options | Verfügbare Check-in-/Check-out-Zeiten und Preise |
GET | /v1/openapi.json | OpenAPI-Beschreibung der gesamten API |
Buchung mit API-Schlüssel
Zum Anlegen und Bezahlen einer Buchung benötigst du einen API-Schlüssel, den du im X-API-Key-Header mitschickst:
| Methode | Pfad | Beschreibung |
|---|---|---|
POST | /v1/orders | Buchung anlegen (Idempotency-Key erforderlich) |
GET | /v1/orders/{orderId} | Status und Details einer Buchung |
POST | /v1/orders/{orderId}/payment | Zahlungslink für die Buchung erzeugen |
API-Schlüssel erstellen
Erstelle und verwalte deine API-Schlüssel selbst in deinem Konto unter API-Schlüssel. Der Schlüssel wird nur einmal angezeigt — bewahre ihn sicher auf. Buchungen, die über einen deiner Schlüssel entstehen, werden deinem Konto zugeordnet.
OpenAPI-Spezifikation
Die vollständige, maschinenlesbare Beschreibung aller Endpunkte, Schemas und Fehlerfälle findest du unter /v1/openapi.json.
MCP-Server
KI-Assistenten können dieselben Fähigkeiten auch über den MCP-Server nutzen: /mcp. Er bietet die Tools search_playrooms, get_playroom, get_booking_options, create_booking, get_booking und create_payment_session.
Regeln und Versionierung
- Versionierung erfolgt über den URL-Pfad (
/v1/, später/v2/); alle Pfade sind lowercase. - Idempotenz:
POST /v1/orderserwartet einenIdempotency-Key-Header, damit wiederholte Aufrufe keine Doppelbuchung erzeugen. - Fehler: Anwendungsfehler verwenden normalerweise
ProblemDetailsmittitle,statusunddetail; verlasse dich nicht auf ein stabilescode-Feld. - Rate-Limit: Die öffentliche API erlaubt 200 Anfragen pro 60 Sekunden, begrenzt pro API-Key oder Client-IP. Ein tägliches Limit ist nicht dokumentiert.
- Webhooks: Die öffentliche API bietet noch keine ausgehenden Buchungs-Webhooks. Frage den Order-Status über den Endpunkt ab.