API Reference

AI Search

Namespaces

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Multi-Instance Search

client.AISearch.Namespaces.Search(ctx, name, params) (*NamespaceSearchResponse, error)

POST/accounts/{account_id}/ai-search/namespaces/{name}/search

Multi-Instance Search

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 NamespaceSearchParams

AccountID param.Field[string]Optional

Path param

AISearchOptions param.Field[NamespaceSearchParamsAISearchOptions]

Body param

InstanceIDs []string

Cache NamespaceSearchParamsAISearchOptionsCacheOptional

CacheThreshold NamespaceSearchParamsAISearchOptionsCacheCacheThresholdOptional

One of the following:

const NamespaceSearchParamsAISearchOptionsCacheCacheThresholdSuperStrictMatch NamespaceSearchParamsAISearchOptionsCacheCacheThreshold = "super_strict_match"

const NamespaceSearchParamsAISearchOptionsCacheCacheThresholdCloseEnough NamespaceSearchParamsAISearchOptionsCacheCacheThreshold = "close_enough"

const NamespaceSearchParamsAISearchOptionsCacheCacheThresholdFlexibleFriend NamespaceSearchParamsAISearchOptionsCacheCacheThreshold = "flexible_friend"

const NamespaceSearchParamsAISearchOptionsCacheCacheThresholdAnythingGoes NamespaceSearchParamsAISearchOptionsCacheCacheThreshold = "anything_goes"

Enabled boolOptional

QueryRewrite NamespaceSearchParamsAISearchOptionsQueryRewriteOptional

Enabled boolOptional

Model NamespaceSearchParamsAISearchOptionsQueryRewriteModelOptional

One of the following:

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfMetaLlama3_3_70bInstructFp8Fast NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/meta/llama-3.3-70b-instruct-fp8-fast"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfZaiOrgGlm4_7Flash NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/zai-org/glm-4.7-flash"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfMetaLlama3_1_8bInstructFast NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/meta/llama-3.1-8b-instruct-fast"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfMetaLlama3_1_8bInstructFp8 NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/meta/llama-3.1-8b-instruct-fp8"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfMetaLlama4Scout17b16eInstruct NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/meta/llama-4-scout-17b-16e-instruct"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfQwenQwen3_30bA3bFp8 NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/qwen/qwen3-30b-a3b-fp8"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfDeepseekAIDeepseekR1DistillQwen32b NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfMoonshotaiKimiK2Instruct NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/moonshotai/kimi-k2-instruct"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfGoogleGemma3_12bIt NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/google/gemma-3-12b-it"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfGoogleGemma4_26bA4bIt NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/google/gemma-4-26b-a4b-it"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCfMoonshotaiKimiK2_5 NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "@cf/moonshotai/kimi-k2.5"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelAnthropicClaude3_7Sonnet NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "anthropic/claude-3-7-sonnet"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelAnthropicClaudeSonnet4 NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "anthropic/claude-sonnet-4"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelAnthropicClaudeOpus4 NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "anthropic/claude-opus-4"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelAnthropicClaude3_5Haiku NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "anthropic/claude-3-5-haiku"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCerebrasQwen3_235bA22bInstruct NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/qwen-3-235b-a22b-instruct"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCerebrasQwen3_235bA22bThinking NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/qwen-3-235b-a22b-thinking"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCerebrasLlama3_3_70b NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/llama-3.3-70b"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCerebrasLlama4Maverick17b128eInstruct NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/llama-4-maverick-17b-128e-instruct"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCerebrasLlama4Scout17b16eInstruct NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/llama-4-scout-17b-16e-instruct"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelCerebrasGptOSs120b NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "cerebras/gpt-oss-120b"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelGoogleAIStudioGemini2_5Flash NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "google-ai-studio/gemini-2.5-flash"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelGoogleAIStudioGemini2_5Pro NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "google-ai-studio/gemini-2.5-pro"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelGrokGrok4 NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "grok/grok-4"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelGroqLlama3_3_70bVersatile NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "groq/llama-3.3-70b-versatile"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelGroqLlama3_1_8bInstant NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "groq/llama-3.1-8b-instant"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelOpenAIGpt5 NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "openai/gpt-5"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelOpenAIGpt5Mini NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "openai/gpt-5-mini"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelOpenAIGpt5Nano NamespaceSearchParamsAISearchOptionsQueryRewriteModel = "openai/gpt-5-nano"

const NamespaceSearchParamsAISearchOptionsQueryRewriteModelEmpty NamespaceSearchParamsAISearchOptionsQueryRewriteModel = ""

RewritePrompt stringOptional

Reranking NamespaceSearchParamsAISearchOptionsRerankingOptional

Enabled boolOptional

MatchThreshold float64Optional

maximum1

minimum0

Model NamespaceSearchParamsAISearchOptionsRerankingModelOptional

One of the following:

const NamespaceSearchParamsAISearchOptionsRerankingModelCfBaaiBgeRerankerBase NamespaceSearchParamsAISearchOptionsRerankingModel = "@cf/baai/bge-reranker-base"

const NamespaceSearchParamsAISearchOptionsRerankingModelEmpty NamespaceSearchParamsAISearchOptionsRerankingModel = ""

Retrieval NamespaceSearchParamsAISearchOptionsRetrievalOptional

BoostBy []NamespaceSearchParamsAISearchOptionsRetrievalBoostByOptional

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 NamespaceSearchParamsAISearchOptionsRetrievalBoostByDirectionOptional

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 NamespaceSearchParamsAISearchOptionsRetrievalBoostByDirectionAsc NamespaceSearchParamsAISearchOptionsRetrievalBoostByDirection = "asc"

