REST API

使用 AI Search REST API 在实例中上传、列出和管理单个文档。

认证

所有请求都需要具有 AI Search:Edit 和 AI Search:Run 权限的 API token。

在 Cloudflare 仪表板中，前往 My Profile（我的个人资料） > API Tokens（API 令牌）。
Go to API Tokens ↗
选择 Create Token（创建令牌）。
选择 Create Custom Token（创建自定义令牌）。
输入 Token name（令牌名称），例如 AI Search Manager。
在 Permissions（权限） 下，添加两项权限：
- Account > AI Search:Edit
- Account > AI Search:Run
选择 Continue to summary（继续查看摘要），然后选择 Create Token（创建令牌）。
复制并保存 token 值。这就是你的 API_TOKEN。

在所有请求的 Authorization header 中包含该 token：

Authorization: Bearer <API_TOKEN>

API 路径

AI Search API 可通过两个基础路径使用：

Path	Description
`/accounts/{account_id}/ai-search/instances/{id}/`	对特定实例进行操作
`/accounts/{account_id}/ai-search/namespaces/{namespace}/instances/{id}/`	对 namespace 内的实例进行操作

两个路径可用的操作相同。有关命名空间作用域 API，请参阅 Namespace API reference。

Items

在实例中上传、列出、获取、删除和下载项目。完整规范请参阅 Items API reference。

Operation	Method	Description
Upload	`POST`	上传文档以进行索引
List	`GET`	列出实例中的所有项目
Get	`GET`	按 ID 获取项目信息
Delete	`DELETE`	删除项目
Download	`GET`	下载原始文件

示例：上传文档

将文件上传到实例：

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/items" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -F "file=@/path/to/your/file.pdf"

示例：列出项目

列出实例中的所有项目：

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/items" \
  -H "Authorization: Bearer <API_TOKEN>"

要按确切的对象键查找单个项目，请传入 key 查询参数：

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/items?key=docs/readme.md" \
  -H "Authorization: Bearer <API_TOKEN>"

键在每个数据源内唯一，因此当同一键存在于多个源时，请将 key 与 source 结合使用（例如 source=builtin）以消除歧义。