HTTP API

本指南面向开发者，详细说明如何通过API扩展ThinkDoc能力，构建定制化企业应用。ThinkDoc提供完整的RESTful API，支持知识库管理、文档解析、融合检索等核心功能。

获取 API 密钥

API 密钥是调用 ThinkDoc 服务的身份凭证，按以下步骤生成：

登录控制台 → 点击右上角 用户头像 → 选择 “账号设置”
进入 “API管理” 标签页 → 点击 “创建密钥”
填写信息：
- 名称：标识用途（如”Dify集成密钥”）
生成密钥：
- 系统返回 td-xxxxxx 格式密钥
🔒 安全建议：
- 定期轮换密钥（每90天）
- 禁止前端明文存储密钥
- 使用环境变量管理密钥

API 接口使用

ThinkDoc提供RESTful API，支持知识库管理、文档解析、融合检索等功能。 基础信息：

根地址：https://doc.bluedigit.ai/api
认证方式：Header中携带 Authorization: Bearer <API_Key>
响应格式：JSON
字符编码：UTF-8

核心接口示例

(1) 知识库管理


### 创建知识库
POST /api/kb
Content-Type: application/json
 
{
  "name": "金融政策库",
  "description": "存储央行报告和行业政策"
}
 
### 响应示例（201 Created）
{
  "_id": "kb_123456",  // 知识库唯一ID
  "name": "金融政策库",
  "description": "存储央行报告和行业政策",
  "created_at": "2025-04-10T12:00:00Z",
  "file_count": 0
}

(2) 文档上传与解析


### 上传文件至知识库
POST /api/kb/{kb_id}/files
Content-Type: multipart/form-data
 
-- 参数 --
file: <二进制文件>  
parse_type: deep  // 解析类型（deep或fast）
 
### 响应示例（202 Accepted）
{
  "_id": "file_7890",
  "filename": "央行报告2024.pdf",
  "parse_status": "ready",  // 解析状态（ready/waiting/parsing/embedding/success/fail）
  "path": "/uploads/kb_123456/央行报告2024.pdf"
}

(3) 融合检索


### 检索知识库内容
POST /api/retrieve
Content-Type: application/json
 
{
  "query": "氢能政策",
  "kb_ids": ["kb_123456"],
  "retrieval_setting": {
    "top_k": 10,
    "score_threshold": 0.5
  }
}
 
### 响应示例（200 OK）
{
  "records": [
    {
      "id_": "node_123",
      "text": "检索到的内容...",
      "md_text": "Markdown格式内容",
      "score": "0.95",
      "file_name": "央行报告2024.pdf",
      "kb_id": "kb_123456",
      "file_id": "file_7890",
      "metadata": {...}
    }
  ]
}

错误码对照表

ThinkDoc API 采用统一的错误响应格式，所有错误都返回以下结构：


{
  "code": 10001,                    // 5位数字错误码，便于分类和排序
  "message": "QUOTA_KB_EXCEEDED",   // 简洁的错误码字符串，用于国际化
  "detail": {                       // 详细的错误信息和调试数据
    "user_message": "Knowledge base count limit reached",
    "current_usage": {
      "kb_count": 1,
      "max_kbs": 1
    },
    "upgrade_suggestion": "Consider upgrading to Professional plan for more quota"
  }
}

错误码分类规则

错误码范围	分类	描述
10000-19999	配额相关	各种配额超限错误
20000-29999	认证授权	登录、权限、Token相关
30000-39999	参数验证	请求参数、格式、验证错误
40000-49999	资源操作	文件、知识库、用户等资源操作
50000-59999	系统服务	内部服务、外部依赖、系统错误

详细错误码对照表

配额相关错误 (10000-19999)

