REST API

AI Search REST API を使って、インスタンス内の個別ドキュメントをアップロード、一覧表示、管理します。

認証

すべてのリクエストには、AI Search:Edit と AI Search:Run の権限を持つ API トークンが必要です。

Cloudflare ダッシュボードで My Profile > API Tokens を開きます。
API Tokens を開く ↗
Create Token を選択します。
Create Custom Token を選択します。
Token name を入力します。例: AI Search Manager
Permissions で次の 2 つの権限を追加します。
- Account > AI Search:Edit
- Account > AI Search:Run
Continue to summary を選択し、続けて Create Token を選択します。
トークンの値をコピーして保存します。これが API_TOKEN です。

すべてのリクエストの Authorization ヘッダーにトークンを含めます。

Authorization: Bearer <API_TOKEN>

API パス

Item API は namespace にスコープされます。

パス	説明
`/accounts/{account_id}/ai-search/namespaces/{namespace}/instances/{id}/`	namespace 内のインスタンスに対して操作します

すべてのアカウントには default namespace があります。カスタム namespace を作成していない場合は default を使います。完全な仕様は Namespace API リファレンスを参照してください。

Items

インスタンス内のアイテムをアップロード、一覧表示、取得、削除、ダウンロードします。完全な仕様は Items API リファレンスを参照してください。

操作	メソッド	説明
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/namespaces/default/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/namespaces/default/instances/<INSTANCE_NAME>/items" \
  -H "Authorization: Bearer <API_TOKEN>"

正確なオブジェクトキーで 1 件のアイテムを探す場合は、key クエリパラメーターを渡します。

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

キーはデータソースごとに一意です。同じキーが複数のソースに存在する場合は、key と source（たとえば source=builtin）を組み合わせて区別します。