Skip to content
Start here

Multi-Instance Chat Completions

client.aiSearch.namespaces.chatCompletions(stringname, NamespaceChatCompletionsParams { account_id, ai_search_options, messages, 2 more } params, RequestOptionsoptions?): NamespaceChatCompletionsResponse { choices, chunks, id, 3 more }
POST/accounts/{account_id}/ai-search/namespaces/{name}/chat/completions

Performs a chat completion request against multiple AI Search instances in parallel, merging retrieved content as context for generating a response.

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
name: string
params: NamespaceChatCompletionsParams { account_id, ai_search_options, messages, 2 more }
account_id: string

Path param

ai_search_options: AISearchOptions

Body param

instance_ids: Array<string>
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
custom_metadata?: Record<string, string | number | boolean>

Metadata added to AI Gateway logs for requests triggered by this operation. Accepts up to 2 string, number, or boolean entries. Keys ‘ai-search’, ‘task’, ‘origin’, and keys beginning with ‘cf.’ are reserved.

One of the following:
string
number
boolean
query_rewrite?: QueryRewrite { enabled, model, rewrite_prompt }
enabled?: boolean
model?: string

A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.

rewrite_prompt?: string
reranking?: Reranking { enabled, match_threshold, model }
enabled?: boolean
match_threshold?: number
maximum1
minimum0
model?: string
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 all four directions (asc, desc, exists, not_exists); text/boolean fields only 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. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to ‘and’.

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
messages: Array<Message>

Body param

content: string | Array<UnionMember0 { text, type } | UnionMember1 { image_url, type } | UnionMember2 { file, type } > | string | null
One of the following:
string
Array<UnionMember0 { text, type } | UnionMember1 { image_url, type } | UnionMember2 { file, type } >
UnionMember0 { text, type }
text: string
minLength1
type: "text"
UnionMember1 { image_url, type }
image_url: ImageURL { url }
url: string
maxLength20971520
minLength1
type: "image_url"
UnionMember2 { file, type }
file: File { filename, file_data, file_id }
filename: string
maxLength255
minLength1
file_data?: string
maxLength13981144
minLength1
file_id?: string
type: "file"
string | null
role: "system" | "developer" | "user" | 2 more
One of the following:
"system"
"developer"
"user"
"assistant"
"tool"
model?: string

Body param: A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.

stream?: boolean

Body param

ReturnsExpand Collapse
NamespaceChatCompletionsResponse { choices, chunks, id, 3 more }
choices: Array<Choice>
message: Message { content, role }
content: string | Array<UnionMember0 { text, type } | UnionMember1 { image_url, type } | UnionMember2 { file, type } > | string | null
One of the following:
string
Array<UnionMember0 { text, type } | UnionMember1 { image_url, type } | UnionMember2 { file, type } >
UnionMember0 { text, type }
text: string
minLength1
type: "text"
UnionMember1 { image_url, type }
image_url: ImageURL { url }
url: string
maxLength20971520
minLength1
type: "image_url"
UnionMember2 { file, type }
file: File { filename, file_data, file_id }
filename: string
maxLength255
minLength1
file_data?: string
maxLength13981144
minLength1
file_id?: string
type: "file"
string | null
role: "system" | "developer" | "user" | 2 more
One of the following:
"system"
"developer"
"user"
"assistant"
"tool"
index?: number
chunks: Array<Chunk>
id: string
instance_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
errors?: Array<Error>
instance_id: string
message: string
model?: string
object?: string

Multi-Instance 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.namespaces.chatCompletions('my-namespace', {
  account_id: 'c3dc5f0b34a14ff8e1b3ec04895e1b22',
  ai_search_options: { instance_ids: ['my-ai-search'] },
  messages: [{ content: 'string', role: 'system' }],
});

console.log(response.id);
{
  "choices": [
    {
      "message": {
        "content": "string",
        "role": "system"
      },
      "index": 0
    }
  ],
  "chunks": [
    {
      "id": "id",
      "instance_id": "instance_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",
  "errors": [
    {
      "instance_id": "instance_id",
      "message": "message"
    }
  ],
  "model": "model",
  "object": "object"
}
Returns Examples
{
  "choices": [
    {
      "message": {
        "content": "string",
        "role": "system"
      },
      "index": 0
    }
  ],
  "chunks": [
    {
      "id": "id",
      "instance_id": "instance_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",
  "errors": [
    {
      "instance_id": "instance_id",
      "message": "message"
    }
  ],
  "model": "model",
  "object": "object"
}