Felo APIs

SuperAgent API

Crea conversazioni, consuma stream SSE, continua la conversazione e consulta i metadati della conversazione.

POST/v2/conversations

Autenticazione

Bearer API key

Tipo di contenuto

application/json and text/event-stream

Note sui limiti

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

La SuperAgent API offre capacità conversazionali basate sull'IA con output in streaming in tempo reale e integrazione con LiveDoc. Il flusso di lavoro tipico è:

Creare una conversazione - ottieni stream_key, thread_short_id e live_doc_short_id
Consumare lo stream SSE - connettiti all'endpoint dello stream usando stream_key
Porre una domanda di follow-up - fai domande di follow-up nella stessa conversazione e ottieni una nuova stream_key
Consultare il dettaglio della conversazione - usa thread_short_id per recuperare i metadati della conversazione
Gestire i LiveDoc - vedi LiveDoc API per CRUD completo e gestione delle risorse

Autenticazione

Tutte le richieste richiedono una chiave API nell'header Authorization:

Authorization: Bearer YOUR_API_KEY

Uso con agenti IA

Installa il pacchetto completo felo-ai per dare a un agente i workflow SuperAgent e ogni altra Felo Skill disponibile. L'installer individua dinamicamente ogni directory del pacchetto che contiene SKILL.md, comprese le aggiunte future del pacchetto. Installa tutte le Skill trovate in Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills o Hermes Agent ~/.hermes/skills. La guida alla configurazione manuale degli agenti IA spiega il processo di installazione sicuro e la configurazione per ogni piattaforma.

1. Creare una conversazione

Endpoint

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

Header della richiesta

Header	Obbligatorio	Descrizione
`Authorization`	Sì	`Bearer YOUR_API_KEY`
`Content-Type`	Sì	`application/json`

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`query`	string	Sì	Query dell'utente, da 1 a 2000 caratteri
`live_doc_short_id`	string	No	Riutilizza un LiveDoc esistente; ometti per crearne uno nuovo
`selected_resource_ids`	array di stringhe	No	ID delle risorse da includere nel contesto
`skill_id`	string	No	ID della Skill da usare per questa conversazione
`accept_language`	string	No	Preferenza di lingua, ad es. `en`
`device_id`	string	No	Identificatore del dispositivo
`extra`	object	No	Parametri aggiuntivi passati a SuperAgent
`ext`	object	No	Parametri di estensione (ad es. `style_id`, `theme`)

Esempio

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

Risposta di successo (200)

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

Campi della risposta

Campo	Tipo	Descrizione
`stream_key`	string	Chiave usata per consumare lo stream SSE (vedi sezione 2)
`thread_short_id`	string	ID della conversazione, usato per consultare il dettaglio
`live_doc_short_id`	string	ID del LiveDoc associato

2. Consumare lo stream SSE

Dopo aver creato una conversazione, connettiti all'endpoint dello stream usando stream_key per ricevere l'output in tempo reale.

Endpoint

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

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`offset`	integer	No	Riprende lo streaming da questa posizione. Da usare per riconnettersi dopo una disconnessione.

Esempio

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

Riconnettersi 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'

Risposta

La risposta è un normale stream Server-Sent Events (SSE) con Content-Type: text/event-stream.

Ogni evento segue il formato SSE:

event: <event_type>
data: <json_payload>

Esempi di eventi:

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

event: done
data: {}

In caso di errore upstream:

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

Note

Connettiti subito dopo aver creato la conversazione: stream_key ha una finestra di validità limitata.
Usa un client compatibile con SSE (ad es. EventSource nei browser o curl -N nel terminale).
Lo stream termina quando viene ricevuto un evento done o quando il server chiude la connessione.

3. Porre una domanda di follow-up

Fai una domanda di follow-up in una conversazione esistente. Restituisce una nuova stream_key per consumare lo stream della risposta.

Endpoint

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

Header della richiesta

Header	Obbligatorio	Descrizione
`Authorization`	Sì	`Bearer YOUR_API_KEY`
`Content-Type`	Sì	`application/json`

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`query`	string	Sì	Domanda di follow-up, da 1 a 2000 caratteri

Esempio

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

Risposta di successo (200)

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

Campi della risposta

Campo	Tipo	Descrizione
`stream_key`	string	Chiave usata per consumare lo stream SSE di questo follow-up
`thread_short_id`	string	Lo stesso ID conversazione della richiesta
`live_doc_short_id`	string	ID del LiveDoc associato

4. Consultare il dettaglio della conversazione

Endpoint

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

Esempio

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

Risposta di successo (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"
  }
}

Campi della risposta

Campo	Tipo	Descrizione
`thread_short_id`	string	ID della conversazione
`title`	string	Titolo della conversazione (derivato dalla query)
`created_at`	string	Timestamp di creazione (ISO 8601)
`updated_at`	string	Timestamp dell'ultimo aggiornamento (ISO 8601)
`live_doc_short_id`	string	ID del LiveDoc associato

Codici di errore

Codice	Stato HTTP	Descrizione
`UNAUTHORIZED`	401	La chiave API non è valida o è revocata
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Creazione della conversazione non riuscita (errore downstream)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Follow-up della conversazione non riuscito (errore downstream)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Consultazione del dettaglio della conversazione non riuscita (errore downstream)

Flusso di integrazione tipico

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

Per la gestione dei LiveDoc (CRUD, caricamento delle risorse, importazione di URL, recupero), vedi la LiveDoc API.