# Namespaces

## List namespaces.

**get** `/accounts/{account_id}/ai-search/namespaces`

List namespaces.

### Path Parameters

- `account_id: optional string`

### Query Parameters

- `order_by: optional "created_at"`

  Order By Column Name

  - `"created_at"`

- `order_by_direction: optional "asc" or "desc"`

  Order By Direction

  - `"asc"`

  - `"desc"`

- `page: optional number`

- `per_page: optional number`

### Returns

- `result: array of  { created_at, name, description }`

  - `created_at: string`

  - `name: string`

  - `description: optional string`

    Optional description for the namespace. Max 256 characters.

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": [
    {
      "created_at": "2019-12-27T18:11:19.117Z",
      "name": "production",
      "description": "Production environment"
    }
  ],
  "success": true
}
```

## Create new namespaces.

**post** `/accounts/{account_id}/ai-search/namespaces`

Create a new namespaces.

### Path Parameters

- `account_id: optional string`

### Body Parameters

- `name: string`

- `description: optional string`

  Optional description for the namespace. Max 256 characters.

### Returns

- `result:  { created_at, name, description }`

  - `created_at: string`

  - `name: string`

  - `description: optional string`

    Optional description for the namespace. Max 256 characters.

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "name": "production",
          "description": "Production environment"
        }'
```

#### Response

```json
{
  "result": {
    "created_at": "2019-12-27T18:11:19.117Z",
    "name": "production",
    "description": "Production environment"
  },
  "success": true
}
```

## Read namespace.

**get** `/accounts/{account_id}/ai-search/namespaces/{name}`

Read namespace.

### Path Parameters

- `account_id: optional string`

- `name: string`

### Returns

- `result:  { created_at, name, description }`

  - `created_at: string`

  - `name: string`

  - `description: optional string`

    Optional description for the namespace. Max 256 characters.

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "created_at": "2019-12-27T18:11:19.117Z",
    "name": "production",
    "description": "Production environment"
  },
  "success": true
}
```

## Update namespace.

**put** `/accounts/{account_id}/ai-search/namespaces/{name}`

Update namespace.

### Path Parameters

- `account_id: optional string`

- `name: string`

### Body Parameters

- `description: optional string`

  Optional description for the namespace. Max 256 characters.

### Returns

- `result:  { created_at, name, description }`

  - `created_at: string`

  - `name: string`

  - `description: optional string`

    Optional description for the namespace. Max 256 characters.

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME \
    -X PUT \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "created_at": "2019-12-27T18:11:19.117Z",
    "name": "production",
    "description": "Production environment"
  },
  "success": true
}
```

## Delete namespace.

**delete** `/accounts/{account_id}/ai-search/namespaces/{name}`

Delete namespace.

### Path Parameters

- `account_id: optional string`

- `name: string`

### Returns

- `result:  { created_at, name, description }`

  - `created_at: string`

  - `name: string`

  - `description: optional string`

    Optional description for the namespace. Max 256 characters.

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME \
    -X DELETE \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "created_at": "2019-12-27T18:11:19.117Z",
    "name": "production",
    "description": "Production environment"
  },
  "success": true
}
```

## Multi-Instance Search

**post** `/accounts/{account_id}/ai-search/namespaces/{name}/search`

Multi-Instance Search

### Path Parameters

- `account_id: optional string`

- `name: string`

### Body Parameters

- `ai_search_options:  { instance_ids, cache, query_rewrite, 2 more }`

  - `instance_ids: array of string`

  - `cache: optional  { cache_threshold, enabled }`

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

      - `"super_strict_match"`

      - `"close_enough"`

      - `"flexible_friend"`

      - `"anything_goes"`

    - `enabled: optional boolean`

  - `query_rewrite: optional  { enabled, model, rewrite_prompt }`

    - `enabled: optional boolean`

    - `model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

      - `"@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"`

      - `"@cf/google/gemma-4-26b-a4b-it"`

      - `"@cf/moonshotai/kimi-k2.5"`

      - `"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: optional string`

  - `reranking: optional  { enabled, match_threshold, model }`

    - `enabled: optional boolean`

    - `match_threshold: optional number`

    - `model: optional "@cf/baai/bge-reranker-base" or ""`

      - `"@cf/baai/bge-reranker-base"`

      - `""`

  - `retrieval: optional  { boost_by, context_expansion, filters, 6 more }`

    - `boost_by: optional array of  { 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 asc/desc directions; text/boolean fields support exists/not_exists.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `context_expansion: optional number`

    - `filters: optional map[unknown]`

    - `fusion_method: optional "max" or "rrf"`

      - `"max"`

      - `"rrf"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

    - `match_threshold: optional number`

    - `max_num_results: optional number`

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

      - `"vector"`

      - `"keyword"`

      - `"hybrid"`

    - `return_on_failure: optional boolean`

- `messages: optional array of  { content, role }`

  - `content: string`

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

    - `"system"`

    - `"developer"`

    - `"user"`

    - `"assistant"`

    - `"tool"`

- `query: optional string`

  A simple text query string. Alternative to 'messages' — provide either this or 'messages', not both.

### Returns

- `result:  { chunks, search_query, errors }`

  - `chunks: array of  { id, instance_id, score, 4 more }`

    - `id: string`

    - `instance_id: string`

    - `score: number`

    - `text: string`

    - `type: string`

    - `item: optional  { key, metadata, timestamp }`

      - `key: string`

      - `metadata: optional map[unknown]`

      - `timestamp: optional number`

    - `scoring_details: optional  { fusion_method, keyword_rank, keyword_score, 3 more }`

      - `fusion_method: optional "rrf" or "max"`

        - `"rrf"`

        - `"max"`

      - `keyword_rank: optional number`

      - `keyword_score: optional number`

      - `reranking_score: optional number`

      - `vector_rank: optional number`

      - `vector_score: optional number`

  - `search_query: string`

  - `errors: optional array of  { instance_id, message }`

    - `instance_id: string`

    - `message: string`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/search \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "ai_search_options": {
            "instance_ids": [
              "my-ai-search"
            ]
          }
        }'
```

#### Response

```json
{
  "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
}
```

## Multi-Instance Chat Completions

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

### Path Parameters

- `account_id: optional string`

- `name: string`

### Body Parameters

- `ai_search_options:  { instance_ids, cache, query_rewrite, 2 more }`

  - `instance_ids: array of string`

  - `cache: optional  { cache_threshold, enabled }`

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

      - `"super_strict_match"`

      - `"close_enough"`

      - `"flexible_friend"`

      - `"anything_goes"`

    - `enabled: optional boolean`

  - `query_rewrite: optional  { enabled, model, rewrite_prompt }`

    - `enabled: optional boolean`

    - `model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

      - `"@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"`

      - `"@cf/google/gemma-4-26b-a4b-it"`

      - `"@cf/moonshotai/kimi-k2.5"`

      - `"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: optional string`

  - `reranking: optional  { enabled, match_threshold, model }`

    - `enabled: optional boolean`

    - `match_threshold: optional number`

    - `model: optional "@cf/baai/bge-reranker-base" or ""`

      - `"@cf/baai/bge-reranker-base"`

      - `""`

  - `retrieval: optional  { boost_by, context_expansion, filters, 6 more }`

    - `boost_by: optional array of  { 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 asc/desc directions; text/boolean fields support exists/not_exists.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `context_expansion: optional number`

    - `filters: optional map[unknown]`

    - `fusion_method: optional "max" or "rrf"`

      - `"max"`

      - `"rrf"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

    - `match_threshold: optional number`

    - `max_num_results: optional number`

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

      - `"vector"`

      - `"keyword"`

      - `"hybrid"`

    - `return_on_failure: optional boolean`

- `messages: array of  { content, role }`

  - `content: string`

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

    - `"system"`

    - `"developer"`

    - `"user"`

    - `"assistant"`

    - `"tool"`

- `model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

  - `"@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"`

  - `"@cf/google/gemma-4-26b-a4b-it"`

  - `"@cf/moonshotai/kimi-k2.5"`

  - `"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: optional boolean`

### Returns

- `choices: array of  { message, index }`

  - `message:  { content, role }`

    - `content: string`

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

      - `"system"`

      - `"developer"`

      - `"user"`

      - `"assistant"`

      - `"tool"`

  - `index: optional number`

- `chunks: array of  { id, instance_id, score, 4 more }`

  - `id: string`

  - `instance_id: string`

  - `score: number`

  - `text: string`

  - `type: string`

  - `item: optional  { key, metadata, timestamp }`

    - `key: string`

    - `metadata: optional map[unknown]`

    - `timestamp: optional number`

  - `scoring_details: optional  { fusion_method, keyword_rank, keyword_score, 3 more }`

    - `fusion_method: optional "rrf" or "max"`

      - `"rrf"`

      - `"max"`

    - `keyword_rank: optional number`

    - `keyword_score: optional number`

    - `reranking_score: optional number`

    - `vector_rank: optional number`

    - `vector_score: optional number`

- `id: optional string`

- `errors: optional array of  { instance_id, message }`

  - `instance_id: string`

  - `message: string`

- `model: optional string`

- `object: optional string`

### Example

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

#### Response

```json
{
  "choices": [
    {
      "message": {
        "content": "content",
        "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"
}
```

## Domain Types

### Namespace List Response

- `NamespaceListResponse  { created_at, name, description }`

  - `created_at: string`

  - `name: string`

  - `description: optional string`

    Optional description for the namespace. Max 256 characters.

### Namespace Create Response

- `NamespaceCreateResponse  { created_at, name, description }`

  - `created_at: string`

  - `name: string`

  - `description: optional string`

    Optional description for the namespace. Max 256 characters.

### Namespace Read Response

- `NamespaceReadResponse  { created_at, name, description }`

  - `created_at: string`

  - `name: string`

  - `description: optional string`

    Optional description for the namespace. Max 256 characters.

### Namespace Update Response

- `NamespaceUpdateResponse  { created_at, name, description }`

  - `created_at: string`

  - `name: string`

  - `description: optional string`

    Optional description for the namespace. Max 256 characters.

### Namespace Delete Response

- `NamespaceDeleteResponse  { created_at, name, description }`

  - `created_at: string`

  - `name: string`

  - `description: optional string`

    Optional description for the namespace. Max 256 characters.

### Namespace Search Response

- `NamespaceSearchResponse  { chunks, search_query, errors }`

  - `chunks: array of  { id, instance_id, score, 4 more }`

    - `id: string`

    - `instance_id: string`

    - `score: number`

    - `text: string`

    - `type: string`

    - `item: optional  { key, metadata, timestamp }`

      - `key: string`

      - `metadata: optional map[unknown]`

      - `timestamp: optional number`

    - `scoring_details: optional  { fusion_method, keyword_rank, keyword_score, 3 more }`

      - `fusion_method: optional "rrf" or "max"`

        - `"rrf"`

        - `"max"`

      - `keyword_rank: optional number`

      - `keyword_score: optional number`

      - `reranking_score: optional number`

      - `vector_rank: optional number`

      - `vector_score: optional number`

  - `search_query: string`

  - `errors: optional array of  { instance_id, message }`

    - `instance_id: string`

    - `message: string`

### Namespace Chat Completions Response

- `NamespaceChatCompletionsResponse  { choices, chunks, id, 3 more }`

  - `choices: array of  { message, index }`

    - `message:  { content, role }`

      - `content: string`

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

        - `"system"`

        - `"developer"`

        - `"user"`

        - `"assistant"`

        - `"tool"`

    - `index: optional number`

  - `chunks: array of  { id, instance_id, score, 4 more }`

    - `id: string`

    - `instance_id: string`

    - `score: number`

    - `text: string`

    - `type: string`

    - `item: optional  { key, metadata, timestamp }`

      - `key: string`

      - `metadata: optional map[unknown]`

      - `timestamp: optional number`

    - `scoring_details: optional  { fusion_method, keyword_rank, keyword_score, 3 more }`

      - `fusion_method: optional "rrf" or "max"`

        - `"rrf"`

        - `"max"`

      - `keyword_rank: optional number`

      - `keyword_score: optional number`

      - `reranking_score: optional number`

      - `vector_rank: optional number`

      - `vector_score: optional number`

  - `id: optional string`

  - `errors: optional array of  { instance_id, message }`

    - `instance_id: string`

    - `message: string`

  - `model: optional string`

  - `object: optional string`

# Instances

