Felo APIs

SuperAgent API

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

POST/v2/conversations

المصادقة

Bearer API key

نوع المحتوى

application/json and text/event-stream

ملاحظات السعر

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

يوفر SuperAgent API قدرات محادثة مدعومة بالذكاء الاصطناعي مع مخرجات بث فورية وتكامل LiveDoc. سير العمل النموذجي هو:

إنشاء محادثة - احصل على stream_key وthread_short_id وlive_doc_short_id
استهلاك تدفق SSE - اتصل بـendpoint البث باستخدام stream_key
المتابعة - اطرح أسئلة متابعة في المحادثة نفسها، واحصل على stream_key جديد
استعلام تفاصيل المحادثة - استخدم thread_short_id لجلب البيانات الوصفية للمحادثة
إدارة LiveDocs - راجع LiveDoc API لإدارة الموارد وCRUD الكاملة

المصادقة

تتطلب كل الطلبات مفتاح API في رأس Authorization:

Authorization: Bearer YOUR_API_KEY

الاستخدام مع وكلاء الذكاء الاصطناعي

ثبّت حزمة felo-ai الكاملة لتزويد وكيل بسير عمل SuperAgent وكل مهارة Felo Skill أخرى متاحة. يكتشف المثبّت ديناميكيًا كل دليل حزمة يحتوي SKILL.md، بما في ذلك إضافات الحزم المستقبلية. ثبّت كل المهارات المكتشفة في Codex ~/.codex/skills أو Claude Code ~/.claude/skills أو OpenClaw ~/.agents/skills أو Hermes Agent ~/.hermes/skills. يشرح دليل إعداد وكيل الذكاء الاصطناعي اليدوي عملية التثبيت الآمن والإعداد لكل منصة.

1. إنشاء محادثة

Endpoint

POST https://openapi.felo.ai/v2/conversations

رؤوس الطلب

الرأس	مطلوب	الوصف
`Authorization`	نعم	`Bearer YOUR_API_KEY`
`Content-Type`	نعم	`application/json`

نص الطلب

المعامل	النوع	مطلوب	الوصف
`query`	string	نعم	استعلام المستخدم، من 1 إلى 2000 حرف
`live_doc_short_id`	string	لا	إعادة استخدام LiveDoc موجود؛ احذفه لإنشاء واحد جديد
`selected_resource_ids`	array of strings	لا	معرّفات الموارد المراد تضمينها في السياق
`skill_id`	string	لا	معرّف المهارة لاستخدامها في هذه المحادثة
`accept_language`	string	لا	تفضيل اللغة، مثل `en`
`device_id`	string	لا	معرّف الجهاز
`extra`	object	لا	معاملات إضافية تُمرَّر إلى SuperAgent
`ext`	object	لا	معاملات الامتداد (مثل `style_id` و`theme`)

مثال

curl -X POST 'https://openapi.felo.ai/v2/conversations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "What is the latest news about AI?",
    "accept_language": "en",
    "skill_id": "your-skill-id",
    "device_id": "device-001",
    "ext": {"style_id": "xxx", "theme": "dark"}
  }'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "stream_key": "sk_abc123xyz",
    "thread_short_id": "TvyKouzJirXjFdst4uKRK3",
    "live_doc_short_id": "PvyKouzJirXjFdst4uKRK3"
  }
}

حقول الاستجابة

الحقل	النوع	الوصف
`stream_key`	string	المفتاح المستخدم لاستهلاك تدفق SSE (راجع القسم 2)
`thread_short_id`	string	معرّف المحادثة، يُستخدم لاستعلام تفاصيل المحادثة
`live_doc_short_id`	string	معرّف LiveDoc المرتبط

2. استهلاك تدفق SSE

بعد إنشاء محادثة، اتصل بـendpoint البث باستخدام stream_key لتلقي المخرجات الفورية.

Endpoint

GET https://openapi.felo.ai/v2/conversations/stream/{stream_key}

معاملات الاستعلام

المعامل	النوع	مطلوب	الوصف
`offset`	integer	لا	استئناف البث من هذا الموضع. استخدمه لإعادة الاتصال بعد الانقطاع.

مثال

curl -N 'https://openapi.felo.ai/v2/conversations/stream/sk_abc123xyz' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: text/event-stream'

