REST API

使用 AI Search REST API 通过 HTTP 管理实例与同步任务。

认证

所有请求都需要具有 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 内的实例进行操作

两个路径的可用操作相同。有关 namespace 范围 API，请参阅 Namespace API reference。

实例

创建、列出、获取、更新和删除 AI Search 实例。完整规范请参阅 Instances API reference。

Operation	Method	Description
Create	`POST`	创建新实例
List	`GET`	列出所有实例
Get	`GET`	按 ID 获取实例
Update	`PUT`	更新实例配置
Delete	`DELETE`	删除实例
Stats	`GET`	获取索引统计信息

示例：创建实例

在默认 namespace 中创建实例：

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-instance"
  }'

任务

触发并监控同步任务，以扫描数据源并索引新增或更新的内容。完整规范请参阅 Jobs API reference。

Operation	Method	Description
Create	`POST`	触发新的同步任务
List	`GET`	列出实例的所有任务
Get	`GET`	获取任务详情
Logs	`GET`	查看任务日志

示例：触发同步任务

为实例启动新的同步任务：

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