## List instances.

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances`

List instances.

### Path Parameters

- `account_id: optional string`

- `name: string`

### Query Parameters

- `namespace: optional string`

- `order_by: optional "created_at"`

  Order By Column Name

  - `"created_at"`

- `order_by_direction: optional "asc" or "desc"`

  Order By Direction

  - `"asc"`

  - `"desc"`

- `page: optional number`

- `per_page: optional number`

- `search: optional string`

  Search by id

### Returns

- `result: array of  { id, created_at, modified_at, 35 more }`

  - `id: string`

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

  - `created_at: string`

  - `modified_at: string`

  - `ai_gateway_id: optional string`

  - `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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"`

    - `""`

  - `cache: optional boolean`

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

    - `"super_strict_match"`

    - `"close_enough"`

    - `"flexible_friend"`

    - `"anything_goes"`

  - `chunk_overlap: optional number`

  - `chunk_size: optional number`

  - `created_by: optional string`

  - `custom_metadata: optional array of  { data_type, field_name }`

    - `data_type: "text" or "number" or "boolean" or "datetime"`

      - `"text"`

      - `"number"`

      - `"boolean"`

      - `"datetime"`

    - `field_name: string`

  - `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

    - `"@cf/qwen/qwen3-embedding-0.6b"`

    - `"@cf/baai/bge-m3"`

    - `"@cf/baai/bge-large-en-v1.5"`

    - `"@cf/google/embeddinggemma-300m"`

    - `"google-ai-studio/gemini-embedding-001"`

    - `"google-ai-studio/gemini-embedding-2-preview"`

    - `"openai/text-embedding-3-small"`

    - `"openai/text-embedding-3-large"`

    - `""`

  - `enable: optional boolean`

  - `engine_version: optional number`

  - `fusion_method: optional "max" or "rrf"`

    - `"max"`

    - `"rrf"`

  - `hybrid_search_enabled: optional boolean`

    Deprecated — use index_method instead.

  - `index_method: optional  { keyword, vector }`

    Controls which storage backends are used during indexing. Defaults to vector-only.

    - `keyword: boolean`

      Enable keyword (BM25) storage backend.

    - `vector: boolean`

      Enable vector (embedding) storage backend.

  - `indexing_options: optional  { keyword_tokenizer }`

    - `keyword_tokenizer: optional "porter" or "trigram"`

      Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

      - `"porter"`

      - `"trigram"`

  - `last_activity: optional string`

  - `max_num_results: optional number`

  - `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

    - `created_from_aisearch_wizard: optional boolean`

    - `search_for_agents: optional  { hostname, zone_id, zone_name }`

      - `hostname: string`

      - `zone_id: string`

      - `zone_name: string`

    - `worker_domain: optional string`

  - `modified_by: optional string`

  - `namespace: optional string`

  - `paused: optional boolean`

  - `public_endpoint_id: optional string`

  - `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

    - `authorized_hosts: optional array of string`

    - `chat_completions_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable chat completions endpoint for this public endpoint

    - `enabled: optional boolean`

    - `mcp: optional  { description, disabled }`

      - `description: optional string`

      - `disabled: optional boolean`

        Disable MCP endpoint for this public endpoint

    - `rate_limit: optional  { period_ms, requests, technique }`

      - `period_ms: optional number`

      - `requests: optional number`

      - `technique: optional "fixed" or "sliding"`

        - `"fixed"`

        - `"sliding"`

    - `search_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable search endpoint for this public endpoint

  - `reranking: optional boolean`

  - `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

    - `"@cf/baai/bge-reranker-base"`

    - `""`

  - `retrieval_options: optional  { boost_by, keyword_match_mode }`

    - `boost_by: optional array of  { field, direction }`

      Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

  - `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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_query: optional boolean`

  - `score_threshold: optional number`

  - `source: optional string`

  - `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

    - `exclude_items: optional array of string`

      List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

    - `include_items: optional array of string`

      List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

    - `prefix: optional string`

    - `r2_jurisdiction: optional string`

    - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

      - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

        - `depth: optional number`

        - `include_external_links: optional boolean`

        - `include_subdomains: optional boolean`

        - `max_age: optional number`

        - `source: optional "all" or "sitemaps" or "links"`

          - `"all"`

          - `"sitemaps"`

          - `"links"`

      - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

        - `content_selector: optional array of  { path, selector }`

          List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

          - `path: string`

            Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

          - `selector: string`

            CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

        - `include_headers: optional map[string]`

        - `include_images: optional boolean`

        - `specific_sitemaps: optional array of string`

          List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

        - `use_browser_rendering: optional boolean`

      - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

        - `"sitemap"`

        - `"feed-rss"`

        - `"crawl"`

      - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

        - `storage_id: string`

        - `r2_jurisdiction: optional string`

        - `storage_type: optional Provider`

          - `"r2"`

  - `status: optional string`

  - `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

    Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

    - `3600`

    - `7200`

    - `14400`

    - `21600`

    - `43200`

    - `86400`

  - `token_id: optional string`

  - `type: optional "r2" or "web-crawler"`

    - `"r2"`

    - `"web-crawler"`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": [
    {
      "id": "my-ai-search",
      "created_at": "2019-12-27T18:11:19.117Z",
      "modified_at": "2019-12-27T18:11:19.117Z",
      "ai_gateway_id": "ai_gateway_id",
      "ai_search_model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
      "cache": true,
      "cache_threshold": "super_strict_match",
      "chunk_overlap": 0,
      "chunk_size": 64,
      "created_by": "created_by",
      "custom_metadata": [
        {
          "data_type": "text",
          "field_name": "x"
        }
      ],
      "embedding_model": "@cf/qwen/qwen3-embedding-0.6b",
      "enable": true,
      "engine_version": 0,
      "fusion_method": "max",
      "hybrid_search_enabled": true,
      "index_method": {
        "keyword": true,
        "vector": true
      },
      "indexing_options": {
        "keyword_tokenizer": "porter"
      },
      "last_activity": "2019-12-27T18:11:19.117Z",
      "max_num_results": 1,
      "metadata": {
        "created_from_aisearch_wizard": true,
        "search_for_agents": {
          "hostname": "hostname",
          "zone_id": "zone_id",
          "zone_name": "zone_name"
        },
        "worker_domain": "worker_domain"
      },
      "modified_by": "modified_by",
      "namespace": "namespace",
      "paused": true,
      "public_endpoint_id": "public_endpoint_id",
      "public_endpoint_params": {
        "authorized_hosts": [
          "string"
        ],
        "chat_completions_endpoint": {
          "disabled": true
        },
        "enabled": true,
        "mcp": {
          "description": "description",
          "disabled": true
        },
        "rate_limit": {
          "period_ms": 60000,
          "requests": 1,
          "technique": "fixed"
        },
        "search_endpoint": {
          "disabled": true
        }
      },
      "reranking": true,
      "reranking_model": "@cf/baai/bge-reranker-base",
      "retrieval_options": {
        "boost_by": [
          {
            "field": "timestamp",
            "direction": "desc"
          }
        ],
        "keyword_match_mode": "and"
      },
      "rewrite_model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
      "rewrite_query": true,
      "score_threshold": 0,
      "source": "source",
      "source_params": {
        "exclude_items": [
          "/admin/**",
          "/private/**",
          "**\\temp\\**"
        ],
        "include_items": [
          "/blog/**",
          "/docs/**/*.html",
          "**\\blog\\**.html"
        ],
        "prefix": "prefix",
        "r2_jurisdiction": "r2_jurisdiction",
        "web_crawler": {
          "crawl_options": {
            "depth": 1,
            "include_external_links": true,
            "include_subdomains": true,
            "max_age": 0,
            "source": "all"
          },
          "parse_options": {
            "content_selector": [
              {
                "path": "**/blog/**",
                "selector": "article .post-body"
              }
            ],
            "include_headers": {
              "foo": "string"
            },
            "include_images": true,
            "specific_sitemaps": [
              "https://example.com/sitemap.xml",
              "https://example.com/blog-sitemap.xml"
            ],
            "use_browser_rendering": true
          },
          "parse_type": "sitemap",
          "store_options": {
            "storage_id": "storage_id",
            "r2_jurisdiction": "r2_jurisdiction",
            "storage_type": "r2"
          }
        }
      },
      "status": "status",
      "sync_interval": 3600,
      "token_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "type": "r2"
    }
  ],
  "success": true
}
```

## Create new instances.

**post** `/accounts/{account_id}/ai-search/namespaces/{name}/instances`

Create a new instances.

### Path Parameters

- `account_id: optional string`

- `name: string`

### Body Parameters

- `id: string`

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

- `ai_gateway_id: optional string`

- `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

  - `"@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"`

  - `"@cf/google/gemma-4-26b-a4b-it"`

  - `"@cf/moonshotai/kimi-k2.5"`

  - `"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"`

  - `""`

- `cache: optional boolean`

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

  - `"super_strict_match"`

  - `"close_enough"`

  - `"flexible_friend"`

  - `"anything_goes"`

- `chunk: optional boolean`

- `chunk_overlap: optional number`

- `chunk_size: optional number`

- `custom_metadata: optional array of  { data_type, field_name }`

  - `data_type: "text" or "number" or "boolean" or "datetime"`

    - `"text"`

    - `"number"`

    - `"boolean"`

    - `"datetime"`

  - `field_name: string`

- `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

  - `"@cf/qwen/qwen3-embedding-0.6b"`

  - `"@cf/baai/bge-m3"`

  - `"@cf/baai/bge-large-en-v1.5"`

  - `"@cf/google/embeddinggemma-300m"`

  - `"google-ai-studio/gemini-embedding-001"`

  - `"google-ai-studio/gemini-embedding-2-preview"`

  - `"openai/text-embedding-3-small"`

  - `"openai/text-embedding-3-large"`

  - `""`

- `fusion_method: optional "max" or "rrf"`

  - `"max"`

  - `"rrf"`

- `hybrid_search_enabled: optional boolean`

  Deprecated — use index_method instead.

- `index_method: optional  { keyword, vector }`

  Controls which storage backends are used during indexing. Defaults to vector-only.

  - `keyword: boolean`

    Enable keyword (BM25) storage backend.

  - `vector: boolean`

    Enable vector (embedding) storage backend.

- `indexing_options: optional  { keyword_tokenizer }`

  - `keyword_tokenizer: optional "porter" or "trigram"`

    Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

    - `"porter"`

    - `"trigram"`

- `max_num_results: optional number`

- `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

  - `created_from_aisearch_wizard: optional boolean`

  - `search_for_agents: optional  { hostname, zone_id, zone_name }`

    - `hostname: string`

    - `zone_id: string`

    - `zone_name: string`

  - `worker_domain: optional string`

- `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

  - `authorized_hosts: optional array of string`

  - `chat_completions_endpoint: optional  { disabled }`

    - `disabled: optional boolean`

      Disable chat completions endpoint for this public endpoint

  - `enabled: optional boolean`

  - `mcp: optional  { description, disabled }`

    - `description: optional string`

    - `disabled: optional boolean`

      Disable MCP endpoint for this public endpoint

  - `rate_limit: optional  { period_ms, requests, technique }`

    - `period_ms: optional number`

    - `requests: optional number`

    - `technique: optional "fixed" or "sliding"`

      - `"fixed"`

      - `"sliding"`

  - `search_endpoint: optional  { disabled }`

    - `disabled: optional boolean`

      Disable search endpoint for this public endpoint

- `reranking: optional boolean`

- `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

  - `"@cf/baai/bge-reranker-base"`

  - `""`

- `retrieval_options: optional  { boost_by, keyword_match_mode }`

  - `boost_by: optional array of  { field, direction }`

    Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

      - `"asc"`

      - `"desc"`

      - `"exists"`

      - `"not_exists"`

  - `keyword_match_mode: optional "and" or "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'.

    - `"and"`

    - `"or"`

- `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

  - `"@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"`

  - `"@cf/google/gemma-4-26b-a4b-it"`

  - `"@cf/moonshotai/kimi-k2.5"`

  - `"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_query: optional boolean`

- `score_threshold: optional number`

- `source: optional string`

- `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

  - `exclude_items: optional array of string`

    List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

  - `include_items: optional array of string`

    List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

  - `prefix: optional string`

  - `r2_jurisdiction: optional string`

  - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

    - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

      - `depth: optional number`

      - `include_external_links: optional boolean`

      - `include_subdomains: optional boolean`

      - `max_age: optional number`

      - `source: optional "all" or "sitemaps" or "links"`

        - `"all"`

        - `"sitemaps"`

        - `"links"`

    - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

      - `content_selector: optional array of  { path, selector }`

        List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

        - `path: string`

          Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

        - `selector: string`

          CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

      - `include_headers: optional map[string]`

      - `include_images: optional boolean`

      - `specific_sitemaps: optional array of string`

        List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

      - `use_browser_rendering: optional boolean`

    - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

      - `"sitemap"`

      - `"feed-rss"`

      - `"crawl"`

    - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

      - `storage_id: string`

      - `r2_jurisdiction: optional string`

      - `storage_type: optional Provider`

        - `"r2"`

- `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

  Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

  - `3600`

  - `7200`

  - `14400`

  - `21600`

  - `43200`

  - `86400`

- `token_id: optional string`

- `type: optional "r2" or "web-crawler"`

  - `"r2"`

  - `"web-crawler"`

### Returns

- `result:  { id, created_at, modified_at, 35 more }`

  - `id: string`

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

  - `created_at: string`

  - `modified_at: string`

  - `ai_gateway_id: optional string`

  - `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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"`

    - `""`

  - `cache: optional boolean`

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

    - `"super_strict_match"`

    - `"close_enough"`

    - `"flexible_friend"`

    - `"anything_goes"`

  - `chunk_overlap: optional number`

  - `chunk_size: optional number`

  - `created_by: optional string`

  - `custom_metadata: optional array of  { data_type, field_name }`

    - `data_type: "text" or "number" or "boolean" or "datetime"`

      - `"text"`

      - `"number"`

      - `"boolean"`

      - `"datetime"`

    - `field_name: string`

  - `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

    - `"@cf/qwen/qwen3-embedding-0.6b"`

    - `"@cf/baai/bge-m3"`

    - `"@cf/baai/bge-large-en-v1.5"`

    - `"@cf/google/embeddinggemma-300m"`

    - `"google-ai-studio/gemini-embedding-001"`

    - `"google-ai-studio/gemini-embedding-2-preview"`

    - `"openai/text-embedding-3-small"`

    - `"openai/text-embedding-3-large"`

    - `""`

  - `enable: optional boolean`

  - `engine_version: optional number`

  - `fusion_method: optional "max" or "rrf"`

    - `"max"`

    - `"rrf"`

  - `hybrid_search_enabled: optional boolean`

    Deprecated — use index_method instead.

  - `index_method: optional  { keyword, vector }`

    Controls which storage backends are used during indexing. Defaults to vector-only.

    - `keyword: boolean`

      Enable keyword (BM25) storage backend.

    - `vector: boolean`

      Enable vector (embedding) storage backend.

  - `indexing_options: optional  { keyword_tokenizer }`

    - `keyword_tokenizer: optional "porter" or "trigram"`

      Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

      - `"porter"`

      - `"trigram"`

  - `last_activity: optional string`

  - `max_num_results: optional number`

  - `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

    - `created_from_aisearch_wizard: optional boolean`

    - `search_for_agents: optional  { hostname, zone_id, zone_name }`

      - `hostname: string`

      - `zone_id: string`

      - `zone_name: string`

    - `worker_domain: optional string`

  - `modified_by: optional string`

  - `namespace: optional string`

  - `paused: optional boolean`

  - `public_endpoint_id: optional string`

  - `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

    - `authorized_hosts: optional array of string`

    - `chat_completions_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable chat completions endpoint for this public endpoint

    - `enabled: optional boolean`

    - `mcp: optional  { description, disabled }`

      - `description: optional string`

      - `disabled: optional boolean`

        Disable MCP endpoint for this public endpoint

    - `rate_limit: optional  { period_ms, requests, technique }`

      - `period_ms: optional number`

      - `requests: optional number`

      - `technique: optional "fixed" or "sliding"`

        - `"fixed"`

        - `"sliding"`

    - `search_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable search endpoint for this public endpoint

  - `reranking: optional boolean`

  - `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

    - `"@cf/baai/bge-reranker-base"`

    - `""`

  - `retrieval_options: optional  { boost_by, keyword_match_mode }`

    - `boost_by: optional array of  { field, direction }`

      Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

  - `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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_query: optional boolean`

  - `score_threshold: optional number`

  - `source: optional string`

  - `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

    - `exclude_items: optional array of string`

      List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

    - `include_items: optional array of string`

      List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

    - `prefix: optional string`

    - `r2_jurisdiction: optional string`

    - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

      - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

        - `depth: optional number`

        - `include_external_links: optional boolean`

        - `include_subdomains: optional boolean`

        - `max_age: optional number`

        - `source: optional "all" or "sitemaps" or "links"`

          - `"all"`

          - `"sitemaps"`

          - `"links"`

      - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

        - `content_selector: optional array of  { path, selector }`

          List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

          - `path: string`

            Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

          - `selector: string`

            CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

        - `include_headers: optional map[string]`

        - `include_images: optional boolean`

        - `specific_sitemaps: optional array of string`

          List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

        - `use_browser_rendering: optional boolean`

      - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

        - `"sitemap"`

        - `"feed-rss"`

        - `"crawl"`

      - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

        - `storage_id: string`

        - `r2_jurisdiction: optional string`

        - `storage_type: optional Provider`

          - `"r2"`

  - `status: optional string`

  - `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

    Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

    - `3600`

    - `7200`

    - `14400`

    - `21600`

    - `43200`

    - `86400`

  - `token_id: optional string`

  - `type: optional "r2" or "web-crawler"`

    - `"r2"`

    - `"web-crawler"`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "id": "my-ai-search"
        }'
