Multi-Instance Chat Completions

client.AISearch.Namespaces.ChatCompletions(ctx, name, params) (*NamespaceChatCompletionsResponse, error)

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

AccountID param.Field[string]

Path param

AISearchOptions param.Field[NamespaceChatCompletionsParamsAISearchOptions]

Body param

InstanceIDs []string

Cache NamespaceChatCompletionsParamsAISearchOptionsCacheOptional

CacheThreshold NamespaceChatCompletionsParamsAISearchOptionsCacheCacheThresholdOptional

One of the following:

const NamespaceChatCompletionsParamsAISearchOptionsCacheCacheThresholdSuperStrictMatch NamespaceChatCompletionsParamsAISearchOptionsCacheCacheThreshold = "super_strict_match"

const NamespaceChatCompletionsParamsAISearchOptionsCacheCacheThresholdCloseEnough NamespaceChatCompletionsParamsAISearchOptionsCacheCacheThreshold = "close_enough"

const NamespaceChatCompletionsParamsAISearchOptionsCacheCacheThresholdFlexibleFriend NamespaceChatCompletionsParamsAISearchOptionsCacheCacheThreshold = "flexible_friend"

const NamespaceChatCompletionsParamsAISearchOptionsCacheCacheThresholdAnythingGoes NamespaceChatCompletionsParamsAISearchOptionsCacheCacheThreshold = "anything_goes"

Enabled boolOptional

CustomMetadata map[string, NamespaceChatCompletionsParamsAISearchOptionsCustomMetadataUnion]Optional

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:

UnionString

UnionFloat

UnionBool

QueryRewrite NamespaceChatCompletionsParamsAISearchOptionsQueryRewriteOptional

Enabled boolOptional

Model stringOptional

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.

RewritePrompt stringOptional

Reranking NamespaceChatCompletionsParamsAISearchOptionsRerankingOptional

Enabled boolOptional

MatchThreshold float64Optional

maximum1

minimum0

Model stringOptional

Retrieval NamespaceChatCompletionsParamsAISearchOptionsRetrievalOptional

BoostBy []NamespaceChatCompletionsParamsAISearchOptionsRetrievalBoostByOptional

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 NamespaceChatCompletionsParamsAISearchOptionsRetrievalBoostByDirectionOptional

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:

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalBoostByDirectionAsc NamespaceChatCompletionsParamsAISearchOptionsRetrievalBoostByDirection = "asc"

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalBoostByDirectionDesc NamespaceChatCompletionsParamsAISearchOptionsRetrievalBoostByDirection = "desc"

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalBoostByDirectionExists NamespaceChatCompletionsParamsAISearchOptionsRetrievalBoostByDirection = "exists"

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalBoostByDirectionNotExists NamespaceChatCompletionsParamsAISearchOptionsRetrievalBoostByDirection = "not_exists"

ContextExpansion int64Optional

maximum3

minimum0

Filters map[string, unknown]Optional

FusionMethod NamespaceChatCompletionsParamsAISearchOptionsRetrievalFusionMethodOptional

One of the following:

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalFusionMethodMax NamespaceChatCompletionsParamsAISearchOptionsRetrievalFusionMethod = "max"

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalFusionMethodRrf NamespaceChatCompletionsParamsAISearchOptionsRetrievalFusionMethod = "rrf"

KeywordMatchMode NamespaceChatCompletionsParamsAISearchOptionsRetrievalKeywordMatchModeOptional

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:

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalKeywordMatchModeAnd NamespaceChatCompletionsParamsAISearchOptionsRetrievalKeywordMatchMode = "and"

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalKeywordMatchModeOr NamespaceChatCompletionsParamsAISearchOptionsRetrievalKeywordMatchMode = "or"

MatchThreshold float64Optional

Minimum score a chunk must reach to be returned. When omitted, each instance’s chunks are filtered by that instance’s score_threshold, capped at the lower of the first instance’s score_threshold and 0.4.

maximum1

minimum0

MaxNumResults int64Optional

