Felo APIs

SuperAgent API

Créez des conversations, consommez des flux SSE, poursuivez l'échange et consultez les métadonnées de conversation.

POST/v2/conversations

Authentification

Bearer API key

Type de contenu

application/json and text/event-stream

Notes sur les limites

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

L'API SuperAgent fournit des capacités de conversation propulsées par l'IA, avec une sortie en streaming en temps réel et une intégration LiveDoc. Le workflow typique est le suivant :

Créer une conversation : obtenez stream_key, thread_short_id et live_doc_short_id
Consommer le flux SSE : connectez-vous à l'endpoint de flux avec stream_key
Poser une question de suivi : posez des questions de suivi dans la même conversation et obtenez un nouveau stream_key
Interroger le détail de la conversation : utilisez thread_short_id pour récupérer les métadonnées de la conversation
Gérer les LiveDocs : consultez LiveDoc API pour le CRUD complet et la gestion des ressources

Authentification

Toutes les requêtes nécessitent une clé API dans l'en-tête Authorization :

Authorization: Bearer YOUR_API_KEY

Utilisation avec des agents IA

Installez le paquet complet felo-ai pour fournir à un agent les workflows SuperAgent et tous les autres Felo Skills disponibles. L'installateur découvre dynamiquement chaque répertoire de paquet contenant SKILL.md, y compris les ajouts futurs au paquet. Installez tous les Skills découverts dans Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills ou Hermes Agent ~/.hermes/skills. Le guide d'installation manuelle des agents IA explique la procédure d'installation sûre et la configuration propre à chaque plateforme.

1. Créer une conversation

Endpoint

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

En-têtes de requête

En-tête	Requis	Description
`Authorization`	Oui	`Bearer YOUR_API_KEY`
`Content-Type`	Oui	`application/json`

Corps de requête

Paramètre	Type	Requis	Description
`query`	string	Oui	Requête utilisateur, 1 à 2000 caractères
`live_doc_short_id`	string	Non	Réutiliser un LiveDoc existant ; omettez pour en créer un nouveau
`selected_resource_ids`	array of strings	Non	ID de ressources à inclure dans le contexte
`skill_id`	string	Non	ID de Skill à utiliser pour cette conversation
`accept_language`	string	Non	Préférence de langue, par exemple `en`
`device_id`	string	Non	Identifiant de l'appareil
`extra`	object	Non	Paramètres supplémentaires transmis à SuperAgent
`ext`	object	Non	Paramètres d'extension (par exemple `style_id`, `theme`)

Exemple

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

Réponse de succès (200)

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

Champs de réponse

Champ	Type	Description
`stream_key`	string	Clé utilisée pour consommer le flux SSE (voir section 2)
`thread_short_id`	string	ID de conversation, utilisé pour interroger le détail de la conversation
`live_doc_short_id`	string	ID du LiveDoc associé

2. Consommer le flux SSE

Après avoir créé une conversation, connectez-vous à l'endpoint de flux avec stream_key pour recevoir la sortie en temps réel.

Endpoint

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

Paramètres de requête

Paramètre	Type	Requis	Description
`offset`	integer	Non	Reprendre le streaming depuis cette position. À utiliser pour une reconnexion après une déconnexion.

Exemple

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

Se reconnecter avec un 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'

Réponse

La réponse est un flux Server-Sent Events (SSE) standard avec Content-Type: text/event-stream.

Chaque événement suit le format SSE :

event: <event_type>
data: <json_payload>

Exemples d'événements :

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

event: done
data: {}

En cas d'erreur upstream :

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

Remarques

Connectez-vous immédiatement après avoir créé la conversation : stream_key a une fenêtre de validité limitée.
Utilisez un client capable de SSE (par exemple EventSource dans les navigateurs, ou curl -N dans le terminal).
Le flux se termine lorsqu'un événement done est reçu ou que la connexion est fermée par le serveur.

3. Poser une question de suivi

Posez une question de suivi dans une conversation existante. Renvoie un nouveau stream_key pour consommer le flux de réponse.

Endpoint

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

En-têtes de requête

En-tête	Requis	Description
`Authorization`	Oui	`Bearer YOUR_API_KEY`
`Content-Type`	Oui	`application/json`

Corps de requête

Paramètre	Type	Requis	Description
`query`	string	Oui	Question de suivi, 1 à 2000 caractères

Exemple

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

Réponse de succès (200)

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

Champs de réponse

Champ	Type	Description
`stream_key`	string	Clé utilisée pour consommer le flux SSE de ce suivi
`thread_short_id`	string	Même ID de conversation que dans la requête
`live_doc_short_id`	string	ID du LiveDoc associé

4. Interroger le détail d'une conversation

Endpoint

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

Exemple

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

Réponse de succès (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"
  }
}

Champs de réponse

Champ	Type	Description
`thread_short_id`	string	ID de conversation
`title`	string	Titre de la conversation (dérivé de la requête)
`created_at`	string	Horodatage de création (ISO 8601)
`updated_at`	string	Horodatage de la dernière mise à jour (ISO 8601)
`live_doc_short_id`	string	ID du LiveDoc associé

Codes d'erreur

Code	Statut HTTP	Description
`UNAUTHORIZED`	401	La clé API est invalide ou révoquée
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Échec de la création de la conversation (erreur en aval)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Échec du suivi de la conversation (erreur en aval)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Échec de l'interrogation du détail de la conversation (erreur en aval)

Flux d'intégration typique

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

Pour la gestion des LiveDocs (CRUD, import de ressources, import d'URL, récupération), consultez l'API LiveDoc.