مرجع توسعه‌دهنده‌های لنگریت

نگاه کلی

دو راه ورود، یک حافظه. هر فراخوانی همان سابقهٔ یادگیری‌ای را می‌خواند یا می‌نویسد که برنامهٔ لنگریت استفاده می‌کند، پس مرورها، استریک و سطح همیشه هماهنگ می‌مانند.

شروع سریع

یک کلاینت 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}}}'

REST API را با توکن شخصی صدا بزن

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

احراز هویت

با هر درخواست یک bearer token بفرست. وقتی کاربرها از برنامهٔ تو وصل می‌شوند از OAuth 2.1 استفاده کن، و برای اسکریپت‌های خودت از توکن شخصی.

OAuth 2.1

کلاینت‌ها سرور احراز هویت را با discovery پیدا می‌کنند، از هدر WWW-Authenticate در پاسخ 401 روی /mcp. ثبت پویای کلاینت و سندهای متادیتای client ID پشتیبانی می‌شوند، پس بیشتر کلاینت‌ها به تنظیم نیاز ندارند.

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 همراه با PKCE (S256). آدرس بازگشت code، state و iss را همراه دارد.
• توکن‌های دسترسی یک ساعت اعتبار دارند. توکن‌های refresh ۶۰ روز اعتبار دارند و با هر استفاده عوض می‌شوند؛ توکن refresh قدیمی دیگر کار نمی‌کند.
• redirect URIها: https، http روی localhost (هر پورتی) یا یک scheme اختصاصی برنامه.

Scopeها

توکن‌های شخصی

در تنظیمات، بخش دسترسی API تا پنج توکن بساز. هر توکن فقط یک بار نشان داده می‌شود و هر وقت بخواهی می‌توانی باطلش کنی.

سرور MCP

Streamable HTTP، بدون حالت، با پاسخ‌های JSON. هر پیام JSON-RPC را با POST بفرست؛ GET پاسخ 405 می‌دهد چون جریان سمت سرور وجود ندارد.

ابزارها

پرامپت‌ها و منابع

پرامپت‌های today، quiz، my-mistakes و write یک جلسهٔ مطالعه به زبان‌های کاربر باز می‌کنند. منبع langrit://me پروفایل را به‌صورت JSON برمی‌گرداند.

نوع سؤال‌ها

recognition همراه گزینه‌ها و جواب مورد انتظار می‌آید؛ typed و translate هیچ‌وقت جواب را قبل از نمره‌دهی نشان نمی‌دهند.

REST API

همان حافظه روی HTTPS. ورودی و خروجی JSON.

مثال

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 }

خطاها

خطاها JSON هستند با error، message و hint. hint برای این نوشته شده که مدل بر اساسش عمل کند؛ آن را بی‌تغییر منتقل کن.

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

محدودیت‌ها

برای هر توکن ۶۰ درخواست در دقیقه روی REST API و ۱۲۰ روی MCP. درخواست‌های POST هدر Idempotency-Key را می‌پذیرند؛ تکرار در ۲۴ ساعت همان پاسخ اول را برمی‌گرداند.

خروجی داده‌ها

GET /api/v1/export همه‌چیز را به‌صورت JSON برمی‌گرداند. format=csv را همراه table=cards، mistakes یا reviews اضافه کن، یا format=anki را برای فایل ورود به Anki. با اشتراک تمام‌شده هم کار می‌کند.