بث الأحداث

المعاملات

Lingara-Versionheaderstringاختياري

إصدار API الذي يُجاب عن هذا الطلب به. بدونه، يحصل رمز الوصول على الإصدار الذي رُبط به عميله، ويحصل الطلب الذي لا رمز مميز فيه على الإصدار الحالي. لا يمكن الوصول إلى الإصدار الذي لا يزال قيد التطوير إلا بذكره هنا. الإصدار غير المعروف يُجاب عنه بـ 400 مع الرمز api_version_unknown. يسرد GET /v1/versions الإصدارات.

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

قيمة id: لآخر حدث استلمته. لها الأولوية على cursor وstart.

cursorquerystringاختياري

من أين تتابع: next_cursor لصفحة سابقة، أو id: لحدث في البث. المؤشر الأقدم من 30 يومًا يُجاب بـ 410 مع الرمز cursor_expired.

startquerystringاختياري

من أين تبدأ دون مؤشر: latest للأحداث من الآن فصاعدًا، أو oldest لكل حدث لا يزال محفوظًا.

typesqueryarray of stringاختياري

هذه الأنواع من الأحداث فقط، مفصولة بفواصل. من دونه، كل نوع تستطيع نطاقات رمزك قراءته.

الاستجابات

200 الأحداث فور وقوعها، حتى done أو error

أحداث البث text/event-stream

يرسل تعليق إبقاء الاتصال (keepalive) كل 15 ثانية.

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: توقف إصدار واجهة البرمجة الخاص بهذا الطلب. cursor_expired: المؤشر أقدم من 30 يومًا؛ ابدأ من جديد دون مؤشر.

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: {}