InfiniSynapse Server API Reference

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

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

1. 接入准备

基础信息

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

鉴权

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

Authorization: Bearer <你的 API Key>

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

语言

可选请求头 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）

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":"再按地区拆分"}'

2.3 其他对话辅助接口

3. 任务管理

控制器前缀：/api/ai_task。

3.1 任务查询

3.2 任务操作

删除任务

• POST /api/ai_task/deleteTaskWithId

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

取消任务

• POST /api/ai_task/cancelTask?taskId=task-001（taskId 作为 Query 参数）

重新运行 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 文件与知识库绑定

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

6. 文件上传

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

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

7. 文件存储与下载

控制器前缀：/api/storage。

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

8. 错误处理

9. 典型调用流程

1. 建立 SSE 连接：GET /api/ai/events?connId=<uuid>。
2. 准备资源：GET /api/ai_database/list、GET /api/ai_rag_sdk，按需 POST /api/ai_database/enabled、POST /api/ai_rag_sdk/enabled 启用。
3. 新建任务：POST /api/ai/message（type=newTask），从 SSE 接收实时回复。
4. 多轮追问：POST /api/ai/message（type=askResponse）。
5. 查看结果：GET /api/ai_task/getTaskWorkspace/:id 列出产物，POST /api/ai_task/previewFile 预览，GET /api/storage/downloadTaskFile/:taskId?path= 下载。