Felo APIs

SuperAgent API

Buat percakapan, konsumsi aliran SSE, lanjutkan percakapan, dan kueri metadata percakapan.

POST/v2/conversations

Autentikasi

Bearer API key

Tipe konten

application/json and text/event-stream

Catatan batas laju

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

SuperAgent API menyediakan kemampuan percakapan bertenaga AI dengan output streaming real-time dan integrasi LiveDoc. Alur kerja umumnya adalah:

Membuat percakapan - dapatkan stream_key, thread_short_id, dan live_doc_short_id
Mengonsumsi stream SSE - hubungkan ke endpoint stream menggunakan stream_key
Melakukan tindak lanjut - ajukan pertanyaan lanjutan dalam percakapan yang sama, dapatkan stream_key baru
Menanyakan detail percakapan - gunakan thread_short_id untuk mengambil metadata percakapan
Mengelola LiveDoc - lihat LiveDoc API untuk CRUD lengkap dan pengelolaan resource

Autentikasi

Semua permintaan memerlukan Kunci API di header Authorization:

Authorization: Bearer YOUR_API_KEY

Penggunaan dengan Agen AI

Pasang paket felo-ai lengkap untuk memberi Agen alur kerja SuperAgent dan setiap Felo Skill lain yang tersedia. Installer menemukan setiap direktori paket yang berisi SKILL.md secara dinamis, termasuk penambahan paket di masa mendatang. Pasang semua Skill yang ditemukan di Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills, atau Hermes Agent ~/.hermes/skills. Panduan penyiapan Agen AI manual menjelaskan proses instalasi yang aman dan konfigurasi per platform.

1. Membuat Percakapan

Endpoint

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

Header Permintaan

Header	Wajib	Deskripsi
`Authorization`	Ya	`Bearer YOUR_API_KEY`
`Content-Type`	Ya	`application/json`

Isi Permintaan

Parameter	Tipe	Wajib	Deskripsi
`query`	string	Ya	Kueri pengguna, 1-2000 karakter
`live_doc_short_id`	string	Tidak	Gunakan ulang LiveDoc yang sudah ada; hilangkan untuk membuat yang baru
`selected_resource_ids`	array of strings	Tidak	ID resource yang disertakan dalam konteks
`skill_id`	string	Tidak	ID Skill yang digunakan untuk percakapan ini
`accept_language`	string	Tidak	Preferensi bahasa, mis. `en`
`device_id`	string	Tidak	Pengenal perangkat
`extra`	object	Tidak	Parameter tambahan yang diteruskan ke SuperAgent
`ext`	object	Tidak	Parameter ekstensi (mis. `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 Berhasil (200)

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

Field Respons

Field	Tipe	Deskripsi
`stream_key`	string	Kunci yang digunakan untuk mengonsumsi stream SSE (lihat bagian 2)
`thread_short_id`	string	ID percakapan, digunakan untuk menanyakan detail percakapan
`live_doc_short_id`	string	ID LiveDoc yang terkait

2. Mengonsumsi Stream SSE

Setelah membuat percakapan, hubungkan ke endpoint stream menggunakan stream_key untuk menerima output real-time.

Endpoint

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

Parameter Kueri

Parameter	Tipe	Wajib	Deskripsi
`offset`	integer	Tidak	Melanjutkan streaming dari posisi ini. Gunakan untuk menyambung kembali setelah koneksi terputus.

Contoh

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

Sambungkan kembali 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 berupa stream Server-Sent Events (SSE) standar dengan Content-Type: text/event-stream.

Setiap event mengikuti format SSE:

event: <event_type>
data: <json_payload>

Contoh event:

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

event: done
data: {}

Saat terjadi error upstream:

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

Catatan

Hubungkan segera setelah membuat percakapan - stream_key memiliki masa berlaku yang terbatas.
Gunakan klien yang mendukung SSE (mis. EventSource di browser, atau curl -N di terminal).
Stream berakhir saat event done diterima atau koneksi ditutup oleh server.

3. Tindak Lanjut Percakapan

Ajukan pertanyaan lanjutan dalam percakapan yang sudah ada. Mengembalikan stream_key baru untuk mengonsumsi stream respons.

Endpoint

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

Header Permintaan

Header	Wajib	Deskripsi
`Authorization`	Ya	`Bearer YOUR_API_KEY`
`Content-Type`	Ya	`application/json`

Isi Permintaan

Parameter	Tipe	Wajib	Deskripsi
`query`	string	Ya	Pertanyaan lanjutan, 1-2000 karakter

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 Berhasil (200)

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

Field Respons

Field	Tipe	Deskripsi
`stream_key`	string	Kunci yang digunakan untuk mengonsumsi stream SSE untuk tindak lanjut ini
`thread_short_id`	string	ID percakapan yang sama seperti pada permintaan
`live_doc_short_id`	string	ID LiveDoc yang terkait

4. Menanyakan Detail Percakapan

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 Berhasil (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"
  }
}

Field Respons

Field	Tipe	Deskripsi
`thread_short_id`	string	ID percakapan
`title`	string	Judul percakapan (diturunkan dari kueri)
`created_at`	string	Stempel waktu pembuatan (ISO 8601)
`updated_at`	string	Stempel waktu pembaruan terakhir (ISO 8601)
`live_doc_short_id`	string	ID LiveDoc yang terkait

Kode Error

Kode	Status HTTP	Deskripsi
`UNAUTHORIZED`	401	Kunci API tidak valid atau sudah dicabut
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Gagal membuat percakapan (error downstream)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Gagal melakukan tindak lanjut percakapan (error downstream)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Gagal menanyakan detail percakapan (error downstream)

Alur Integrasi Umum

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 pengelolaan LiveDoc (CRUD, unggah resource, impor URL, retrieval), lihat LiveDoc API.