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 برای دریافت فراداده گفت‌وگو
مدیریت LiveDocها - برای CRUD کامل و مدیریت منابع LiveDoc API را ببینید

احراز هویت

همه درخواست‌ها به یک کلید API در سرآیند Authorization نیاز دارند:

Authorization: Bearer YOUR_API_KEY

استفاده با عامل‌های هوش مصنوعی

بسته کامل felo-ai را نصب کنید تا گردش‌کارهای SuperAgent و هر Felo Skill در دسترس دیگر به یک عامل داده شود. نصب‌کننده به‌صورت پویا هر پوشه بسته شامل SKILL.md را کشف می‌کند، از جمله افزوده‌های آینده بسته. همه Skillهای کشف‌شده را در ~/.codex/skills مربوط به Codex، ~/.claude/skills مربوط به Claude Code، ~/.agents/skills مربوط به OpenClaw یا ~/.hermes/skills مربوط به Hermes Agent نصب کنید. راهنمای راه‌اندازی دستی عامل هوش مصنوعی فرآیند نصب ایمن و پیکربندی هر پلتفرم را توضیح می‌دهد.

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`	آرایه‌ای از رشته‌ها	خیر	شناسه منابع برای گنجاندن در زمینه
`skill_id`	string	خیر	شناسه Skill برای استفاده در این گفت‌وگو
`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

پس از ساخت گفت‌وگو، با stream_key به endpoint جریان وصل شوید تا خروجی زمان واقعی دریافت کنید.

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 را ببینید.