REST API (5)

Last updated Oct 1, 2026 Use the AI Search REST API to query your AI Search instances over HTTP.

Authentication

All requests require an API token with AI Search:Edit and AI Search:Run permissions.

  1. In the Cloudflare dashboard, go to My Profile > API Tokens. Go to API Tokens ↗
  2. Select Create Token.
  3. Select Create Custom Token.
  4. Enter a Token name, for example AI Search Manager.
  5. Under Permissions, add two permissions:
  6. Account > AI Search:Edit
  7. Account > AI Search:Run
  8. Select Continue to summary, then select Create Token.
  9. Copy and save the token value. This is your API_TOKEN.

Include the token in the Authorization header for all requests:

Authorization: Bearer <API_TOKEN>

Search and chat

AI Search provides two APIs for querying an instance. Both use an OpenAI-compatible messages format.

  • Search returns relevant content chunks. Use this when you want to handle generation yourself or display results directly.
  • Chat completions retrieves content and generates a response in one call.

API paths

Search and chat APIs are scoped to a namespace:

Path Description
/accounts/{account_id}/ai-search/namespaces/{namespace}/instances/{id}/ Operates on a specific instance within a namespace

Every account has a default namespace. Use default unless you created a custom namespace. For the full specification, refer to the Namespace API reference.

Search a specific instance. The search endpoint also accepts a query string parameter. For the full specification, refer to the Search API reference.

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

Generate a response from a specific instance. For the full specification, refer to the Chat completions API reference.

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"
      }
    ]
  }'

Image queries

Set messages[].content to an array of content parts. Use an image_url part with an HTTPS URL or an inline data:image/<subtype>;base64,... URI.

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": [{
      "role": "user",
      "content": [{
        "type": "image_url",
        "image_url": { "url": "https://example.com/product.png" }
      }]
    }]
  }'

The response includes query_kind as image. Image-only responses omit search_query. Add a text part to create a multimodal query. Native image embedding requires @cf/qwen/qwen3-vl-embedding-2b or google-ai-studio/gemini-embedding-2. Text-only embedding models caption the image before embedding it.

Streaming

Set stream to true to receive responses as Server-Sent Events (SSE). The retrieved chunks are sent first as a chunks event, followed by the streamed response.

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]

Cross-instance search and chat

The search and chat completions APIs are also available at the namespace level. These work the same as the instance endpoints, but you pass an instance_ids array to specify which instances to query. Each chunk in the response includes an instance_id field identifying which instance it came from. For the full specification, refer to the Namespace API reference.

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"]
    }
  }'

Was this helpful?

YesNo

On this page

REST API (5) - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-search/api/search/rest-api/#page","headline":"REST API","description":"Query AI Search instances over HTTP using the REST API for search and chat completions.","url":"https://developers.cloudflare.com/ai-search/api/search/rest-api/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-search/api/search/rest-api/og.png?v=2130d71799ac2da7","dateModified":"2026-10-01","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Search and chat with AI Search instances from a Cloudflare Worker using the Workers binding. title: Workers binding image: https://developers.cloudflare.com/ai-search/api/search/workers-binding/og.png?v=fa78d292a041eecc

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/ai-search/llms.txt
Use this file to discover all available pages before exploring further.