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	Push-Event `booking.created` 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`
`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 mit geplanten Terminen
GET /api/public/v1/bookings — bis zu 100 neueste Buchungen, ohne Cursor

Antworten haben die Form { "data": [ … ] }. Erfolgreiche Antworten setzen Cache-Control: private, no-store. Das Limit liegt bei 120 Anfragen pro Key und 60 Sekunden.

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

Status	`code`	Bedeutung
`401`	`invalid_api_key`	fehlender, ungültiger oder widerrufener Key
`403`	`missing_scope`	vorhandener Key ohne den nötigen Scope
`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