```

#### Response

```json
{
  "result": {
    "id": "my-ai-search",
    "created_at": "2019-12-27T18:11:19.117Z",
    "modified_at": "2019-12-27T18:11:19.117Z",
    "ai_gateway_id": "ai_gateway_id",
    "ai_search_model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "cache": true,
    "cache_threshold": "super_strict_match",
    "chunk_overlap": 0,
    "chunk_size": 64,
    "created_by": "created_by",
    "custom_metadata": [
      {
        "data_type": "text",
        "field_name": "x"
      }
    ],
    "embedding_model": "@cf/qwen/qwen3-embedding-0.6b",
    "enable": true,
    "engine_version": 0,
    "fusion_method": "max",
    "hybrid_search_enabled": true,
    "index_method": {
      "keyword": true,
      "vector": true
    },
    "indexing_options": {
      "keyword_tokenizer": "porter"
    },
    "last_activity": "2019-12-27T18:11:19.117Z",
    "max_num_results": 1,
    "metadata": {
      "created_from_aisearch_wizard": true,
      "search_for_agents": {
        "hostname": "hostname",
        "zone_id": "zone_id",
        "zone_name": "zone_name"
      },
      "worker_domain": "worker_domain"
    },
    "modified_by": "modified_by",
    "namespace": "namespace",
    "paused": true,
    "public_endpoint_id": "public_endpoint_id",
    "public_endpoint_params": {
      "authorized_hosts": [
        "string"
      ],
      "chat_completions_endpoint": {
        "disabled": true
      },
      "enabled": true,
      "mcp": {
        "description": "description",
        "disabled": true
      },
      "rate_limit": {
        "period_ms": 60000,
        "requests": 1,
        "technique": "fixed"
      },
      "search_endpoint": {
        "disabled": true
      }
    },
    "reranking": true,
    "reranking_model": "@cf/baai/bge-reranker-base",
    "retrieval_options": {
      "boost_by": [
        {
          "field": "timestamp",
          "direction": "desc"
        }
      ],
      "keyword_match_mode": "and"
    },
    "rewrite_model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "rewrite_query": true,
    "score_threshold": 0,
    "source": "source",
    "source_params": {
      "exclude_items": [
        "/admin/**",
        "/private/**",
        "**\\temp\\**"
      ],
      "include_items": [
        "/blog/**",
        "/docs/**/*.html",
        "**\\blog\\**.html"
      ],
      "prefix": "prefix",
      "r2_jurisdiction": "r2_jurisdiction",
      "web_crawler": {
        "crawl_options": {
          "depth": 1,
          "include_external_links": true,
          "include_subdomains": true,
          "max_age": 0,
          "source": "all"
        },
        "parse_options": {
          "content_selector": [
            {
              "path": "**/blog/**",
              "selector": "article .post-body"
            }
          ],
          "include_headers": {
            "foo": "string"
          },
          "include_images": true,
          "specific_sitemaps": [
            "https://example.com/sitemap.xml",
            "https://example.com/blog-sitemap.xml"
          ],
          "use_browser_rendering": true
        },
        "parse_type": "sitemap",
        "store_options": {
          "storage_id": "storage_id",
          "r2_jurisdiction": "r2_jurisdiction",
          "storage_type": "r2"
        }
      }
    },
    "status": "status",
    "sync_interval": 3600,
    "token_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "type": "r2"
  },
  "success": true
}
```

## Read instances.

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}`

Read instances.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Returns

- `result:  { id, created_at, modified_at, 35 more }`

  - `id: string`

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

  - `created_at: string`

  - `modified_at: string`

  - `ai_gateway_id: optional string`

  - `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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"`

    - `""`

  - `cache: optional boolean`

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

    - `"super_strict_match"`

    - `"close_enough"`

    - `"flexible_friend"`

    - `"anything_goes"`

  - `chunk_overlap: optional number`

  - `chunk_size: optional number`

  - `created_by: optional string`

  - `custom_metadata: optional array of  { data_type, field_name }`

    - `data_type: "text" or "number" or "boolean" or "datetime"`

      - `"text"`

      - `"number"`

      - `"boolean"`

      - `"datetime"`

    - `field_name: string`

  - `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

    - `"@cf/qwen/qwen3-embedding-0.6b"`

    - `"@cf/baai/bge-m3"`

    - `"@cf/baai/bge-large-en-v1.5"`

    - `"@cf/google/embeddinggemma-300m"`

    - `"google-ai-studio/gemini-embedding-001"`

    - `"google-ai-studio/gemini-embedding-2-preview"`

    - `"openai/text-embedding-3-small"`

    - `"openai/text-embedding-3-large"`

    - `""`

  - `enable: optional boolean`

  - `engine_version: optional number`

  - `fusion_method: optional "max" or "rrf"`

    - `"max"`

    - `"rrf"`

  - `hybrid_search_enabled: optional boolean`

    Deprecated — use index_method instead.

  - `index_method: optional  { keyword, vector }`

    Controls which storage backends are used during indexing. Defaults to vector-only.

    - `keyword: boolean`

      Enable keyword (BM25) storage backend.

    - `vector: boolean`

      Enable vector (embedding) storage backend.

  - `indexing_options: optional  { keyword_tokenizer }`

    - `keyword_tokenizer: optional "porter" or "trigram"`

      Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

      - `"porter"`

      - `"trigram"`

  - `last_activity: optional string`

  - `max_num_results: optional number`

  - `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

    - `created_from_aisearch_wizard: optional boolean`

    - `search_for_agents: optional  { hostname, zone_id, zone_name }`

      - `hostname: string`

      - `zone_id: string`

      - `zone_name: string`

    - `worker_domain: optional string`

  - `modified_by: optional string`

  - `namespace: optional string`

  - `paused: optional boolean`

  - `public_endpoint_id: optional string`

  - `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

    - `authorized_hosts: optional array of string`

    - `chat_completions_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable chat completions endpoint for this public endpoint

    - `enabled: optional boolean`

    - `mcp: optional  { description, disabled }`

      - `description: optional string`

      - `disabled: optional boolean`

        Disable MCP endpoint for this public endpoint

    - `rate_limit: optional  { period_ms, requests, technique }`

      - `period_ms: optional number`

      - `requests: optional number`

      - `technique: optional "fixed" or "sliding"`

        - `"fixed"`

        - `"sliding"`

    - `search_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable search endpoint for this public endpoint

  - `reranking: optional boolean`

  - `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

    - `"@cf/baai/bge-reranker-base"`

    - `""`

  - `retrieval_options: optional  { boost_by, keyword_match_mode }`

    - `boost_by: optional array of  { field, direction }`

      Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

  - `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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_query: optional boolean`

  - `score_threshold: optional number`

  - `source: optional string`

  - `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

    - `exclude_items: optional array of string`

      List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

    - `include_items: optional array of string`

      List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

    - `prefix: optional string`

    - `r2_jurisdiction: optional string`

    - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

      - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

        - `depth: optional number`

        - `include_external_links: optional boolean`

        - `include_subdomains: optional boolean`

        - `max_age: optional number`

        - `source: optional "all" or "sitemaps" or "links"`

          - `"all"`

          - `"sitemaps"`

          - `"links"`

      - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

        - `content_selector: optional array of  { path, selector }`

          List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

          - `path: string`

            Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

          - `selector: string`

            CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

        - `include_headers: optional map[string]`

        - `include_images: optional boolean`

        - `specific_sitemaps: optional array of string`

          List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

        - `use_browser_rendering: optional boolean`

      - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

        - `"sitemap"`

        - `"feed-rss"`

        - `"crawl"`

      - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

        - `storage_id: string`

        - `r2_jurisdiction: optional string`

        - `storage_type: optional Provider`

          - `"r2"`

  - `status: optional string`

  - `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

    Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

    - `3600`

    - `7200`

    - `14400`

    - `21600`

    - `43200`

    - `86400`

  - `token_id: optional string`

  - `type: optional "r2" or "web-crawler"`

    - `"r2"`

    - `"web-crawler"`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "id": "my-ai-search",
    "created_at": "2019-12-27T18:11:19.117Z",
    "modified_at": "2019-12-27T18:11:19.117Z",
    "ai_gateway_id": "ai_gateway_id",
    "ai_search_model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "cache": true,
    "cache_threshold": "super_strict_match",
    "chunk_overlap": 0,
    "chunk_size": 64,
    "created_by": "created_by",
    "custom_metadata": [
      {
        "data_type": "text",
        "field_name": "x"
      }
    ],
    "embedding_model": "@cf/qwen/qwen3-embedding-0.6b",
    "enable": true,
    "engine_version": 0,
    "fusion_method": "max",
    "hybrid_search_enabled": true,
    "index_method": {
      "keyword": true,
      "vector": true
    },
    "indexing_options": {
      "keyword_tokenizer": "porter"
    },
    "last_activity": "2019-12-27T18:11:19.117Z",
    "max_num_results": 1,
    "metadata": {
      "created_from_aisearch_wizard": true,
      "search_for_agents": {
        "hostname": "hostname",
        "zone_id": "zone_id",
        "zone_name": "zone_name"
      },
      "worker_domain": "worker_domain"
    },
    "modified_by": "modified_by",
    "namespace": "namespace",
    "paused": true,
    "public_endpoint_id": "public_endpoint_id",
    "public_endpoint_params": {
      "authorized_hosts": [
        "string"
      ],
      "chat_completions_endpoint": {
        "disabled": true
      },
      "enabled": true,
      "mcp": {
        "description": "description",
        "disabled": true
      },
      "rate_limit": {
        "period_ms": 60000,
        "requests": 1,
        "technique": "fixed"
      },
      "search_endpoint": {
        "disabled": true
      }
    },
    "reranking": true,
    "reranking_model": "@cf/baai/bge-reranker-base",
    "retrieval_options": {
      "boost_by": [
        {
          "field": "timestamp",
          "direction": "desc"
        }
      ],
      "keyword_match_mode": "and"
    },
    "rewrite_model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "rewrite_query": true,
    "score_threshold": 0,
    "source": "source",
    "source_params": {
      "exclude_items": [
        "/admin/**",
        "/private/**",
        "**\\temp\\**"
      ],
      "include_items": [
        "/blog/**",
        "/docs/**/*.html",
        "**\\blog\\**.html"
      ],
      "prefix": "prefix",
      "r2_jurisdiction": "r2_jurisdiction",
      "web_crawler": {
        "crawl_options": {
          "depth": 1,
          "include_external_links": true,
          "include_subdomains": true,
          "max_age": 0,
          "source": "all"
        },
        "parse_options": {
          "content_selector": [
            {
              "path": "**/blog/**",
              "selector": "article .post-body"
            }
          ],
          "include_headers": {
            "foo": "string"
          },
          "include_images": true,
          "specific_sitemaps": [
            "https://example.com/sitemap.xml",
            "https://example.com/blog-sitemap.xml"
          ],
          "use_browser_rendering": true
        },
        "parse_type": "sitemap",
        "store_options": {
          "storage_id": "storage_id",
          "r2_jurisdiction": "r2_jurisdiction",
          "storage_type": "r2"
        }
      }
    },
    "status": "status",
    "sync_interval": 3600,
    "token_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "type": "r2"
  },
  "success": true
}
```

## Update instances.

**put** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}`

Update instances.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Body Parameters

- `ai_gateway_id: optional string`

- `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

  - `"@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"`

  - `"@cf/google/gemma-4-26b-a4b-it"`

  - `"@cf/moonshotai/kimi-k2.5"`

  - `"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"`

  - `""`

- `cache: optional boolean`

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

  - `"super_strict_match"`

  - `"close_enough"`

  - `"flexible_friend"`

  - `"anything_goes"`

- `chunk: optional boolean`

- `chunk_overlap: optional number`

- `chunk_size: optional number`

- `custom_metadata: optional array of  { data_type, field_name }`

  - `data_type: "text" or "number" or "boolean" or "datetime"`

    - `"text"`

    - `"number"`

    - `"boolean"`

    - `"datetime"`

  - `field_name: string`

- `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

  - `"@cf/qwen/qwen3-embedding-0.6b"`

  - `"@cf/baai/bge-m3"`

  - `"@cf/baai/bge-large-en-v1.5"`

  - `"@cf/google/embeddinggemma-300m"`

  - `"google-ai-studio/gemini-embedding-001"`

  - `"google-ai-studio/gemini-embedding-2-preview"`

  - `"openai/text-embedding-3-small"`

  - `"openai/text-embedding-3-large"`

  - `""`

- `fusion_method: optional "max" or "rrf"`

  - `"max"`

  - `"rrf"`

- `index_method: optional  { keyword, vector }`

  Controls which storage backends are used during indexing. Defaults to vector-only.

  - `keyword: boolean`

    Enable keyword (BM25) storage backend.

  - `vector: boolean`

    Enable vector (embedding) storage backend.

- `indexing_options: optional  { keyword_tokenizer }`

  - `keyword_tokenizer: optional "porter" or "trigram"`

    Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

    - `"porter"`

    - `"trigram"`

- `max_num_results: optional number`

- `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

  - `created_from_aisearch_wizard: optional boolean`

  - `search_for_agents: optional  { hostname, zone_id, zone_name }`

    - `hostname: string`

    - `zone_id: string`

    - `zone_name: string`

  - `worker_domain: optional string`

- `paused: optional boolean`

- `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

  - `authorized_hosts: optional array of string`

  - `chat_completions_endpoint: optional  { disabled }`

    - `disabled: optional boolean`

      Disable chat completions endpoint for this public endpoint

  - `enabled: optional boolean`

  - `mcp: optional  { description, disabled }`

    - `description: optional string`

    - `disabled: optional boolean`

      Disable MCP endpoint for this public endpoint

  - `rate_limit: optional  { period_ms, requests, technique }`

    - `period_ms: optional number`

    - `requests: optional number`

    - `technique: optional "fixed" or "sliding"`

      - `"fixed"`

      - `"sliding"`

  - `search_endpoint: optional  { disabled }`

    - `disabled: optional boolean`

      Disable search endpoint for this public endpoint