إعادة الاتصال مع offset:

curl -N 'https://openapi.felo.ai/v2/conversations/stream/sk_abc123xyz?offset=42' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: text/event-stream'

الاستجابة

الاستجابة تدفق Server-Sent Events (SSE) قياسي بـContent-Type: text/event-stream.

يتبع كل حدث تنسيق SSE:

event: <event_type>
data: <json_payload>

أمثلة الأحداث:

event: message
data: {"content": "The latest AI news includes..."}

event: done
data: {}

عند خطأ في المزوّد الأعلى:

event: error
data: {"message": "upstream error: 502"}

ملاحظات

اتصل فورًا بعد إنشاء المحادثة - فلـstream_key نافذة صلاحية محدودة.
استخدم عميلًا يدعم SSE (مثل EventSource في المتصفحات أو curl -N في الطرفية).
ينتهي البث عند تلقي حدث done أو إغلاق الخادم الاتصال.

3. متابعة المحادثة

اطرح سؤال متابعة في محادثة موجودة. يعيد stream_key جديدًا لاستهلاك تدفق الاستجابة.

Endpoint

POST https://openapi.felo.ai/v2/conversations/{thread_short_id}/follow_up

رؤوس الطلب

الرأس	مطلوب	الوصف
`Authorization`	نعم	`Bearer YOUR_API_KEY`
`Content-Type`	نعم	`application/json`

نص الطلب

المعامل	النوع	مطلوب	الوصف
`query`	string	نعم	سؤال المتابعة، من 1 إلى 2000 حرف

مثال

curl -X POST 'https://openapi.felo.ai/v2/conversations/TvyKouzJirXjFdst4uKRK3/follow_up' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Can you elaborate on that?"
  }'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "stream_key": "sk_def456uvw",
    "thread_short_id": "TvyKouzJirXjFdst4uKRK3",
    "live_doc_short_id": "PvyKouzJirXjFdst4uKRK3"
  }
}

حقول الاستجابة

الحقل	النوع	الوصف
`stream_key`	string	المفتاح المستخدم لاستهلاك تدفق SSE لهذه المتابعة
`thread_short_id`	string	معرّف المحادثة نفسه كما في الطلب
`live_doc_short_id`	string	معرّف LiveDoc المرتبط

4. استعلام تفاصيل المحادثة

Endpoint

GET https://openapi.felo.ai/v2/conversations/{thread_short_id}

مثال

curl 'https://openapi.felo.ai/v2/conversations/TvyKouzJirXjFdst4uKRK3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

استجابة النجاح (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "thread_short_id": "TvyKouzJirXjFdst4uKRK3",
    "title": "What is the latest news about AI?",
    "created_at": "2026-03-09T10:00:00Z",
    "updated_at": "2026-03-09T10:00:30Z",
    "live_doc_short_id": "PvyKouzJirXjFdst4uKRK3"
  }
}

حقول الاستجابة

الحقل	النوع	الوصف
`thread_short_id`	string	معرّف المحادثة
`title`	string	عنوان المحادثة (مشتق من الاستعلام)
`created_at`	string	طابع زمني للإنشاء (ISO 8601)
`updated_at`	string	طابع زمني لآخر تحديث (ISO 8601)
`live_doc_short_id`	string	معرّف LiveDoc المرتبط

رموز الأخطاء

الرمز	حالة HTTP	الوصف
`UNAUTHORIZED`	401	مفتاح API غير صالح أو مُبطَل
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	فشل إنشاء المحادثة (خطأ لاحق)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	فشل متابعة المحادثة (خطأ لاحق)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	فشل استعلام تفاصيل المحادثة (خطأ لاحق)

تدفق التكامل النموذجي

1. POST /v2/conversations                              → get stream_key + thread_short_id + live_doc_short_id
2. GET  /v2/conversations/stream/{stream_key}          → consume SSE until "done"
3. POST /v2/conversations/{thread_short_id}/follow_up  → ask follow-up, get new stream_key
4. GET  /v2/conversations/stream/{new_stream_key}      → consume follow-up SSE until "done"
5. GET  /v2/conversations/{thread_short_id}            → fetch conversation metadata

لإدارة LiveDoc (CRUD ورفع الموارد واستيراد عناوين URL والاسترجاع)، راجع LiveDoc API.