Namespace public endpoints

A namespace can expose its own public endpoint. A single URL then searches across several instances in that namespace and merges the results. Use one when a single search experience covers content that lives in several instances, such as documentation, a blog, and a support portal.

A namespace endpoint serves the same paths and takes the same settings as an instance endpoint, including custom domains and Cloudflare Access. Refer to Public endpoint settings. This page covers what is specific to namespaces.

Set public_endpoint_params on the namespace and list the instances to expose in instances_allowed.

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_endpoint_params": {
      "enabled": true,
      "instances_allowed": ["docs", "blog", "support"]
    }
  }'

The response returns the generated public_endpoint_id. A namespace hostname is prefixed with ns-:

https://ns-<NAMESPACE_ENDPOINT_ID>.search.ai.cloudflare.com/search

Enabling a namespace endpoint does not change the instance endpoints inside it. Each is enabled and disabled separately.

instances_allowed controls which instances the endpoint can reach.

• Every entry must be an existing instance in that namespace. An unknown entry returns error 7097.
• The list holds up to 10 instances.
• An empty list means nothing is searchable. This is the state a namespace starts in when you first enable the endpoint.
• Deleting an instance, or moving it to another namespace, removes it from the allowlist.

A request that resolves to no searchable instance returns a 404 with error 60013. This response is identical whether the instance does not exist, is outside the allowlist, or the allowlist is empty, so callers cannot discover which instances a namespace contains.

By default, a request searches every instance in the allowlist. To narrow a single request, set ai_search_options.instance_ids in the request body.

curl https://ns-<NAMESPACE_ENDPOINT_ID>.search.ai.cloudflare.com/search \
  --header "Content-Type: application/json" \
  --data '{
    "messages": [
      {
        "content": "How do I configure AI Search?",
        "role": "user"
      }
    ],
    "ai_search_options": {
      "instance_ids": ["docs", "support"]
    }
  }'

Every value must be in the allowlist. Rules for this field:

• Omitting the field, or setting it to null, searches the full allowlist.
• A malformed value, such as an empty array or a non-string entry, returns a 400 with error 60012.
• A value outside the allowlist returns a 404 with error 60013.

Set public_endpoint_params to null. This clears the configuration and stops serving traffic, but keeps the identifier so the URL is reused if you enable the endpoint again.

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_endpoint_params": null
  }'