Felo APIs

SuperAgent API

Crea conversaciones, consume flujos SSE, continúa la conversación y consulta los metadatos de la conversación.

POST/v2/conversations

Autenticación

Bearer API key

Tipo de contenido

application/json and text/event-stream

Notas sobre límites

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

La SuperAgent API ofrece capacidades de conversación impulsadas por IA con salida en streaming en tiempo real e integración con LiveDoc. El flujo de trabajo típico es:

Crear una conversación: obtén stream_key, thread_short_id y live_doc_short_id
Consumir el flujo SSE: conéctate al endpoint del flujo con stream_key
Hacer seguimiento: plantea preguntas de seguimiento en la misma conversación y obtén un nuevo stream_key
Consultar el detalle de la conversación: usa thread_short_id para obtener los metadatos de la conversación
Gestionar LiveDocs: consulta la LiveDoc API para las operaciones CRUD completas y la gestión de recursos

Autenticación

Todas las solicitudes requieren una clave de API en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

Uso con agentes de IA

Instala el paquete completo felo-ai para dar a un agente los flujos de trabajo de SuperAgent y todas las demás Felo Skills disponibles. El instalador descubre dinámicamente todos los directorios del paquete que contengan SKILL.md, incluidas las incorporaciones futuras. Instala todas las Skills descubiertas en Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills o Hermes Agent ~/.hermes/skills. La guía de configuración manual de agentes de IA explica el proceso de instalación segura y la configuración de cada plataforma.

1. Crear una conversación

Endpoint

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

Encabezados de la solicitud

Encabezado	Obligatorio	Descripción
`Authorization`	Sí	`Bearer YOUR_API_KEY`
`Content-Type`	Sí	`application/json`

Cuerpo de la solicitud

Parámetro	Tipo	Obligatorio	Descripción
`query`	string	Sí	Consulta del usuario, de 1 a 2000 caracteres
`live_doc_short_id`	string	No	Reutiliza un LiveDoc existente; omítelo para crear uno nuevo
`selected_resource_ids`	array de strings	No	ID de recursos que se incluirán en el contexto
`skill_id`	string	No	ID de la Skill que se usará en esta conversación
`accept_language`	string	No	Preferencia de idioma, por ejemplo `en`
`device_id`	string	No	Identificador del dispositivo
`extra`	object	No	Parámetros adicionales que se pasan directamente a SuperAgent
`ext`	object	No	Parámetros de extensión (por ejemplo, `style_id`, `theme`)

Ejemplo

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

Respuesta correcta (200)

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

Campos de la respuesta

Campo	Tipo	Descripción
`stream_key`	string	Clave que se usa para consumir el flujo SSE (consulta la sección 2)
`thread_short_id`	string	ID de la conversación, que se usa para consultar su detalle
`live_doc_short_id`	string	ID del LiveDoc asociado

2. Consumir el flujo SSE

Después de crear una conversación, conéctate al endpoint del flujo con stream_key para recibir la salida en tiempo real.

Endpoint

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

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
`offset`	integer	No	Reanuda el streaming desde esta posición. Úsalo para reconectar tras una desconexión.

Ejemplo

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

Reconectar con 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'

Respuesta

La respuesta es un flujo estándar de Server-Sent Events (SSE) con Content-Type: text/event-stream.

Cada evento sigue el formato SSE:

event: <event_type>
data: <json_payload>

Eventos de ejemplo:

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

event: done
data: {}

En caso de error upstream:

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

Notas

Conéctate inmediatamente después de crear la conversación: stream_key tiene una ventana de validez limitada.
Usa un cliente compatible con SSE (por ejemplo, EventSource en navegadores o curl -N en la terminal).
El flujo termina cuando se recibe un evento done o cuando el servidor cierra la conexión.

3. Hacer seguimiento de una conversación

Plantea una pregunta de seguimiento en una conversación existente. Devuelve un nuevo stream_key para consumir el flujo de respuesta.

Endpoint

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

Encabezados de la solicitud

Encabezado	Obligatorio	Descripción
`Authorization`	Sí	`Bearer YOUR_API_KEY`
`Content-Type`	Sí	`application/json`

Cuerpo de la solicitud

Parámetro	Tipo	Obligatorio	Descripción
`query`	string	Sí	Pregunta de seguimiento, de 1 a 2000 caracteres

Ejemplo

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

Respuesta correcta (200)

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

Campos de la respuesta

Campo	Tipo	Descripción
`stream_key`	string	Clave que se usa para consumir el flujo SSE de este seguimiento
`thread_short_id`	string	El mismo ID de conversación que en la solicitud
`live_doc_short_id`	string	ID del LiveDoc asociado

4. Consultar el detalle de la conversación

Endpoint

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

Ejemplo

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

Respuesta correcta (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"
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`thread_short_id`	string	ID de la conversación
`title`	string	Título de la conversación (derivado de la consulta)
`created_at`	string	Marca de tiempo de creación (ISO 8601)
`updated_at`	string	Marca de tiempo de la última actualización (ISO 8601)
`live_doc_short_id`	string	ID del LiveDoc asociado

Códigos de error

Código	Estado HTTP	Descripción
`UNAUTHORIZED`	401	La clave de API no es válida o está revocada
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Falló la creación de la conversación (error downstream)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Falló el seguimiento de la conversación (error downstream)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Falló la consulta del detalle de la conversación (error downstream)

Flujo de integración típico

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

Para la gestión de LiveDocs (CRUD, carga de recursos, importación de URL y recuperación), consulta la LiveDoc API.