Für Entwickler:innen

LearnSphere API

Drei Zugänge, ein Prinzip: Du bekommst Kursdaten als sauberes JSON über HTTPS. Die öffentliche Katalog-API ist kostenlos, die Creator-API ist Teil des API-Pakets.

Grundlagen

Alle Endpunkte liefern JSON (UTF-8) und sind nur über HTTPS erreichbar. Erfolgreiche Antworten stecken in { "data": … }, Fehler in { "error": "code" } mit passendem HTTP-Status. Preise sind immer Cent-Beträge (priceCents), damit beim Rechnen keine Rundungsfehler entstehen.

Versionierung

Jede API trägt ihre Version im Pfad (/api/public/v1/…, /api/v1/…). Innerhalb einer Version bleiben bestehende Felder und ihr Verhalten stabil – es kommen höchstens neue, optionale Felder hinzu. Inkompatible Änderungen erscheinen ausschließlich unter einer neuen Version (v2), die alte läuft mit Vorlaufankündigung weiter. Baue deine Integration deshalb so, dass unbekannte zusätzliche Felder ignoriert werden.

Health-Check

Ein Endpunkt für Monitoring und Load Balancer – ohne Key, ohne Rate-Limit, nie zwischengespeichert. Er antwortet mit 200, solange alle Prüfungen bestehen, und mit 503, sobald eine fehlschlägt. Für automatische Überwachung reicht es, den HTTP-Status auszuwerten; der Rumpf nennt zusätzlich Laufzeit, Version und die einzelnen Prüfungen mit ihrer Dauer. Fehlerursachen stehen bewusst nur im Server-Log, nicht in der Antwort.

curl -i "https://learnsphere.one/api/health"

{
  "status": "ok",
  "timestamp": "2026-07-22T10:15:00.000Z",
  "uptimeSeconds": 86400,
  "version": "0.1.0",
  "checks": {
    "database": { "status": "ok", "durationMs": 3 }
  }
}

1. Öffentliche Katalog-API (kostenlos)

Ohne Anmeldung und ohne Key. Sie liefert ausschließlich Kurse, die auf LearnSphere veröffentlicht und im Shop gelistet sind – also genau das, was auch auf der Kurse-Seite zu sehen ist. Kurse, die ein Creator nur über eigene Kanäle vertreibt, tauchen hier nicht auf.

curl "https://learnsphere.one/api/public/v1/courses?q=react&per=12"

