InfiniSynapse Server API Reference

本文是 InfiniSynapse 服务端（Server）面向外部用户/SDK 的 HTTP API 参考。通过一个 API Key（Bearer Token）即可直接调用，完成多轮 AI 任务对话、数据源管理、RAG 知识库管理、Skill 管理、文件上传与下载等操作，无需依赖前端界面。

仅需命令行集成的用户，可优先查阅《InfiniSynapse CLI API Reference》；本文面向需要直接发起 HTTP 请求的开发者。

1. 接入准备

基础信息

国内用户请使用 .cn 域名，海外用户请使用 .com 域名；私有化部署时替换为你自己的服务地址。下文示例统一以 .cn 域名书写，海外环境将其替换为 .com 即可。

鉴权

所有业务接口都需要在请求头携带 Bearer Token：

Authorization: Bearer <你的 API Key>

服务端从 Token 的 sub 声明中解析出用户身份（userId），所有资源（任务、数据源、知识库、文件）都按用户隔离。少数标注「公开只读」的接口无需鉴权。

获取 InfiniSynapse SaaS API Key

开发者可以在 InfiniSynapse SaaS 控制台生成或查看自己的 API Key：

1. 打开并登录 https://app.infinisynapse.cn/tasks。
2. 点击左下角「设置」齿轮图标，在弹出的菜单中选择 API Key Management。

3. 进入 API Key Management 页面后，点击 Create API Key 创建新的 Key；也可以在列表中查看已有 Key 的名称、状态、过期时间和创建时间。
4. 将获取到的 Key 作为 Bearer Token 放入请求头：Authorization: Bearer <你的 API Key>。

截图中的 Key 已做脱敏处理。请将 SaaS API Key 保存在服务端或安全的密钥管理系统中，不要写入前端代码、公开仓库或客户端配置；如果 Key 泄露，应在 API Key Management 中删除旧 Key 并重新创建。

将 /tasks 作为开发者后台

对开发者而言，https://app.infinisynapse.cn/tasks 也可以作为 SaaS API 调用的后台控制台：

• 自己开发的应用通过 Server API 发往 InfiniSynapse 后端的任务，都会出现在左侧 ALL TASKS 列表中，便于回看任务状态、消息记录、执行过程和任务工作区产物。
• 控制台右上角可查看账户额度并进行充值，也可以切换或配置计算资源。
• 默认的 public-engine 是公共计算资源；如果应用需要更稳定的配额、资源隔离或独占执行环境，可以点击右上角当前计算资源（如 public-engine）下拉菜单，选择 Create Exclusive Compute Resource 创建独占计算资源。创建完成后，可在同一菜单中切换到自己的独占资源。

语言

可选请求头 x-lang 控制服务端返回的提示文案语言，取值：zh_CN（默认）、en、ar、ja、ko、ru。

x-lang: zh_CN

统一响应结构

绝大多数接口返回统一信封：

{
  "code": 200,
  "message": "success",
  "data": { }
}

• code === 200 表示成功，业务数据在 data 中。
• code 为 1101 / 1105：Token 过期或失效，需更换 API Key。
• 参数校验失败返回 HTTP 422，message 为第一条校验错误信息。
• 文件下载类接口直接返回二进制流（application/octet-stream 或 application/zip），不走该信封。

分页约定

列表类接口（继承自通用分页参数）支持以下 Query 参数：

分页响应的 data 结构：

{
  "items": [ ],
  "meta": {
    "itemCount": 10,
    "totalItems": 42,
    "itemsPerPage": 10,
    "totalPages": 5,
    "currentPage": 1
  }
}

快速开始示例

curl -X GET "https://app.infinisynapse.cn/api/ai_database/list?page=1&pageSize=10&source=all" \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "x-lang: zh_CN"

2. AI 对话与任务执行

AI 对话采用「SSE 长连接 + 消息投递」的异步模式：先订阅事件流接收实时推送，再通过消息接口发送指令。

2.1 订阅事件流（SSE）

