Felo APIs

SuperAgent API

Maak gesprekken, verbruik SSE-streams, ga door met de conversatie en bevraag gespreksmetadata.

POST/v2/conversations

Authenticatie

Bearer API key

Inhoudstype

application/json and text/event-stream

Toelichting op limieten

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

De SuperAgent API biedt AI-gedreven gespreksmogelijkheden met realtime streaming-uitvoer en LiveDoc-integratie. De gebruikelijke workflow is:

Een gesprek aanmaken - ontvang stream_key, thread_short_id en live_doc_short_id
De SSE-stream consumeren - verbind met het stream-endpoint via stream_key
Doorgaan - stel vervolgvragen in hetzelfde gesprek en ontvang een nieuwe stream_key
Gespreksdetails opvragen - gebruik thread_short_id om de metadata van het gesprek op te halen
LiveDocs beheren - zie de LiveDoc API voor volledige CRUD en resourcebeheer

Authenticatie

Alle verzoeken vereisen een API-sleutel in de Authorization-header:

Authorization: Bearer YOUR_API_KEY

Gebruik met AI-agents

Installeer het volledige pakket felo-ai om een agent SuperAgent-workflows en alle andere beschikbare Felo Skills te geven. Het installatieprogramma ontdekt dynamisch elke pakketmap die SKILL.md bevat, inclusief toekomstige pakketten. Installeer alle gevonden Skills in Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills of Hermes Agent ~/.hermes/skills. De handleiding voor handmatige AI-agentconfiguratie legt het veilige installatieproces en de configuratie per platform uit.

1. Een gesprek aanmaken

Endpoint

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

Verzoekheaders

Header	Verplicht	Beschrijving
`Authorization`	Ja	`Bearer YOUR_API_KEY`
`Content-Type`	Ja	`application/json`

Verzoekbody

Parameter	Type	Verplicht	Beschrijving
`query`	string	Ja	Query van de gebruiker, 1-2000 tekens
`live_doc_short_id`	string	Nee	Hergebruik een bestaande LiveDoc; laat weg om een nieuwe te maken
`selected_resource_ids`	array van strings	Nee	Resource-ID's om in de context op te nemen
`skill_id`	string	Nee	Skill-ID om voor dit gesprek te gebruiken
`accept_language`	string	Nee	Taalvoorkeur, bijvoorbeeld `en`
`device_id`	string	Nee	Apparaatidentificatie
`extra`	object	Nee	Extra parameters die aan SuperAgent worden doorgegeven
`ext`	object	Nee	Uitbreidingsparameters (bijvoorbeeld `style_id`, `theme`)

Voorbeeld

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

Succesrespons (200)

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

Responsvelden

Veld	Type	Beschrijving
`stream_key`	string	Sleutel om de SSE-stream te consumeren (zie sectie 2)
`thread_short_id`	string	Gespreks-ID, gebruikt om gespreksdetails op te vragen
`live_doc_short_id`	string	Gekoppelde LiveDoc-ID

2. De SSE-stream consumeren

Nadat je een gesprek hebt aangemaakt, verbind je met het stream-endpoint via de stream_key om realtime uitvoer te ontvangen.

Endpoint

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

Queryparameters

Parameter	Type	Verplicht	Beschrijving
`offset`	integer	Nee	Hervat de stream vanaf deze positie. Gebruik dit om opnieuw te verbinden na een onderbreking.

Voorbeeld

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

Opnieuw verbinden met 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

De respons is een standaard Server-Sent Events (SSE)-stream met Content-Type: text/event-stream.

Elke gebeurtenis volgt het SSE-formaat:

event: <event_type>
data: <json_payload>

Voorbeeldgebeurtenissen:

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

event: done
data: {}

Bij een fout upstream:

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

Opmerkingen

Verbind direct na het aanmaken van het gesprek - de stream_key is maar beperkt geldig.
Gebruik een SSE-compatibele client (bijvoorbeeld EventSource in browsers of curl -N in de terminal).
De stream eindigt wanneer een done-gebeurtenis wordt ontvangen of de server de verbinding sluit.

3. Doorgaan met een gesprek

Stel een vervolgvraag in een bestaand gesprek. Je ontvangt een nieuwe stream_key om de responsstream te consumeren.

Endpoint

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

Verzoekheaders

Header	Verplicht	Beschrijving
`Authorization`	Ja	`Bearer YOUR_API_KEY`
`Content-Type`	Ja	`application/json`

Verzoekbody

Parameter	Type	Verplicht	Beschrijving
`query`	string	Ja	Vervolgvraag, 1-2000 tekens

Voorbeeld

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

Succesrespons (200)

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

Responsvelden

Veld	Type	Beschrijving
`stream_key`	string	Sleutel om de SSE-stream voor dit vervolg te consumeren
`thread_short_id`	string	Dezelfde gespreks-ID als in het verzoek
`live_doc_short_id`	string	Gekoppelde LiveDoc-ID

4. Gespreksdetails opvragen

Endpoint

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

Voorbeeld

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

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

Responsvelden

Veld	Type	Beschrijving
`thread_short_id`	string	Gespreks-ID
`title`	string	Titel van het gesprek (afgeleid van de query)
`created_at`	string	Tijdstempel van aanmaken (ISO 8601)
`updated_at`	string	Tijdstempel van laatste wijziging (ISO 8601)
`live_doc_short_id`	string	Gekoppelde LiveDoc-ID

Foutcodes

Code	HTTP-status	Beschrijving
`UNAUTHORIZED`	401	API-sleutel is ongeldig of ingetrokken
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Gesprek aanmaken is mislukt (fout downstream)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Doorgaan met het gesprek is mislukt (fout downstream)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Gespreksdetails opvragen is mislukt (fout downstream)

Typische integratieflow

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

Zie de LiveDoc API voor LiveDoc-beheer (CRUD, resources uploaden, URL's importeren en ophalen).