Felo APIs

SuperAgent API

Erstellen Sie Konversationen, konsumieren Sie SSE-Streams, stellen Sie Rückfragen und fragen Sie Konversationsmetadaten ab.

POST/v2/conversations

Authentifizierung

Bearer API key

Inhaltstyp

application/json and text/event-stream

Hinweise zu Limits

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

Die SuperAgent API bietet KI-gestützte Konversationsfunktionen mit Echtzeit-Streaming-Ausgabe und LiveDoc-Integration. Der typische Workflow ist:

Konversation erstellen – stream_key, thread_short_id und live_doc_short_id erhalten
SSE-Stream konsumieren – mit stream_key eine Verbindung zum Stream-Endpoint herstellen
Rückfrage stellen – in derselben Konversation Rückfragen stellen und einen neuen stream_key erhalten
Konversationsdetails abfragen – mit thread_short_id Konversationsmetadaten abrufen
LiveDocs verwalten – vollständige CRUD- und Ressourcenverwaltung siehe LiveDoc API

Authentifizierung

Alle Anfragen erfordern einen API-Schlüssel im Authorization-Header:

Authorization: Bearer YOUR_API_KEY

Verwendung mit KI-Agenten

Installieren Sie das vollständige Paket felo-ai, um einem Agenten SuperAgent-Workflows und jeden anderen verfügbaren Felo-Skill bereitzustellen. Der Installer ermittelt dynamisch jedes Paketverzeichnis mit SKILL.md, einschließlich künftiger Paketergänzungen. Installieren Sie alle gefundenen Skills in Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills oder Hermes Agent ~/.hermes/skills. Die manuelle Einrichtungsanleitung für KI-Agenten erklärt den sicheren Installationsablauf und die Konfiguration für jede Plattform.

1. Konversation erstellen

Endpoint

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

Anfrage-Header

Header	Erforderlich	Beschreibung
`Authorization`	Ja	`Bearer YOUR_API_KEY`
`Content-Type`	Ja	`application/json`

Anfrage-Textkörper

Parameter	Typ	Erforderlich	Beschreibung
`query`	string	Ja	Benutzerabfrage, 1–2000 Zeichen
`live_doc_short_id`	string	Nein	Ein vorhandenes LiveDoc wiederverwenden; weglassen, um ein neues zu erstellen
`selected_resource_ids`	array of strings	Nein	Ressourcen-IDs, die in den Kontext aufgenommen werden
`skill_id`	string	Nein	Skill-ID für diese Konversation
`accept_language`	string	Nein	Sprachpräferenz, z. B. `en`
`device_id`	string	Nein	Gerätekennung
`extra`	object	Nein	Zusätzliche Parameter, die an SuperAgent durchgereicht werden
`ext`	object	Nein	Erweiterungsparameter (z. B. `style_id`, `theme`)

Beispiel

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

Erfolgreiche Antwort (200)

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

Antwortfelder

Feld	Typ	Beschreibung
`stream_key`	string	Schlüssel zum Konsumieren des SSE-Streams (siehe Abschnitt 2)
`thread_short_id`	string	Konversations-ID zum Abfragen der Konversationsdetails
`live_doc_short_id`	string	Zugehörige LiveDoc-ID

2. SSE-Stream konsumieren

Stellen Sie nach dem Erstellen einer Konversation mit dem stream_key eine Verbindung zum Stream-Endpoint her, um die Echtzeitausgabe zu erhalten.

Endpoint

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

Query-Parameter

Parameter	Typ	Erforderlich	Beschreibung
`offset`	integer	Nein	Setzt das Streaming an dieser Position fort. Verwenden Sie dies für die Wiederverbindung nach einer Trennung.

Beispiel

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

Mit Offset erneut verbinden:

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

Antwort

Die Antwort ist ein standardmäßiger Server-Sent Events (SSE)-Stream mit Content-Type: text/event-stream.

Jedes Ereignis folgt dem SSE-Format:

event: <event_type>
data: <json_payload>

Beispielereignisse:

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

event: done
data: {}

Bei einem Upstream-Fehler:

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

Hinweise

Verbinden Sie sich sofort nach dem Erstellen der Konversation – stream_key hat ein begrenztes Gültigkeitsfenster.
Verwenden Sie einen SSE-fähigen Client (z. B. EventSource in Browsern oder curl -N im Terminal).
Der Stream endet, wenn ein done-Ereignis empfangen wird oder der Server die Verbindung schließt.

3. Rückfrage in einer Konversation stellen

Stellen Sie in einer bestehenden Konversation eine Rückfrage. Die Antwort enthält einen neuen stream_key zum Konsumieren des Antwortstreams.

Endpoint

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

Anfrage-Header

Header	Erforderlich	Beschreibung
`Authorization`	Ja	`Bearer YOUR_API_KEY`
`Content-Type`	Ja	`application/json`

Anfrage-Textkörper

Parameter	Typ	Erforderlich	Beschreibung
`query`	string	Ja	Rückfrage, 1–2000 Zeichen

Beispiel

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

Erfolgreiche Antwort (200)

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

Antwortfelder

Feld	Typ	Beschreibung
`stream_key`	string	Schlüssel zum Konsumieren des SSE-Streams für diese Rückfrage
`thread_short_id`	string	Dieselbe Konversations-ID wie in der Anfrage
`live_doc_short_id`	string	Zugehörige LiveDoc-ID

4. Konversationsdetails abfragen

Endpoint

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

Beispiel

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

Erfolgreiche Antwort (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"
  }
}

Antwortfelder

Feld	Typ	Beschreibung
`thread_short_id`	string	Konversations-ID
`title`	string	Konversationstitel (aus der Abfrage abgeleitet)
`created_at`	string	Erstellungszeitstempel (ISO 8601)
`updated_at`	string	Zeitstempel der letzten Aktualisierung (ISO 8601)
`live_doc_short_id`	string	Zugehörige LiveDoc-ID

Fehlercodes

Code	HTTP-Status	Beschreibung
`UNAUTHORIZED`	401	Der API-Schlüssel ist ungültig oder widerrufen
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Konversation konnte nicht erstellt werden (Downstream-Fehler)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Rückfrage in der Konversation ist fehlgeschlagen (Downstream-Fehler)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Konversationsdetails konnten nicht abgefragt werden (Downstream-Fehler)

Typischer Integrationsablauf

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

Zur Verwaltung von LiveDocs (CRUD, Ressourcen-Upload, URL-Import, Retrieval) siehe die LiveDoc API.