REST API - Dokumentation

Basis-URL

https://kursator.de/api/v1

Alle API-Endpunkte sind relativ zu dieser Basis-URL.

Authentifizierung

Öffentliche Endpunkte (Kurslisten) benötigen keine Authentifizierung. Für Anbieter-spezifische Endpunkte ist ein API-Schlüssel erforderlich.

API-Schlüssel senden

// Als Header
X-API-Key: IHR_API_SCHLUESSEL

// Oder als Query-Parameter
?api_key=IHR_API_SCHLUESSEL
            

Kurse

GET /courses

Liste aller aktiven Kurse

Query-Parameter

Parameter	Typ	Beschreibung
q	string	Suchbegriff
category	string	Kategorie-Slug filtern
city	string	Nach Stadt filtern
from	date	Startdatum (YYYY-MM-DD)
to	date	Enddatum (YYYY-MM-DD)
limit	int	Anzahl Ergebnisse (Standard: 20, Max: 100)
offset	int	Offset für Pagination

Beispiel-Antwort

{
  "data": [
    {
      "id": 1,
      "name": "Töpferkurs für Anfänger",
      "slug": "toepferkurs-anfaenger",
      "description": "Lernen Sie die Grundlagen...",
      "skill_level": "beginner",
      "duration_minutes": 180,
      "provider": {
        "id": 1,
        "name": "Kreativwerkstatt Berlin"
      },
      "next_instance": {
        "start_date": "2026-03-15T10:00:00",
        "price_from": 4500
      }
    }
  ],
  "meta": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}
            

GET /courses/{slug}

Einzelnen Kurs mit allen Details abrufen

GET /courses/{slug}/instances

Alle Termine eines Kurses

Anbieter

GET /providers

Liste aller aktiven Anbieter

GET /providers/{slug}

Einzelnen Anbieter mit Kursen abrufen

GET /providers/{slug}/courses

Alle Kurse eines Anbieters

Buchungen (API-Key erforderlich)

POST /bookings

Neue Buchung erstellen

Request Body

{
  "course_instance_id": 123,
  "offer_id": 456,
  "quantity": 2,
  "customer": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "email": "max@example.com",
    "phone": "+49 123 456789"
  },
  "notes": "Vegetarisches Essen gewünscht"
}
            

GET /bookings/{id}

Buchungsdetails abrufen

Kategorien

GET /categories

Liste aller Kategorien mit Kursanzahl

Fehlerbehandlung

Bei Fehlern wird ein JSON-Objekt mit Fehlerdetails zurückgegeben:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Kurs nicht gefunden"
  }
}
            

HTTP-Statuscodes

200	Erfolg
400	Ungültige Anfrage (fehlende Parameter)
401	Nicht authentifiziert
403	Keine Berechtigung
404	Ressource nicht gefunden
429	Rate Limit überschritten
500	Server-Fehler

Rate Limiting

Die API ist auf 100 Anfragen pro Minute pro IP-Adresse begrenzt. Bei Überschreitung wird HTTP 429 zurückgegeben.