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

Use with AI Agents

Install the complete felo-ai package to give an Agent SuperAgent workflows and every other available Felo Skill. The installer dynamically discovers every package directory containing SKILL.md, including future package additions. Install all discovered Skills in Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills, or Hermes Agent ~/.hermes/skills. The manual AI Agent setup guide explains the safe installation process and per-platform configuration.

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.