错误码	错误信息	HTTP状态码	用户提示信息	使用场景
10001	QUOTA_KB_EXCEEDED	429	知识库数量已达上限	创建知识库超出限制
10002	QUOTA_FILE_EXCEEDED	429	文件数量已达上限	上传文件超出限制
10003	QUOTA_STORAGE_EXCEEDED	429	存储空间已达上限	上传文件超出存储限制
10004	QUOTA_UPGRADE_REQUIRED	429	当前套餐配额不足，请升级	综合配额不足

认证授权错误 (20000-29999)

错误码	错误信息	HTTP状态码	用户提示信息	使用场景
20001	AUTH_REQUIRED	401	需要身份认证	未登录
20002	AUTH_TOKEN_INVALID	401	Token无效或已过期	Token无效或过期
20003	AUTH_TOKEN_MISSING	401	缺少身份认证Token	未提供Token
20004	PERMISSION_DENIED	403	权限不足	权限不足
20005	ADMIN_REQUIRED	403	需要管理员权限	非管理员操作
20006	INVALID_API_KEY	401	API密钥无效	API密钥错误

参数验证错误 (30000-39999)

错误码	错误信息	HTTP状态码	用户提示信息	使用场景
30001	PARAM_INVALID	400	参数格式无效	参数验证失败
30002	PARAM_MISSING	400	缺少必需参数	缺少必需参数
30003	PARAM_TOO_LONG	400	参数长度超出限制	参数过长
30004	PARAM_FORMAT_ERROR	400	参数格式错误	格式错误
30005	BAD_REQUEST	400	请求错误	通用请求错误

资源操作错误 (40000-49999)

错误码	错误信息	HTTP状态码	用户提示信息	使用场景
40001	NOT_FOUND	404	资源不存在	资源不存在
40002	ALREADY_EXISTS	409	资源已存在	重复创建
40003	IN_USE	409	资源正在使用中	资源被占用
40004	FILE_TOO_LARGE	413	文件大小超出限制	文件过大
40005	UNSUPPORTED_TYPE	415	不支持的文件类型	文件类型不支持
40006	KB_NOT_FOUND	404	知识库不存在	知识库不存在
40007	FILE_NOT_FOUND	404	文件不存在	文件不存在
40008	USER_NOT_FOUND	404	用户不存在	用户不存在
40009	MARKDOWN_NOT_FOUND	404	Markdown文件不存在	Markdown文件不存在

系统服务错误 (50000-59999)

错误码	错误信息	HTTP状态码	用户提示信息	使用场景
50001	SERVER_ERROR	500	服务器内部错误	未知异常
50002	SERVICE_UNAVAILABLE	503	服务暂时不可用	服务维护或过载
50003	DATABASE_ERROR	500	数据库操作失败	数据库异常
50004	EXTERNAL_API_ERROR	502	外部服务调用失败	第三方服务异常
50005	TASK_QUEUE_ERROR	503	任务队列服务不可用	任务队列异常

错误处理建议

前端错误处理策略

10000-19999: 显示配额信息，引导升级
20000-29999: 跳转登录页面或显示权限提示
30000-39999: 高亮错误字段，提示用户修正
40000-49999: 显示具体资源操作错误
50000-59999: 显示通用错误页面

国际化支持

使用 message 字段作为国际化键值
detail.user_message 提供默认英文提示
前端根据语言环境选择对应错误消息

错误响应示例

配额超限错误示例


{
  "code": 10001,
  "message": "QUOTA_KB_EXCEEDED",
  "detail": {
    "user_message": "Knowledge base count limit reached",
    "current_usage": {
      "kb_count": 1,
      "max_kbs": 1,
      "level": "standard"
    },
    "upgrade_suggestion": "Consider upgrading to Professional plan for more quota",
    "upgrade_url": "/account/upgrade"
  }
}

参数错误示例


{
  "code": 30001,
  "message": "PARAM_INVALID",
  "detail": {
    "user_message": "Invalid parameter format",
    "invalid_fields": ["email"],
    "field_errors": {
      "email": "Invalid email format"
    }
  }
}

📘 完整 API 文档：
🔗 https://doc.bluedigit.ai/api/redoc