Änderungen

Dieses Changelog beschreibt sichtbare Änderungen am öffentlichen Integrationsvertrag. Einträge erscheinen bevor inkompatibles Verhalten ausgeliefert wird. Die maschinenlesbare Quelle bleibt /openapi/public-v1.yaml.

Versionierung erfolgt über die URI /v1/. Siehe Dokumentationsstandard.

2026-09-29: Längere Webhook-Retries und vollständiger Buchungsexport

• Webhooks versuchen die Zustellung bis zu 15 Mal. Die Wartezeiten reichen über 5 Stunden, 25 Minuten und 15 Sekunden; jede einzelne Wartezeit ist auf eine Stunde begrenzt.
• Gültige Kalender-Tokens und API-Keys verbrauchen nur ihr eigenes Budget. Gemeinsame IP-Adressen von Kalenderanbietern oder Integrationen teilen diese Budgets nicht. IP-Limits gelten weiterhin für ungültige Zugangsdaten.
• GET /api/public/v1/bookings unterstützt cursor und pageSize von 1 bis 100. nextCursor und pageSize ergänzen die Antwort. Bestehende Aufrufe liefern weiterhin bis zu 100 Buchungen unter data, neueste zuerst.

2026-09-01 — Webhook-Eventkatalog

Kompatible Ergänzung der ausgehenden Webhooks. Bestehende Empfänger von booking.created bleiben gültig: type, data.booking und data.course bleiben; workspaceId, resource und weitere Snapshot-Felder kommen additiv hinzu.

• Der Katalog umfasst jeden Typ aus webhookEventTypes, inklusive ping.
• Endpunkte dürfen * abonnieren (Alle Events (auch künftige)) oder eine explizite Liste.
• Envelope mit workspaceId und resource: { type, id }. data trägt den Snapshot der Primärressource.
• Personenbezogene Felder nur mit Scope participants:read (Teilnehmerdaten mitsenden).
• Zustellreihenfolge über Events hinweg ist nicht garantiert.
• Aufbewahrung: 30 Tage zugestellt, 90 Tage endgültig fehlgeschlagen.
• OpenAPI public-v1.yaml beschreibt jedes Event unter webhooks: samt WebhookEnvelope und Snapshot-Schemas.

2026-08-30: Begrenzter Kalenderfeed

Inkompatible Begrenzung des Beta-Kalenderfeeds unter /api/calendar/v1/{token}.ics. Kalenderprogramme müssen 429 beachten und den Abruf nach Retry-After wiederholen.

• Ein Abruf enthält höchstens die frühesten 1.000 Termine, deren Beginn zwischen 30 Tagen vor und ausschließlich 365 Tagen nach dem Abrufzeitpunkt liegt.
• Pro Feed gelten 60 Abrufe in 15 Minuten. Pro Client gelten 240 Abrufe im selben Zeitraum. Die Zähler liegen persistent in PostgreSQL.
• GET und HEAD verbrauchen das Polling-Budget.
• Nach Überschreitung folgt 429 / calendar_rate_limit_exceeded mit einem dynamischen Retry-After-Header.
• Zuletzt abgerufen wird höchstens einmal pro Stunde aktualisiert.

2026-08-30 — Cursor-Pagination für Kurse und Sitzungen

Kompatible Ergänzung in /v1/. Anfragen ohne cursor liefern weiter die erste Seite. Große Kataloge werden nicht mehr vollständig in einer Antwort ausgeliefert.

• GET /api/public/v1/courses paginiert Kurse über Query pageSize und cursor. Standard und Maximum 50. Die Antwort enthält nextCursor und pageSize.
• Jeder Kurs in der Liste enthält höchstens pageSize Termine, früheste zuerst. Weitere Termine liefert GET /api/public/v1/courses/{courseId}.
• GET /api/public/v1/courses/{courseId} paginiert Sitzungen mit denselben Query-Parametern. nextCursor gilt dort für Termine.
• Ungültiger Cursor oder pageSize außerhalb 1–50 ergeben 400 / invalid_pagination.
• Die JSON-Antwort der Kursendpunkte ist zusätzlich auf 256 KiB begrenzt.
• Clients ohne Cursor bleiben gültig; sie erhalten die erste Seite statt der gesamten Sammlung.

2026-08-28 — Planabhängige Entwicklerfunktionen

Kompatible Ergänzung in /v1/. Bestehende Keys in Plänen mit Entwickler-API verhalten sich unverändert.

• Neuer Fehlercode capability_not_in_plan mit Status 403, wenn der Plan des Arbeitsbereichs die Entwickler-API nicht enthält
• Derselbe Code mit 403 am Kalenderfeed /api/calendar/v1/{token}.ics, wenn der Plan keine Kalenderfeeds enthält
• Der Code ist in ErrorBody.code in public-v1.yaml aufgenommen
• capability_not_in_plan verschwindet nicht durch einen neuen Key oder zusätzliche Scopes, sondern nur durch einen Planwechsel
• Das Anlegen von API-Keys, Kalenderfeeds und Webhook-Endpunkten im Dashboard ist an dieselbe Planfunktion gebunden
• GET /api/public/v1/bookings dokumentiert jetzt zusätzlich 405 / method_not_allowed; das Verhalten galt schon vorher für alle Methoden außer GET

2026-08-25 — Lesende Kursfelder und Kursdetail

Kompatible Ergänzung in /v1/.

• GET /api/public/v1/courses/{courseId} mit Scope courses:read
• Kursobjekte enthalten zusätzlich audience, offeringKind, priceInCents, capacity und waitlistEnabled
• Sitzungen enthalten zusätzlich deliveryMode
• Schreibende Methoden auf /api/public/v1/ liefern 405 / method_not_allowed mit Header Allow: GET
• Unbekannte Kurs-IDs liefern 404 / course_not_found
• Der Bereich Integrationen zeigt nach dem Erstellen oder Rotieren eines Keys einen kopierbaren GET-Aufruf. Endpunkte und Scopes stehen in der Dokumentation.

2026-08-18 — Version 1 (Beta)

Erste dokumentierte öffentliche REST-API.

• Bearer-Keys orb_api_* aus Integrationen
• Scopes courses:read, bookings:read, participants:read
• GET /api/public/v1/courses und GET /api/public/v1/bookings
• Buchungen enthalten participant nur mit participants:read
• Fehlerform { "error": { "code", "message" } }
• 401 invalid_api_key, 403 missing_scope, 429 rate_limit_exceeded mit Retry-After: 60
• 120 Anfragen / 60 Sekunden / Key
• Cache-Control: private, no-store
• Bookings-Limit 100, keine Cursor-Pagination
• Kalenderfeed /api/calendar/v1/{token}.ics
• Webhook booking.created, Header x-kursnaut-signature, HTTPS, höchstens acht Versuche
• Widget-API bleibt ein getrennter Vertrag unter /api/widget/v1/