Felo APIs

SuperAgent API

Crie conversas, consuma streams SSE, continue a conversa e consulte metadados da conversa.

POST/v2/conversations

Autenticação

Bearer API key

Tipo de conteúdo

application/json and text/event-stream

Notas de limite

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

A SuperAgent API oferece recursos de conversa com IA, saída em streaming em tempo real e integração com o LiveDoc. O fluxo típico é:

Criar uma conversa - obtém stream_key, thread_short_id e live_doc_short_id
Consumir o stream SSE - conecta ao endpoint de stream usando stream_key
Fazer acompanhamento - faz perguntas de acompanhamento na mesma conversa e recebe uma nova stream_key
Consultar detalhes da conversa - usa thread_short_id para obter os metadados da conversa
Gerenciar LiveDocs - consulte LiveDoc API para CRUD completo e gerenciamento de recursos

Autenticação

Todas as requisições exigem uma chave de API no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Uso com agentes de IA

Instale o pacote completo felo-ai para dar a um agente os fluxos do SuperAgent e todos os demais Felo Skills disponíveis. O instalador descobre dinamicamente todos os diretórios de pacote que contêm SKILL.md, incluindo adições futuras de pacotes. Instale todos os Skills descobertos em ~/.codex/skills para o Codex, ~/.claude/skills para o Claude Code, ~/.agents/skills para o OpenClaw ou ~/.hermes/skills para o Hermes Agent. O guia de configuração manual de agentes de IA explica o processo de instalação segura e a configuração de cada plataforma.

1. Criar uma conversa

Endpoint

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

Cabeçalhos da requisição

Cabeçalho	Obrigatório	Descrição
`Authorization`	Sim	`Bearer YOUR_API_KEY`
`Content-Type`	Sim	`application/json`

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Sim	Consulta do usuário, de 1 a 2000 caracteres
`live_doc_short_id`	string	Não	Reutiliza um LiveDoc existente; omita para criar um novo
`selected_resource_ids`	array de strings	Não	IDs de recursos a serem incluídos no contexto
`skill_id`	string	Não	ID do Skill a ser usado nesta conversa
`accept_language`	string	Não	Preferência de idioma, por exemplo `en`
`device_id`	string	Não	Identificador do dispositivo
`extra`	object	Não	Parâmetros extras repassados ao SuperAgent
`ext`	object	Não	Parâmetros de extensão (por exemplo, `style_id`, `theme`)

Exemplo

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

Resposta de sucesso (200)

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

Campos da resposta

Campo	Tipo	Descrição
`stream_key`	string	Chave usada para consumir o stream SSE (veja a seção 2)
`thread_short_id`	string	ID da conversa, usado para consultar os detalhes da conversa
`live_doc_short_id`	string	ID do LiveDoc associado

2. Consumir o stream SSE

Depois de criar uma conversa, conecte ao endpoint de stream usando a stream_key para receber a saída em tempo real.

Endpoint

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

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`offset`	integer	Não	Retoma o streaming a partir desta posição. Use para reconectar após uma desconexão.

Exemplo

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

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

Resposta

A resposta é um stream padrão de Server-Sent Events (SSE) com Content-Type: text/event-stream.

Cada evento segue o formato SSE:

event: <event_type>
data: <json_payload>

Exemplos de eventos:

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

event: done
data: {}

Em caso de erro no upstream:

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

Observações

Conecte imediatamente após criar a conversa - a stream_key tem uma janela de validade limitada.
Use um cliente com suporte a SSE (por exemplo, EventSource em navegadores ou curl -N no terminal).
O stream termina quando um evento done é recebido ou quando o servidor fecha a conexão.

3. Fazer acompanhamento na conversa

Faça uma pergunta de acompanhamento em uma conversa existente. Retorna uma nova stream_key para consumir o stream da resposta.

Endpoint

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

Cabeçalhos da requisição

Cabeçalho	Obrigatório	Descrição
`Authorization`	Sim	`Bearer YOUR_API_KEY`
`Content-Type`	Sim	`application/json`

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Sim	Pergunta de acompanhamento, de 1 a 2000 caracteres

Exemplo

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

Resposta de sucesso (200)

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

Campos da resposta

Campo	Tipo	Descrição
`stream_key`	string	Chave usada para consumir o stream SSE deste acompanhamento
`thread_short_id`	string	O mesmo ID de conversa da requisição
`live_doc_short_id`	string	ID do LiveDoc associado

4. Consultar detalhes da conversa

Endpoint

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

Exemplo

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

Resposta de sucesso (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 da resposta

Campo	Tipo	Descrição
`thread_short_id`	string	ID da conversa
`title`	string	Título da conversa (derivado da consulta)
`created_at`	string	Timestamp de criação (ISO 8601)
`updated_at`	string	Timestamp da última atualização (ISO 8601)
`live_doc_short_id`	string	ID do LiveDoc associado

Códigos de erro

Código	Status HTTP	Descrição
`UNAUTHORIZED`	401	A chave de API é inválida ou foi revogada
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Falha ao criar a conversa (erro downstream)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Falha no acompanhamento da conversa (erro downstream)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Falha ao consultar os detalhes da conversa (erro downstream)

Fluxo típico de integração

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 gerenciamento de LiveDocs (CRUD, envio de recursos, importação de URL, recuperação), consulte a LiveDoc API.