用 REST API 把问数接进业务系统

AskTable 的接口统一挂在部署实例的 /v1 下，适合应用开发团队把问数接进业务系统、门户、服务流程或自动化平台。最少只要一个接口就能跑通：POST /v1/integration/query，传数据源和问题，拿回自然语言回答。

开始前

一个 AskTable 部署实例，以及它的对外地址。
一个项目 API-Key。只提问用 asker 类型；要调管理类接口（建数据源、改权限、删智能体）用 admin 类型。
创建位置：左侧主导航 → 「设置」 → 「API-Key」 → 「创建 API-KEY」。完整值只在创建时显示一次。
至少一个状态可用的数据源，以及它的 ID（形如 ds_xxxxxxxx）。
文档入口：底部头像 → 「文档」 → 「REST API」，直接打开该实例的 Redoc。

操作步骤

确认接口根地址和文档地址

假设 AskTable 地址是 https://asktable.example.com：

用途	地址
API 根路径	`https://asktable.example.com/v1`
交互式文档（Redoc）	`https://asktable.example.com/v1/redoc`
Swagger UI	`https://asktable.example.com/v1/docs`
OpenAPI 描述文件	`https://asktable.example.com/openapi.json`

接口和字段以当前实例的 Redoc 为准，不同版本可能有增减。

带上认证头

所有业务接口都用同一个请求头：

Authorization: Bearer YOUR_API_KEY

asker 类型的 Key 只能走问数类接口（如 POST /v1/integration/query）；admin 类型才能调管理类接口。

发起一次提问

POST /v1/integration/query 是稳定的提问入口，成功返回 HTTP 201。datasource_ids 至少给一个，question 上限 4096 个字符：

curl -X POST 'https://asktable.example.com/v1/integration/query' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "datasource_ids": ["ds_xxxxxxxx"],
    "question": "你的数据问题"
  }'

需要按角色限制数据范围时，加上 role_id 和 role_variables：

{
  "datasource_ids": ["ds_xxxxxxxx"],
  "role_id": "role_xxxxxxxx",
  "role_variables": { "dept_id": "D001" },
  "question": "你的数据问题"
}

读返回体

{
  "conversation_id": "00000000-0000-0000-0000-000000000000",
  "answer": "自然语言回答，失败时为 null",
  "status": "success"
}

status 只有 success 和 failed 两个值。conversation_id 用于追溯这次调用，可以拿它到「所有对话」里打开同一条会话继续看。

按需扩展到其他资源接口

同一个 /v1 根下还有数据源、数据智能体、技能、角色、策略、对话、数据看板、画卷、模型组等资源接口。能调哪些由 Key 类型和项目权限决定，具体路径以 Redoc 为准。

上生产前收口

每个应用或环境用独立的项目 API-Key，不共用管理员 Key。
只在服务端调用，不要把 Key 放进浏览器、移动端或 iframe 页面。
给请求设超时和重试上限，区分认证失败、权限拒绝、参数错误、数据源未就绪和服务超时。
业务日志里记调用方、项目、时间、耗时、HTTP 状态和 conversation_id，不要记完整问题里的敏感数据。
role_id 和 role_variables 由服务端决定，不接受调用方直接传上来的任意值，避免被用来扩大数据范围。

关键约束

项目	值或默认	在哪里改
API 根路径	`/v1`	无界面开关
文档地址	`<你的站点>/v1/redoc`、`<你的站点>/v1/docs`	底部头像 → 「文档」 → 「REST API」
认证头	`Authorization: Bearer <API-Key>`	调用方
`POST /v1/integration/query` 所需权限	`priv_asker`（`asker` 类型 Key 即可）	「设置」 → 「API-Key」
`datasource_ids`	必填，至少一个	请求体
`question`	必填，最多 4096 个字符	请求体
`role_id`	选填，不传就不做权限过滤	请求体
成功状态码	201	无界面开关
`status` 取值	`success` 或 `failed`	响应体
项目 API-Key 数量	每个项目最多 10 个	「设置」 → 「API-Key」

出问题怎么判断

现象	判定条件	处理
返回 HTTP 401，`code` 是 `AUTH_ERROR`	Key 缺失、拼错或已删除	重新创建项目 API-Key；确认请求头格式是 `Authorization: Bearer YOUR_API_KEY`
返回 HTTP 403，`code` 是 `PERMISSION_DENIED`	用的是 `asker` Key 调了管理类接口，或项目角色不够	管理类调用换 `admin` Key；确认 Key 属于目标项目
返回 HTTP 404，`code` 是 `DATASOURCE_NOT_FOUND`	`datasource_ids` 里的 ID 在项目里不存在	到「数据源」页复制正确的 ID
返回 HTTP 400，`code` 是 `DATASOURCE_META_NOT_READY`	数据源元数据还没就绪，`message` 里带当前状态	等同步完成，或到「数据源」页手动触发同步
返回 HTTP 422，`code` 是 `VALIDATION_ERROR`	`message` 里逐条列出字段与原因	按字段改：`datasource_ids` 不能为空、`question` 不超 4096 字符
`status` 是 `failed`，`answer` 是 `null`	HTTP 状态正常但分析没跑完	用 `conversation_id` 到「所有对话」里打开这条会话看原因；多为数据源或模型问题
拿返回的 `conversation_id` 打不开对话	该 ID 属于别的项目，或会话已被删	确认 Key 与项目一致；`conversation_id` 不能跨项目使用
接口地址报 404	请求路径少了或多了 `/v1` 前缀	单次提问的正确路径是 `POST /v1/integration/query`

下一步

让 AI 客户端自己发现并调用这些能力：MCP
在终端或脚本里直接操作：命令行工具
在扣子里配成插件给机器人用：接入扣子 Coze

部署与运维

选择接入方式

飞书机器人

网页嵌入

开发与自动化

定时分析报告

用 REST API 把问数接进业务系统

开始前

操作步骤

关键约束

出问题怎么判断

下一步

​开始前

​操作步骤

​关键约束

​出问题怎么判断

​下一步

开始前

操作步骤

关键约束

出问题怎么判断

下一步