Felo APIs

SuperAgent API

Tạo hội thoại, tiêu thụ luồng SSE, tiếp tục hội thoại và truy vấn siêu dữ liệu hội thoại.

POST/v2/conversations

Xác thực

Bearer API key

Loại nội dung

application/json and text/event-stream

Ghi chú về giới hạn

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

SuperAgent API cung cấp khả năng hội thoại do AI hỗ trợ với đầu ra truyền trực tiếp theo thời gian thực và tích hợp LiveDoc. Quy trình điển hình là:

Tạo một hội thoại - nhận stream_key, thread_short_id và live_doc_short_id
Tiêu thụ luồng SSE - kết nối đến endpoint luồng bằng stream_key
Hỏi tiếp - đặt câu hỏi tiếp theo trong cùng hội thoại, nhận stream_key mới
Truy vấn chi tiết hội thoại - dùng thread_short_id để lấy siêu dữ liệu hội thoại
Quản lý LiveDoc - xem LiveDoc API để biết đầy đủ CRUD và quản lý tài nguyên

Xác thực

Mọi yêu cầu đều cần khóa API trong header Authorization:

Authorization: Bearer YOUR_API_KEY

Dùng với AI Agent

Cài gói felo-ai đầy đủ để cung cấp cho một Agent các quy trình SuperAgent và mọi Felo Skill khác hiện có. Trình cài đặt tự động khám phá mọi thư mục gói có chứa SKILL.md, bao gồm các bổ sung gói trong tương lai. Hãy cài mọi Skill được phát hiện vào Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills hoặc Hermes Agent ~/.hermes/skills. Hướng dẫn thiết lập AI Agent thủ công giải thích quy trình cài đặt an toàn và cấu hình riêng cho từng nền tảng.

1. Tạo hội thoại

Endpoint

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

Header yêu cầu

Header	Bắt buộc	Mô tả
`Authorization`	Có	`Bearer YOUR_API_KEY`
`Content-Type`	Có	`application/json`

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`query`	string	Có	Truy vấn của người dùng, 1-2000 ký tự
`live_doc_short_id`	string	Không	Dùng lại một LiveDoc hiện có; bỏ qua để tạo mới
`selected_resource_ids`	array of strings	Không	Các ID tài nguyên cần đưa vào ngữ cảnh
`skill_id`	string	Không	ID Skill dùng cho hội thoại này
`accept_language`	string	Không	Tùy chọn ngôn ngữ, ví dụ `en`
`device_id`	string	Không	Định danh thiết bị
`extra`	object	Không	Các tham số bổ sung được chuyển tiếp đến SuperAgent
`ext`	object	Không	Các tham số mở rộng (ví dụ `style_id`, `theme`)

Ví dụ

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

Phản hồi thành công (200)

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

Các trường phản hồi

Trường	Kiểu	Mô tả
`stream_key`	string	Khóa dùng để tiêu thụ luồng SSE (xem phần 2)
`thread_short_id`	string	ID hội thoại, dùng để truy vấn chi tiết hội thoại
`live_doc_short_id`	string	ID LiveDoc liên kết

2. Tiêu thụ luồng SSE

Sau khi tạo hội thoại, hãy kết nối đến endpoint luồng bằng stream_key để nhận đầu ra theo thời gian thực.

Endpoint

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

Tham số truy vấn

Tham số	Kiểu	Bắt buộc	Mô tả
`offset`	integer	Không	Tiếp tục truyền từ vị trí này. Dùng để kết nối lại sau khi mất kết nối.

Ví dụ

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

Kết nối lại với 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'

Phản hồi

Phản hồi là một luồng Server-Sent Events (SSE) chuẩn với Content-Type: text/event-stream.

Mỗi sự kiện theo định dạng SSE:

event: <event_type>
data: <json_payload>

Ví dụ sự kiện:

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

event: done
data: {}

Khi lỗi thượng nguồn:

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

Ghi chú

Kết nối ngay sau khi tạo hội thoại - stream_key có cửa sổ hiệu lực giới hạn.
Dùng một máy khách hỗ trợ SSE (ví dụ EventSource trong trình duyệt, hoặc curl -N trong terminal).
Luồng kết thúc khi nhận sự kiện done hoặc khi máy chủ đóng kết nối.

3. Hỏi tiếp trong hội thoại

Đặt câu hỏi tiếp theo trong một hội thoại hiện có. Trả về stream_key mới để tiêu thụ luồng phản hồi.

Endpoint

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

Header yêu cầu

Header	Bắt buộc	Mô tả
`Authorization`	Có	`Bearer YOUR_API_KEY`
`Content-Type`	Có	`application/json`

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
`query`	string	Có	Câu hỏi tiếp theo, 1-2000 ký tự

Ví dụ

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

Phản hồi thành công (200)

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

Các trường phản hồi

Trường	Kiểu	Mô tả
`stream_key`	string	Khóa dùng để tiêu thụ luồng SSE cho lần hỏi tiếp này
`thread_short_id`	string	Cùng ID hội thoại như trong yêu cầu
`live_doc_short_id`	string	ID LiveDoc liên kết

4. Truy vấn chi tiết hội thoại

Endpoint

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

Ví dụ

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

Phản hồi thành công (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"
  }
}

Các trường phản hồi

Trường	Kiểu	Mô tả
`thread_short_id`	string	ID hội thoại
`title`	string	Tiêu đề hội thoại (suy ra từ truy vấn)
`created_at`	string	Dấu thời gian tạo (ISO 8601)
`updated_at`	string	Dấu thời gian cập nhật lần cuối (ISO 8601)
`live_doc_short_id`	string	ID LiveDoc liên kết

Mã lỗi

Mã	Trạng thái HTTP	Mô tả
`UNAUTHORIZED`	401	Khóa API không hợp lệ hoặc đã bị thu hồi
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Tạo hội thoại thất bại (lỗi hạ nguồn)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Hỏi tiếp trong hội thoại thất bại (lỗi hạ nguồn)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Truy vấn chi tiết hội thoại thất bại (lỗi hạ nguồn)

Luồng tích hợp điển hình

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

Để quản lý LiveDoc (CRUD, tải tài nguyên lên, nhập URL, truy xuất), xem LiveDoc API.