Namespace public endpoints

Last updated Aug 6, 2026 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.

Enable a namespace public endpoint

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.

The instances allowlist

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.

Caution

public_endpoint_params is replaced in full on every update. Send the complete object, including instances_allowed, or omitted fields revert to their defaults. Omitting instances_allowed resets it to an empty list and makes the endpoint return 404 for every request.

Search a subset of instances

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.

Note

The request body must be a JSON object. An array, a string, or an empty body returns a 400 with error 60015.

Disable a namespace public endpoint

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
  }'

Errors

Next steps

Namespaces

Group instances into namespaces and manage them from a Workers binding.

Search across multiple instances

Query several instances from a Worker or the REST API.

Custom domains

Serve a namespace public endpoint from a hostname that you own.

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/namespace/#page","headline":"Namespace public endpoints","description":"Expose several AI Search instances through a single public endpoint scoped to a namespace.","url":"https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/namespace/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-search/configuration/retrieval/public-endpoint/namespace/og.png?v=f40ee0336faa3652","dateModified":"2026-08-06","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Improve AI Search retrieval quality by enabling query rewriting to rephrase user queries. title: Query rewriting image: https://developers.cloudflare.com/ai-search/configuration/retrieval/query-rewriting/og.png?v=16e3741ca81d20d3

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/ai-search/llms.txt
Use this file to discover all available pages before exploring further.