Langrit developer reference

Overview

Two ways in, one memory. Every call reads or writes the same learner record the Langrit app uses, so reviews, streaks and levels stay in sync.

Quick start

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

Call the REST API with a personal token

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

Authentication

Send a bearer token on every request. Use OAuth 2.1 when people connect from your app, or a personal token for your own scripts.

OAuth 2.1

Clients find the authorization server through discovery, starting from the WWW-Authenticate header of a 401 on /mcp. Dynamic client registration and client ID metadata documents are supported, so most clients need no setup.

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

• Authorization code with PKCE (S256) only. The redirect carries code, state and iss.
• Access tokens last one hour. Refresh tokens last 60 days and rotate on every use; an old refresh token stops working.
• Redirect URIs: https, http on localhost (any port) or a private app scheme.

Scopes

Personal tokens

Create up to five in Settings, API access. A token is shown once and can be revoked at any time.

MCP server

Streamable HTTP, stateless, JSON responses. POST every JSON-RPC message; GET returns 405 because there is no server stream.

Tools

Prompts and resources

Prompts today, quiz, my-mistakes and write open a study session in the learner's languages. The resource langrit://me returns the profile as JSON.

Question modes

recognition comes with choices and the expected answer; typed and translate never reveal the answer before grading.

REST API

The same memory over HTTPS. JSON in and out.

Example

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 }

Errors

Errors are JSON with error, message and hint. The hint is written for a model to act on; pass it through.

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 requests a minute per token on the REST API and 120 on MCP. POST requests accept an Idempotency-Key header; a repeat within 24 hours returns the first response.

Data export

GET /api/v1/export returns everything as JSON. Add format=csv with table=cards, mistakes or reviews, or format=anki for an Anki import file. Works on an ended plan too.