• GET /api/ai/events
• 建立 Server-Sent Events 长连接，服务端主动推送消息变更、状态就绪、通知等。

Query 参数

请求头：Authorization: Bearer <token> 必填，建议带 Accept: text/event-stream。

事件类型（每条格式为 event: <event>\ndata: <JSON>\n\n）

Agent 消息字段

mini-app 或 SDK 通常只需要消费 message.add / message.partial 中的 data.message：

curl -N "https://app.infinisynapse.cn/api/ai/events?connId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Accept: text/event-stream"

2.2 发送消息

• POST /api/ai/message
• 根据 body 的 type 分发到不同逻辑。回复实时推送到 SSE 通道，本接口本身仅返回执行结果。

常用 type 及字段

响应

• 成功通常为 { "success": true }；
• newTask、回滚、编辑首条等会附带 { success: true, state, forceReplace? }；
• 失败可能为 { success: false, error } 或 { success: false, notification: { type, title, message } }（如扣费校验失败）。

# 新建任务
curl -X POST "https://app.infinisynapse.cn/api/ai/message" \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{"type":"newTask","text":"分析最近一个月的销售趋势","connId":"550e8400-..."}'

# 多轮追问
curl -X POST "https://app.infinisynapse.cn/api/ai/message" \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{"type":"askResponse","taskId":"task-001","askResponse":"messageResponse","text":"再按地区拆分"}'

mini-app / Agent 集成建议流程

1. 客户端生成 connId；如需要并发安全或后续轮询稳定，也生成 taskId。
2. 先建立 GET /api/ai/events?connId=<uuid>，等待 state.ready 或短暂超时。
3. 调用 POST /api/ai/message，type=newTask，带上同一个 connId、任务 text、可选 taskId、images、autoApprovalSettings 和 chatSettings: { "mode": "act" }。
4. 从 SSE 的 message.partial / message.add 读取进度；notification.type=error 应视为任务失败。
5. 如果收到 message.type=ask 且 message.ask=upload_file_to_sandbox，先上传文件，再用 type=askResponse、askResponse=messageResponse、同一个 taskId 和 connId 把上传结果 JSON 发回。
6. 收到 message.ask=completion_result 或 message.say=completion_result 后，再用任务文件接口读取报告、图表、PDF、Word 等产物。

2.3 其他对话辅助接口

3. 任务管理

控制器前缀：/api/ai_task。

3.1 任务查询

3.2 任务操作

删除任务

• POST /api/ai_task/deleteTaskWithId

{ "ids": ["task-001", "task-002"] }

取消任务

• GET /api/ai_task/cancelTask?taskId=task-001 或 POST /api/ai_task/cancelTask?taskId=task-001

taskId 作为 Query 参数传入。部分服务端 mini-app 为了与自己的 DELETE 业务路由衔接，会向 InfiniSynapse 后端发起 POST；旧客户端也可能使用 POST /api/ai/message + type=cancelTask。

重新运行 SQL 任务

• POST /api/ai_task/rerunSqlTask

{ "id": "task-001", "chat_index": 0 }

运行提取的 SQL

• POST /api/ai_task/runExtractSql

{
  "variables": { "startDate": "2024-01-01", "endDate": "2024-12-31" },
  "register_tables": "orders,users",
  "databases": "main_db",
  "sqls": "SELECT * FROM orders WHERE created_at BETWEEN :startDate AND :endDate"
}

3.3 任务与 RAG

3.4 任务分类

3.5 任务文件

3.6 任务分享（公开只读，无需鉴权）

4. 数据源管理

控制器前缀：/api/ai_database。支持的数据库类型：mysql、postgres、sqlite、sqlserver、clickhouse、snowflake、doris、starrocks、gbase、kingbase、dm、supabase、deltalake、file（测试连接还支持 mongodb、elasticsearch）。

4.1 列表查询

• GET /api/ai_database/list

Query 参数：分页参数 + 以下可选项

4.2 增删改

add 请求体示例：

