Felo APIs

SuperAgent API

Cipta perbualan, gunakan strim SSE, teruskan perbualan dan pertanyaan metadata perbualan.

POST/v2/conversations

Pengesahan

Bearer API key

Jenis kandungan

application/json and text/event-stream

Nota had kadar

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

SuperAgent API menyediakan keupayaan perbualan berkuasa AI dengan output penstriman masa nyata dan integrasi LiveDoc. Aliran kerja biasa ialah:

Cipta perbualan - dapatkan stream_key, thread_short_id, dan live_doc_short_id
Gunakan strim SSE - sambung ke endpoint strim menggunakan stream_key
Susuli - tanya soalan susulan dalam perbualan yang sama, dapatkan stream_key baharu
Tanyakan butiran perbualan - gunakan thread_short_id untuk mengambil metadata perbualan
Urus LiveDoc - lihat LiveDoc API untuk CRUD penuh dan pengurusan sumber

Pengesahan

Semua permintaan memerlukan Kunci API dalam pengepala Authorization:

Authorization: Bearer YOUR_API_KEY

Guna dengan Ejen AI

Pasang pakej lengkap felo-ai untuk memberikan Ejen aliran kerja SuperAgent dan setiap Felo Skill lain yang tersedia. Pemasang menemui secara dinamik setiap direktori pakej yang mengandungi SKILL.md, termasuk penambahan pakej pada masa hadapan. Pasang semua Skill yang ditemui dalam ~/.codex/skills Codex, ~/.claude/skills Claude Code, ~/.agents/skills OpenClaw, atau ~/.hermes/skills Hermes Agent. Panduan persediaan Ejen AI manual menerangkan proses pemasangan selamat dan konfigurasi setiap platform.

1. Cipta Perbualan

Endpoint

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

Pengepala Permintaan

Pengepala	Wajib	Penerangan
`Authorization`	Ya	`Bearer YOUR_API_KEY`
`Content-Type`	Ya	`application/json`

Isi Badan Permintaan

Parameter	Jenis	Wajib	Penerangan
`query`	string	Ya	Pertanyaan pengguna, 1-2000 aksara
`live_doc_short_id`	string	Tidak	Guna semula LiveDoc sedia ada; tinggalkan untuk mencipta yang baharu
`selected_resource_ids`	array of strings	Tidak	ID sumber untuk disertakan dalam konteks
`skill_id`	string	Tidak	ID Skill untuk digunakan bagi perbualan ini
`accept_language`	string	Tidak	Keutamaan bahasa, contohnya `en`
`device_id`	string	Tidak	Pengecam peranti
`extra`	object	Tidak	Parameter tambahan yang dihantar kepada SuperAgent
`ext`	object	Tidak	Parameter sambungan (contohnya `style_id`, `theme`)

Contoh

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"}
  }'

Respons Berjaya (200)

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

Medan Respons

Medan	Jenis	Penerangan
`stream_key`	string	Kunci yang digunakan untuk menggunakan strim SSE (lihat bahagian 2)
`thread_short_id`	string	ID perbualan, digunakan untuk menanyakan butiran perbualan
`live_doc_short_id`	string	ID LiveDoc yang berkaitan

2. Gunakan Strim SSE

Selepas mencipta perbualan, sambung ke endpoint strim menggunakan stream_key untuk menerima output masa nyata.

Endpoint

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

Parameter Pertanyaan

Parameter	Jenis	Wajib	Penerangan
`offset`	integer	Tidak	Sambung penstriman daripada kedudukan ini. Gunakan untuk menyambung semula selepas terputus.

Contoh

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

Sambung semula dengan 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'

Respons

Respons ialah strim Server-Sent Events (SSE) piawai dengan Content-Type: text/event-stream.

Setiap peristiwa mengikut format SSE:

event: <event_type>
data: <json_payload>

Contoh peristiwa:

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

event: done
data: {}

Pada ralat huluan:

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

Nota

Sambung serta-merta selepas mencipta perbualan - stream_key mempunyai tetingkap kesahan terhad.
Gunakan klien yang menyokong SSE (contohnya EventSource dalam pelayar, atau curl -N dalam terminal).
Strim tamat apabila peristiwa done diterima atau sambungan ditutup oleh pelayan.

3. Susuli Perbualan

Tanya soalan susulan dalam perbualan sedia ada. Mengembalikan stream_key baharu untuk menggunakan strim respons.

Endpoint

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

Pengepala Permintaan

Pengepala	Wajib	Penerangan
`Authorization`	Ya	`Bearer YOUR_API_KEY`
`Content-Type`	Ya	`application/json`

Isi Badan Permintaan

Parameter	Jenis	Wajib	Penerangan
`query`	string	Ya	Soalan susulan, 1-2000 aksara

Contoh

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?"
  }'

Respons Berjaya (200)

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

Medan Respons

Medan	Jenis	Penerangan
`stream_key`	string	Kunci yang digunakan untuk menggunakan strim SSE bagi susulan ini
`thread_short_id`	string	ID perbualan yang sama seperti permintaan
`live_doc_short_id`	string	ID LiveDoc yang berkaitan

4. Tanyakan Butiran Perbualan

Endpoint

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

Contoh

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

Respons Berjaya (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"
  }
}

Medan Respons

Medan	Jenis	Penerangan
`thread_short_id`	string	ID perbualan
`title`	string	Tajuk perbualan (diperoleh daripada pertanyaan)
`created_at`	string	Cap masa penciptaan (ISO 8601)
`updated_at`	string	Cap masa kemas kini terakhir (ISO 8601)
`live_doc_short_id`	string	ID LiveDoc yang berkaitan

Kod Ralat

Kod	Status HTTP	Penerangan
`UNAUTHORIZED`	401	Kunci API tidak sah atau telah dibatalkan
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Gagal mencipta perbualan (ralat hiliran)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Gagal menyusuli perbualan (ralat hiliran)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Gagal menanyakan butiran perbualan (ralat hiliran)

Aliran Integrasi Biasa

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

Untuk pengurusan LiveDoc (CRUD, muat naik sumber, import URL, pengambilan), lihat LiveDoc API.