Referenz

Feld	Wert
Version	1
Geprüft	2026-08-18
Status	Beta
OpenAPI	/openapi/public-v1.yaml
Basis-URL	https://api.orbinaut.ccl-dev.com

Diese Seite beschreibt den ausgelieferten Vertrag. Abweichungen gehören zuerst in die OpenAPI-Datei, dann hierher und in den Changelog.

Authentifizierung

Eigenschaft	Wert
Schema	Authorization: Bearer <key>
Key-Präfix	orb_api_
Herkunft	Dashboard Integrationen, nur Owner und Admin
Workspace	ausschließlich aus dem Key, kein Query-Parameter

Ungültige, fehlende, zu lange, widerrufene oder rotierte Keys ergeben 401 / invalid_api_key. Die Fehlermeldung enthält keine Hashes und keine internen IDs.

Scopes

Scope	Endpunkt	Personenbezogene Daten
courses:read	GET /api/public/v1/courses	nein
bookings:read	GET /api/public/v1/bookings	nein
participants:read	derselbe Bookings-Endpunkt	participant.name, participant.email

participants:read ohne bookings:read lässt sich nicht anlegen. Ein Key mit nur courses:read erhält auf /bookings 403 / missing_scope.

GET /api/public/v1/courses

Liefert veröffentlichte Kursdurchführungen (courseRun) mit geplanten Sitzungen des Key-Workspaces, sortiert nach Sitzungsbeginn.

Erfolg: 200, Body { "data": Course[] }, Header Cache-Control: private, no-store.

Course

Feld	Typ	Bedeutung
id	string	ID der Kursdurchführung
title	string	Titel der Kursvorlage
description	string	Beschreibung der Kursvorlage
sessions	Session[]	geplante Termine

Session

Feld	Typ	Bedeutung
id	string	Sitzungs-ID
startsAt	string (ISO-8601 UTC)	Beginn
durationMinutes	integer	Dauer in Minuten
timeZone	string	IANA-Zeitzone, zum Beispiel Europe/Berlin
location	string	Veranstaltungsort

Entwürfe, nicht veröffentlichte Durchführungen und abgesagte Sitzungen fehlen. Es gibt keine Pagination.

GET /api/public/v1/bookings

Liefert Buchungen des Key-Workspaces, neueste zuerst, festes Limit 100. Es gibt keine Cursor-Pagination und keine Filter-Query-Parameter.

Erfolg: 200, Body { "data": Booking[] }, Header Cache-Control: private, no-store.

Booking

Feld	Typ	Bedeutung
id	string	Buchungs-ID
courseRunId	string	zugehörige Kursdurchführung
source	string	admin, public_page, widget oder api
status	string	pending, confirmed, waitlisted, cancelled oder expired
createdAt	string (ISO-8601 UTC)	Anlage
updatedAt	string (ISO-8601 UTC)	letzte Änderung
participant	object, optional	nur mit Scope participants:read

participant

Feld	Typ	Bedeutung
name	string	Name der teilnehmenden Person
email	string	E-Mail-Adresse

Ohne participants:read fehlt das Feld participant vollständig. Es wird nicht als null geliefert.

Fehler

Jede Fehlerantwort:

{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid API key is required"
  }
}

HTTP	error.code	Wann
401	invalid_api_key	Header fehlt, Key ungültig, widerrufen oder rotiert
403	missing_scope	Key gültig, Scope für den Endpunkt fehlt
429	rate_limit_exceeded	mehr als 120 Anfragen in 60 Sekunden

Bei 429 setzt die API den Header Retry-After: 60. Clients sollen so viele Sekunden warten, bevor sie erneut senden.

Limits und Caching

Limit	Wert
Rate-Limit	120 Anfragen / 60 Sekunden / API-Key
Bookings-Seite	100, ohne Cursor
Cache	Cache-Control: private, no-store
Methoden	nur GET

Das Rate-Limit ist von Auth-, Widget- und Widget-Analytics-Limits getrennt. Es gibt keine schreibenden öffentlichen REST-Endpunkte in Version 1.

Nicht Teil dieses Vertrags

• Widget-API unter /api/widget/v1/
• Dashboard-tRPC
• Google-Kalender-Synchronisation (Roadmap)
• native Zapier-App (Roadmap; signierte Webhooks sind der v1-Weg)

Kalenderfeed und Webhooks stehen in Webhooks und Kalender.