{
  "name": "production_db",
  "type": "mysql",
  "config": "{\"mysql_host\":\"127.0.0.1\",\"mysql_port\":3306,\"mysql_username\":\"root\",\"mysql_password\":\"***\",\"mysql_database\":\"sales\"}",
  "enabled": 1,
  "description": "生产环境数据库",
  "nickname": "销售数据源"
}

注意：数据库 name 不能以 remote_ 或 subscribe_ 开头。

4.3 连接测试与查询

4.4 文件与知识库绑定

4.5 数据源市场订阅

共享数据源的发现、订阅和详情查询属于账号/市场 API，国内基础地址为 https://api.infinisynapse.cn/api，海外基础地址为 https://api.infinisynapse.com/api。鉴权同样使用登录态或访问令牌形式的 Authorization: Bearer <token>。

自动化订阅时建议先查 my，再查 public；只对确认免费的市场条目自动调用 subscribe。订阅完成后，再回到 Server API 使用 GET /api/ai_database/list?source=all&subscribeSource=all&name=<name> 查找用户空间中的数据源，并用 POST /api/ai_database/enabled 启用。

5. RAG 知识库管理

控制器前缀：/api/ai_rag_sdk。

5.1 查询

5.2 增删改

create 请求体示例：

{
  "name": "sales_kb",
  "nickname": "销售知识库",
  "description": "销售相关文档",
  "ragDocFilterRelevance": "0.5",
  "requiredExts": [".pdf", ".docx", ".txt"],
  "docDir": "/path/to/docs",
  "enabled": 1,
  "database_ids": ["uuid-1", "uuid-2"]
}

5.3 数据库绑定

5.4 文件操作（支持 file / oss / s3）

fileTree 请求体示例（远程 OSS）：

{
  "file_system": "oss",
  "directory": "/docs",
  "endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
  "access_key_id": "***",
  "access_key_secret": "***",
  "filter": "both"
}

5.5 RAG 市场订阅

共享知识库的发现、订阅和详情查询也属于账号/市场 API，国内基础地址为 https://api.infinisynapse.cn/api，海外基础地址为 https://api.infinisynapse.com/api。鉴权同样使用登录态或访问令牌形式的 Authorization: Bearer <token>。

自动化订阅时建议先查 my，再查 public；只对确认免费的市场条目自动调用 subscribe。订阅完成后，再回到 Server API 使用 GET /api/ai_rag_sdk?source=all&subscribeSource=all&keyword=<name> 查找用户空间中的知识库，并用 POST /api/ai_rag_sdk/enabled 启用。

6. Skill 管理

Skill 可以通过两种方式进入 Agent 工作流：