- `reranking: optional boolean`

- `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

  - `"@cf/baai/bge-reranker-base"`

  - `""`

- `retrieval_options: optional  { boost_by, keyword_match_mode }`

  - `boost_by: optional array of  { field, direction }`

    Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

      - `"asc"`

      - `"desc"`

      - `"exists"`

      - `"not_exists"`

  - `keyword_match_mode: optional "and" or "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'.

    - `"and"`

    - `"or"`

- `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

  - `"@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"`

  - `"@cf/google/gemma-4-26b-a4b-it"`

  - `"@cf/moonshotai/kimi-k2.5"`

  - `"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_query: optional boolean`

- `score_threshold: optional number`

- `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

  - `exclude_items: optional array of string`

    List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

  - `include_items: optional array of string`

    List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

  - `prefix: optional string`

  - `r2_jurisdiction: optional string`

  - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

    - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

      - `depth: optional number`

      - `include_external_links: optional boolean`

      - `include_subdomains: optional boolean`

      - `max_age: optional number`

      - `source: optional "all" or "sitemaps" or "links"`

        - `"all"`

        - `"sitemaps"`

        - `"links"`

    - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

      - `content_selector: optional array of  { path, selector }`

        List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

        - `path: string`

          Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

        - `selector: string`

          CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

      - `include_headers: optional map[string]`

      - `include_images: optional boolean`

      - `specific_sitemaps: optional array of string`

        List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

      - `use_browser_rendering: optional boolean`

    - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

      - `"sitemap"`

      - `"feed-rss"`

      - `"crawl"`

    - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

      - `storage_id: string`

      - `r2_jurisdiction: optional string`

      - `storage_type: optional Provider`

        - `"r2"`

- `summarization: optional boolean`

- `summarization_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

  - `"@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"`

  - `"@cf/google/gemma-4-26b-a4b-it"`

  - `"@cf/moonshotai/kimi-k2.5"`

  - `"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"`

  - `""`

- `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

  Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

  - `3600`

  - `7200`

  - `14400`

  - `21600`

  - `43200`

  - `86400`

- `system_prompt_ai_search: optional string`

- `system_prompt_index_summarization: optional string`

- `system_prompt_rewrite_query: optional string`

- `token_id: optional string`

### Returns

- `result:  { id, created_at, modified_at, 35 more }`

  - `id: string`

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

  - `created_at: string`

  - `modified_at: string`

  - `ai_gateway_id: optional string`

  - `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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"`

    - `""`

  - `cache: optional boolean`

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

    - `"super_strict_match"`

    - `"close_enough"`

    - `"flexible_friend"`

    - `"anything_goes"`

  - `chunk_overlap: optional number`

  - `chunk_size: optional number`

  - `created_by: optional string`

  - `custom_metadata: optional array of  { data_type, field_name }`

    - `data_type: "text" or "number" or "boolean" or "datetime"`

      - `"text"`

      - `"number"`

      - `"boolean"`

      - `"datetime"`

    - `field_name: string`

  - `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

    - `"@cf/qwen/qwen3-embedding-0.6b"`

    - `"@cf/baai/bge-m3"`

    - `"@cf/baai/bge-large-en-v1.5"`

    - `"@cf/google/embeddinggemma-300m"`

    - `"google-ai-studio/gemini-embedding-001"`

    - `"google-ai-studio/gemini-embedding-2-preview"`

    - `"openai/text-embedding-3-small"`

    - `"openai/text-embedding-3-large"`

    - `""`

  - `enable: optional boolean`

  - `engine_version: optional number`

  - `fusion_method: optional "max" or "rrf"`

    - `"max"`

    - `"rrf"`

  - `hybrid_search_enabled: optional boolean`

    Deprecated — use index_method instead.

  - `index_method: optional  { keyword, vector }`

    Controls which storage backends are used during indexing. Defaults to vector-only.

    - `keyword: boolean`

      Enable keyword (BM25) storage backend.

    - `vector: boolean`

      Enable vector (embedding) storage backend.

  - `indexing_options: optional  { keyword_tokenizer }`

    - `keyword_tokenizer: optional "porter" or "trigram"`

      Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

      - `"porter"`

      - `"trigram"`

  - `last_activity: optional string`

  - `max_num_results: optional number`

  - `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

    - `created_from_aisearch_wizard: optional boolean`

    - `search_for_agents: optional  { hostname, zone_id, zone_name }`

      - `hostname: string`

      - `zone_id: string`

      - `zone_name: string`

    - `worker_domain: optional string`

  - `modified_by: optional string`

  - `namespace: optional string`

  - `paused: optional boolean`

  - `public_endpoint_id: optional string`

  - `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

    - `authorized_hosts: optional array of string`

    - `chat_completions_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable chat completions endpoint for this public endpoint

    - `enabled: optional boolean`

    - `mcp: optional  { description, disabled }`

      - `description: optional string`

      - `disabled: optional boolean`

        Disable MCP endpoint for this public endpoint

    - `rate_limit: optional  { period_ms, requests, technique }`

      - `period_ms: optional number`

      - `requests: optional number`

      - `technique: optional "fixed" or "sliding"`

        - `"fixed"`

        - `"sliding"`

    - `search_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable search endpoint for this public endpoint

  - `reranking: optional boolean`

  - `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

    - `"@cf/baai/bge-reranker-base"`

    - `""`

  - `retrieval_options: optional  { boost_by, keyword_match_mode }`

    - `boost_by: optional array of  { field, direction }`

      Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

  - `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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_query: optional boolean`

  - `score_threshold: optional number`

  - `source: optional string`

  - `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

    - `exclude_items: optional array of string`

      List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

    - `include_items: optional array of string`

      List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

    - `prefix: optional string`

    - `r2_jurisdiction: optional string`

    - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

      - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

        - `depth: optional number`

        - `include_external_links: optional boolean`

        - `include_subdomains: optional boolean`

        - `max_age: optional number`

        - `source: optional "all" or "sitemaps" or "links"`

          - `"all"`

          - `"sitemaps"`

          - `"links"`

      - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

        - `content_selector: optional array of  { path, selector }`

          List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

          - `path: string`

            Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

          - `selector: string`

            CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

        - `include_headers: optional map[string]`

        - `include_images: optional boolean`

        - `specific_sitemaps: optional array of string`

          List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

        - `use_browser_rendering: optional boolean`

      - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

        - `"sitemap"`

        - `"feed-rss"`

        - `"crawl"`

      - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

        - `storage_id: string`

        - `r2_jurisdiction: optional string`

        - `storage_type: optional Provider`

          - `"r2"`

  - `status: optional string`

  - `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

    Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

    - `3600`

    - `7200`

    - `14400`

    - `21600`

    - `43200`

    - `86400`

  - `token_id: optional string`

  - `type: optional "r2" or "web-crawler"`

    - `"r2"`

    - `"web-crawler"`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID \
    -X PUT \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "id": "my-ai-search",
    "created_at": "2019-12-27T18:11:19.117Z",
    "modified_at": "2019-12-27T18:11:19.117Z",
    "ai_gateway_id": "ai_gateway_id",
    "ai_search_model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "cache": true,
    "cache_threshold": "super_strict_match",
    "chunk_overlap": 0,
    "chunk_size": 64,
    "created_by": "created_by",
    "custom_metadata": [
      {
        "data_type": "text",
        "field_name": "x"
      }
    ],
    "embedding_model": "@cf/qwen/qwen3-embedding-0.6b",
    "enable": true,
    "engine_version": 0,
    "fusion_method": "max",
    "hybrid_search_enabled": true,
    "index_method": {
      "keyword": true,
      "vector": true
    },
    "indexing_options": {
      "keyword_tokenizer": "porter"
    },
    "last_activity": "2019-12-27T18:11:19.117Z",
    "max_num_results": 1,
    "metadata": {
      "created_from_aisearch_wizard": true,
      "search_for_agents": {
        "hostname": "hostname",
        "zone_id": "zone_id",
        "zone_name": "zone_name"
      },
      "worker_domain": "worker_domain"
    },
    "modified_by": "modified_by",
    "namespace": "namespace",
    "paused": true,
    "public_endpoint_id": "public_endpoint_id",
    "public_endpoint_params": {
      "authorized_hosts": [
        "string"
      ],
      "chat_completions_endpoint": {
        "disabled": true
      },
      "enabled": true,
      "mcp": {
        "description": "description",
        "disabled": true
      },
      "rate_limit": {
        "period_ms": 60000,
        "requests": 1,
        "technique": "fixed"
      },
      "search_endpoint": {
        "disabled": true
      }
    },
    "reranking": true,
    "reranking_model": "@cf/baai/bge-reranker-base",
    "retrieval_options": {
      "boost_by": [
        {
          "field": "timestamp",
          "direction": "desc"
        }
      ],
      "keyword_match_mode": "and"
    },
    "rewrite_model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "rewrite_query": true,
    "score_threshold": 0,
    "source": "source",
    "source_params": {
      "exclude_items": [
        "/admin/**",
        "/private/**",
        "**\\temp\\**"
      ],
      "include_items": [
        "/blog/**",
        "/docs/**/*.html",
        "**\\blog\\**.html"
      ],
      "prefix": "prefix",
      "r2_jurisdiction": "r2_jurisdiction",
      "web_crawler": {
        "crawl_options": {
          "depth": 1,
          "include_external_links": true,
          "include_subdomains": true,
          "max_age": 0,
          "source": "all"
        },
        "parse_options": {
          "content_selector": [
            {
              "path": "**/blog/**",
              "selector": "article .post-body"
            }
          ],
          "include_headers": {
            "foo": "string"
          },
          "include_images": true,
          "specific_sitemaps": [
            "https://example.com/sitemap.xml",
            "https://example.com/blog-sitemap.xml"
          ],
          "use_browser_rendering": true
        },
        "parse_type": "sitemap",
        "store_options": {
          "storage_id": "storage_id",
          "r2_jurisdiction": "r2_jurisdiction",
          "storage_type": "r2"
        }
      }
    },
    "status": "status",
    "sync_interval": 3600,
    "token_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "type": "r2"
  },
  "success": true
}
```

## Delete instances.

**delete** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}`

Delete instances.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Returns

- `result:  { id, created_at, modified_at, 35 more }`

  - `id: string`

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

  - `created_at: string`

  - `modified_at: string`

  - `ai_gateway_id: optional string`

  - `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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"`

    - `""`

  - `cache: optional boolean`

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

    - `"super_strict_match"`

    - `"close_enough"`

    - `"flexible_friend"`

    - `"anything_goes"`

  - `chunk_overlap: optional number`

  - `chunk_size: optional number`

  - `created_by: optional string`

  - `custom_metadata: optional array of  { data_type, field_name }`

    - `data_type: "text" or "number" or "boolean" or "datetime"`

      - `"text"`

      - `"number"`

      - `"boolean"`

      - `"datetime"`

    - `field_name: string`

  - `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

    - `"@cf/qwen/qwen3-embedding-0.6b"`

    - `"@cf/baai/bge-m3"`

    - `"@cf/baai/bge-large-en-v1.5"`

    - `"@cf/google/embeddinggemma-300m"`

    - `"google-ai-studio/gemini-embedding-001"`

    - `"google-ai-studio/gemini-embedding-2-preview"`

    - `"openai/text-embedding-3-small"`

    - `"openai/text-embedding-3-large"`

    - `""`

  - `enable: optional boolean`

  - `engine_version: optional number`

  - `fusion_method: optional "max" or "rrf"`

    - `"max"`

    - `"rrf"`

  - `hybrid_search_enabled: optional boolean`

    Deprecated — use index_method instead.

  - `index_method: optional  { keyword, vector }`

    Controls which storage backends are used during indexing. Defaults to vector-only.

    - `keyword: boolean`

      Enable keyword (BM25) storage backend.

    - `vector: boolean`

      Enable vector (embedding) storage backend.

  - `indexing_options: optional  { keyword_tokenizer }`

    - `keyword_tokenizer: optional "porter" or "trigram"`

      Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

      - `"porter"`

      - `"trigram"`

  - `last_activity: optional string`

  - `max_num_results: optional number`

  - `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

    - `created_from_aisearch_wizard: optional boolean`

    - `search_for_agents: optional  { hostname, zone_id, zone_name }`

      - `hostname: string`

      - `zone_id: string`

      - `zone_name: string`

    - `worker_domain: optional string`

  - `modified_by: optional string`

  - `namespace: optional string`

  - `paused: optional boolean`

  - `public_endpoint_id: optional string`

  - `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

    - `authorized_hosts: optional array of string`

    - `chat_completions_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable chat completions endpoint for this public endpoint

    - `enabled: optional boolean`

    - `mcp: optional  { description, disabled }`

      - `description: optional string`

      - `disabled: optional boolean`

        Disable MCP endpoint for this public endpoint

    - `rate_limit: optional  { period_ms, requests, technique }`

      - `period_ms: optional number`

      - `requests: optional number`

      - `technique: optional "fixed" or "sliding"`

        - `"fixed"`

        - `"sliding"`

    - `search_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable search endpoint for this public endpoint

  - `reranking: optional boolean`

  - `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

    - `"@cf/baai/bge-reranker-base"`

    - `""`

  - `retrieval_options: optional  { boost_by, keyword_match_mode }`

    - `boost_by: optional array of  { field, direction }`

      Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

  - `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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_query: optional boolean`

  - `score_threshold: optional number`

  - `source: optional string`

  - `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

    - `exclude_items: optional array of string`

      List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

    - `include_items: optional array of string`

      List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

    - `prefix: optional string`

    - `r2_jurisdiction: optional string`

    - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

      - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

        - `depth: optional number`

        - `include_external_links: optional boolean`

        - `include_subdomains: optional boolean`

        - `max_age: optional number`

        - `source: optional "all" or "sitemaps" or "links"`

          - `"all"`

          - `"sitemaps"`

          - `"links"`

      - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

        - `content_selector: optional array of  { path, selector }`

          List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

          - `path: string`

            Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

          - `selector: string`

            CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

        - `include_headers: optional map[string]`

        - `include_images: optional boolean`

        - `specific_sitemaps: optional array of string`

          List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

        - `use_browser_rendering: optional boolean`

      - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

        - `"sitemap"`

        - `"feed-rss"`

        - `"crawl"`

      - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

        - `storage_id: string`

        - `r2_jurisdiction: optional string`

        - `storage_type: optional Provider`

          - `"r2"`

  - `status: optional string`

  - `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

    Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

    - `3600`

    - `7200`

    - `14400`

    - `21600`

    - `43200`

    - `86400`

  - `token_id: optional string`

  - `type: optional "r2" or "web-crawler"`

    - `"r2"`

    - `"web-crawler"`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID \
    -X DELETE \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "id": "my-ai-search",
    "created_at": "2019-12-27T18:11:19.117Z",
    "modified_at": "2019-12-27T18:11:19.117Z",
    "ai_gateway_id": "ai_gateway_id",
    "ai_search_model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "cache": true,
    "cache_threshold": "super_strict_match",
    "chunk_overlap": 0,
    "chunk_size": 64,
    "created_by": "created_by",
    "custom_metadata": [
      {
        "data_type": "text",
        "field_name": "x"
      }
    ],
    "embedding_model": "@cf/qwen/qwen3-embedding-0.6b",
    "enable": true,
    "engine_version": 0,
    "fusion_method": "max",
    "hybrid_search_enabled": true,
    "index_method": {
      "keyword": true,
      "vector": true
    },
    "indexing_options": {
      "keyword_tokenizer": "porter"
    },
    "last_activity": "2019-12-27T18:11:19.117Z",
    "max_num_results": 1,
    "metadata": {
      "created_from_aisearch_wizard": true,
      "search_for_agents": {
        "hostname": "hostname",
        "zone_id": "zone_id",
        "zone_name": "zone_name"
      },
      "worker_domain": "worker_domain"
    },
    "modified_by": "modified_by",
    "namespace": "namespace",
    "paused": true,
    "public_endpoint_id": "public_endpoint_id",
    "public_endpoint_params": {
      "authorized_hosts": [
        "string"
      ],
      "chat_completions_endpoint": {
        "disabled": true
      },
      "enabled": true,
      "mcp": {
        "description": "description",
        "disabled": true
      },
      "rate_limit": {
        "period_ms": 60000,
        "requests": 1,
        "technique": "fixed"
      },
      "search_endpoint": {
        "disabled": true
      }
    },
    "reranking": true,
    "reranking_model": "@cf/baai/bge-reranker-base",
    "retrieval_options": {
      "boost_by": [
        {
          "field": "timestamp",
          "direction": "desc"
        }
      ],
      "keyword_match_mode": "and"
    },
    "rewrite_model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "rewrite_query": true,
    "score_threshold": 0,
    "source": "source",
    "source_params": {
      "exclude_items": [
        "/admin/**",
        "/private/**",
        "**\\temp\\**"
      ],
      "include_items": [
        "/blog/**",
        "/docs/**/*.html",
        "**\\blog\\**.html"
      ],
      "prefix": "prefix",
      "r2_jurisdiction": "r2_jurisdiction",
      "web_crawler": {
        "crawl_options": {
          "depth": 1,
          "include_external_links": true,
          "include_subdomains": true,
          "max_age": 0,
          "source": "all"
        },
        "parse_options": {
          "content_selector": [
            {
              "path": "**/blog/**",
              "selector": "article .post-body"
            }
          ],
          "include_headers": {
            "foo": "string"
          },
          "include_images": true,
          "specific_sitemaps": [
            "https://example.com/sitemap.xml",
            "https://example.com/blog-sitemap.xml"
          ],
          "use_browser_rendering": true
        },
        "parse_type": "sitemap",
        "store_options": {
          "storage_id": "storage_id",
          "r2_jurisdiction": "r2_jurisdiction",
          "storage_type": "r2"
        }
      }
    },
    "status": "status",
    "sync_interval": 3600,
    "token_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "type": "r2"
  },
  "success": true
}
```

## Stats

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/stats`

