Every AI Search instance belongs to a namespace. A namespace is a logical grouping of instances within your account.
Common reasons to use namespaces include:
- Domain separation: Separate instances by product area, for example
blog,support, anddocs. - Tenant isolation: Assign each tenant their own namespace so that instance names do not collide across tenants.
- Agent isolation: Give each agent its own namespace for independent context management.
For a step-by-step guide to isolating search per tenant, see Multitenancy.
The namespace binding requires the following minimum package versions for TypeScript types and local development support.
| Package | Minimum version |
|---|---|
@cloudflare/workers-types |
4.20260304.0 |
wrangler |
4.68.1 |
When you add an ai_search_namespaces binding to your Wrangler configuration, you specify which namespace the binding has access to. The binding grants full access to all instances within that namespace. You can get, list, create, and delete instances at runtime.
{
"$schema": "./node_modules/wrangler/config-schema.json",
"ai_search_namespaces": [
{
"binding": "AI_SEARCH",
"namespace": "my-namespace"
}
]
}[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "my-namespace"At runtime, env.AI_SEARCH is the namespace handle. Use env.AI_SEARCH.get("my-instance") to get a handle to a specific instance:
const instance = env.AI_SEARCH.get("my-instance");
const results = await instance.search({
messages: [{ role: "user", content: "How does caching work?" }],
});The get() method is synchronous and does not make a network call. The instance is resolved lazily when you call a method like search() or chatCompletions().
The binding manages instances inside its namespace. To create, update, or delete namespaces themselves, refer to the Namespaces API.
A default namespace is automatically created for every account. If you do not need multiple namespaces, use default for all your instances.
You can also bind directly to specific instances in the default namespace using the ai_search binding. This binds each entry to a single pre-existing instance without needing to call get().
{
"$schema": "./node_modules/wrangler/config-schema.json",
"ai_search": [
{
"binding": "PROD_SEARCH",
"instance_name": "production"
},
{
"binding": "STAGING_SEARCH",
"instance_name": "staging"
}
]
}[[ai_search]]
binding = "PROD_SEARCH"
instance_name = "production"
[[ai_search]]
binding = "STAGING_SEARCH"
instance_name = "staging"The ai_search binding provides the same instance methods (search(), chatCompletions(), info(), stats(), items) but does not support namespace-level operations like list(), create(), or delete().
You can declare multiple namespace bindings in the same Worker. Each binding maps to a different namespace and provides isolated access to its instances.
{
"$schema": "./node_modules/wrangler/config-schema.json",
"ai_search_namespaces": [
{
"binding": "BLOG_SEARCH",
"namespace": "blog"
},
{
"binding": "SUPPORT_SEARCH",
"namespace": "support"
}
]
}[[ai_search_namespaces]]
binding = "BLOG_SEARCH"
namespace = "blog"
[[ai_search_namespaces]]
binding = "SUPPORT_SEARCH"
namespace = "support"From Cloudflare Terraform provider ↗︎ v5.29.0, use the cloudflare_ai_search_namespace resource to create a namespace, and set namespace on cloudflare_ai_search_instance to create an instance in it. If you omit namespace, the instance is created in default.
resource "cloudflare_ai_search_namespace" "support" {
account_id = var.account_id
name = "support"
}
resource "cloudflare_ai_search_instance" "docs" {
account_id = var.account_id
id = "docs"
namespace = cloudflare_ai_search_namespace.support.name
}Changing namespace on an existing instance replaces it. For imports, data sources, and other options, refer to Namespaces with Terraform and Instances with Terraform.
A namespace can expose its own public /search, /chat/completions, and /mcp endpoints. One URL then searches across the instances you choose in that namespace and merges the results.
Refer to Namespace public endpoints.
An instance name must be unique within a namespace. This means you can have an instance named docs in both the blog and support namespaces without conflict.