REST-API

Die öffentliche REST-API ist ein lesender Integrationsvertrag für Owner und Admins. Sie liefert veröffentlichte Kurse und Buchungen des Workspaces, dessen API-Key die Anfrage authentifiziert. Schreibende Buchungen, Widget-Einbettung und das Dashboard laufen über andere Schnittstellen.

Der Stand ist Beta. Die maschinenlesbare Quelle der Wahrheit ist /openapi/public-v1.yaml.

Abgrenzung

Schnittstelle	Zweck
Öffentliche REST-API `/api/public/v1/`	Server-zu-Server-Lesen mit Bearer-Key `orb_api_*`
Widget-API `/api/widget/v1/`	Eingebettetes Buchungs-Widget; eigener Key, andere Limits
Kalenderfeed `/api/calendar/v1/{token}.ics`	Abonnierbarer iCal-Feed ohne Teilnehmerdaten
Ausgehende Webhooks	Signierter Eventkatalog an eine HTTPS-URL

Die Widget-API ist nicht Teil dieses Vertrags. Widget-Keys funktionieren nicht an den öffentlichen REST-Endpunkten.

Authentifizierung

API-Keys werden unter Integrationen im Dashboard erzeugt. Der Klartext beginnt mit orb_api_ und ist nur bei Erstellung oder Rotation einmal sichtbar. Anfragen senden ihn als Bearer-Token:

Authorization: Bearer orb_api_…

Der Workspace kommt ausschließlich aus dem Key. Es gibt keinen Parameter, mit dem ein anderer Workspace gewählt werden könnte. Widerrufene oder rotierte Keys liefern 401.

Berechtigungen

Scope	Wirkung
`courses:read`	`GET /api/public/v1/courses` und `GET /api/public/v1/courses/{courseId}`
`bookings:read`	`GET /api/public/v1/bookings` ohne personenbezogene Felder
`participants:read`	ergänzt `participant.name` und `participant.email` in Buchungen

participants:read setzt bookings:read voraus. Ohne diesen Scope fehlt das Objekt participant vollständig.

Endpunkte

GET /api/public/v1/courses: veröffentlichte Kurse, bis zu 50 pro Cursor-Seite
GET /api/public/v1/courses/{courseId}: ein veröffentlichter Kurs, Termine mit Cursor-Paginierung
GET /api/public/v1/bookings: bis zu 100 neueste Buchungen, ohne Cursor

Kurslisten haben die Form { "data": [ … ], "nextCursor", "pageSize" }, das Kursdetail { "data": { … }, "nextCursor", "pageSize" }. Erfolgreiche Antworten setzen Cache-Control: private, no-store. Das Limit liegt bei 120 Anfragen pro Key und 60 Sekunden. Die Kursseitengröße ist 50.

Fehler haben immer die Form { "error": { "code", "message" } }:

Status	`code`	Bedeutung
`400`	`invalid_pagination`	ungültiger Cursor oder unzulässige Seitengröße
`401`	`invalid_api_key`	fehlender, ungültiger oder widerrufener Key
`403`	`missing_scope`	vorhandener Key ohne den nötigen Scope
`404`	`course_not_found`	Kurs unbekannt, unveröffentlicht oder fremder Workspace
`405`	`method_not_allowed`	schreibende Methode; die API ist nur lesend
`429`	`rate_limit_exceeded`	Limit überschritten; `Retry-After: 60`

Weiterlesen

Dokumentationsstandard: OpenAPI, Versionierung, CI
Quickstart: ersten Request mit curl senden
Referenz: Felder, Fehler und Limits
Webhooks und Kalender: Push und iCal
Änderungen: vor jedem Breaking Change