Retrieves usage statistics for AI Search instances.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Returns

- `result:  { completed, engine, error, 7 more }`

  - `completed: optional number`

  - `engine: optional  { r2, vectorize }`

    Engine-specific metadata. Present only for managed (v3) instances.

    - `r2: optional  { metadataSizeBytes, objectCount, payloadSizeBytes }`

      R2 bucket storage usage in bytes.

      - `metadataSizeBytes: number`

      - `objectCount: number`

      - `payloadSizeBytes: number`

    - `vectorize: optional  { dimensions, vectorsCount }`

      Vectorize index metadata (dimensions, vector count).

      - `dimensions: number`

      - `vectorsCount: number`

  - `error: optional number`

  - `file_embed_errors: optional map[unknown]`

  - `index_source_errors: optional map[unknown]`

  - `last_activity: optional string`

  - `outdated: optional number`

  - `queued: optional number`

  - `running: optional number`

  - `skipped: optional number`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/stats \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "completed": 0,
    "engine": {
      "r2": {
        "metadataSizeBytes": 0,
        "objectCount": 0,
        "payloadSizeBytes": 0
      },
      "vectorize": {
        "dimensions": 0,
        "vectorsCount": 0
      }
    },
    "error": 0,
    "file_embed_errors": {
      "foo": "bar"
    },
    "index_source_errors": {
      "foo": "bar"
    },
    "last_activity": "2019-12-27T18:11:19.117Z",
    "outdated": 0,
    "queued": 0,
    "running": 0,
    "skipped": 0
  },
  "success": true
}
```

## Search

**post** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/search`

Executes a semantic search query against an AI Search instance to find relevant indexed content.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Body Parameters

- `ai_search_options: optional  { cache, query_rewrite, reranking, retrieval }`

  - `cache: optional  { cache_threshold, enabled }`

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

      - `"super_strict_match"`

      - `"close_enough"`

      - `"flexible_friend"`

      - `"anything_goes"`

    - `enabled: optional boolean`

  - `query_rewrite: optional  { enabled, model, rewrite_prompt }`

    - `enabled: optional boolean`

    - `model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

      - `"@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"`

      - `"@cf/google/gemma-4-26b-a4b-it"`

      - `"@cf/moonshotai/kimi-k2.5"`

      - `"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: optional string`

  - `reranking: optional  { enabled, match_threshold, model }`

    - `enabled: optional boolean`

    - `match_threshold: optional number`

    - `model: optional "@cf/baai/bge-reranker-base" or ""`

      - `"@cf/baai/bge-reranker-base"`

      - `""`

  - `retrieval: optional  { boost_by, context_expansion, filters, 6 more }`

    - `boost_by: optional array of  { 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 asc/desc directions; text/boolean fields support exists/not_exists.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `context_expansion: optional number`

    - `filters: optional map[unknown]`

    - `fusion_method: optional "max" or "rrf"`

      - `"max"`

      - `"rrf"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

    - `match_threshold: optional number`

    - `max_num_results: optional number`

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

      - `"vector"`

      - `"keyword"`

      - `"hybrid"`

    - `return_on_failure: optional boolean`

- `messages: optional array of  { content, role }`

  - `content: string`

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

    - `"system"`

    - `"developer"`

    - `"user"`

    - `"assistant"`

    - `"tool"`

- `query: optional string`

  A simple text query string. Alternative to 'messages' — provide either this or 'messages', not both.

### Returns

- `result:  { chunks, search_query }`

  - `chunks: array of  { id, score, text, 3 more }`

    - `id: string`

    - `score: number`

    - `text: string`

    - `type: string`

    - `item: optional  { key, metadata, timestamp }`

      - `key: string`

      - `metadata: optional map[unknown]`

      - `timestamp: optional number`

    - `scoring_details: optional  { fusion_method, keyword_rank, keyword_score, 3 more }`

      - `fusion_method: optional "rrf" or "max"`

        - `"rrf"`

        - `"max"`

      - `keyword_rank: optional number`

      - `keyword_score: optional number`

      - `reranking_score: optional number`

      - `vector_rank: optional number`

      - `vector_score: optional number`

  - `search_query: string`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/search \
    -X POST \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "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
        }
      }
    ],
    "search_query": "search_query"
  },
  "success": true
}
```

## Chat Completions

**post** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/chat/completions`

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

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Body Parameters

- `messages: array of  { content, role }`

  - `content: string`

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

    - `"system"`

    - `"developer"`

    - `"user"`

    - `"assistant"`

    - `"tool"`

- `ai_search_options: optional  { cache, query_rewrite, reranking, retrieval }`

  - `cache: optional  { cache_threshold, enabled }`

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

      - `"super_strict_match"`

      - `"close_enough"`

      - `"flexible_friend"`

      - `"anything_goes"`

    - `enabled: optional boolean`

  - `query_rewrite: optional  { enabled, model, rewrite_prompt }`

    - `enabled: optional boolean`

    - `model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

      - `"@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"`

      - `"@cf/google/gemma-4-26b-a4b-it"`

      - `"@cf/moonshotai/kimi-k2.5"`

      - `"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: optional string`

  - `reranking: optional  { enabled, match_threshold, model }`

    - `enabled: optional boolean`

    - `match_threshold: optional number`

    - `model: optional "@cf/baai/bge-reranker-base" or ""`

      - `"@cf/baai/bge-reranker-base"`

      - `""`

  - `retrieval: optional  { boost_by, context_expansion, filters, 6 more }`

    - `boost_by: optional array of  { 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 asc/desc directions; text/boolean fields support exists/not_exists.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `context_expansion: optional number`

    - `filters: optional map[unknown]`

    - `fusion_method: optional "max" or "rrf"`

      - `"max"`

      - `"rrf"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

    - `match_threshold: optional number`

    - `max_num_results: optional number`

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

      - `"vector"`

      - `"keyword"`

      - `"hybrid"`

    - `return_on_failure: optional boolean`

- `model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

  - `"@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"`

  - `"@cf/google/gemma-4-26b-a4b-it"`

  - `"@cf/moonshotai/kimi-k2.5"`

  - `"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: optional boolean`

### Returns

- `choices: array of  { message, index }`

  - `message:  { content, role }`

    - `content: string`

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

      - `"system"`

      - `"developer"`

      - `"user"`

      - `"assistant"`

      - `"tool"`

  - `index: optional number`

- `chunks: array of  { id, score, text, 3 more }`

  - `id: string`

  - `score: number`

  - `text: string`

  - `type: string`

  - `item: optional  { key, metadata, timestamp }`

    - `key: string`

    - `metadata: optional map[unknown]`

    - `timestamp: optional number`

  - `scoring_details: optional  { fusion_method, keyword_rank, keyword_score, 3 more }`

    - `fusion_method: optional "rrf" or "max"`

      - `"rrf"`

      - `"max"`

    - `keyword_rank: optional number`

    - `keyword_score: optional number`

    - `reranking_score: optional number`

    - `vector_rank: optional number`

    - `vector_score: optional number`

- `id: optional string`

- `model: optional string`

- `object: optional string`

### Example

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

#### Response

```json
{
  "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"
}
```

## Domain Types

### Instance List Response

- `InstanceListResponse  { id, created_at, modified_at, 35 more }`

  - `id: string`

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

  - `created_at: string`

  - `modified_at: string`

  - `ai_gateway_id: optional string`

  - `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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"`

    - `""`

  - `cache: optional boolean`

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

    - `"super_strict_match"`

    - `"close_enough"`

    - `"flexible_friend"`

    - `"anything_goes"`

  - `chunk_overlap: optional number`

  - `chunk_size: optional number`

  - `created_by: optional string`

  - `custom_metadata: optional array of  { data_type, field_name }`

    - `data_type: "text" or "number" or "boolean" or "datetime"`

      - `"text"`

      - `"number"`

      - `"boolean"`

      - `"datetime"`

    - `field_name: string`

  - `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

    - `"@cf/qwen/qwen3-embedding-0.6b"`

    - `"@cf/baai/bge-m3"`

    - `"@cf/baai/bge-large-en-v1.5"`

    - `"@cf/google/embeddinggemma-300m"`

    - `"google-ai-studio/gemini-embedding-001"`

    - `"google-ai-studio/gemini-embedding-2-preview"`

    - `"openai/text-embedding-3-small"`

    - `"openai/text-embedding-3-large"`

    - `""`

  - `enable: optional boolean`

  - `engine_version: optional number`

  - `fusion_method: optional "max" or "rrf"`

    - `"max"`

    - `"rrf"`

  - `hybrid_search_enabled: optional boolean`

    Deprecated — use index_method instead.

  - `index_method: optional  { keyword, vector }`

    Controls which storage backends are used during indexing. Defaults to vector-only.

    - `keyword: boolean`

      Enable keyword (BM25) storage backend.

    - `vector: boolean`

      Enable vector (embedding) storage backend.

  - `indexing_options: optional  { keyword_tokenizer }`

    - `keyword_tokenizer: optional "porter" or "trigram"`

      Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

      - `"porter"`

      - `"trigram"`

  - `last_activity: optional string`

  - `max_num_results: optional number`

  - `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

    - `created_from_aisearch_wizard: optional boolean`

    - `search_for_agents: optional  { hostname, zone_id, zone_name }`

      - `hostname: string`

      - `zone_id: string`

      - `zone_name: string`

    - `worker_domain: optional string`

  - `modified_by: optional string`

  - `namespace: optional string`

  - `paused: optional boolean`

  - `public_endpoint_id: optional string`

  - `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

    - `authorized_hosts: optional array of string`

    - `chat_completions_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable chat completions endpoint for this public endpoint

    - `enabled: optional boolean`

    - `mcp: optional  { description, disabled }`

      - `description: optional string`

      - `disabled: optional boolean`

        Disable MCP endpoint for this public endpoint

    - `rate_limit: optional  { period_ms, requests, technique }`

      - `period_ms: optional number`

      - `requests: optional number`

      - `technique: optional "fixed" or "sliding"`

        - `"fixed"`

        - `"sliding"`

    - `search_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable search endpoint for this public endpoint

  - `reranking: optional boolean`

  - `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

    - `"@cf/baai/bge-reranker-base"`

    - `""`

  - `retrieval_options: optional  { boost_by, keyword_match_mode }`

    - `boost_by: optional array of  { field, direction }`

      Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

  - `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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_query: optional boolean`

  - `score_threshold: optional number`

  - `source: optional string`

  - `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

    - `exclude_items: optional array of string`

      List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

    - `include_items: optional array of string`

      List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

    - `prefix: optional string`

    - `r2_jurisdiction: optional string`

    - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

      - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

        - `depth: optional number`

        - `include_external_links: optional boolean`

        - `include_subdomains: optional boolean`

        - `max_age: optional number`

        - `source: optional "all" or "sitemaps" or "links"`

          - `"all"`

          - `"sitemaps"`

          - `"links"`

      - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

        - `content_selector: optional array of  { path, selector }`

          List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

          - `path: string`

            Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

          - `selector: string`

            CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

        - `include_headers: optional map[string]`

        - `include_images: optional boolean`

        - `specific_sitemaps: optional array of string`

          List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

        - `use_browser_rendering: optional boolean`

      - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

        - `"sitemap"`

        - `"feed-rss"`

        - `"crawl"`

      - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

        - `storage_id: string`

        - `r2_jurisdiction: optional string`

        - `storage_type: optional Provider`

          - `"r2"`

  - `status: optional string`

  - `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

    Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

    - `3600`

    - `7200`

    - `14400`

    - `21600`

    - `43200`

    - `86400`

  - `token_id: optional string`

  - `type: optional "r2" or "web-crawler"`

    - `"r2"`

    - `"web-crawler"`

