REST API

AI Search REST API を使うと、HTTP 経由で AI Search インスタンスをクエリできます。

認証

すべてのリクエストには、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>

検索とチャット

AI Search は、インスタンスをクエリする 2 つの API を提供します。どちらも OpenAI 互換の messages 形式を使います。

Search は関連するコンテンツチャンクを返します。生成を自分で行う場合や、結果を直接表示する場合に使います。
Chat completions はコンテンツを取得し、1 回の呼び出しで応答を生成します。

API パス

Search と chat の API は namespace 単位です。

Path	Description
`/accounts/{account_id}/ai-search/namespaces/{namespace}/instances/{id}/`	namespace 内の特定インスタンスに対して操作します

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

Search

特定のインスタンスを検索します。search エンドポイントは query 文字列パラメーターも受け付けます。完全な仕様は Search API リファレンスを参照してください。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/default/instances/<INSTANCE_NAME>/search" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "content": "What is Cloudflare?",
        "role": "user"
      }
    ]
  }'

Chat completions

特定のインスタンスから応答を生成します。完全な仕様は Chat completions API リファレンスを参照してください。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/default/instances/<INSTANCE_NAME>/chat/completions" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "content": "What is Cloudflare?",
        "role": "user"
      }
    ]
  }'

Streaming

stream を true にすると、Server-Sent Events (SSE) として応答を受け取れます。取得したチャンクはまず chunks イベントとして送られ、その後にストリーミング応答が続きます。

event: chunks
data: [{"id":"chunk-001","type":"text","score":0.85,"text":"...","item":{"key":"about-cloudflare.md","timestamp":1775925540000},"scoring_details":{"vector_score":0.85}}]

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" document"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" you provided doesn"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"'t contain"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" information"}}]}

data: [DONE]

インスタンスをまたぐ検索とチャット

search と chat completions の API は namespace レベルでも使えます。インスタンスのエンドポイントと同じ動きですが、クエリ対象のインスタンスを指定するために instance_ids 配列を渡します。レスポンスの各チャンクには、どのインスタンスから来たかを示す instance_id フィールドが含まれます。完全な仕様は Namespace API リファレンスを参照してください。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>/search" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ],
    "ai_search_options": {
      "instance_ids": ["product-docs", "customer-abc123"]
    }
  }'