Quickstart

Dieser Einstieg holt veröffentlichte Kurse über die öffentliche REST-API. Voraussetzungen:

Ein Workspace, in dem du Owner oder Admin bist.
Ein Plan mit Entwickler-API, also Studio oder Business. Im Plan Solo lässt sich kein API-Key anlegen.
Mindestens ein veröffentlichter Kurs mit geplantem Termin.

1. API-Key erzeugen

Öffne im Dashboard Integrationen und dort den Tab API.
Vergib einen Namen, zum Beispiel Kurskatalog.
Wähle den Scope courses:read.
Wähle API-Key erstellen.
Speichere den einmal angezeigten, mit orb_api_ beginnenden Wert lokal.

Der Klartext ist danach nicht mehr lesbar. Rotiere den Key bei Verlust und verwende den neuen Wert. Lege den Key nicht in Git, Tickets, Screenshots oder Client-Code ab.

Setze für Buchungen zusätzlich bookings:read. Name und E-Mail-Adresse der Teilnehmenden erfordern participants:read (setzt bookings:read voraus). Nach dem Erstellen erscheint unter Integrationen ein kopierbarer GET-Aufruf mit dem neuen Key. Die Endpunkte selbst stehen in diesem Quickstart.

2. Kurse lesen

Ersetze YOUR_API_KEY durch den gespeicherten Key. Die Basis-URL der Produktions-API ist https://api.kursnaut.ccl-dev.com.

curl -sS \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  https://api.kursnaut.ccl-dev.com/api/public/v1/courses

Erwartete erfolgreiche Antwort:

{
  "data": [
    {
      "id": "course-run-id",
      "title": "Aquarellkurs",
      "description": "Einführung ins Aquarell",
      "audience": "Anfänger:innen",
      "offeringKind": "series",
      "priceInCents": 4900,
      "capacity": 12,
      "waitlistEnabled": false,
      "sessions": [
        {
          "id": "session-id",
          "startsAt": "2026-09-01T17:00:00.000Z",
          "durationMinutes": 90,
          "timeZone": "Europe/Berlin",
          "location": "Studio Mitte",
          "deliveryMode": "in_person"
        }
      ]
    }
  ],
  "nextCursor": null,
  "pageSize": 50
}

Ohne Query-Parameter liefert die erste Seite höchstens 50 Kurse, jeder mit höchstens 50 Terminen. Die nächste Kursseite holst du mit ?cursor=…&pageSize=50. Einen einzelnen Kurs holst du unter /api/public/v1/courses/{courseId}; dort paginiert nextCursor die Termine. Ungültige pageSize- oder Cursor-Werte ergeben 400 / invalid_pagination.

Die Antwort darf nicht zwischengespeichert werden (Cache-Control: private, no-store). POST, PUT, PATCH und DELETE sind nicht Teil dieser API und liefern 405.

3. Buchungen lesen

Derselbe Aufruf mit einem Key, der bookings:read besitzt:

curl -sS \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  https://api.kursnaut.ccl-dev.com/api/public/v1/bookings

Ohne participants:read enthält jedes Element id, courseRunId, source, status, createdAt und updatedAt. Mit dem Scope kommt participant: { "name", "email" } hinzu. Ohne Query-Parameter liefert die API höchstens die 100 neuesten Buchungen unter data. Die Antwort enthält zusätzlich nextCursor und pageSize.

Für ältere Buchungen sende den zurückgegebenen nextCursor unverändert als cursor, zum Beispiel mit ?cursor=…&pageSize=100. Wiederhole den Abruf, bis nextCursor den Wert null hat. pageSize erlaubt Werte von 1 bis 100.

Typische Fehler

Fehlender oder ungültiger Key:

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

Key ohne den nötigen Scope (HTTP 403):

{
  "error": {
    "code": "missing_scope",
    "message": "The bookings:read scope is required"
  }
}

Mehr als 120 Anfragen in 60 Sekunden liefern HTTP 429 mit error.code rate_limit_exceeded und Header Retry-After: 60.

Die vollständige Feldliste steht in der Referenz. Das OpenAPI-Dokument liegt unter /openapi/public-v1.yaml.