### Instance Create Response

- `InstanceCreateResponse  { id, created_at, modified_at, 35 more }`

  - `id: string`

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

  - `created_at: string`

  - `modified_at: string`

  - `ai_gateway_id: optional string`

  - `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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"`

    - `""`

  - `cache: optional boolean`

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

    - `"super_strict_match"`

    - `"close_enough"`

    - `"flexible_friend"`

    - `"anything_goes"`

  - `chunk_overlap: optional number`

  - `chunk_size: optional number`

  - `created_by: optional string`

  - `custom_metadata: optional array of  { data_type, field_name }`

    - `data_type: "text" or "number" or "boolean" or "datetime"`

      - `"text"`

      - `"number"`

      - `"boolean"`

      - `"datetime"`

    - `field_name: string`

  - `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

    - `"@cf/qwen/qwen3-embedding-0.6b"`

    - `"@cf/baai/bge-m3"`

    - `"@cf/baai/bge-large-en-v1.5"`

    - `"@cf/google/embeddinggemma-300m"`

    - `"google-ai-studio/gemini-embedding-001"`

    - `"google-ai-studio/gemini-embedding-2-preview"`

    - `"openai/text-embedding-3-small"`

    - `"openai/text-embedding-3-large"`

    - `""`

  - `enable: optional boolean`

  - `engine_version: optional number`

  - `fusion_method: optional "max" or "rrf"`

    - `"max"`

    - `"rrf"`

  - `hybrid_search_enabled: optional boolean`

    Deprecated — use index_method instead.

  - `index_method: optional  { keyword, vector }`

    Controls which storage backends are used during indexing. Defaults to vector-only.

    - `keyword: boolean`

      Enable keyword (BM25) storage backend.

    - `vector: boolean`

      Enable vector (embedding) storage backend.

  - `indexing_options: optional  { keyword_tokenizer }`

    - `keyword_tokenizer: optional "porter" or "trigram"`

      Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

      - `"porter"`

      - `"trigram"`

  - `last_activity: optional string`

  - `max_num_results: optional number`

  - `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

    - `created_from_aisearch_wizard: optional boolean`

    - `search_for_agents: optional  { hostname, zone_id, zone_name }`

      - `hostname: string`

      - `zone_id: string`

      - `zone_name: string`

    - `worker_domain: optional string`

  - `modified_by: optional string`

  - `namespace: optional string`

  - `paused: optional boolean`

  - `public_endpoint_id: optional string`

  - `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

    - `authorized_hosts: optional array of string`

    - `chat_completions_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable chat completions endpoint for this public endpoint

    - `enabled: optional boolean`

    - `mcp: optional  { description, disabled }`

      - `description: optional string`

      - `disabled: optional boolean`

        Disable MCP endpoint for this public endpoint

    - `rate_limit: optional  { period_ms, requests, technique }`

      - `period_ms: optional number`

      - `requests: optional number`

      - `technique: optional "fixed" or "sliding"`

        - `"fixed"`

        - `"sliding"`

    - `search_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable search endpoint for this public endpoint

  - `reranking: optional boolean`

  - `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

    - `"@cf/baai/bge-reranker-base"`

    - `""`

  - `retrieval_options: optional  { boost_by, keyword_match_mode }`

    - `boost_by: optional array of  { field, direction }`

      Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

  - `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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_query: optional boolean`

  - `score_threshold: optional number`

  - `source: optional string`

  - `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

    - `exclude_items: optional array of string`

      List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

    - `include_items: optional array of string`

      List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

    - `prefix: optional string`

    - `r2_jurisdiction: optional string`

    - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

      - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

        - `depth: optional number`

        - `include_external_links: optional boolean`

        - `include_subdomains: optional boolean`

        - `max_age: optional number`

        - `source: optional "all" or "sitemaps" or "links"`

          - `"all"`

          - `"sitemaps"`

          - `"links"`

      - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

        - `content_selector: optional array of  { path, selector }`

          List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

          - `path: string`

            Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

          - `selector: string`

            CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

        - `include_headers: optional map[string]`

        - `include_images: optional boolean`

        - `specific_sitemaps: optional array of string`

          List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

        - `use_browser_rendering: optional boolean`

      - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

        - `"sitemap"`

        - `"feed-rss"`

        - `"crawl"`

      - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

        - `storage_id: string`

        - `r2_jurisdiction: optional string`

        - `storage_type: optional Provider`

          - `"r2"`

  - `status: optional string`

  - `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

    Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

    - `3600`

    - `7200`

    - `14400`

    - `21600`

    - `43200`

    - `86400`

  - `token_id: optional string`

  - `type: optional "r2" or "web-crawler"`

    - `"r2"`

    - `"web-crawler"`

### Instance Read Response

- `InstanceReadResponse  { id, created_at, modified_at, 35 more }`

  - `id: string`

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

  - `created_at: string`

  - `modified_at: string`

  - `ai_gateway_id: optional string`

  - `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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"`

    - `""`

  - `cache: optional boolean`

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

    - `"super_strict_match"`

    - `"close_enough"`

    - `"flexible_friend"`

    - `"anything_goes"`

  - `chunk_overlap: optional number`

  - `chunk_size: optional number`

  - `created_by: optional string`

  - `custom_metadata: optional array of  { data_type, field_name }`

    - `data_type: "text" or "number" or "boolean" or "datetime"`

      - `"text"`

      - `"number"`

      - `"boolean"`

      - `"datetime"`

    - `field_name: string`

  - `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

    - `"@cf/qwen/qwen3-embedding-0.6b"`

    - `"@cf/baai/bge-m3"`

    - `"@cf/baai/bge-large-en-v1.5"`

    - `"@cf/google/embeddinggemma-300m"`

    - `"google-ai-studio/gemini-embedding-001"`

    - `"google-ai-studio/gemini-embedding-2-preview"`

    - `"openai/text-embedding-3-small"`

    - `"openai/text-embedding-3-large"`

    - `""`

  - `enable: optional boolean`

  - `engine_version: optional number`

  - `fusion_method: optional "max" or "rrf"`

    - `"max"`

    - `"rrf"`

  - `hybrid_search_enabled: optional boolean`

    Deprecated — use index_method instead.

  - `index_method: optional  { keyword, vector }`

    Controls which storage backends are used during indexing. Defaults to vector-only.

    - `keyword: boolean`

      Enable keyword (BM25) storage backend.

    - `vector: boolean`

      Enable vector (embedding) storage backend.

  - `indexing_options: optional  { keyword_tokenizer }`

    - `keyword_tokenizer: optional "porter" or "trigram"`

      Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

      - `"porter"`

      - `"trigram"`

  - `last_activity: optional string`

  - `max_num_results: optional number`

  - `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

    - `created_from_aisearch_wizard: optional boolean`

    - `search_for_agents: optional  { hostname, zone_id, zone_name }`

      - `hostname: string`

      - `zone_id: string`

      - `zone_name: string`

    - `worker_domain: optional string`

  - `modified_by: optional string`

  - `namespace: optional string`

  - `paused: optional boolean`

  - `public_endpoint_id: optional string`

  - `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

    - `authorized_hosts: optional array of string`

    - `chat_completions_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable chat completions endpoint for this public endpoint

    - `enabled: optional boolean`

    - `mcp: optional  { description, disabled }`

      - `description: optional string`

      - `disabled: optional boolean`

        Disable MCP endpoint for this public endpoint

    - `rate_limit: optional  { period_ms, requests, technique }`

      - `period_ms: optional number`

      - `requests: optional number`

      - `technique: optional "fixed" or "sliding"`

        - `"fixed"`

        - `"sliding"`

    - `search_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable search endpoint for this public endpoint

  - `reranking: optional boolean`

  - `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

    - `"@cf/baai/bge-reranker-base"`

    - `""`

  - `retrieval_options: optional  { boost_by, keyword_match_mode }`

    - `boost_by: optional array of  { field, direction }`

      Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

  - `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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_query: optional boolean`

  - `score_threshold: optional number`

  - `source: optional string`

  - `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

    - `exclude_items: optional array of string`

      List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

    - `include_items: optional array of string`

      List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

    - `prefix: optional string`

    - `r2_jurisdiction: optional string`

    - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

      - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

        - `depth: optional number`

        - `include_external_links: optional boolean`

        - `include_subdomains: optional boolean`

        - `max_age: optional number`

        - `source: optional "all" or "sitemaps" or "links"`

          - `"all"`

          - `"sitemaps"`

          - `"links"`

      - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

        - `content_selector: optional array of  { path, selector }`

          List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

          - `path: string`

            Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

          - `selector: string`

            CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

        - `include_headers: optional map[string]`

        - `include_images: optional boolean`

        - `specific_sitemaps: optional array of string`

          List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

        - `use_browser_rendering: optional boolean`

      - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

        - `"sitemap"`

        - `"feed-rss"`

        - `"crawl"`

      - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

        - `storage_id: string`

        - `r2_jurisdiction: optional string`

        - `storage_type: optional Provider`

          - `"r2"`

  - `status: optional string`

  - `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

    Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

    - `3600`

    - `7200`

    - `14400`

    - `21600`

    - `43200`

    - `86400`

  - `token_id: optional string`

  - `type: optional "r2" or "web-crawler"`

    - `"r2"`

    - `"web-crawler"`

### Instance Update Response

- `InstanceUpdateResponse  { id, created_at, modified_at, 35 more }`

  - `id: string`

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

  - `created_at: string`

  - `modified_at: string`

  - `ai_gateway_id: optional string`

  - `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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"`

    - `""`

  - `cache: optional boolean`

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

    - `"super_strict_match"`

    - `"close_enough"`

    - `"flexible_friend"`

    - `"anything_goes"`

  - `chunk_overlap: optional number`

  - `chunk_size: optional number`

  - `created_by: optional string`

  - `custom_metadata: optional array of  { data_type, field_name }`

    - `data_type: "text" or "number" or "boolean" or "datetime"`

      - `"text"`

      - `"number"`

      - `"boolean"`

      - `"datetime"`

    - `field_name: string`

  - `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

    - `"@cf/qwen/qwen3-embedding-0.6b"`

    - `"@cf/baai/bge-m3"`

    - `"@cf/baai/bge-large-en-v1.5"`

    - `"@cf/google/embeddinggemma-300m"`

    - `"google-ai-studio/gemini-embedding-001"`

    - `"google-ai-studio/gemini-embedding-2-preview"`

    - `"openai/text-embedding-3-small"`

    - `"openai/text-embedding-3-large"`

    - `""`

  - `enable: optional boolean`

  - `engine_version: optional number`

  - `fusion_method: optional "max" or "rrf"`

    - `"max"`

    - `"rrf"`

  - `hybrid_search_enabled: optional boolean`

    Deprecated — use index_method instead.

  - `index_method: optional  { keyword, vector }`

    Controls which storage backends are used during indexing. Defaults to vector-only.

    - `keyword: boolean`

      Enable keyword (BM25) storage backend.

    - `vector: boolean`

      Enable vector (embedding) storage backend.

  - `indexing_options: optional  { keyword_tokenizer }`

    - `keyword_tokenizer: optional "porter" or "trigram"`

      Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

      - `"porter"`

      - `"trigram"`

  - `last_activity: optional string`

  - `max_num_results: optional number`

  - `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

    - `created_from_aisearch_wizard: optional boolean`

    - `search_for_agents: optional  { hostname, zone_id, zone_name }`

      - `hostname: string`

      - `zone_id: string`

      - `zone_name: string`

    - `worker_domain: optional string`

  - `modified_by: optional string`

  - `namespace: optional string`

  - `paused: optional boolean`

  - `public_endpoint_id: optional string`

  - `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

    - `authorized_hosts: optional array of string`

    - `chat_completions_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable chat completions endpoint for this public endpoint

    - `enabled: optional boolean`

    - `mcp: optional  { description, disabled }`

      - `description: optional string`

      - `disabled: optional boolean`

        Disable MCP endpoint for this public endpoint

    - `rate_limit: optional  { period_ms, requests, technique }`

      - `period_ms: optional number`

      - `requests: optional number`

      - `technique: optional "fixed" or "sliding"`

        - `"fixed"`

        - `"sliding"`

    - `search_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable search endpoint for this public endpoint

  - `reranking: optional boolean`

  - `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

    - `"@cf/baai/bge-reranker-base"`

    - `""`

  - `retrieval_options: optional  { boost_by, keyword_match_mode }`

    - `boost_by: optional array of  { field, direction }`

      Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

  - `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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_query: optional boolean`

  - `score_threshold: optional number`

  - `source: optional string`

  - `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

    - `exclude_items: optional array of string`

      List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

    - `include_items: optional array of string`

      List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

    - `prefix: optional string`

    - `r2_jurisdiction: optional string`

    - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

      - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

        - `depth: optional number`

        - `include_external_links: optional boolean`

        - `include_subdomains: optional boolean`

        - `max_age: optional number`

        - `source: optional "all" or "sitemaps" or "links"`

          - `"all"`

          - `"sitemaps"`

          - `"links"`

      - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

        - `content_selector: optional array of  { path, selector }`

          List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

          - `path: string`

            Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

          - `selector: string`

            CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

        - `include_headers: optional map[string]`

        - `include_images: optional boolean`

        - `specific_sitemaps: optional array of string`

          List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

        - `use_browser_rendering: optional boolean`

      - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

        - `"sitemap"`

        - `"feed-rss"`

        - `"crawl"`

      - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

        - `storage_id: string`

        - `r2_jurisdiction: optional string`

        - `storage_type: optional Provider`

          - `"r2"`

  - `status: optional string`

  - `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

    Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

    - `3600`

    - `7200`

    - `14400`

    - `21600`

    - `43200`

    - `86400`

  - `token_id: optional string`

  - `type: optional "r2" or "web-crawler"`

    - `"r2"`

    - `"web-crawler"`