Maximum number of merged results to return. When omitted, defaults to the first instance’s max_num_results, then 10.

maximum50

minimum1

RetrievalType NamespaceChatCompletionsParamsAISearchOptionsRetrievalRetrievalTypeOptional

One of the following:

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalRetrievalTypeVector NamespaceChatCompletionsParamsAISearchOptionsRetrievalRetrievalType = "vector"

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalRetrievalTypeKeyword NamespaceChatCompletionsParamsAISearchOptionsRetrievalRetrievalType = "keyword"

const NamespaceChatCompletionsParamsAISearchOptionsRetrievalRetrievalTypeHybrid NamespaceChatCompletionsParamsAISearchOptionsRetrievalRetrievalType = "hybrid"

ReturnOnFailure boolOptional

Messages param.Field[[]NamespaceChatCompletionsParamsMessage]

Body param

Content NamespaceChatCompletionsParamsMessagesContentUnion

One of the following:

UnionString

type NamespaceChatCompletionsParamsMessagesContentArray []NamespaceChatCompletionsParamsMessagesContentArray

One of the following:

type NamespaceChatCompletionsParamsMessagesContentArrayObject struct{…}

Text string

minLength1

Type NamespaceChatCompletionsParamsMessagesContentArrayObjectType

type NamespaceChatCompletionsParamsMessagesContentArrayObject struct{…}

ImageURL NamespaceChatCompletionsParamsMessagesContentArrayObjectImageURL

URL string

maxLength20971520

minLength1

Type NamespaceChatCompletionsParamsMessagesContentArrayObjectType

type NamespaceChatCompletionsParamsMessagesContentArrayObject struct{…}

File NamespaceChatCompletionsParamsMessagesContentArrayObjectFile

Filename string

maxLength255

minLength1

FileData stringOptional
maxLength13981144
minLength1

FileID stringOptional

Type NamespaceChatCompletionsParamsMessagesContentArrayObjectType

UnionString

Role NamespaceChatCompletionsParamsMessagesRole

One of the following:

const NamespaceChatCompletionsParamsMessagesRoleSystem NamespaceChatCompletionsParamsMessagesRole = "system"

const NamespaceChatCompletionsParamsMessagesRoleDeveloper NamespaceChatCompletionsParamsMessagesRole = "developer"

const NamespaceChatCompletionsParamsMessagesRoleUser NamespaceChatCompletionsParamsMessagesRole = "user"

const NamespaceChatCompletionsParamsMessagesRoleAssistant NamespaceChatCompletionsParamsMessagesRole = "assistant"

const NamespaceChatCompletionsParamsMessagesRoleTool NamespaceChatCompletionsParamsMessagesRole = "tool"

Model param.Field[string]Optional

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 param.Field[bool]Optional

Body param

ReturnsExpand Collapse

type NamespaceChatCompletionsResponse struct{…}

Choices []NamespaceChatCompletionsResponseChoice

Message NamespaceChatCompletionsResponseChoicesMessage

Content NamespaceChatCompletionsResponseChoicesMessageContentUnion

One of the following:

UnionString

type NamespaceChatCompletionsResponseChoicesMessageContentArray []NamespaceChatCompletionsResponseChoicesMessageContentArrayItem

One of the following:

type NamespaceChatCompletionsResponseChoicesMessageContentArrayObject struct{…}

Text string

minLength1

Type NamespaceChatCompletionsResponseChoicesMessageContentArrayObjectType

type NamespaceChatCompletionsResponseChoicesMessageContentArrayObject struct{…}

ImageURL NamespaceChatCompletionsResponseChoicesMessageContentArrayObjectImageURL

URL string

maxLength20971520

minLength1

Type NamespaceChatCompletionsResponseChoicesMessageContentArrayObjectType

type NamespaceChatCompletionsResponseChoicesMessageContentArrayObject struct{…}

File NamespaceChatCompletionsResponseChoicesMessageContentArrayObjectFile

Filename string

maxLength255

minLength1

