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 انضمام کے ساتھ AI سے چلنے والی مکالماتی صلاحیتیں فراہم کرتا ہے۔ عام ورک فلو یہ ہے:

مکالمہ بنائیں - stream_key، thread_short_id اور live_doc_short_id حاصل کریں
SSE اسٹریم استعمال کریں - stream_key استعمال کرتے ہوئے اسٹریم endpoint سے جڑیں
مزید پوچھیں - اُسی مکالمے میں مزید سوالات پوچھیں اور نیا stream_key حاصل کریں
مکالمے کی تفصیل معلوم کریں - مکالمے کی میٹاڈیٹا حاصل کرنے کے لیے thread_short_id استعمال کریں
LiveDocs کا انتظام کریں - مکمل CRUD اور ریسورس مینجمنٹ کے لیے LiveDoc API دیکھیں

تصدیق

تمام درخواستوں کے لیے Authorization ہیڈر میں API کلید درکار ہے:

Authorization: Bearer YOUR_API_KEY

AI ایجنٹس کے ساتھ استعمال

ایجنٹ کو SuperAgent ورک فلوز اور باقی تمام دستیاب Felo Skills دینے کے لیے مکمل felo-ai پیکج انسٹال کریں۔ انسٹالر SKILL.md رکھنے والی ہر پیکج ڈائریکٹری کو متحرک طور پر دریافت کرتا ہے، بشمول مستقبل کے پیکج اضافے۔ دریافت شدہ تمام Skills کو Codex میں ~/.codex/skills، Claude Code میں ~/.claude/skills، OpenClaw میں ~/.agents/skills یا Hermes Agent میں ~/.hermes/skills پر انسٹال کریں۔ AI ایجنٹ کی دستی سیٹ اپ گائیڈ محفوظ تنصیبی عمل اور ہر پلیٹ فارم کی کنفیگریشن کی وضاحت کرتی ہے۔

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`	strings کا ایرے	نہیں	سیاق و سباق میں شامل کرنے کے لیے ریسورس IDs
`skill_id`	string	نہیں	اِس مکالمے کے لیے استعمال ہونے والا Skill ID
`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	مکالمے کی ID، مکالمے کی تفصیل معلوم کرنے کے لیے استعمال ہوتی ہے
`live_doc_short_id`	string	متعلقہ LiveDoc ID

2. SSE اسٹریم استعمال کریں

مکالمہ بنانے کے بعد حقیقی وقت کا آؤٹ پٹ وصول کرنے کے لیے stream_key استعمال کرتے ہوئے اسٹریم endpoint سے جڑیں۔

endpoint

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

Query Parameters

پیرامیٹر	قسم	لازمی	تفصیل
`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'

جواب

جواب Content-Type: text/event-stream کے ساتھ معیاری Server-Sent Events (SSE) اسٹریم ہے۔

ہر ایونٹ 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	درخواست جیسی مکالمے کی ID
`live_doc_short_id`	string	متعلقہ LiveDoc ID

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	مکالمے کی ID
`title`	string	مکالمے کا عنوان (استفسار سے ماخوذ)
`created_at`	string	تخلیق کا ٹائم اسٹیمپ (ISO 8601)
`updated_at`	string	آخری اپ ڈیٹ کا ٹائم اسٹیمپ (ISO 8601)
`live_doc_short_id`	string	متعلقہ LiveDoc ID

ایرر کوڈز

کوڈ	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 دیکھیں۔