Felo APIs

SuperAgent API

Konuşmalar oluşturun, SSE akışlarını kullanın, ek sorular sorun ve konuşma üst verilerini görüntüleyin.

POST/v2/conversations

Kimlik doğrulama

Bearer API key

İçerik türü

application/json and text/event-stream

Hız sınırı notları

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

SuperAgent API, gerçek zamanlı akış çıktısı ve LiveDoc entegrasyonuyla yapay zekâ destekli konuşma yetenekleri sunar. Tipik iş akışı şöyledir:

Konuşma oluşturma - stream_key, thread_short_id ve live_doc_short_id değerlerini alın
SSE akışını tüketme - stream_key kullanarak akış endpoint'ine bağlanın
Takip sorusu sorma - aynı konuşmada takip soruları sorun ve yeni bir stream_key alın
Konuşma ayrıntılarını sorgulama - konuşma üst verilerini almak için thread_short_id kullanın
LiveDoc'ları yönetme - tam CRUD ve kaynak yönetimi için LiveDoc API bölümüne bakın

Kimlik Doğrulama

Tüm istekler, Authorization başlığında bir API anahtarı gerektirir:

Authorization: Bearer YOUR_API_KEY

AI Ajanlarıyla Kullanım

Bir Ajana SuperAgent iş akışlarını ve mevcut tüm diğer Felo Skill'lerini kazandırmak için eksiksiz felo-ai paketini kurun. Kurulum programı, SKILL.md içeren her paket dizinini (gelecekteki paket eklemeleri dahil) dinamik olarak keşfeder. Keşfedilen tüm Skill'leri Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills veya Hermes Agent ~/.hermes/skills dizinlerine kurun. Manuel AI Ajanı kurulum kılavuzu, güvenli kurulum sürecini ve platforma özgü yapılandırmayı açıklar.

1. Konuşma Oluşturma

Endpoint

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

İstek Başlıkları

Başlık	Gerekli	Açıklama
`Authorization`	Evet	`Bearer YOUR_API_KEY`
`Content-Type`	Evet	`application/json`

İstek Gövdesi

Parametre	Tür	Gerekli	Açıklama
`query`	string	Evet	Kullanıcı sorgusu, 1-2000 karakter
`live_doc_short_id`	string	Hayır	Mevcut bir LiveDoc'u yeniden kullanın; yenisini oluşturmak için bunu atlayın
`selected_resource_ids`	array of strings	Hayır	Bağlama dahil edilecek kaynak kimlikleri
`skill_id`	string	Hayır	Bu konuşma için kullanılacak Skill kimliği
`accept_language`	string	Hayır	Dil tercihi, ör. `en`
`device_id`	string	Hayır	Cihaz tanımlayıcısı
`extra`	object	Hayır	SuperAgent'a iletilen ek parametreler
`ext`	object	Hayır	Uzantı parametreleri (ör. `style_id`, `theme`)

Örnek

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

Başarılı Yanıt (200)

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

Yanıt Alanları

Alan	Tür	Açıklama
`stream_key`	string	SSE akışını tüketmek için kullanılan anahtar (bkz. bölüm 2)
`thread_short_id`	string	Konuşma kimliği; konuşma ayrıntılarını sorgulamak için kullanılır
`live_doc_short_id`	string	İlişkili LiveDoc kimliği

2. SSE Akışını Tüketme

Bir konuşma oluşturduktan sonra, gerçek zamanlı çıktı almak için stream_key ile akış endpoint'ine bağlanın.

Endpoint

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

Sorgu Parametreleri

Parametre	Tür	Gerekli	Açıklama
`offset`	integer	Hayır	Akışı bu konumdan sürdürün. Bağlantı koptuktan sonra yeniden bağlanmak için kullanın.

Örnek

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

Offset ile yeniden bağlanma:

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

Yanıt

Yanıt, Content-Type: text/event-stream başlığına sahip standart bir Server-Sent Events (SSE) akışıdır.

Her olay SSE biçimini izler:

event: <event_type>
data: <json_payload>

Örnek olaylar:

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

event: done
data: {}

Üst akış hatası durumunda:

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

Notlar

Konuşmayı oluşturduktan hemen sonra bağlanın - stream_key sınırlı bir geçerlilik penceresine sahiptir.
SSE destekli bir istemci kullanın (ör. tarayıcılarda EventSource veya terminalde curl -N).
Akış, bir done olayı alındığında veya bağlantı sunucu tarafından kapatıldığında sona erer.

3. Konuşmada Takip Sorusu Gönderme

Mevcut bir konuşmada takip sorusu sorun. Yanıt akışını tüketmek için yeni bir stream_key döndürür.

Endpoint

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

İstek Başlıkları

Başlık	Gerekli	Açıklama
`Authorization`	Evet	`Bearer YOUR_API_KEY`
`Content-Type`	Evet	`application/json`

İstek Gövdesi

Parametre	Tür	Gerekli	Açıklama
`query`	string	Evet	Takip sorusu, 1-2000 karakter

Örnek

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

Başarılı Yanıt (200)

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

Yanıt Alanları

Alan	Tür	Açıklama
`stream_key`	string	Bu takip sorusu için SSE akışını tüketmekte kullanılan anahtar
`thread_short_id`	string	İstektekiyle aynı konuşma kimliği
`live_doc_short_id`	string	İlişkili LiveDoc kimliği

4. Konuşma Ayrıntılarını Sorgulama

Endpoint

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

Örnek

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

Başarılı Yanıt (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"
  }
}

Yanıt Alanları

Alan	Tür	Açıklama
`thread_short_id`	string	Konuşma kimliği
`title`	string	Konuşma başlığı (sorgudan türetilir)
`created_at`	string	Oluşturma zaman damgası (ISO 8601)
`updated_at`	string	Son güncelleme zaman damgası (ISO 8601)
`live_doc_short_id`	string	İlişkili LiveDoc kimliği

Hata Kodları

Kod	HTTP Durumu	Açıklama
`UNAUTHORIZED`	401	API anahtarı geçersiz veya iptal edilmiş
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Konuşma oluşturulamadı (alt sistem hatası)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Konuşmada takip sorusu gönderilemedi (alt sistem hatası)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Konuşma ayrıntıları sorgulanamadı (alt sistem hatası)

Tipik Entegrasyon Akışı

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 yönetimi (CRUD, kaynak yükleme, URL içe aktarma, getirme) için LiveDoc API bölümüne bakın.