Skip to content
Start here

Chat Completions

client.aiSearch.instances.chatCompletions(stringid, InstanceChatCompletionsParams { account_id, messages, ai_search_options, 2 more } params, RequestOptionsoptions?): InstanceChatCompletionsResponse { choices, chunks, id, 2 more }
POST/accounts/{account_id}/ai-search/instances/{id}/chat/completions

Performs a chat completion request against an AI Search instance, using indexed content as context for generating responses.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
ParametersExpand Collapse
id: string

AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.

maxLength64
minLength1
params: InstanceChatCompletionsParams { account_id, messages, ai_search_options, 2 more }
account_id: string

Path param

messages: Array<Message>

Body param

content: string | null
role: "system" | "developer" | "user" | 2 more
One of the following:
"system"
"developer"
"user"
"assistant"
"tool"
ai_search_options?: AISearchOptions

Body param

cache?: Cache { cache_threshold, enabled }
cache_threshold?: "super_strict_match" | "close_enough" | "flexible_friend" | "anything_goes"
One of the following:
"super_strict_match"
"close_enough"
"flexible_friend"
"anything_goes"
enabled?: boolean
query_rewrite?: QueryRewrite { enabled, model, rewrite_prompt }
enabled?: boolean
model?: "@cf/meta/llama-3.3-70b-instruct-fp8-fast" | "@cf/zai-org/glm-4.7-flash" | "@cf/meta/llama-3.1-8b-instruct-fast" | 25 more
One of the following:
"@cf/meta/llama-3.3-70b-instruct-fp8-fast"
"@cf/zai-org/glm-4.7-flash"
"@cf/meta/llama-3.1-8b-instruct-fast"
"@cf/meta/llama-3.1-8b-instruct-fp8"
"@cf/meta/llama-4-scout-17b-16e-instruct"
"@cf/qwen/qwen3-30b-a3b-fp8"
"@cf/deepseek-ai/deepseek-r1-distill-qwen-32b"
"@cf/moonshotai/kimi-k2-instruct"
"@cf/google/gemma-3-12b-it"
"anthropic/claude-3-7-sonnet"
"anthropic/claude-sonnet-4"
"anthropic/claude-opus-4"
"anthropic/claude-3-5-haiku"
"cerebras/qwen-3-235b-a22b-instruct"
"cerebras/qwen-3-235b-a22b-thinking"
"cerebras/llama-3.3-70b"
"cerebras/llama-4-maverick-17b-128e-instruct"
"cerebras/llama-4-scout-17b-16e-instruct"
"cerebras/gpt-oss-120b"
"google-ai-studio/gemini-2.5-flash"
"google-ai-studio/gemini-2.5-pro"
"grok/grok-4"
"groq/llama-3.3-70b-versatile"
"groq/llama-3.1-8b-instant"
"openai/gpt-5"
"openai/gpt-5-mini"
"openai/gpt-5-nano"
""
rewrite_prompt?: string
reranking?: Reranking { enabled, match_threshold, model }
enabled?: boolean
match_threshold?: number
maximum1
minimum0
model?: "@cf/baai/bge-reranker-base" | ""
One of the following:
"@cf/baai/bge-reranker-base"
""
retrieval?: Retrieval { boost_by, context_expansion, filters, 6 more }
boost_by?: Array<BoostBy>

Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.

field: string

Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support asc/desc directions; text/boolean fields support exists/not_exists.

maxLength64
minLength1
direction?: "asc" | "desc" | "exists" | "not_exists"

Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional ��� defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.

One of the following:
"asc"
"desc"
"exists"
"not_exists"
context_expansion?: number
maximum3
minimum0
filters?: Record<string, unknown>
fusion_method?: "max" | "rrf"
One of the following:
"max"
"rrf"
keyword_match_mode?: "and" | "or"

Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. Defaults to 'and'. Legacy values 'exact_match' and 'fuzzy_match' are accepted and map to 'and' and 'or' respectively.

One of the following:
"and"
"or"
match_threshold?: number
maximum1
minimum0
max_num_results?: number
maximum50
minimum1
retrieval_type?: "vector" | "keyword" | "hybrid"
One of the following:
"vector"
"keyword"
"hybrid"
return_on_failure?: boolean
model?: "@cf/meta/llama-3.3-70b-instruct-fp8-fast" | "@cf/zai-org/glm-4.7-flash" | "@cf/meta/llama-3.1-8b-instruct-fast" | 25 more

