Chat Completions

POST/accounts/{account_id}/ai-search/namespaces/{namespace}/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

Path ParametersExpand Collapse

account_id: string

namespace: string

id: string

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

maxLength64

minLength1

Body ParametersJSONExpand Collapse

messages: array of object { content, role }

content: string or array of object { text, type } or object { image_url, type } or object { file, type } or string

One of the following:

string

array of object { text, type } or object { image_url, type } or object { file, type }

One of the following:

object { text, type }

text: string

minLength1

type: "text"

object { image_url, type }

image_url: object { url }

url: string

maxLength20971520

minLength1

type: "image_url"

object { file, type }

file: object { filename, file_data, file_id }

filename: string

maxLength255

minLength1

file_data: optional string
maxLength13981144
minLength1

file_id: optional string

type: "file"

string

role: "system" or "developer" or "user" or 2 more

One of the following:

"system"

"developer"

"user"

"assistant"

"tool"

ai_search_options: optional object { cache, custom_metadata, query_rewrite, 2 more }

cache: optional object { cache_threshold, enabled }

cache_threshold: optional "super_strict_match" or "close_enough" or "flexible_friend" or "anything_goes"

One of the following:

"super_strict_match"

"close_enough"

"flexible_friend"

"anything_goes"

enabled: optional boolean

custom_metadata: optional map[string or number or boolean]

Metadata added to AI Gateway logs for requests this operation triggers. Accepts up to 2 string, number, or boolean entries. Reserved keys: ‘ai-search’, ‘task’, ‘origin’, and any key beginning with ‘cf.’.

One of the following:

string

number

boolean

query_rewrite: optional object { enabled, model, rewrite_prompt }

enabled: optional boolean

model: optional 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: optional string

reranking: optional object { enabled, match_threshold, model }

enabled: optional boolean

match_threshold: optional number

maximum1

minimum0

model: optional string

retrieval: optional object { boost_by, context_expansion, filters, 6 more }

boost_by: optional array of object { field, direction }

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: optional "asc" or "desc" or "exists" or "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: optional number

maximum3

minimum0

filters: optional map[unknown]

fusion_method: optional "max" or "rrf"

One of the following:

"max"

"rrf"

keyword_match_mode: optional "and" or "or"

Controls which documents become candidates for BM25 scoring. ‘and’ restricts candidates to documents containing all query terms; ‘or’ includes any document containing at least one term and ranks results according to 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: optional number

Minimum similarity score a chunk must reach to be returned. When omitted, falls back to the instance-level score_threshold, then to 0.4.

maximum1

minimum0

max_num_results: optional number

Maximum number of results to return. When omitted, falls back to the instance-level max_num_results, then to 10.

maximum50

minimum1

retrieval_type: optional "vector" or "keyword" or "hybrid"

One of the following:

"vector"

"keyword"

"hybrid"

return_on_failure: optional boolean

model: optional 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.

stream: optional boolean

ReturnsExpand Collapse

choices: array of object { message, index }

message: object { content, role }

content: string or array of object { text, type } or object { image_url, type } or object { file, type } or string

One of the following:

string

array of object { text, type } or object { image_url, type } or object { file, type }

One of the following:

object { text, type }

text: string

minLength1

type: "text"

object { image_url, type }

image_url: object { url }

url: string

maxLength20971520

minLength1

type: "image_url"

object { file, type }

file: object { filename, file_data, file_id }

filename: string

maxLength255

minLength1

file_data: optional string
maxLength13981144
minLength1

file_id: optional string

type: "file"

string

role: "system" or "developer" or "user" or 2 more

One of the following:

"system"

"developer"

"user"

"assistant"

"tool"

index: optional number

chunks: array of object { id, score, text, 6 more }

id: string

score: number

maximum1

minimum0

text: string

type: string

item: optional object { key, metadata, timestamp }

key: string

metadata: optional map[unknown]

timestamp: optional number

media_end_ms: optional number

Audio/video transcript chunks only: end, in milliseconds from the start of the media (whole seconds), of the last transcript section the matched chunk covers. Describes the matched chunk before any context expansion, not the expanded text.

minimum0

media_start_ms: optional number

Audio/video transcript chunks only: start, in milliseconds from the start of the media (whole seconds), of the transcript section the matched chunk begins in. Describes the matched chunk before any context expansion, not the expanded text.

minimum0

scoring_details: optional object { fusion_method, keyword_rank, keyword_score, 3 more }

fusion_method: optional "rrf" or "max"

One of the following:

"rrf"

"max"

keyword_rank: optional number

keyword_score: optional number

minimum0

reranking_score: optional number

maximum1

minimum0

vector_rank: optional number

vector_score: optional number

maximum1

minimum0

source_media_type: optional "audio" or "video"

Audio/video transcript chunks only: type of the source media file. Omitted for all other chunks.

One of the following:

"audio"

"video"

id: optional string

model: optional string

object: optional string

Chat Completions

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAMESPACE/instances/$ID/chat/completions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "messages": [
            {
              "content": "string",
              "role": "system"
            }
          ]
        }'

{
  "choices": [
    {
      "message": {
        "content": "string",
        "role": "system"
      },
      "index": 0
    }
  ],
  "chunks": [
    {
      "id": "id",
      "score": 0,
      "text": "text",
      "type": "type",
      "item": {
        "key": "key",
        "metadata": {
          "foo": "bar"
        },
        "timestamp": 0
      },
      "media_end_ms": 0,
      "media_start_ms": 0,
      "scoring_details": {
        "fusion_method": "rrf",
        "keyword_rank": 0,
        "keyword_score": 0,
        "reranking_score": 0,
        "vector_rank": 0,
        "vector_score": 0
      },
      "source_media_type": "audio"
    }
  ],
  "id": "id",
  "model": "model",
  "object": "object"
}

Returns Examples

{
  "choices": [
    {
      "message": {
        "content": "string",
        "role": "system"
      },
      "index": 0
    }
  ],
  "chunks": [
    {
      "id": "id",
      "score": 0,
      "text": "text",
      "type": "type",
      "item": {
        "key": "key",
        "metadata": {
          "foo": "bar"
        },
        "timestamp": 0
      },
      "media_end_ms": 0,
      "media_start_ms": 0,
      "scoring_details": {
        "fusion_method": "rrf",
        "keyword_rank": 0,
        "keyword_score": 0,
        "reranking_score": 0,
        "vector_rank": 0,
        "vector_score": 0
      },
      "source_media_type": "audio"
    }
  ],
  "id": "id",
  "model": "model",
  "object": "object"
}