Workers binding

Workers provides a serverless execution environment that allows you to create new applications or augment existing ones. Use a Workers binding to upload, list, and manage documents in your AI Search instances from a Cloudflare Worker. Access the Items API through the items property on an instance handle.

To use AI Search with Workers, you must create an AI Search binding. You create bindings by updating your Wrangler configuration. AI Search provides two types of bindings:

• Namespace binding: ai_search_namespaces
• Instance binding: ai_search

Access all instances within a namespace. You can get, create, list, and delete instances at runtime.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search_namespaces": [
    {
      "binding": "AI_SEARCH",
      "namespace": "my-namespace"
    }
  ]
}

compatibility_date = "2026-03-27"

[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "my-namespace"

Bind directly to a single instance in the default namespace. Use this when you know which instance you need at deploy time.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search": [
    {
      "binding": "MY_SEARCH",
      "instance_name": "my-instance"
    }
  ]
}

compatibility_date = "2026-03-27"

[[ai_search]]
binding = "MY_SEARCH"
instance_name = "my-instance"

The Items API methods are available on both the ai_search_namespaces and ai_search bindings. With the namespace binding, call methods on the handle returned by get(). With the instance binding, call methods directly on the binding (for example, env.MY_SEARCH.items.upload()).

The examples below use the namespace binding.

const instance = env.AI_SEARCH.get("my-instance");

Uploads a document for indexing. Returns immediately. The document is queued for processing.

// Upload from a string
await instance.items.upload(
	"faq.md",
	"# FAQ\n\nQ: How do I reset my password?\nA: Go to Settings > Security...",
);

// Upload from an ArrayBuffer
const pdfResponse = await fetch("https://example.com/guide.pdf");
const pdfBuffer = await pdfResponse.arrayBuffer();
await instance.items.upload("guide.pdf", pdfBuffer);

// Upload from a ReadableStream
await instance.items.upload("doc.txt", request.body);

Attach custom metadata to a document for filtering in search queries. Custom metadata fields must be defined on the instance first using the update() method or at creation time.

await instance.items.upload("guide.pdf", pdfBuffer, {
	metadata: {
		category: "onboarding",
		language: "en",
		version: "2.0",
	},
});

Uploads a document and polls until processing completes or the timeout is reached. Use this when you need to search the document immediately after upload.

// Wait for a specific document to finish indexing before searching
const item = await instance.items.uploadAndPoll(
	"handbook.txt",
	handbookContent,
);
console.log(`handbook.txt status: ${item.status}`); // "completed"

// Now search across all uploaded documents
const results = await instance.search({
	messages: [{ role: "user", content: "password reset policy" }],
});

Same as items.upload(), with additional polling options:

Returns the full item object after polling completes:

Returns a paginated list of items in the instance.

const { result, result_info } = await instance.items.list();

for (const item of result) {
	console.log(`${item.key} (${item.status})`);
}
// result_info.total_count contains the total number of items

Deletes an item and its indexed chunks.

await instance.items.delete("item-id-123");

Returns void. Throws an error if the item does not exist.

Returns a handle to a specific item for retrieving its status or downloading the original file.

Returns the status and metadata of a specific item.

const itemInfo = await instance.items.get("item-id-123").info();

Downloads the original source file for an item.

const file = await instance.items.get("item-id-123").download();
// file.body is a ReadableStream