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 מספק יכולות שיחה מבוססות AI עם פלט בזרימה בזמן אמת ושילוב 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

שימוש עם סוכני AI

התקינו את החבילה המלאה felo-ai כדי להעניק לסוכן תהליכי SuperAgent וכל Felo Skill זמין אחר. המתקין מגלה באופן דינמי כל תיקיית חבילה שמכילה 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`	array of strings	לא	מזהי משאבים לכלול בהקשר
`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

לאחר יצירת שיחה, התחברו ל-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.