Langrit-Referenz für Entwickler

Überblick

Zwei Zugänge, ein Gedächtnis. Jeder Aufruf liest oder schreibt dieselben Lerndaten wie die Langrit-App, also bleiben Wiederholungen, Serien und Niveaus synchron.

Schnellstart

MCP-Client verbinden

claude mcp add --transport http langrit https://langrit.com/mcp

curl https://langrit.com/mcp \
  -H "Authorization: Bearer lgr_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"whats_due","arguments":{"limit":5}}}'

REST API mit persönlichem Token aufrufen

curl https://langrit.com/api/v1/due?limit=5 \
  -H "Authorization: Bearer lgr_…"

Authentifizierung

Sende bei jeder Anfrage ein Bearer-Token mit. Nutze OAuth 2.1, wenn sich Leute aus deiner App verbinden, oder ein persönliches Token für deine eigenen Skripte.

OAuth 2.1

Clients finden den Autorisierungsserver per Discovery, ausgehend vom WWW-Authenticate-Header einer 401 auf /mcp. Dynamische Client-Registrierung und Client-ID-Metadaten-Dokumente werden unterstützt, deshalb brauchen die meisten Clients keine Einrichtung.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://langrit.com/.well-known/oauth-protected-resource/mcp"

GET https://langrit.com/.well-known/oauth-protected-resource/mcp
GET https://langrit.com/.well-known/oauth-authorization-server

authorize  https://langrit.com/oauth/authorize
token      https://langrit.com/oauth/token
register   https://langrit.com/oauth/register
revoke     https://langrit.com/oauth/revoke

• Nur Authorization Code mit PKCE (S256). Der Redirect enthält code, state und iss.
• Access-Tokens gelten eine Stunde. Refresh-Tokens gelten 60 Tage und wechseln bei jeder Nutzung; ein altes Refresh-Token funktioniert dann nicht mehr.
• Redirect-URIs: https, http auf localhost (beliebiger Port) oder ein eigenes App-Schema.

Scopes

Persönliche Tokens

Erstelle bis zu fünf unter Einstellungen, API-Zugang. Ein Token wird nur einmal angezeigt und lässt sich jederzeit widerrufen.

MCP-Server

Streamable HTTP, zustandslos, JSON-Antworten. Sende jede JSON-RPC-Nachricht per POST; GET liefert 405, weil es keinen Server-Stream gibt.

Tools

Prompts und Ressourcen

Die Prompts today, quiz, my-mistakes und write starten eine Lerneinheit in den Sprachen der lernenden Person. Die Ressource langrit://me liefert das Profil als JSON.

Fragemodi

recognition kommt mit Auswahl und erwarteter Antwort; typed und translate zeigen die Antwort nie vor der Bewertung.

REST API

Dasselbe Gedächtnis über HTTPS. JSON rein, JSON raus.

Beispiel

POST /api/v1/mistakes
Idempotency-Key: 6f1c…

{ "wrong": "de huis", "correct": "het huis", "rule": "huis is a het-word" }

201 -> { "created": 1, "merged": 0,
         "cards": [{ "id": 812, "pattern": "article_de_het", "pattern_label": "de vs het",
                     "merged": false, "l1_hint": "…" }] }

POST /api/v1/reviews
{ "card_id": 812, "answer": "het huis", "mode": "typed" }

200 -> { "correct": true, "expected": "het huis", "explanation_l1": null,
         "next_due_at": "2026-11-08T09:00:00Z", "interval_days": 4,
         "ladder": { "before": 1, "after": 2 }, "streak": 12 }

Fehler

Fehler kommen als JSON mit error, message und hint. Der Hinweis ist so geschrieben, dass ein Modell damit weitermachen kann; gib ihn einfach weiter.

402 -> { "error": "subscription_required",
         "message": "The Langrit subscription for this account is not active.",
         "url": "https://langrit.com/pricing?ref=api",
         "hint": "Tell the learner their Langrit trial or subscription has ended and give them the url." }

Limits

60 Anfragen pro Minute und Token bei der REST API und 120 bei MCP. POST-Anfragen akzeptieren einen Idempotency-Key-Header; eine Wiederholung innerhalb von 24 Stunden liefert die erste Antwort.

Datenexport

GET /api/v1/export liefert alles als JSON. Füge format=csv mit table=cards, mistakes oder reviews hinzu, oder format=anki für eine Anki-Importdatei. Funktioniert auch nach Ende deines Tarifs.