{
  "data": [
    {
      "id": "cm…",
      "slug": "react-fuer-einsteiger",
      "title": "React für Einsteiger",
      "subtitle": "Von null zur ersten App",
      "language": "de",
      "priceCents": 4900,
      "currency": "EUR",
      "creatorName": "Jane Doe",
      "sectionCount": 6,
      "lessonCount": 42,
      "averageRating": 4.8,
      "reviewCount": 31,
      "url": "https://learnsphere.one/de/courses/react-fuer-einsteiger",
      "createdAt": "2026-07-01T09:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "pages": 1, "per": 12 }
}

Kursdetail inklusive Beschreibung und Curriculum-Metadaten (Abschnitte, Lektionstitel, Dauer, Vorschau-Flag). Kursinhalte selbst – Videos, Dateien, Texte – gibt es hier bewusst nicht.

Rate-Limit: 60 Anfragen pro Minute und IP. Antworten dürfen bis zu 60 Sekunden gecacht werden.

2. Affiliate-API

Für Mitglieder des Partnerprogramms: der komplette Shop-Katalog mit deinen persönlichen Provisions-Links. Käufe über diese Links bringen dir 15 % Provision – gültig für jeden Kurskauf innerhalb von 7 Tagen nach dem Klick.

Auth: Bearer-API-Key (wie bei der Creator-API; ein API-Paket ist dafür nicht nötig, nur die Programm-Mitgliedschaft). Der Parameter affiliate=true ist Pflicht für die Provision: Nur dann tragen die zurückgegebenen urls deinen Affiliate-Code (?aff=…) – ohne den Parameter sind es neutrale Links ohne Provision. Rate-Limit: 60 Anfragen/Minute je Key.

3. Creator-API (im API-Paket)

Für Creator mit aktivem API-Paket (25 €/Monat, 20 €/Monat bei jährlicher Zahlung). Damit baust du deinen eigenen Shop: Die API liefert alle deine veröffentlichten Kurse – auch die, die nicht im LearnSphere-Shop gelistet sind. Verkäufe über deine API-Links zählen als eigener Kanal: 75 % Anteil statt 50 %.

Authentifizierung

Erstelle einen API-Key im Creator-Studio unter Vertrieb. Der Key (ls_…) wird dir genau einmal angezeigt und bei uns nur als Hash gespeichert. Sende ihn als Bearer-Token:

curl "https://learnsphere.one/api/v1/courses" \
  -H "Authorization: Bearer ls_1234…abcd"

Ohne gültigen Key oder aktives Paket kommt ein Fehler:

{ "error": "api_plan_required" }

Alle deine veröffentlichten Kurse mit Preisen, Bewertungen, url (Kauflink mit ?via=api – so wird der Verkauf deinem Kanal zugerechnet) und embedUrl fürs Widget. Optional seitenweise mit ?page=1&per=25 (max. 100) – dann kommt ein meta-Block dazu.

Kursdetail inklusive komplettem Curriculum (Abschnitte und Lektionen mit Dauer und Vorschau-Flag) – nur für deine eigenen Kurse.

Kursinhalt deines Kurses: Abschnitte, Lektionen und aufgelöste Blöcke (Texte, signierte Video-/Datei-URLs, Kapitelmarken, KI-Herkunftsangaben). Die email ist Pflicht und muss in diesem Kurs eingeschrieben sein – Inhalte gibt es ausschließlich im Kontext eines gültigen Kaufs, auch für dich als Betreiber (sonst 403). Die signierten Medien-URLs laufen ab, also pro Abruf frisch holen statt cachen. Übersetzungen über &lang=en.

Einschreibungen einer Käufer:in in deinen Kursen – damit entscheidet deine Seite, wer Inhalte sehen darf: Nutzer:in bei dir einloggen, E-Mail hier prüfen, bei Treffer den Kursinhalt ausliefern. Optional &course={slug} für einen einzelnen Kurs.

{
  "data": [
    {
      "course": "react-fuer-einsteiger",
      "enrolledAt": "2026-07-24T10:15:00.000Z",
      "completedAt": null
    }
  ]
}

Der komplette Checkout für deine eigene Seite: Du schickst Kurs-Slug, Käufer-E-Mail und deine Rücksprung-URLs – zurück kommt eine Stripe-Checkout-URL, zu der du weiterleitest. Nach der Zahlung wird die Einschreibung automatisch angelegt (Konto entsteht bei Bedarf anhand der E-Mail – die Person wird darüber per Mail informiert), der Verkauf läuft als externer Kanal mit 75 % Anteil für dich. Gratis-Kurse schreiben direkt ein ({ "enrolled": true }), bereits gekaufte melden { "alreadyEnrolled": true }. Optional: couponCode (deine Kurs-Gutscheine werden serverseitig geprüft und angewendet) und locale. Die Rücksprung-URLs müssen https sein (http nur für localhost); identische Anfragen liefern 30 Minuten lang dieselbe Checkout-URL statt neuer Sessions.

curl -X POST "https://learnsphere.one/api/v1/checkout" \
  -H "Authorization: Bearer ls_1234…abcd" \
  -H "Content-Type: application/json" \
  -d '{
    "course": "react-fuer-einsteiger",
    "email": "kundin@example.com",
    "successUrl": "https://deine-seite.de/danke",
    "cancelUrl": "https://deine-seite.de/kurs"
  }'

{ "data": { "url": "https://checkout.stripe.com/c/pay/cs_…" } }

So schützt du deinen Key

• Rufe die Creator-API nur von deinem Server auf – nie aus dem Browser. Im Frontend-Code wäre dein Key öffentlich.
• Lege den Key in eine Umgebungsvariable, nicht ins Repository.
• Widerrufe Keys sofort im Studio, wenn du ein Leck vermutest – der alte Key ist dann augenblicklich ungültig.

Sicherheit

• Alle Anfragen laufen über HTTPS; Keys nur als Bearer-Header.
• API-Keys werden ausschließlich gehasht gespeichert und nur einmal im Klartext angezeigt.
• Jede Anfrage prüft Key und Abo-Status – ein gekündigtes Paket schließt die API automatisch.
• Öffentliche Endpunkte enthalten keinerlei personenbezogene Daten und sind rate-limitiert.
• Zahlungen laufen nie über deine Server: Der Kauflink führt auf die LearnSphere-Kaufabwicklung (Stripe) – Kartendaten berühren deine Infrastruktur nicht.

Integration mit KI-Agents

Du baust deine Integration mit Claude Code oder einem anderen Coding-Agent? Wir stellen eine fertige SKILL.mdbereit: Sie beschreibt Endpunkte, Auth, Fehlercodes und die Sicherheitsregeln (z. B. „API-Key nie im Browser“) in einem Format, das dein Agent direkt versteht – so entsteht die Anbindung korrekt statt geraten.

Lege die Datei in deinem Projekt unter .claude/skills/learnsphere-api/SKILL.mdab und sag deinem Agent z. B. „binde meine LearnSphere-Kurse ein“. Für LLM-Crawler gibt es außerdem eine /llms.txt.