設定 Harness

SuperAgent API

建立對話、消費 SSE 串流、繼續追問，並查詢對話中繼資料。

POST/v2/conversations

認證

Bearer API key

Content type

application/json and text/event-stream

限流說明

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

SuperAgent API 用於建立帶即時 SSE 輸出的 AI 對話，並自動關聯 LiveDoc。典型流程是建立 conversation、消費 stream、繼續追問、查詢 conversation detail，並用 LiveDoc 管理上下文資源。

認證

Authorization: Bearer YOUR_API_KEY

1. 建立對話

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

請求 Body

引數	型別	必填	說明
`query`	string	是	使用者問題，1-2000 字元
`live_doc_short_id`	string	否	複用現有 LiveDoc；不傳時會建立新的 LiveDoc
`selected_resource_ids`	array of strings	否	用於上下文的資源 ID
`skill_id`	string	否	本次對話使用的 Skill ID
`accept_language`	string	否	語言偏好，例如 `en`
`device_id`	string	否	裝置識別碼
`extra`	object	否	傳遞給 SuperAgent 的額外引數
`ext`	object	否	擴充引數，例如 `style_id` or `theme`

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

回應欄位

欄位	型別	說明
`stream_key`	string	Key used to consume the SSE stream
`thread_short_id`	string	Conversation ID for follow-up and detail query
`live_doc_short_id`	string	Associated LiveDoc ID

2. 消費 SSE 串流

建立 conversation 後立即連線 stream endpoint，使用 stream_key 接收即時輸出。

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

引數	型別	必填	說明
`offset`	integer	否	Resume streaming from this position after disconnect

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

The response uses standard SSE format with events such as message, done, and error. Connect soon after creating the conversation because stream_key has a limited validity window.

3. 繼續追問對話

追問現有 conversation。介面會返回新的 stream_key，用於繼續消費 SSE stream。

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

引數	型別	必填	說明
`query`	string	是	Follow-up question, 1-2000 characters

4. 查詢對話詳情

查詢 conversation metadata，包括標題、建立時間、更新時間和關聯的 LiveDoc ID。

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

回應欄位

欄位	型別	說明
`thread_short_id`	string	Conversation ID
`title`	string	Conversation title derived from the query
`created_at`	string	Creation timestamp, ISO 8601
`updated_at`	string	Last update timestamp, ISO 8601
`live_doc_short_id`	string	Associated LiveDoc ID

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 CRUD, resource upload, URL import, and retrieval, see the LiveDoc API.

錯誤碼

Code	HTTP Status	說明
`INVALID_API_KEY`	401	API Key is invalid or revoked
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	建立 conversation 失敗
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	追問失敗
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	查詢 conversation detail 失敗