Felo APIs

SuperAgent API

Vytvářejte konverzace, používejte streamy SSE, ptejte se dál a prohlížejte metadata konverzace.

POST/v2/conversations

Ověřování

Bearer API key

Typ obsahu

application/json and text/event-stream

Poznámky k limitům

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

SuperAgent API poskytuje konverzační možnosti poháněné AI s výstupem streamovaným v reálném čase a integrací LiveDoc. Typický workflow je:

Vytvoření konverzace – získáte stream_key, thread_short_id a live_doc_short_id
Odběr SSE streamu – připojte se k endpointu streamu pomocí stream_key
Doplňující dotaz – kládejte doplňující otázky ve stejné konverzaci a získáte nový stream_key
Dotaz na detail konverzace – pomocí thread_short_id načtěte metadata konverzace
Správa LiveDoců – kompletní CRUD a správu zdrojů najdete v LiveDoc API

Ověřování

Všechny požadavky vyžadují API klíč v hlavičce Authorization:

Authorization: Bearer YOUR_API_KEY

Použití s AI agenty

Nainstalujte kompletní balíček felo-ai, aby agent mohl používat workflow SuperAgent a všechny ostatní dostupné Felo Skills. Instalátor dynamicky objevuje každý adresář balíčku obsahující SKILL.md, včetně budoucích přírůstků balíčku. Nainstalujte všechny objevené Skills do ~/.codex/skills pro Codex, ~/.claude/skills pro Claude Code, ~/.agents/skills pro OpenClaw nebo ~/.hermes/skills pro Hermes Agent. Příručka k ručnímu nastavení AI agenta vysvětluje bezpečný postup instalace a konfiguraci pro jednotlivé platformy.

1. Vytvoření konverzace

Endpoint

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

Hlavičky požadavku

Hlavička	Povinné	Popis
`Authorization`	Ano	`Bearer YOUR_API_KEY`
`Content-Type`	Ano	`application/json`

Tělo požadavku

Parametr	Typ	Povinné	Popis
`query`	string	Ano	Dotaz uživatele, 1–2000 znaků
`live_doc_short_id`	string	Ne	Znovu použít existující LiveDoc; vynechte pro vytvoření nového
`selected_resource_ids`	pole řetězců	Ne	ID zdrojů, která se mají zahrnout do kontextu
`skill_id`	string	Ne	ID Skillu, který se má pro tuto konverzaci použít
`accept_language`	string	Ne	Jazyková preference, např. `en`
`device_id`	string	Ne	Identifikátor zařízení
`extra`	object	Ne	Doplňující parametry předávané do SuperAgent
`ext`	object	Ne	Rozšiřující parametry (např. `style_id`, `theme`)

Příklad

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

Úspěšná odpověď (200)

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

Pole odpovědi

Pole	Typ	Popis
`stream_key`	string	Klíč používaný k odběru SSE streamu (viz část 2)
`thread_short_id`	string	ID konverzace, používané k dotazu na detail konverzace
`live_doc_short_id`	string	Přidružené ID LiveDocu

2. Odběr SSE streamu

Po vytvoření konverzace se připojte k endpointu streamu pomocí stream_key a přijímejte výstup v reálném čase.

Endpoint

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

Parametry dotazu

Parametr	Typ	Povinné	Popis
`offset`	integer	Ne	Pokračovat ve streamování od této pozice. Použijte při opětovném připojení po odpojení.

Příklad

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

Opětovné připojení s offsetem:

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

Odpověď

Odpověď je standardní stream Server-Sent Events (SSE) s Content-Type: text/event-stream.

Každá událost má formát SSE:

event: <event_type>
data: <json_payload>

Příklady událostí:

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

event: done
data: {}

Při chybě upstreamu:

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

Poznámky

Připojte se okamžitě po vytvoření konverzace – stream_key má omezené okno platnosti.
Použijte klienta podporujícího SSE (např. EventSource v prohlížečích nebo curl -N v terminálu).
Stream skončí, když je přijata událost done nebo když server připojení zavře.

3. Doplňující dotaz v konverzaci

Položte doplňující otázku v existující konverzaci. Vrací nový stream_key pro odběr streamu odpovědi.

Endpoint

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

Hlavičky požadavku

Hlavička	Povinné	Popis
`Authorization`	Ano	`Bearer YOUR_API_KEY`
`Content-Type`	Ano	`application/json`

Tělo požadavku

Parametr	Typ	Povinné	Popis
`query`	string	Ano	Doplňující otázka, 1–2000 znaků

Příklad

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

Úspěšná odpověď (200)

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

Pole odpovědi

Pole	Typ	Popis
`stream_key`	string	Klíč používaný k odběru SSE streamu pro tento doplňující dotaz
`thread_short_id`	string	Stejné ID konverzace jako v požadavku
`live_doc_short_id`	string	Přidružené ID LiveDocu

4. Dotaz na detail konverzace

Endpoint

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

Příklad

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

Úspěšná odpověď (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"
  }
}

Pole odpovědi

Pole	Typ	Popis
`thread_short_id`	string	ID konverzace
`title`	string	Název konverzace (odvozený z dotazu)
`created_at`	string	Časové razítko vytvoření (ISO 8601)
`updated_at`	string	Časové razítko poslední aktualizace (ISO 8601)
`live_doc_short_id`	string	Přidružené ID LiveDocu

Kódy chyb

Kód	Stav HTTP	Popis
`UNAUTHORIZED`	401	API klíč je neplatný nebo zrušený
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Vytvoření konverzace selhalo (chyba navazující služby)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Doplňující dotaz v konverzaci selhal (chyba navazující služby)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Dotaz na detail konverzace selhal (chyba navazující služby)

Typický průběh integrace

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

Správu LiveDoců (CRUD, nahrávání zdrojů, import URL, vyhledávání) najdete v LiveDoc API.