### Instance Delete Response

- `InstanceDeleteResponse  { id, created_at, modified_at, 35 more }`

  - `id: string`

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

  - `created_at: string`

  - `modified_at: string`

  - `ai_gateway_id: optional string`

  - `ai_search_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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"`

    - `""`

  - `cache: optional boolean`

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

    - `"super_strict_match"`

    - `"close_enough"`

    - `"flexible_friend"`

    - `"anything_goes"`

  - `chunk_overlap: optional number`

  - `chunk_size: optional number`

  - `created_by: optional string`

  - `custom_metadata: optional array of  { data_type, field_name }`

    - `data_type: "text" or "number" or "boolean" or "datetime"`

      - `"text"`

      - `"number"`

      - `"boolean"`

      - `"datetime"`

    - `field_name: string`

  - `embedding_model: optional "@cf/qwen/qwen3-embedding-0.6b" or "@cf/baai/bge-m3" or "@cf/baai/bge-large-en-v1.5" or 6 more`

    - `"@cf/qwen/qwen3-embedding-0.6b"`

    - `"@cf/baai/bge-m3"`

    - `"@cf/baai/bge-large-en-v1.5"`

    - `"@cf/google/embeddinggemma-300m"`

    - `"google-ai-studio/gemini-embedding-001"`

    - `"google-ai-studio/gemini-embedding-2-preview"`

    - `"openai/text-embedding-3-small"`

    - `"openai/text-embedding-3-large"`

    - `""`

  - `enable: optional boolean`

  - `engine_version: optional number`

  - `fusion_method: optional "max" or "rrf"`

    - `"max"`

    - `"rrf"`

  - `hybrid_search_enabled: optional boolean`

    Deprecated — use index_method instead.

  - `index_method: optional  { keyword, vector }`

    Controls which storage backends are used during indexing. Defaults to vector-only.

    - `keyword: boolean`

      Enable keyword (BM25) storage backend.

    - `vector: boolean`

      Enable vector (embedding) storage backend.

  - `indexing_options: optional  { keyword_tokenizer }`

    - `keyword_tokenizer: optional "porter" or "trigram"`

      Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.

      - `"porter"`

      - `"trigram"`

  - `last_activity: optional string`

  - `max_num_results: optional number`

  - `metadata: optional  { created_from_aisearch_wizard, search_for_agents, worker_domain }`

    - `created_from_aisearch_wizard: optional boolean`

    - `search_for_agents: optional  { hostname, zone_id, zone_name }`

      - `hostname: string`

      - `zone_id: string`

      - `zone_name: string`

    - `worker_domain: optional string`

  - `modified_by: optional string`

  - `namespace: optional string`

  - `paused: optional boolean`

  - `public_endpoint_id: optional string`

  - `public_endpoint_params: optional  { authorized_hosts, chat_completions_endpoint, enabled, 3 more }`

    - `authorized_hosts: optional array of string`

    - `chat_completions_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable chat completions endpoint for this public endpoint

    - `enabled: optional boolean`

    - `mcp: optional  { description, disabled }`

      - `description: optional string`

      - `disabled: optional boolean`

        Disable MCP endpoint for this public endpoint

    - `rate_limit: optional  { period_ms, requests, technique }`

      - `period_ms: optional number`

      - `requests: optional number`

      - `technique: optional "fixed" or "sliding"`

        - `"fixed"`

        - `"sliding"`

    - `search_endpoint: optional  { disabled }`

      - `disabled: optional boolean`

        Disable search endpoint for this public endpoint

  - `reranking: optional boolean`

  - `reranking_model: optional "@cf/baai/bge-reranker-base" or ""`

    - `"@cf/baai/bge-reranker-base"`

    - `""`

  - `retrieval_options: optional  { boost_by, keyword_match_mode }`

    - `boost_by: optional array of  { field, direction }`

      Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric fields and '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.

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

        - `"asc"`

        - `"desc"`

        - `"exists"`

        - `"not_exists"`

    - `keyword_match_mode: optional "and" or "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'.

      - `"and"`

      - `"or"`

  - `rewrite_model: optional "@cf/meta/llama-3.3-70b-instruct-fp8-fast" or "@cf/zai-org/glm-4.7-flash" or "@cf/meta/llama-3.1-8b-instruct-fast" or 27 more`

    - `"@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"`

    - `"@cf/google/gemma-4-26b-a4b-it"`

    - `"@cf/moonshotai/kimi-k2.5"`

    - `"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_query: optional boolean`

  - `score_threshold: optional number`

  - `source: optional string`

  - `source_params: optional  { exclude_items, include_items, prefix, 2 more }`

    - `exclude_items: optional array of string`

      List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced)

    - `include_items: optional array of string`

      List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post)

    - `prefix: optional string`

    - `r2_jurisdiction: optional string`

    - `web_crawler: optional  { crawl_options, parse_options, parse_type, store_options }`

      - `crawl_options: optional  { depth, include_external_links, include_subdomains, 2 more }`

        - `depth: optional number`

        - `include_external_links: optional boolean`

        - `include_subdomains: optional boolean`

        - `max_age: optional number`

        - `source: optional "all" or "sitemaps" or "links"`

          - `"all"`

          - `"sitemaps"`

          - `"links"`

      - `parse_options: optional  { content_selector, include_headers, include_images, 2 more }`

        - `content_selector: optional array of  { path, selector }`

          List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed.

          - `path: string`

            Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.

          - `selector: string`

            CSS selector to extract content from pages matching the path pattern. Supports standard CSS selectors including class, ID, element, and attribute selectors.

        - `include_headers: optional map[string]`

        - `include_images: optional boolean`

        - `specific_sitemaps: optional array of string`

          List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.

        - `use_browser_rendering: optional boolean`

      - `parse_type: optional "sitemap" or "feed-rss" or "crawl"`

        - `"sitemap"`

        - `"feed-rss"`

        - `"crawl"`

      - `store_options: optional  { storage_id, r2_jurisdiction, storage_type }`

        - `storage_id: string`

        - `r2_jurisdiction: optional string`

        - `storage_type: optional Provider`

          - `"r2"`

  - `status: optional string`

  - `sync_interval: optional 3600 or 7200 or 14400 or 3 more`

    Interval between automatic syncs, in seconds. Allowed values: 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).

    - `3600`

    - `7200`

    - `14400`

    - `21600`

    - `43200`

    - `86400`

  - `token_id: optional string`

  - `type: optional "r2" or "web-crawler"`

    - `"r2"`

    - `"web-crawler"`

### Instance Stats Response

- `InstanceStatsResponse  { completed, engine, error, 7 more }`

  - `completed: optional number`

  - `engine: optional  { r2, vectorize }`

    Engine-specific metadata. Present only for managed (v3) instances.

    - `r2: optional  { metadataSizeBytes, objectCount, payloadSizeBytes }`

      R2 bucket storage usage in bytes.

      - `metadataSizeBytes: number`

      - `objectCount: number`

      - `payloadSizeBytes: number`

    - `vectorize: optional  { dimensions, vectorsCount }`

      Vectorize index metadata (dimensions, vector count).

      - `dimensions: number`

      - `vectorsCount: number`

  - `error: optional number`

  - `file_embed_errors: optional map[unknown]`

  - `index_source_errors: optional map[unknown]`

  - `last_activity: optional string`

  - `outdated: optional number`

  - `queued: optional number`

  - `running: optional number`

  - `skipped: optional number`

### Instance Search Response

- `InstanceSearchResponse  { chunks, search_query }`

  - `chunks: array of  { id, score, text, 3 more }`

    - `id: string`

    - `score: number`

    - `text: string`

    - `type: string`

    - `item: optional  { key, metadata, timestamp }`

      - `key: string`

      - `metadata: optional map[unknown]`

      - `timestamp: optional number`

    - `scoring_details: optional  { fusion_method, keyword_rank, keyword_score, 3 more }`

      - `fusion_method: optional "rrf" or "max"`

        - `"rrf"`

        - `"max"`

      - `keyword_rank: optional number`

      - `keyword_score: optional number`

      - `reranking_score: optional number`

      - `vector_rank: optional number`

      - `vector_score: optional number`

  - `search_query: string`

### Instance Chat Completions Response

- `InstanceChatCompletionsResponse  { choices, chunks, id, 2 more }`

  - `choices: array of  { message, index }`

    - `message:  { content, role }`

      - `content: string`

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

        - `"system"`

        - `"developer"`

        - `"user"`

        - `"assistant"`

        - `"tool"`

    - `index: optional number`

  - `chunks: array of  { id, score, text, 3 more }`

    - `id: string`

    - `score: number`

    - `text: string`

    - `type: string`

    - `item: optional  { key, metadata, timestamp }`

      - `key: string`

      - `metadata: optional map[unknown]`

      - `timestamp: optional number`

    - `scoring_details: optional  { fusion_method, keyword_rank, keyword_score, 3 more }`

      - `fusion_method: optional "rrf" or "max"`

        - `"rrf"`

        - `"max"`

      - `keyword_rank: optional number`

      - `keyword_score: optional number`

      - `reranking_score: optional number`

      - `vector_rank: optional number`

      - `vector_score: optional number`

  - `id: optional string`

  - `model: optional string`

  - `object: optional string`

# Jobs

## List Jobs

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs`

Lists indexing jobs for an AI Search instance.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Query Parameters

- `page: optional number`

- `per_page: optional number`

### Returns

- `result: array of  { id, source, description, 4 more }`

  - `id: string`

  - `source: "user" or "schedule"`

    - `"user"`

    - `"schedule"`

  - `description: optional string`

  - `end_reason: optional string`

  - `ended_at: optional string`

  - `last_seen_at: optional string`

  - `started_at: optional string`

- `result_info:  { count, page, per_page, total_count }`

  - `count: number`

  - `page: number`

  - `per_page: number`

  - `total_count: number`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/jobs \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": [
    {
      "id": "id",
      "source": "user",
      "description": "description",
      "end_reason": "end_reason",
      "ended_at": "ended_at",
      "last_seen_at": "last_seen_at",
      "started_at": "started_at"
    }
  ],
  "result_info": {
    "count": 0,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  },
  "success": true
}
```

## Create new job

**post** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs`

Creates a new indexing job for an AI Search instance.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Body Parameters

- `description: optional string`

### Returns

- `result:  { id, source, description, 4 more }`

  - `id: string`

  - `source: "user" or "schedule"`

    - `"user"`

    - `"schedule"`

  - `description: optional string`

  - `end_reason: optional string`

  - `ended_at: optional string`

  - `last_seen_at: optional string`

  - `started_at: optional string`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/jobs \
    -X POST \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "id": "id",
    "source": "user",
    "description": "description",
    "end_reason": "end_reason",
    "ended_at": "ended_at",
    "last_seen_at": "last_seen_at",
    "started_at": "started_at"
  },
  "success": true
}
```

## Get a Job Details

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs/{job_id}`

Retrieves details for a specific AI Search indexing job.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

- `job_id: string`

### Returns

- `result:  { id, source, description, 4 more }`

  - `id: string`

  - `source: "user" or "schedule"`

    - `"user"`

    - `"schedule"`

  - `description: optional string`

  - `end_reason: optional string`

  - `ended_at: optional string`

  - `last_seen_at: optional string`

  - `started_at: optional string`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/jobs/$JOB_ID \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "id": "id",
    "source": "user",
    "description": "description",
    "end_reason": "end_reason",
    "ended_at": "ended_at",
    "last_seen_at": "last_seen_at",
    "started_at": "started_at"
  },
  "success": true
}
```

## Change Job Status

**patch** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs/{job_id}`

Updates the status of an AI Search indexing job.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

- `job_id: string`

### Body Parameters

- `action: "cancel"`

  - `"cancel"`

### Returns

- `result:  { id, source, description, 4 more }`

  - `id: string`

  - `source: "user" or "schedule"`

    - `"user"`

    - `"schedule"`

  - `description: optional string`

  - `end_reason: optional string`

  - `ended_at: optional string`

  - `last_seen_at: optional string`

  - `started_at: optional string`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/jobs/$JOB_ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "action": "cancel"
        }'
```

#### Response

```json
{
  "result": {
    "id": "id",
    "source": "user",
    "description": "description",
    "end_reason": "end_reason",
    "ended_at": "ended_at",
    "last_seen_at": "last_seen_at",
    "started_at": "started_at"
  },
  "success": true
}
```

## List Job Logs

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs/{job_id}/logs`

Lists log entries for an AI Search indexing job.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

- `job_id: string`

### Query Parameters

- `page: optional number`

- `per_page: optional number`

### Returns

- `result: array of  { id, created_at, message, message_type }`

  - `id: number`

  - `created_at: number`

  - `message: string`

  - `message_type: number`

- `result_info:  { count, page, per_page, total_count }`

  - `count: number`

  - `page: number`

  - `per_page: number`

  - `total_count: number`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/jobs/$JOB_ID/logs \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": [
    {
      "id": 0,
      "created_at": 0,
      "message": "message",
      "message_type": 0
    }
  ],
  "result_info": {
    "count": 0,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  },
  "success": true
}
```

## Domain Types

### Job List Response

- `JobListResponse  { id, source, description, 4 more }`

  - `id: string`

  - `source: "user" or "schedule"`

    - `"user"`

    - `"schedule"`

  - `description: optional string`

  - `end_reason: optional string`

  - `ended_at: optional string`

  - `last_seen_at: optional string`

  - `started_at: optional string`

### Job Create Response

- `JobCreateResponse  { id, source, description, 4 more }`

  - `id: string`

  - `source: "user" or "schedule"`

    - `"user"`

    - `"schedule"`

  - `description: optional string`

  - `end_reason: optional string`

  - `ended_at: optional string`

  - `last_seen_at: optional string`

  - `started_at: optional string`

### Job Get Response

- `JobGetResponse  { id, source, description, 4 more }`

  - `id: string`

  - `source: "user" or "schedule"`

    - `"user"`

    - `"schedule"`

  - `description: optional string`

  - `end_reason: optional string`

  - `ended_at: optional string`

  - `last_seen_at: optional string`

  - `started_at: optional string`

### Job Update Response

- `JobUpdateResponse  { id, source, description, 4 more }`

  - `id: string`

  - `source: "user" or "schedule"`

    - `"user"`

    - `"schedule"`

  - `description: optional string`

  - `end_reason: optional string`

  - `ended_at: optional string`

  - `last_seen_at: optional string`

  - `started_at: optional string`

### Job Logs Response

