Referencia de Langrit para desarrolladores

Resumen

Dos entradas, una sola memoria. Cada llamada lee o escribe el mismo registro de aprendizaje que usa la app de Langrit, así que los repasos, las rachas y los niveles siguen sincronizados.

Inicio rápido

Conecta un cliente MCP

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

Llama a la REST API con un token personal

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

Autenticación

Envía un token bearer en cada petición. Usa OAuth 2.1 cuando la gente se conecte desde tu app, o un token personal para tus propios scripts.

OAuth 2.1

Los clientes encuentran el servidor de autorización mediante discovery, a partir de la cabecera WWW-Authenticate de un 401 en /mcp. Se admiten el registro dinámico de clientes y los documentos de metadatos de client ID, así que la mayoría de los clientes no necesitan configuración.

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

• Solo authorization code con PKCE (S256). La redirección lleva code, state e iss.
• Los tokens de acceso duran una hora. Los refresh tokens duran 60 días y rotan en cada uso; un refresh token antiguo deja de funcionar.
• URI de redirección: https, http en localhost (cualquier puerto) o un esquema privado de app.

Scopes

Tokens personales

Crea hasta cinco en Ajustes, Acceso API. Cada token se muestra una sola vez y puedes revocarlo cuando quieras.

Servidor MCP

Streamable HTTP, sin estado, respuestas en JSON. Envía cada mensaje JSON-RPC con POST; GET devuelve 405 porque no hay stream del servidor.

Herramientas

Prompts y recursos

Los prompts today, quiz, my-mistakes y write abren una sesión de estudio en los idiomas del estudiante. El recurso langrit://me devuelve el perfil en JSON.

Modos de pregunta

recognition incluye opciones y la respuesta esperada; typed y translate nunca revelan la respuesta antes de calificar.

REST API

La misma memoria por HTTPS. JSON de entrada y de salida.

Ejemplo

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 }

Errores

Los errores son JSON con error, message y hint. El hint está escrito para que un modelo pueda actuar; pásalo tal cual.

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

Límites

60 peticiones por minuto por token en la REST API y 120 en MCP. Las peticiones POST aceptan una cabecera Idempotency-Key; una repetición en 24 horas devuelve la primera respuesta.

Exportación de datos

GET /api/v1/export lo devuelve todo en JSON. Añade format=csv con table=cards, mistakes o reviews, o format=anki para un archivo de importación de Anki. También funciona con un plan terminado.