Workers binding

The ai_search_namespaces binding gives a Worker access to one namespace. Use it to get, list, create, and delete instances in that namespace, and to search across several of its instances in one call.

The binding is scoped to the namespace you configure. It cannot create, list, update, or delete namespaces. To manage namespaces, use the REST API, Terraform, or Wrangler.

Configure the binding

Add an ai_search_namespaces entry to your Wrangler configuration and set the namespace the binding can access:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  // Set this to today's date
  "compatibility_date": "2026-11-14",
  "ai_search_namespaces": [
    {
      "binding": "AI_SEARCH",
      "namespace": "support"
    }
  ]
}

# Set this to today's date
compatibility_date = "2026-11-14"

[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "support"

Field	Type	Required	Description
`binding`	string	Yes	The variable name available on `env`. For example, `"AI_SEARCH"` makes it accessible as `env.AI_SEARCH`.
`namespace`	string	Yes	The namespace to bind to. A `default` namespace exists for every account. If the namespace does not exist, Wrangler creates it when you deploy.
`remote`	boolean	No	Set to `true` for local development with `wrangler dev`.

What the binding can do

At runtime, env.AI_SEARCH is the namespace handle. It exposes the following methods:

Method	Description
`get()`	Returns a handle to an instance. Does not make a network call.
`list()`	Lists the instances in the namespace.
`create()`	Creates an instance in the namespace and returns a handle.
`delete()`	Permanently deletes an instance and its indexed content.
`search()`	Searches across several instances in the namespace.
`chatCompletions()`	Generates a response from several instances in the namespace.

For parameters and responses of the instance methods, refer to the Instances Workers binding reference. For search() and chatCompletions(), refer to the Search Workers binding reference.

Get an instance

const instance = env.AI_SEARCH.get("docs");
const results = await instance.search({
	messages: [{ role: "user", content: "How do I reset my password?" }],
});

List instances

const { result } = await env.AI_SEARCH.list();

for (const instance of result) {
	console.log(instance.id);
}

Create an instance

const instance = await env.AI_SEARCH.create({
	id: "faq",
});

Delete an instance

await env.AI_SEARCH.delete("faq");

Bind multiple namespaces

Declare one binding per namespace. Each binding only reaches the instances in its own namespace.

{
  "$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"

const blogPosts = await env.BLOG_SEARCH.list();
const supportDocs = env.SUPPORT_SEARCH.get("docs");