Body param

One of the following:
"@cf/meta/llama-3.3-70b-instruct-fp8-fast"
"@cf/zai-org/glm-4.7-flash"
"@cf/meta/llama-3.1-8b-instruct-fast"
"@cf/meta/llama-3.1-8b-instruct-fp8"
"@cf/meta/llama-4-scout-17b-16e-instruct"
"@cf/qwen/qwen3-30b-a3b-fp8"
"@cf/deepseek-ai/deepseek-r1-distill-qwen-32b"
"@cf/moonshotai/kimi-k2-instruct"
"@cf/google/gemma-3-12b-it"
"anthropic/claude-3-7-sonnet"
"anthropic/claude-sonnet-4"
"anthropic/claude-opus-4"
"anthropic/claude-3-5-haiku"
"cerebras/qwen-3-235b-a22b-instruct"
"cerebras/qwen-3-235b-a22b-thinking"
"cerebras/llama-3.3-70b"
"cerebras/llama-4-maverick-17b-128e-instruct"
"cerebras/llama-4-scout-17b-16e-instruct"
"cerebras/gpt-oss-120b"
"google-ai-studio/gemini-2.5-flash"
"google-ai-studio/gemini-2.5-pro"
"grok/grok-4"
"groq/llama-3.3-70b-versatile"
"groq/llama-3.1-8b-instant"
"openai/gpt-5"
"openai/gpt-5-mini"
"openai/gpt-5-nano"
""
stream?: boolean

Body param

ReturnsExpand Collapse
InstanceChatCompletionsResponse { choices, chunks, id, 2 more }
choices: Array<Choice>
message: Message { content, role }
content: string | null
role: "system" | "developer" | "user" | 2 more
One of the following:
"system"
"developer"
"user"
"assistant"
"tool"
index?: number
chunks: Array<Chunk>
id: string
score: number
maximum1
minimum0
text: string
type: string
item?: Item { key, metadata, timestamp }
key: string
metadata?: Record<string, unknown>
timestamp?: number
scoring_details?: ScoringDetails { fusion_method, keyword_rank, keyword_score, 3 more }
fusion_method?: "rrf" | "max"
One of the following:
"rrf"
"max"
keyword_rank?: number
keyword_score?: number
minimum0
reranking_score?: number
maximum1
minimum0
vector_rank?: number
vector_score?: number
maximum1
minimum0
id?: string
model?: string
object?: string

Chat Completions

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const response = await client.aiSearch.instances.chatCompletions('my-ai-search', {
  account_id: 'c3dc5f0b34a14ff8e1b3ec04895e1b22',
  messages: [{ content: 'content', role: 'system' }],
});

console.log(response.id);
{
  "choices": [
    {
      "message": {
        "content": "content",
        "role": "system"
      },
      "index": 0
    }
  ],
  "chunks": [
    {
      "id": "id",
      "score": 0,
      "text": "text",
      "type": "type",
      "item": {
        "key": "key",
        "metadata": {
          "foo": "bar"
        },
        "timestamp": 0
      },
      "scoring_details": {
        "fusion_method": "rrf",
        "keyword_rank": 0,
        "keyword_score": 0,
        "reranking_score": 0,
        "vector_rank": 0,
        "vector_score": 0
      }
    }
  ],
  "id": "id",
  "model": "model",
  "object": "object"
}
Returns Examples
{
  "choices": [
    {
      "message": {
        "content": "content",
        "role": "system"
      },
      "index": 0
    }
  ],
  "chunks": [
    {
      "id": "id",
      "score": 0,
      "text": "text",
      "type": "type",
      "item": {
        "key": "key",
        "metadata": {
          "foo": "bar"
        },
        "timestamp": 0
      },
      "scoring_details": {
        "fusion_method": "rrf",
        "keyword_rank": 0,
        "keyword_score": 0,
        "reranking_score": 0,
        "vector_rank": 0,
        "vector_score": 0
      }
    }
  ],
  "id": "id",
  "model": "model",
  "object": "object"
}