API 参考总览

本章面向集成开发者。如果你要把 combo agent 接入自己的系统，这里是起点。

子章节

HTTP API

RESTful 风格，流式（SSE）+ 非流式，Agent / Session / Completions / 文件 / 技能

Webhook 事件

外部事件入站（代码平台 / ALM / IM）+ 事件出站（平台主动推送）

CLI 命令行

管理员工具 · 批量导入 · 数据迁移 · 调试

基础 URL 与认证

基础 URL

SaaS：https://api.your-combo-saas.com/v1
私有化：http://<your-host>:9380/v1

认证方式

方式	使用场景	Header
API Key	服务端对服务端调用	`Authorization: Bearer ragflow-<key>`
JWT Session	Web 前端 / 管理台	`Authorization: Bearer <jwt>`
Webhook Signature	入站 Webhook 验签	`X-Combo-Signature: sha256=...`

API Key 在管理台「个人设置 → API Key」创建；Webhook Signature 在「集成对接 → Webhook」配置。

版本策略

稳定版：/v1/*，向后兼容
弃用策略：弃用接口至少提前 6 个月通过 Release Notes 通知，继续可用 6 个月后移除
废弃标识：响应 Header 会带 X-Deprecated: true + X-Deprecated-Sunset: <date>

响应格式

标准响应

{
  "code": 0,
  "data": { ... },
  "message": "ok"
}

`code`	含义
0	成功
1xxxx	客户端错误（参数、权限）
2xxxx	服务端错误（内部异常）
3xxxx	上游错误（LLM / 外部 API）

流式响应（SSE）

用于对话补全，按 text/event-stream 返回：

event: message
data: {"answer": "...", "reference": [...]}

event: done
data: {"session_id": "..."}

限流

默认限流（每 API Key）：

端点类型	限制
对话补全	60 次 / 分钟
文件上传	10 次 / 分钟
其他	300 次 / 分钟

超限返回 429 Too Many Requests，Retry-After 头指示可重试时间。

SDK 与代码生成

语言	状态
Python	✅ 官方（`combo_sdk`）
TypeScript / JavaScript	🚧 规划中
Go	按需
Java	按需

非官方 SDK 可通过 OpenAPI 规格自动生成，平台提供 OpenAPI JSON：

GET /v1/openapi.json

快速示例

Python

from combo_sdk import ComboAgent
 
client = ComboAgent(api_key="ragflow-...", base_url="https://...")
 
session = client.sessions.create(agent_id="...")
response = client.completions.create(
    session_id=session.id,
    question="帮我审查一下这个 PR",
    stream=False,
)
print(response.answer)

curl

curl -H "Authorization: Bearer ragflow-..." \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"question":"你好","session_id":"...","stream":false}' \
     https://api.your-combo-saas.com/v1/combo/agents/{agent_id}/completions

开发工具

Postman Collection：管理台 → API 参考 → 下载 Collection
OpenAPI 文档浏览器：/v1/docs（Swagger UI）