- `JobLogsResponse = array of  { id, created_at, message, message_type }`

  - `id: number`

  - `created_at: number`

  - `message: string`

  - `message_type: number`

# Items

## Items List.

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items`

Lists indexed items in an AI Search instance.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Query Parameters

- `metadata_filter: optional string`

  JSON-encoded metadata filter using Vectorize filter syntax. Examples: {"folder":"reports/"}, {"timestamp":{"$gte":1700000000000}}, {"folder":{"$in":["docs/","reports/"]}}

- `page: optional number`

- `per_page: optional number`

- `search: optional string`

- `sort_by: optional "status" or "modified_at"`

  Sort order for items. "status" (default) sorts by status priority then last_seen_at. "modified_at" sorts by file modification time (most recent first), falling back to created_at.

  - `"status"`

  - `"modified_at"`

- `source: optional string`

  Filter items by source_id. Use "builtin" for uploaded files, or a source identifier like "web-crawler:https://example.com".

- `status: optional "queued" or "running" or "completed" or 3 more`

  - `"queued"`

  - `"running"`

  - `"completed"`

  - `"error"`

  - `"skipped"`

  - `"outdated"`

### Returns

- `result: array of  { id, checksum, chunks_count, 9 more }`

  - `id: string`

  - `checksum: string`

  - `chunks_count: number`

  - `created_at: string`

  - `file_size: number`

  - `key: string`

  - `last_seen_at: string`

  - `namespace: string`

  - `next_action: "INDEX" or "DELETE"`

    - `"INDEX"`

    - `"DELETE"`

  - `source_id: string`

    Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.

  - `status: "queued" or "running" or "completed" or 3 more`

    - `"queued"`

    - `"running"`

    - `"completed"`

    - `"error"`

    - `"skipped"`

    - `"outdated"`

  - `error: optional string`

- `result_info:  { count, page, total_count, per_page }`

  - `count: number`

  - `page: number`

  - `total_count: number`

  - `per_page: optional number`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/items \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": [
    {
      "id": "id",
      "checksum": "checksum",
      "chunks_count": 0,
      "created_at": "2019-12-27T18:11:19.117Z",
      "file_size": 0,
      "key": "key",
      "last_seen_at": "2019-12-27T18:11:19.117Z",
      "namespace": "namespace",
      "next_action": "INDEX",
      "source_id": "source_id",
      "status": "queued",
      "error": "error"
    }
  ],
  "result_info": {
    "count": 0,
    "page": 0,
    "total_count": 0,
    "per_page": 5
  },
  "success": true
}
```

## Upload Item.

**post** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items`

Uploads a file to a managed AI Search instance via multipart/form-data (max 4MB).

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Returns

- `result:  { id, checksum, chunks_count, 9 more }`

  - `id: string`

  - `checksum: string`

  - `chunks_count: number`

  - `created_at: string`

  - `file_size: number`

  - `key: string`

  - `last_seen_at: string`

  - `namespace: string`

  - `next_action: "INDEX" or "DELETE"`

    - `"INDEX"`

    - `"DELETE"`

  - `source_id: string`

    Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.

  - `status: "queued" or "running" or "completed" or 3 more`

    - `"queued"`

    - `"running"`

    - `"completed"`

    - `"error"`

    - `"skipped"`

    - `"outdated"`

  - `error: optional string`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/items \
    -H 'Content-Type: multipart/form-data' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -F file='{"file":"Example data"}'
```

#### Response

```json
{
  "result": {
    "id": "id",
    "checksum": "checksum",
    "chunks_count": 0,
    "created_at": "2019-12-27T18:11:19.117Z",
    "file_size": 0,
    "key": "key",
    "last_seen_at": "2019-12-27T18:11:19.117Z",
    "namespace": "namespace",
    "next_action": "INDEX",
    "source_id": "source_id",
    "status": "queued",
    "error": "error"
  },
  "success": true
}
```

## Create or Update Item.

**put** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items`

Creates or updates an indexed item in an AI Search instance.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

### Body Parameters

- `key: string`

  Item key / filename. Must not exceed 128 characters.

- `next_action: "INDEX"`

  - `"INDEX"`

### Returns

- `result:  { id, checksum, chunks_count, 9 more }`

  - `id: string`

  - `checksum: string`

  - `chunks_count: number`

  - `created_at: string`

  - `file_size: number`

  - `key: string`

  - `last_seen_at: string`

  - `namespace: string`

  - `next_action: "INDEX" or "DELETE"`

    - `"INDEX"`

    - `"DELETE"`

  - `source_id: string`

    Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.

  - `status: "queued" or "running" or "completed" or 3 more`

    - `"queued"`

    - `"running"`

    - `"completed"`

    - `"error"`

    - `"skipped"`

    - `"outdated"`

  - `error: optional string`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/items \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "key": "key",
          "next_action": "INDEX"
        }'
```

#### Response

```json
{
  "result": {
    "id": "id",
    "checksum": "checksum",
    "chunks_count": 0,
    "created_at": "2019-12-27T18:11:19.117Z",
    "file_size": 0,
    "key": "key",
    "last_seen_at": "2019-12-27T18:11:19.117Z",
    "namespace": "namespace",
    "next_action": "INDEX",
    "source_id": "source_id",
    "status": "queued",
    "error": "error"
  },
  "success": true
}
```

## Get Item.

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}`

Retrieves a specific indexed item from an AI Search instance.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

- `item_id: string`

### Returns

- `result:  { id, checksum, chunks_count, 9 more }`

  - `id: string`

  - `checksum: string`

  - `chunks_count: number`

  - `created_at: string`

  - `file_size: number`

  - `key: string`

  - `last_seen_at: string`

  - `namespace: string`

  - `next_action: "INDEX" or "DELETE"`

    - `"INDEX"`

    - `"DELETE"`

  - `source_id: string`

    Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.

  - `status: "queued" or "running" or "completed" or 3 more`

    - `"queued"`

    - `"running"`

    - `"completed"`

    - `"error"`

    - `"skipped"`

    - `"outdated"`

  - `error: optional string`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/items/$ITEM_ID \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "id": "id",
    "checksum": "checksum",
    "chunks_count": 0,
    "created_at": "2019-12-27T18:11:19.117Z",
    "file_size": 0,
    "key": "key",
    "last_seen_at": "2019-12-27T18:11:19.117Z",
    "namespace": "namespace",
    "next_action": "INDEX",
    "source_id": "source_id",
    "status": "queued",
    "error": "error"
  },
  "success": true
}
```

## Sync Item.

**patch** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}`

Syncs an item to an AI Search instance index.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

- `item_id: string`

### Body Parameters

- `next_action: "INDEX"`

  - `"INDEX"`

### Returns

- `result:  { id, checksum, chunks_count, 9 more }`

  - `id: string`

  - `checksum: string`

  - `chunks_count: number`

  - `created_at: string`

  - `file_size: number`

  - `key: string`

  - `last_seen_at: string`

  - `namespace: string`

  - `next_action: "INDEX" or "DELETE"`

    - `"INDEX"`

    - `"DELETE"`

  - `source_id: string`

    Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.

  - `status: "queued" or "running" or "completed" or 3 more`

    - `"queued"`

    - `"running"`

    - `"completed"`

    - `"error"`

    - `"skipped"`

    - `"outdated"`

  - `error: optional string`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/items/$ITEM_ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "next_action": "INDEX"
        }'
```

#### Response

```json
{
  "result": {
    "id": "id",
    "checksum": "checksum",
    "chunks_count": 0,
    "created_at": "2019-12-27T18:11:19.117Z",
    "file_size": 0,
    "key": "key",
    "last_seen_at": "2019-12-27T18:11:19.117Z",
    "namespace": "namespace",
    "next_action": "INDEX",
    "source_id": "source_id",
    "status": "queued",
    "error": "error"
  },
  "success": true
}
```

## Delete Item.

**delete** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}`

Deletes a file from a managed AI Search instance and triggers a reindex.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

- `item_id: string`

### Returns

- `result:  { key }`

  - `key: string`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/items/$ITEM_ID \
    -X DELETE \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": {
    "key": "key"
  },
  "success": true
}
```

## Download Item Content.

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}/download`

Downloads the raw file content for a specific item from the managed AI Search instance storage.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

- `item_id: string`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/items/$ITEM_ID/download \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

## Item Logs.

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}/logs`

Lists processing logs for a specific item in an AI Search instance.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

- `item_id: string`

### Query Parameters

- `cursor: optional string`

- `limit: optional number`

### Returns

- `result: array of  { action, chunkCount, errorType, 4 more }`

  - `action: string`

  - `chunkCount: number`

  - `errorType: string`

  - `fileKey: string`

  - `message: string`

  - `processingTimeMs: number`

  - `timestamp: string`

- `result_info:  { count, cursor, per_page, truncated }`

  - `count: number`

  - `cursor: string`

  - `per_page: number`

  - `truncated: boolean`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/items/$ITEM_ID/logs \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": [
    {
      "action": "action",
      "chunkCount": 0,
      "errorType": "errorType",
      "fileKey": "fileKey",
      "message": "message",
      "processingTimeMs": 0,
      "timestamp": "2019-12-27T18:11:19.117Z"
    }
  ],
  "result_info": {
    "count": 0,
    "cursor": "cursor",
    "per_page": 0,
    "truncated": true
  },
  "success": true
}
```

## List Item Chunks.

**get** `/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}/chunks`

Lists chunks for a specific item in an AI Search instance, including their text content.

### Path Parameters

- `account_id: optional string`

- `name: string`

- `id: string`

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

- `item_id: string`

### Query Parameters

- `limit: optional number`

- `offset: optional number`

### Returns

- `result: array of  { id, item, text, 2 more }`

  - `id: string`

  - `item:  { key, metadata, timestamp }`

    - `key: string`

    - `metadata: optional map[unknown]`

    - `timestamp: optional number`

  - `text: string`

  - `end_byte: optional number`

  - `start_byte: optional number`

- `result_info:  { count, limit, offset, total }`

  - `count: number`

  - `limit: number`

  - `offset: number`

  - `total: number`

- `success: boolean`

### Example

```http
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/namespaces/$NAME/instances/$ID/items/$ITEM_ID/chunks \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

#### Response

```json
{
  "result": [
    {
      "id": "id",
      "item": {
        "key": "key",
        "metadata": {
          "foo": "bar"
        },
        "timestamp": 0
      },
      "text": "text",
      "end_byte": 0,
      "start_byte": 0
    }
  ],
  "result_info": {
    "count": 0,
    "limit": 0,
    "offset": 0,
    "total": 0
  },
  "success": true
}
```

## Domain Types

### Item List Response

- `ItemListResponse  { id, checksum, chunks_count, 9 more }`

  - `id: string`

  - `checksum: string`

  - `chunks_count: number`

  - `created_at: string`

  - `file_size: number`

  - `key: string`

  - `last_seen_at: string`

  - `namespace: string`

  - `next_action: "INDEX" or "DELETE"`

    - `"INDEX"`

    - `"DELETE"`

  - `source_id: string`

    Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.

  - `status: "queued" or "running" or "completed" or 3 more`

    - `"queued"`

    - `"running"`

    - `"completed"`

    - `"error"`

    - `"skipped"`

    - `"outdated"`

  - `error: optional string`

### Item Upload Response

- `ItemUploadResponse  { id, checksum, chunks_count, 9 more }`

  - `id: string`

  - `checksum: string`

  - `chunks_count: number`

  - `created_at: string`

  - `file_size: number`

  - `key: string`

  - `last_seen_at: string`

  - `namespace: string`

  - `next_action: "INDEX" or "DELETE"`

    - `"INDEX"`

    - `"DELETE"`

  - `source_id: string`

    Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.

  - `status: "queued" or "running" or "completed" or 3 more`

    - `"queued"`

    - `"running"`

    - `"completed"`

    - `"error"`

    - `"skipped"`

    - `"outdated"`

  - `error: optional string`

### Item Create Or Update Response

- `ItemCreateOrUpdateResponse  { id, checksum, chunks_count, 9 more }`

  - `id: string`

  - `checksum: string`

  - `chunks_count: number`

  - `created_at: string`

  - `file_size: number`

  - `key: string`

  - `last_seen_at: string`

  - `namespace: string`

  - `next_action: "INDEX" or "DELETE"`

    - `"INDEX"`

    - `"DELETE"`

  - `source_id: string`

    Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.

  - `status: "queued" or "running" or "completed" or 3 more`

    - `"queued"`

    - `"running"`

    - `"completed"`

    - `"error"`

    - `"skipped"`

    - `"outdated"`

  - `error: optional string`

### Item Get Response

- `ItemGetResponse  { id, checksum, chunks_count, 9 more }`

  - `id: string`

  - `checksum: string`

  - `chunks_count: number`

  - `created_at: string`

  - `file_size: number`

  - `key: string`

  - `last_seen_at: string`

  - `namespace: string`

  - `next_action: "INDEX" or "DELETE"`

    - `"INDEX"`

    - `"DELETE"`

  - `source_id: string`

    Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.

  - `status: "queued" or "running" or "completed" or 3 more`

    - `"queued"`

    - `"running"`

    - `"completed"`

    - `"error"`

    - `"skipped"`

    - `"outdated"`

  - `error: optional string`

### Item Sync Response

- `ItemSyncResponse  { id, checksum, chunks_count, 9 more }`

  - `id: string`

  - `checksum: string`

  - `chunks_count: number`

  - `created_at: string`

  - `file_size: number`

  - `key: string`

  - `last_seen_at: string`

  - `namespace: string`

  - `next_action: "INDEX" or "DELETE"`

    - `"INDEX"`

    - `"DELETE"`

  - `source_id: string`

    Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.

  - `status: "queued" or "running" or "completed" or 3 more`

    - `"queued"`

    - `"running"`

    - `"completed"`

    - `"error"`

    - `"skipped"`

    - `"outdated"`

  - `error: optional string`

### Item Delete Response

- `ItemDeleteResponse  { key }`

  - `key: string`

### Item Logs Response

- `ItemLogsResponse = array of  { action, chunkCount, errorType, 4 more }`

  - `action: string`

  - `chunkCount: number`

  - `errorType: string`

  - `fileKey: string`

  - `message: string`

  - `processingTimeMs: number`

  - `timestamp: string`

### Item Chunks Response

- `ItemChunksResponse = array of  { id, item, text, 2 more }`

  - `id: string`

  - `item:  { key, metadata, timestamp }`

    - `key: string`

    - `metadata: optional map[unknown]`

    - `timestamp: optional number`

  - `text: string`

  - `end_byte: optional number`

  - `start_byte: optional number`