• 安装到用户 Skill 库：使用 /api/ai_skill/* 管理用户级 Skill，安装后 active 状态的 Skill 会进入 Agent 可用 Skill 列表，Agent 可通过 use_skill 加载。
• 作为单次任务上下文上传：例如报告快写允许用户上传包含 SKILL.md 的目录或方法论文档；这些文件随当前任务进入 sandbox / 工作区，只影响本次报告任务，不会安装为用户级 Skill。

6.1 Skill 市场发现

Skill 市场发现属于账号/市场 API，国内基础地址为 https://api.infinisynapse.cn/api，海外基础地址为 https://api.infinisynapse.com/api。

6.2 已安装 Skill 管理

控制器前缀：/api/ai_skill。这些接口管理当前用户已安装的 Skill，需携带当前用户的 Bearer Token。

install 请求体示例：

{
  "skillId": "507f1f77bcf86cd799439011",
  "name": "market-research",
  "alias": "市场研究",
  "author": "InfiniSynapse",
  "version": "1.0.0",
  "intro": "市场调研与竞争分析流程",
  "tags": "[\"research\", \"report\"]"
}

6.3 本地 Skill 上传

本地上传适合团队自定义 Skill 或尚未发布到市场的 Skill。上传包必须是 zip，解压后的任意层级中必须包含 SKILL.md；服务端会自动定位 SKILL.md 所在目录，并把该目录内容安装到当前用户的 Skill 目录。上传同名本地 Skill 会覆盖原内容。

curl -X POST "https://app.infinisynapse.cn/api/ai_skill/upload" \
  -H "Authorization: Bearer <你的 Token>" \
  -F "name=report-methodology" \
  -F "alias=报告方法论" \
  -F "author=Data Team" \
  -F "status=active" \
  -F "version=1.0.0" \
  -F 'tags=["report","methodology"]' \
  -F "file=@./report-methodology.zip"

6.4 报告快写的 Skill 上下文模式

报告快写已经支持上传「Skills / 方法论上下文」：用户可以上传包含 SKILL.md 的目录，也可以上传单独的 Markdown、PDF、Word、表格或模板文档。这个模式不会调用 /api/ai_skill/upload 安装全局 Skill，而是把 Skill 目录树、文件路径和 SKILL.md 位置写入报告任务 prompt；当 Agent 需要读取文件时，通过 upload_file_to_sandbox 请求客户端/服务端上传对应文件，再继续写作。

自建报告类 mini-app 可以复用这个模式：

1. 前端收集 Skill 目录或文档，保留相对路径、文件名、大小、MIME、是否包含 SKILL.md 等元数据。
2. 创建任务前，把目录树放入业务层字段，例如 skillContext；把真实文件作为 multipart 文件队列上传到自己的服务端业务路由。
3. 服务端在 POST /api/ai/message 的 text 中写清 Skill 目录树和读取要求，提示 Agent 优先读取 SKILL.md 并遵循相关步骤。
4. SSE 中收到 message.ask=upload_file_to_sandbox 时，使用 POST /api/ai/upload?taskId= 或 POST /api/tools/taskUpload/:taskId 上传队列中的对应文件。
5. 上传后用 POST /api/ai/message，type=askResponse，把上传结果 JSON 回传给 Agent。

这种模式适合「一次报告任务临时带入方法论、规范、模板」；如果希望所有后续任务都能通过 use_skill 发现并加载同一 Skill，应使用 6.3 的本地 Skill 上传或 6.2 的市场安装。

7. 文件上传

上传相关接口注册在根路径下（即 /api/...）。除任务上传外，普通上传以「目录」组织。

curl -X POST "https://app.infinisynapse.cn/api/upload/my-folder" \
  -H "Authorization: Bearer <你的 API Key>" \
  -F "file=@./data.csv"

# 上传到任务沙箱，供 Agent 继续读取
curl -X POST "https://app.infinisynapse.cn/api/ai/upload?taskId=task-001" \
  -H "Authorization: Bearer <你的 API Key>" \
  -F "file=@./attachment.pdf"

# 上传到任务工作目录的指定子目录
curl -X POST "https://app.infinisynapse.cn/api/tools/taskUpload/task-001?subdir=upload_documents&naming=original" \
  -H "Authorization: Bearer <你的 API Key>" \
  -F "file=@./report-source.docx"

8. 文件存储与下载

普通文件存储控制器前缀为 /api/storage；任务工作区下载在当前 Server API 中使用 /api/tools/storage 前缀。

curl "https://app.infinisynapse.cn/api/tools/storage/downloadTaskFile/task-001?path=data%2Fresult.csv" \
  -H "Authorization: Bearer <你的 API Key>" \
  -o result.csv

9. 错误处理

10. 典型调用流程

1. 建立 SSE 连接：GET /api/ai/events?connId=<uuid>。
2. 准备资源：如需共享市场资源，先通过数据源市场 API 或 RAG 市场 API 订阅；随后用 GET /api/ai_database/list、GET /api/ai_rag_sdk 查找资源，并按需 POST /api/ai_database/enabled、POST /api/ai_rag_sdk/enabled 启用。
3. 准备 Skill：需要长期复用时，先通过 /api/ai_skill/install 或 /api/ai_skill/upload 安装并启用；只对单次任务生效时，可把包含 SKILL.md 的目录作为任务上下文上传。
4. 新建任务：POST /api/ai/message（type=newTask），从 SSE 接收实时回复。
5. 如 Agent 请求上传本地文件：POST /api/ai/upload?taskId= 或 POST /api/tools/taskUpload/:taskId，然后 POST /api/ai/message（type=askResponse）回传上传结果。
6. 多轮追问：POST /api/ai/message（type=askResponse）。
7. 取消任务：GET /api/ai_task/cancelTask?taskId= 或 POST /api/ai_task/cancelTask?taskId=。
8. 查看结果：GET /api/ai_task/getTaskWorkspace/:id 列出产物，POST /api/ai_task/previewFile 预览，GET /api/tools/storage/downloadTaskFile/:taskId?path= 下载。

11. 参考已落地 App 的 API 使用场景与组合

真实 mini-app 通常不要把 API Key 暴露到浏览器。推荐在自己的服务端实现一个业务路由，由服务端持有 API Key、组装 prompt、转发文件和读取任务产物；前端只和自己的业务路由通信。

11.1 通用 Agent 任务骨架

适用于高考助手、购物比价、报告快写等所有需要 Agent 长任务的应用。

1. 前端请求自己的服务端路由，服务端生成 connId，必要时也预生成 taskId 方便恢复和轮询。
2. 服务端先建立 GET /api/ai/events?connId=<uuid>，开始消费 SSE。
3. 服务端调用 POST /api/ai/message，type=newTask，带上同一个 connId、任务 text、可选 taskId、autoApprovalSettings 和 chatSettings: { "mode": "act" }。
4. 从 SSE 的 message.partial / message.add 推进状态；把 message.text 转成前端可展示的进度、结论或结构化结果。
5. 遇到 message.ask=upload_file_to_sandbox 时，先上传文件，再用 POST /api/ai/message（type=askResponse）把上传结果回传给 Agent。
6. 遇到 message.ask=completion_result 或 message.say=completion_result 后，按任务类型读取消息、工作区文件或下载产物。
7. 用户中止时调用 GET /api/ai_task/cancelTask?taskId= 或 POST /api/ai_task/cancelTask?taskId=，并在自己的业务数据库里标记任务状态。

11.2 高考助手：表单输入 + 可选文件 + PDF 结果

高考志愿/专业咨询类 App 的核心是「一次表单输入生成结构化报告」。这类应用通常不需要浏览器插件。

11.3 购物比价助手：Chrome 插件 + 实时 Agent + 消息结果

购物类 App 的关键是让 Agent 能看到用户正在浏览的商品页、搜索页或多个电商页面。这里通常先检查 Chrome 插件是否在线，再启动任务。

11.4 报告快写：批量资料上传 + 知识/数据资源 + 工作区产物

报告类 App 的核心不是只拿一段回答，而是让 Agent 在任务工作区里持续生成 Markdown、图表、PDF、Word 等文件。

11.5 组合原则

• 先连 SSE，再发任务：长任务最稳的顺序是先建立 /api/ai/events，再调用 /api/ai/message，避免错过早期状态。
• 服务端托管凭据和状态：API Key、taskId、文件路径、分享状态、业务用户 ID 都应保存在服务端，前端只拿业务结果。
• 区分两类上传：/api/ai/upload?taskId= 用于响应 Agent 的 sandbox 上传请求；/api/tools/taskUpload/:taskId 适合应用主动把资料归档到任务工作区。
• 区分两类 Skill：用户级 Skill 走 /api/ai_skill/* 安装、上传、启停；报告快写这类单次任务方法论上下文走任务文件上传链路，不会自动进入用户 Skill 库。
• 结果优先走工作区：只展示文本时可读 SSE 消息；需要下载、预览、版本化或导出时，应使用 getTaskWorkspace、previewFile 和 downloadTaskFile。
• 资源在任务前启用：数据库和知识库应在 newTask 前完成市场订阅、list/enabled，否则 Agent 可能看不到预期资源。
• 恢复能力要前置设计：mini-app 应保存 taskId、connId、用户输入、上传文件映射和最后状态，刷新页面后用 getUiMessageById 与 getTaskWorkspace 恢复。