SuperAgent API

The SuperAgent API provides AI-powered conversation capabilities with real-time streaming output and LiveDoc integration. The typical workflow is:

1. Create a conversation - get stream_key, thread_short_id, and live_doc_short_id
2. Consume the SSE stream - connect to the stream endpoint using stream_key
3. Follow up - ask follow-up questions in the same conversation, get a new stream_key
4. Query conversation detail - use thread_short_id to fetch conversation metadata
5. Manage LiveDocs - see LiveDoc API for full CRUD and resource management

Authentication

All requests require an API Key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

1. Create Conversation

Endpoint

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

Request Headers

Request Body

Example

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

Success Response (200)

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

Response Fields

2. Consume SSE Stream

After creating a conversation, connect to the stream endpoint using the stream_key to receive real-time output.

Endpoint

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

Query Parameters

Example

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

Reconnect with 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'

Response

The response is a standard Server-Sent Events (SSE) stream with Content-Type: text/event-stream.

Each event follows the SSE format:

event: <event_type>
data: <json_payload>

Example events:

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

event: done
data: {}

On upstream error:

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

Notes

• Connect immediately after creating the conversation - stream_key has a limited validity window.
• Use an SSE-capable client (e.g. EventSource in browsers, or curl -N in terminal).
• The stream ends when a done event is received or the connection is closed by the server.

3. Follow Up Conversation

Ask a follow-up question in an existing conversation. Returns a new stream_key to consume the response stream.

Endpoint

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

Request Headers

Request Body

Example

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

Success Response (200)

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

Response Fields

4. Query Conversation Detail

Endpoint

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

Example

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

Success Response (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"
  }
}

Response Fields

Error Codes

Typical Integration Flow

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

For LiveDoc management (CRUD, resource upload, URL import, retrieval), see the LiveDoc API.