Langrit-naslag voor ontwikkelaars

Overzicht

Twee ingangen, één geheugen. Elke aanroep leest of schrijft hetzelfde leerdossier als de Langrit-app, dus herhalingen, reeksen en niveaus blijven gelijk.

Snel aan de slag

Verbind een MCP-client

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}}}'

Roep de REST API aan met een persoonlijk token

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

Authenticatie

Stuur bij elk verzoek een bearer-token mee. Gebruik OAuth 2.1 als mensen verbinden vanuit jouw app, of een persoonlijk token voor je eigen scripts.

OAuth 2.1

Clients vinden de autorisatieserver via discovery, vanaf de WWW-Authenticate-header van een 401 op /mcp. Dynamische clientregistratie en client ID metadata documents worden ondersteund, dus de meeste clients hoeven niets in te stellen.

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

• Alleen authorization code met PKCE (S256). De redirect bevat code, state en iss.
• Toegangstokens zijn een uur geldig. Refresh tokens zijn 60 dagen geldig en wisselen bij elk gebruik; een oud refresh token werkt dan niet meer.
• Redirect-URI's: https, http op localhost (elke poort) of een eigen app-scheme.

Scopes

Persoonlijke tokens

Maak er tot vijf aan in Instellingen, API-toegang. Je ziet een token maar één keer en je kunt het altijd intrekken.

MCP-server

Streamable HTTP, stateless, JSON-antwoorden. Stuur elk JSON-RPC-bericht met POST; GET geeft 405, want er is geen serverstream.

Tools

Prompts en resources

De prompts today, quiz, my-mistakes en write openen een studiesessie in de talen van de leerling. De resource langrit://me geeft het profiel terug als JSON.

Vraagmodi

recognition komt met keuzes en het verwachte antwoord; typed en translate tonen het antwoord nooit voor de beoordeling.

REST API

Hetzelfde geheugen via HTTPS. JSON erin en eruit.

Voorbeeld

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 }

Fouten

Fouten zijn JSON met error, message en hint. De hint is geschreven zodat een model ermee aan de slag kan; geef hem door.

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." }

Limieten

60 verzoeken per minuut per token op de REST API en 120 op MCP. POST-verzoeken accepteren een Idempotency-Key-header; een herhaling binnen 24 uur geeft het eerste antwoord terug.

Data-export

GET /api/v1/export geeft alles terug als JSON. Voeg format=csv toe met table=cards, mistakes of reviews, of format=anki voor een Anki-importbestand. Werkt ook als je abonnement is afgelopen.