const NamespaceSearchParamsAISearchOptionsRetrievalBoostByDirectionDesc NamespaceSearchParamsAISearchOptionsRetrievalBoostByDirection = "desc"

const NamespaceSearchParamsAISearchOptionsRetrievalBoostByDirectionExists NamespaceSearchParamsAISearchOptionsRetrievalBoostByDirection = "exists"

const NamespaceSearchParamsAISearchOptionsRetrievalBoostByDirectionNotExists NamespaceSearchParamsAISearchOptionsRetrievalBoostByDirection = "not_exists"

ContextExpansion int64Optional

maximum3

minimum0

Filters map[string, unknown]Optional

FusionMethod NamespaceSearchParamsAISearchOptionsRetrievalFusionMethodOptional

One of the following:

const NamespaceSearchParamsAISearchOptionsRetrievalFusionMethodMax NamespaceSearchParamsAISearchOptionsRetrievalFusionMethod = "max"

const NamespaceSearchParamsAISearchOptionsRetrievalFusionMethodRrf NamespaceSearchParamsAISearchOptionsRetrievalFusionMethod = "rrf"

KeywordMatchMode NamespaceSearchParamsAISearchOptionsRetrievalKeywordMatchModeOptional

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’.

One of the following:

const NamespaceSearchParamsAISearchOptionsRetrievalKeywordMatchModeAnd NamespaceSearchParamsAISearchOptionsRetrievalKeywordMatchMode = "and"

const NamespaceSearchParamsAISearchOptionsRetrievalKeywordMatchModeOr NamespaceSearchParamsAISearchOptionsRetrievalKeywordMatchMode = "or"

MatchThreshold float64Optional

maximum1

minimum0

MaxNumResults int64Optional

maximum50

minimum1

RetrievalType NamespaceSearchParamsAISearchOptionsRetrievalRetrievalTypeOptional

One of the following:

const NamespaceSearchParamsAISearchOptionsRetrievalRetrievalTypeVector NamespaceSearchParamsAISearchOptionsRetrievalRetrievalType = "vector"

const NamespaceSearchParamsAISearchOptionsRetrievalRetrievalTypeKeyword NamespaceSearchParamsAISearchOptionsRetrievalRetrievalType = "keyword"

const NamespaceSearchParamsAISearchOptionsRetrievalRetrievalTypeHybrid NamespaceSearchParamsAISearchOptionsRetrievalRetrievalType = "hybrid"

ReturnOnFailure boolOptional

Messages param.Field[[]NamespaceSearchParamsMessage]Optional

Body param

Content string

Role NamespaceSearchParamsMessagesRole

One of the following:

const NamespaceSearchParamsMessagesRoleSystem NamespaceSearchParamsMessagesRole = "system"

const NamespaceSearchParamsMessagesRoleDeveloper NamespaceSearchParamsMessagesRole = "developer"

const NamespaceSearchParamsMessagesRoleUser NamespaceSearchParamsMessagesRole = "user"

const NamespaceSearchParamsMessagesRoleAssistant NamespaceSearchParamsMessagesRole = "assistant"

const NamespaceSearchParamsMessagesRoleTool NamespaceSearchParamsMessagesRole = "tool"

Query param.Field[string]Optional

Body param: A simple text query string. Alternative to ‘messages’ — provide either this or ‘messages’, not both.

minLength1

ReturnsExpand Collapse

type NamespaceSearchResponse struct{…}

Chunks []NamespaceSearchResponseChunk

ID string

InstanceID string

Score float64

maximum1

minimum0

Text string

Type string

Item NamespaceSearchResponseChunksItemOptional

Key string

Metadata map[string, unknown]Optional

Timestamp float64Optional

ScoringDetails NamespaceSearchResponseChunksScoringDetailsOptional

FusionMethod NamespaceSearchResponseChunksScoringDetailsFusionMethodOptional

One of the following:

const NamespaceSearchResponseChunksScoringDetailsFusionMethodRrf NamespaceSearchResponseChunksScoringDetailsFusionMethod = "rrf"

const NamespaceSearchResponseChunksScoringDetailsFusionMethodMax NamespaceSearchResponseChunksScoringDetailsFusionMethod = "max"

KeywordRank float64Optional

KeywordScore float64Optional

minimum0

RerankingScore float64Optional

maximum1

minimum0

VectorRank float64Optional

VectorScore float64Optional

maximum1

minimum0

SearchQuery string

Errors []NamespaceSearchResponseErrorOptional

InstanceID string

Message string

Multi-Instance Search

Go

HTTP

TypeScript

Python

Go

Terraform

package main

import (
  "context"
  "fmt"

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

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.AISearch.Namespaces.Search(
    context.TODO(),
    "my-namespace",
    ai_search.NamespaceSearchParams{
      AccountID: cloudflare.F("c3dc5f0b34a14ff8e1b3ec04895e1b22"),
      AISearchOptions: cloudflare.F(ai_search.NamespaceSearchParamsAISearchOptions{
        InstanceIDs: cloudflare.F([]string{"my-ai-search"}),
      }),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Chunks)
}

200 example

{
  "result": {
    "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
        }
      }
    ],
    "search_query": "search_query",
    "errors": [
      {
        "instance_id": "instance_id",
        "message": "message"
      }
    ]
  },
  "success": true
}

Returns Examples

200 example

{
  "result": {
    "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
        }
      }
    ],
    "search_query": "search_query",
    "errors": [
      {
        "instance_id": "instance_id",
        "message": "message"
      }
    ]
  },
  "success": true
}