FileData stringOptional
maxLength13981144
minLength1

FileID stringOptional

Type NamespaceChatCompletionsResponseChoicesMessageContentArrayObjectType

UnionString

Role NamespaceChatCompletionsResponseChoicesMessageRole

One of the following:

const NamespaceChatCompletionsResponseChoicesMessageRoleSystem NamespaceChatCompletionsResponseChoicesMessageRole = "system"

const NamespaceChatCompletionsResponseChoicesMessageRoleDeveloper NamespaceChatCompletionsResponseChoicesMessageRole = "developer"

const NamespaceChatCompletionsResponseChoicesMessageRoleUser NamespaceChatCompletionsResponseChoicesMessageRole = "user"

const NamespaceChatCompletionsResponseChoicesMessageRoleAssistant NamespaceChatCompletionsResponseChoicesMessageRole = "assistant"

const NamespaceChatCompletionsResponseChoicesMessageRoleTool NamespaceChatCompletionsResponseChoicesMessageRole = "tool"

Index int64Optional

Chunks []NamespaceChatCompletionsResponseChunk

ID string

InstanceID string

Score float64

maximum1

minimum0

Text string

Type string

Item NamespaceChatCompletionsResponseChunksItemOptional

Key string

Metadata map[string, unknown]Optional

Timestamp float64Optional

MediaEndMs int64Optional

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

MediaStartMs int64Optional

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

ScoringDetails NamespaceChatCompletionsResponseChunksScoringDetailsOptional

FusionMethod NamespaceChatCompletionsResponseChunksScoringDetailsFusionMethodOptional

One of the following:

const NamespaceChatCompletionsResponseChunksScoringDetailsFusionMethodRrf NamespaceChatCompletionsResponseChunksScoringDetailsFusionMethod = "rrf"

const NamespaceChatCompletionsResponseChunksScoringDetailsFusionMethodMax NamespaceChatCompletionsResponseChunksScoringDetailsFusionMethod = "max"

KeywordRank float64Optional

KeywordScore float64Optional

minimum0

RerankingScore float64Optional

maximum1

minimum0

VectorRank float64Optional

VectorScore float64Optional

maximum1

minimum0

SourceMediaType NamespaceChatCompletionsResponseChunksSourceMediaTypeOptional

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

One of the following:

const NamespaceChatCompletionsResponseChunksSourceMediaTypeAudio NamespaceChatCompletionsResponseChunksSourceMediaType = "audio"

const NamespaceChatCompletionsResponseChunksSourceMediaTypeVideo NamespaceChatCompletionsResponseChunksSourceMediaType = "video"

ID stringOptional

Errors []NamespaceChatCompletionsResponseErrorOptional

InstanceID string

Message string

Model stringOptional

Object stringOptional

Multi-Instance Chat Completions

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/ai_search"
  "github.com/cloudflare/cloudflare-go/option"
  "github.com/cloudflare/cloudflare-go/shared"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.AISearch.Namespaces.ChatCompletions(
    context.TODO(),
    "my-namespace",
    ai_search.NamespaceChatCompletionsParams{
      AccountID: cloudflare.F("c3dc5f0b34a14ff8e1b3ec04895e1b22"),
      AISearchOptions: cloudflare.F(ai_search.NamespaceChatCompletionsParamsAISearchOptions{
        InstanceIDs: cloudflare.F([]string{"my-ai-search"}),
      }),
      Messages: cloudflare.F([]ai_search.NamespaceChatCompletionsParamsMessage{ai_search.NamespaceChatCompletionsParamsMessage{
        Content: cloudflare.F[ai_search.NamespaceChatCompletionsParamsMessagesContentUnion](shared.UnionString("string")),
        Role: cloudflare.F(ai_search.NamespaceChatCompletionsParamsMessagesRoleSystem),
      }}),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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
      },
      "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",
  "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
      },
      "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",
  "errors": [
    {
      "instance_id": "instance_id",
      "message": "message"
    }
  ],
  "model": "model",
  "object": "object"
}