جریان رویدادها

پارامترها

Lingara-Versionheaderstringاختیاری

نسخهٔ API‌ای که این درخواست با آن جواب داده می‌شود. بدون آن، توکن دسترسی نسخه‌ای را می‌گیرد که کلاینت آن به آن وصل است، و درخواستی بدون توکن نسخهٔ فعلی را می‌گیرد. به نسخه‌ای که هنوز در حال انکشاف است تنها با نام‌بردن آن در اینجا می‌توان رسید. نسخهٔ ناشناخته با 400 و کد api_version_unknown جواب داده می‌شود. GET /v1/versions نسخه‌ها را فهرست می‌کند.

Last-Event-IDheaderstringاختیاری

id: آخرین رویدادی که دریافت کرده‌اید. این بر cursor و start مقدم است.

cursorquerystringاختیاری

از کجا ادامه دهید: next_cursor یک صفحهٔ قبلی، یا id: یک رویداد جریان. نشانگری کهنه‌تر از ۳۰ روز با 410 و کد cursor_expired پاسخ می‌گیرد.

startquerystringاختیاری

بدون نشانگر از کجا آغاز کنید: latest برای رویدادها از همین حالا به بعد، یا oldest برای هر رویدادی که هنوز نگه داشته شده است.

typesqueryarray of stringاختیاری

فقط این نوع رویدادها، جداشده با کامه. بدون آن، هر نوعی که ساحه‌های توکن شما خوانده می‌توانند.

پاسخ‌ها

200 رویدادها همان لحظه که رخ می‌دهند، تا done یا error

رویدادهای جریان text/event-stream

هر 15 ثانیه یک یادداشت keepalive می‌فرستد.

event EventEnvelope

idstringضروری

typestringضروری

created_atstringضروری

api_versionstringضروری

subjectstringضروری

dataobjectضروری

done Done جریان را پایان می‌دهد

error StreamError جریان را پایان می‌دهد

در داخل پاسخ 200 می‌رسد. خط وضعیت قبلاً فرستاده شده است، بنابراین هر ناکامی پس از باز شدن جریان به‌عنوان این رویداد گزارش می‌شود.

codestringضروری

messagestringضروری

plan_idstring | nullاختیاری

خطاها

410application/json

api_version_discontinued: نسخهٔ API این درخواست متوقف شده است. cursor_expired: نشانگر کهنه‌تر از ۳۰ روز است؛ بدون آن دوباره آغاز کنید.

4XXapplication/json

درخواست رد شد. code دلیل را مشخص می‌کند و error آن را با کلمات بیان می‌کند.

503application/json · text/plain

خدمات به طور موقت در دسترس نیست؛ پس از تعداد ثانیه‌های ذکرشده در Retry-After دوباره کوشش کنید. در زمان ترمیمات، بدنهٔ پاسخ به جای پاکت خطا، متن ساده است.

5XXapplication/json

درخواست رد شد. code دلیل را مشخص می‌کند و error آن را با کلمات بیان می‌کند.

codestringضروری

دلیل رد شدن درخواست، به شکل کدی ثابت که می‌توان بر اساس آن تصمیم گرفت: برای مثال insufficient_scope (403)، rate_limited (429) و، برای یک کلاینت مصرفی، spend_cap_reached (402) و metered_billing_inactive (402).

errorstringضروری

نمونه

curl -N "https://api.getlingara.com/v1/events/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

کتابخانه را ترجیح می‌دهید؟ بخش کتابخانه‌ها را ببینید.

نمونهٔ جریان

id: djEuNzQ0MTIuOTkxLjE3OTAyNDk1NjQ
event: event
data: {"id":"lgr_evt_4f2a9c1e7b3d4e5f8a9b0c1d2e3f4a5b","type":"lesson_plan.ready","created_at":"2026-10-01T09:12:44Z","api_version":"2026-09-equipped-boxfish","subject":"lgr_sub_0f1e2d3c4b5a69788796a5b4c3d2e1f0","data":{"plan_id":"3f1c2a9e-5b7d-4e21-9a0c-6d8e4f2b1a37","status":"complete","title":"At the night market","source_lang":"en","target_lang":"zh","level":2}}

id: djEuNzQ0MzAuMC4xNzkwMjUwNDY0
event: done
data: {}