From 7efd4b53b21e56369c82766c2f9e3a1b59b19006 Mon Sep 17 00:00:00 2001 From: ttmx Date: Tue, 30 Jun 2026 09:29:11 +0100 Subject: [PATCH 1/4] Added Integrated SDKs section to AI Search docs --- .../docs/ai-search/get-started/index.mdx | 5 + .../ai-search/get-started/integrated-sdks.mdx | 141 ++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 src/content/docs/ai-search/get-started/integrated-sdks.mdx diff --git a/src/content/docs/ai-search/get-started/index.mdx b/src/content/docs/ai-search/get-started/index.mdx index 335d36c6395..3b7ec530ef3 100644 --- a/src/content/docs/ai-search/get-started/index.mdx +++ b/src/content/docs/ai-search/get-started/index.mdx @@ -39,4 +39,9 @@ If you plan to use an R2 bucket as your data source, you must have an active [R2 description="Create and manage AI Search instances from the command line." href="/ai-search/get-started/wrangler/" /> + diff --git a/src/content/docs/ai-search/get-started/integrated-sdks.mdx b/src/content/docs/ai-search/get-started/integrated-sdks.mdx new file mode 100644 index 00000000000..bc20c3eb7cd --- /dev/null +++ b/src/content/docs/ai-search/get-started/integrated-sdks.mdx @@ -0,0 +1,141 @@ +--- +title: Integrated SDKs +pcx_content_type: get-started +sidebar: + order: 4 +description: Use AI Search from the Cloudflare Python SDK and Workers TypeScript bindings. +products: + - ai-search +--- + +import { TypeScriptExample } from "~/components"; + +Use AI Search from Python applications with the [Cloudflare Python SDK](https://github.com/cloudflare/cloudflare-python), or from a Worker with the Workers TypeScript binding. + +- [Python SDK](#python-sdk) +- [Workers TypeScript binding](#workers-typescript-binding) + +## Prerequisites + +- Your [account ID](/fundamentals/account/find-account-and-zone-ids/). +- An API token with **AI Search:Edit** and **AI Search:Run** permissions. +- An AI Search instance with indexed content. To create one first, refer to [Dashboard](/ai-search/get-started/dashboard/), [REST API](/ai-search/get-started/api/), or [Wrangler commands](/ai-search/get-started/wrangler/). + +## Python SDK + +Install the official `cloudflare` package: + +```sh +pip install cloudflare +``` + +Set your credentials: + +```sh +export CLOUDFLARE_ACCOUNT_ID="" +export CLOUDFLARE_API_TOKEN="" +``` + +Search an AI Search instance: + +```python +import os + +from cloudflare import Cloudflare + +client = Cloudflare(api_token=os.environ["CLOUDFLARE_API_TOKEN"]) +account_id = os.environ["CLOUDFLARE_ACCOUNT_ID"] + +results = client.aisearch.namespaces.instances.search( + "my-instance", + account_id=account_id, + name="my-namespace", + query="How do I get started with AI Search?", + aisearch_options={"retrieval": {"max_num_results": 3, "retrieval_type": "hybrid"}}, +) + +print(results.chunks[0].text) +``` + +Upload a file to an instance that uses [built-in storage](/ai-search/configuration/data-source/built-in-storage/): + +```python +item = client.aisearch.namespaces.instances.items.upload( + "my-instance", + account_id=account_id, + name="my-namespace", + file={ + "file": ("getting-started.md", b"AI Search indexes content.", "text/markdown"), + "wait_for_completion": True, + }, + timeout=120, +) + +print(item.status) +``` + +## Workers TypeScript binding + +Use a Workers binding to call AI Search without manually signing REST API requests. Add a namespace binding to your Wrangler configuration: + +```jsonc +{ + "compatibility_date": "2026-03-27", + "ai_search_namespaces": [ + { + "binding": "AI_SEARCH", + "namespace": "my-namespace", + }, + ], +} +``` + +Then call AI Search from your Worker: + + + +```ts +export interface Env { + AI_SEARCH: AiSearchNamespace; +} + +export default { + async fetch(request, env): Promise { + const query = + new URL(request.url).searchParams.get("q") ?? "What is Cloudflare?"; + + const results = await env.AI_SEARCH.get("my-instance").search({ + messages: [{ role: "user", content: query }], + ai_search_options: { + retrieval: { max_num_results: 3, retrieval_type: "hybrid" }, + }, + }); + + return Response.json(results.chunks); + }, +} satisfies ExportedHandler; +``` + + + +To upload content from a Worker, use `items.uploadAndPoll()`: + + + +```ts +const item = await env.AI_SEARCH.get("my-instance").items.uploadAndPoll( + "support-faq.md", + "# Support FAQ\n\nAI Search indexes uploaded content for retrieval.", + { timeoutMs: 60_000 }, +); + +return Response.json({ status: item.status }); +``` + + + +## Next steps + +- Review the [Workers binding reference](/ai-search/api/search/workers-binding/). +- Learn how to [manage items with Workers bindings](/ai-search/api/items/workers-binding/). +- Compare these examples with the [REST API guide](/ai-search/get-started/api/). From aa7e1b167e0fe1359a0ea9897dd5c362fc6d622a Mon Sep 17 00:00:00 2001 From: ttmx Date: Tue, 30 Jun 2026 09:40:44 +0100 Subject: [PATCH 2/4] Added changelog for AI Search+Python --- .../changelog/ai-search/2025-06-30-integrated-sdks.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 src/content/changelog/ai-search/2025-06-30-integrated-sdks.mdx diff --git a/src/content/changelog/ai-search/2025-06-30-integrated-sdks.mdx b/src/content/changelog/ai-search/2025-06-30-integrated-sdks.mdx new file mode 100644 index 00000000000..a1810f5a0b4 --- /dev/null +++ b/src/content/changelog/ai-search/2025-06-30-integrated-sdks.mdx @@ -0,0 +1,9 @@ +--- +title: AI Search Python SDK and Workers TypeScript binding +description: New documentation for using AI Search from the Cloudflare Python SDK and Workers TypeScript binding. +products: + - ai-search +date: 2026-06-30 +--- + +Added documentation for using AI Search from Cloudflare's Python bindings and added a Workers example \ No newline at end of file From de5f3afa828e6b6f37c742c2074d422dd63b9d24 Mon Sep 17 00:00:00 2001 From: Anni Wang Date: Thu, 2 Jul 2026 17:57:12 -0700 Subject: [PATCH 3/4] update the get started guide and break out workers + python sdk --- .../ai-search/2025-06-30-integrated-sdks.mdx | 9 -- .../docs/ai-search/get-started/api.mdx | 2 +- .../docs/ai-search/get-started/dashboard.mdx | 2 +- .../docs/ai-search/get-started/index.mdx | 31 ++-- .../ai-search/get-started/integrated-sdks.mdx | 141 ---------------- .../docs/ai-search/get-started/python.mdx | 153 ++++++++++++++++++ .../docs/ai-search/get-started/workers.mdx | 147 +++++++++++++++++ .../docs/ai-search/get-started/wrangler.mdx | 2 +- 8 files changed, 319 insertions(+), 168 deletions(-) delete mode 100644 src/content/changelog/ai-search/2025-06-30-integrated-sdks.mdx delete mode 100644 src/content/docs/ai-search/get-started/integrated-sdks.mdx create mode 100644 src/content/docs/ai-search/get-started/python.mdx create mode 100644 src/content/docs/ai-search/get-started/workers.mdx diff --git a/src/content/changelog/ai-search/2025-06-30-integrated-sdks.mdx b/src/content/changelog/ai-search/2025-06-30-integrated-sdks.mdx deleted file mode 100644 index a1810f5a0b4..00000000000 --- a/src/content/changelog/ai-search/2025-06-30-integrated-sdks.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: AI Search Python SDK and Workers TypeScript binding -description: New documentation for using AI Search from the Cloudflare Python SDK and Workers TypeScript binding. -products: - - ai-search -date: 2026-06-30 ---- - -Added documentation for using AI Search from Cloudflare's Python bindings and added a Workers example \ No newline at end of file diff --git a/src/content/docs/ai-search/get-started/api.mdx b/src/content/docs/ai-search/get-started/api.mdx index 8ec6d962ab1..2b7dca61b51 100644 --- a/src/content/docs/ai-search/get-started/api.mdx +++ b/src/content/docs/ai-search/get-started/api.mdx @@ -2,7 +2,7 @@ title: REST API pcx_content_type: get-started sidebar: - order: 2 + order: 5 description: Create AI Search instances programmatically using the REST API. products: - ai-search diff --git a/src/content/docs/ai-search/get-started/dashboard.mdx b/src/content/docs/ai-search/get-started/dashboard.mdx index 9cdce7e087b..02744e0ec62 100644 --- a/src/content/docs/ai-search/get-started/dashboard.mdx +++ b/src/content/docs/ai-search/get-started/dashboard.mdx @@ -2,7 +2,7 @@ title: Dashboard pcx_content_type: get-started sidebar: - order: 1 + order: 4 description: Create and configure AI Search using the Cloudflare dashboard. products: - ai-search diff --git a/src/content/docs/ai-search/get-started/index.mdx b/src/content/docs/ai-search/get-started/index.mdx index 3b7ec530ef3..291622dd2fb 100644 --- a/src/content/docs/ai-search/get-started/index.mdx +++ b/src/content/docs/ai-search/get-started/index.mdx @@ -13,35 +13,36 @@ products: - ai-search --- -import { DashButton, CardGrid, LinkCard } from "~/components"; +import { CardGrid, LinkCard } from "~/components"; AI Search is a managed search service. Connect a website, an R2 bucket, or upload your own documents, and AI Search indexes your content for natural language queries. -## Prerequisites - -If you plan to use an R2 bucket as your data source, you must have an active [R2 subscription](/r2/get-started/) before creating your AI Search instance. If you plan to use a website or upload files directly, no additional setup is required. - ## Choose your setup method + diff --git a/src/content/docs/ai-search/get-started/integrated-sdks.mdx b/src/content/docs/ai-search/get-started/integrated-sdks.mdx deleted file mode 100644 index bc20c3eb7cd..00000000000 --- a/src/content/docs/ai-search/get-started/integrated-sdks.mdx +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Integrated SDKs -pcx_content_type: get-started -sidebar: - order: 4 -description: Use AI Search from the Cloudflare Python SDK and Workers TypeScript bindings. -products: - - ai-search ---- - -import { TypeScriptExample } from "~/components"; - -Use AI Search from Python applications with the [Cloudflare Python SDK](https://github.com/cloudflare/cloudflare-python), or from a Worker with the Workers TypeScript binding. - -- [Python SDK](#python-sdk) -- [Workers TypeScript binding](#workers-typescript-binding) - -## Prerequisites - -- Your [account ID](/fundamentals/account/find-account-and-zone-ids/). -- An API token with **AI Search:Edit** and **AI Search:Run** permissions. -- An AI Search instance with indexed content. To create one first, refer to [Dashboard](/ai-search/get-started/dashboard/), [REST API](/ai-search/get-started/api/), or [Wrangler commands](/ai-search/get-started/wrangler/). - -## Python SDK - -Install the official `cloudflare` package: - -```sh -pip install cloudflare -``` - -Set your credentials: - -```sh -export CLOUDFLARE_ACCOUNT_ID="" -export CLOUDFLARE_API_TOKEN="" -``` - -Search an AI Search instance: - -```python -import os - -from cloudflare import Cloudflare - -client = Cloudflare(api_token=os.environ["CLOUDFLARE_API_TOKEN"]) -account_id = os.environ["CLOUDFLARE_ACCOUNT_ID"] - -results = client.aisearch.namespaces.instances.search( - "my-instance", - account_id=account_id, - name="my-namespace", - query="How do I get started with AI Search?", - aisearch_options={"retrieval": {"max_num_results": 3, "retrieval_type": "hybrid"}}, -) - -print(results.chunks[0].text) -``` - -Upload a file to an instance that uses [built-in storage](/ai-search/configuration/data-source/built-in-storage/): - -```python -item = client.aisearch.namespaces.instances.items.upload( - "my-instance", - account_id=account_id, - name="my-namespace", - file={ - "file": ("getting-started.md", b"AI Search indexes content.", "text/markdown"), - "wait_for_completion": True, - }, - timeout=120, -) - -print(item.status) -``` - -## Workers TypeScript binding - -Use a Workers binding to call AI Search without manually signing REST API requests. Add a namespace binding to your Wrangler configuration: - -```jsonc -{ - "compatibility_date": "2026-03-27", - "ai_search_namespaces": [ - { - "binding": "AI_SEARCH", - "namespace": "my-namespace", - }, - ], -} -``` - -Then call AI Search from your Worker: - - - -```ts -export interface Env { - AI_SEARCH: AiSearchNamespace; -} - -export default { - async fetch(request, env): Promise { - const query = - new URL(request.url).searchParams.get("q") ?? "What is Cloudflare?"; - - const results = await env.AI_SEARCH.get("my-instance").search({ - messages: [{ role: "user", content: query }], - ai_search_options: { - retrieval: { max_num_results: 3, retrieval_type: "hybrid" }, - }, - }); - - return Response.json(results.chunks); - }, -} satisfies ExportedHandler; -``` - - - -To upload content from a Worker, use `items.uploadAndPoll()`: - - - -```ts -const item = await env.AI_SEARCH.get("my-instance").items.uploadAndPoll( - "support-faq.md", - "# Support FAQ\n\nAI Search indexes uploaded content for retrieval.", - { timeoutMs: 60_000 }, -); - -return Response.json({ status: item.status }); -``` - - - -## Next steps - -- Review the [Workers binding reference](/ai-search/api/search/workers-binding/). -- Learn how to [manage items with Workers bindings](/ai-search/api/items/workers-binding/). -- Compare these examples with the [REST API guide](/ai-search/get-started/api/). diff --git a/src/content/docs/ai-search/get-started/python.mdx b/src/content/docs/ai-search/get-started/python.mdx new file mode 100644 index 00000000000..79cde854981 --- /dev/null +++ b/src/content/docs/ai-search/get-started/python.mdx @@ -0,0 +1,153 @@ +--- +title: Python SDK +pcx_content_type: get-started +sidebar: + order: 2 +description: Create, populate, and query an AI Search instance from Python. +products: + - ai-search +--- + +import { LinkCard, DashButton } from "~/components"; + +This guide walks you through creating an AI Search instance, uploading content, and querying it from a Python application using the [Cloudflare Python SDK](https://github.com/cloudflare/cloudflare-python). + +## Prerequisites + +- [Python](https://www.python.org/downloads/) 3.8 or later. +- Your [account ID](/fundamentals/account/find-account-and-zone-ids/). + +This guide uses the `default` [namespace](/ai-search/concepts/namespaces/), which exists automatically on every account. To group instances into your own namespace, create one with `client.aisearch.namespaces.create()`. + +## 1. Create an API token + +You need an API token with **AI Search:Edit** and **AI Search:Run** permissions. + +1. In the Cloudflare dashboard, go to **My Profile** > **API Tokens**. + + + +2. Select **Create Token**. +3. Select **Create Custom Token**. +4. Enter a **Token name**, for example `AI Search Python`. +5. Under **Permissions**, add two permissions: + - **Account** > **AI Search:Edit** + - **Account** > **AI Search:Run** +6. Select **Continue to summary**, then select **Create Token**. +7. Copy and save the token value. This is your `API_TOKEN`. + +## 2. Set up your Python environment + +Create a project directory and a virtual environment to isolate your dependencies. + +```sh +mkdir ai-search-python && cd ai-search-python +python3 -m venv .venv +source .venv/bin/activate +``` + +On Windows, activate the virtual environment with `.venv\Scripts\activate` instead. + +## 3. Install the Cloudflare Python SDK + +Install the official `cloudflare` package: + +```sh +pip install cloudflare +``` + +## 4. Set your credentials + +Export your account ID and API token as environment variables. + +```sh +export CLOUDFLARE_ACCOUNT_ID="" +export CLOUDFLARE_API_TOKEN="" +``` + +## 5. Create an AI Search instance + +Create a file named `quickstart.py`. The following code sets up a client and creates an instance named `my-instance` in the `default` namespace. Because no data source is specified, the instance uses [built-in storage](/ai-search/configuration/data-source/built-in-storage/), so you can upload files to it directly. + +```python title="quickstart.py" +import os + +from cloudflare import Cloudflare + +client = Cloudflare(api_token=os.environ["CLOUDFLARE_API_TOKEN"]) +account_id = os.environ["CLOUDFLARE_ACCOUNT_ID"] + +instance = client.aisearch.namespaces.instances.create( + name="default", + account_id=account_id, + id="my-instance", +) + +print(f"Created instance: {instance.id}") +``` + +:::note +Creating an instance is a one-time action. If you run the script again, remove this step, because an instance name must be unique within a namespace. +::: + +## 6. Upload content + +Add the following to `quickstart.py` to upload a document. Setting `wait_for_completion` to `True` waits for indexing before returning so the file is ready to search. If indexing is still finishing, `item.status` may be `running`; the file continues indexing in the background and becomes searchable shortly after. + +```python title="quickstart.py" +item = client.aisearch.namespaces.instances.items.upload( + id="my-instance", + account_id=account_id, + name="default", + file={ + "file": ( + "getting-started.md", + b"AI Search indexes uploaded content for retrieval.", + "text/markdown", + ), + "wait_for_completion": True, + }, +) + +print(f"Uploaded item status: {item.status}") +``` + +## 7. Search your instance + +Add the following to `quickstart.py` to run a query against your indexed content. + +```python title="quickstart.py" +results = client.aisearch.namespaces.instances.search( + id="my-instance", + account_id=account_id, + name="default", + query="How does AI Search handle uploaded content?", + aisearch_options={"retrieval": {"max_num_results": 3}}, +) + +if results.chunks: + print(results.chunks[0].text) +else: + print("No results yet — your content may still be indexing. Try again in a moment.") +``` + +Run the script: + +```sh +python quickstart.py +``` + +If the search returns no results, the content may still be indexing. Wait a moment, then run the search again. + +## Next steps + + + diff --git a/src/content/docs/ai-search/get-started/workers.mdx b/src/content/docs/ai-search/get-started/workers.mdx new file mode 100644 index 00000000000..5b6393e7315 --- /dev/null +++ b/src/content/docs/ai-search/get-started/workers.mdx @@ -0,0 +1,147 @@ +--- +title: Workers binding +pcx_content_type: get-started +sidebar: + order: 1 +description: Create, populate, and query an AI Search instance from a Cloudflare Worker. +products: + - ai-search +--- + +import { + Render, + PackageManagers, + WranglerConfig, + TypeScriptExample, + LinkCard, +} from "~/components"; + +This guide walks you through creating and querying an AI Search instance from a [Cloudflare Worker](/workers/) using the Workers Binding. The Workers Binding uses a runtime [API](/ai-search/api/search/workers-binding/) that runs inside a Worker and calls AI Search without managing API tokens. + + + +## 1. Create a Worker project + +Create a new Worker project using the `create-cloudflare` CLI (C3). [C3](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare) is a command-line tool designed to help you set up and deploy new applications to Cloudflare. + +Create a new project named `ai-search-tutorial` by running: + + + + + +Go to your application directory: + +```sh +cd ai-search-tutorial +``` + +## 2. Connect your Worker to AI Search + +Create a binding between your Worker and your AI Search instance. [Bindings](/workers/runtime-apis/bindings/) allow your Worker to interact with resources on the Cloudflare Developer Platform. + +Add the following to your [Wrangler configuration file](/workers/wrangler/configuration/): + + + +```toml +[[ai_search_namespaces]] +binding = "AI_SEARCH" +namespace = "default" +remote = true +``` + + + +This binds the `default` namespace to `env.AI_SEARCH`. Instances that you create without specifying a namespace belong to the `default` namespace. The `remote` option lets `wrangler dev` proxy requests to your deployed instance, since AI Search does not run locally. For all binding options, refer to the [Workers binding reference](/ai-search/api/search/workers-binding/). + +## 3. Create and query AI Search from your Worker + +Update the `src/index.ts` file in your `ai-search-tutorial` directory with the following code. It exposes two routes: `/setup` creates an instance named `my-instance` and indexes a sample document, and the default route queries it. + + + +```ts +export interface Env { + AI_SEARCH: AiSearchNamespace; +} + +export default { + async fetch(request, env): Promise { + const url = new URL(request.url); + + // Visit /setup once to create an instance and index a sample document. + if (url.pathname === "/setup") { + const instance = await env.AI_SEARCH.create({ id: "my-instance" }); + const item = await instance.items.uploadAndPoll( + "getting-started.md", + "AI Search indexes uploaded content for retrieval.", + ); + return Response.json({ created: "my-instance", status: item.status }); + } + + // Query the instance. + const query = url.searchParams.get("q") ?? "What does AI Search do?"; + + const results = await env.AI_SEARCH.get("my-instance").search({ + messages: [{ role: "user", content: query }], + ai_search_options: { + retrieval: { max_num_results: 3 }, + }, + }); + + return Response.json(results.chunks); + }, +} satisfies ExportedHandler; +``` + + + +## 4. Develop locally + +Start a local development server: + +```sh +npx wrangler dev +``` + +Wrangler gives you a URL (usually `localhost:8787`). Visit `/setup` once to create your instance and index the sample document, then query it at `/?q=your+search+terms`. + +## 5. Deploy your Worker + +Log in with your Cloudflare account: + +```sh +npx wrangler login +``` + +Deploy your Worker to make it accessible on the Internet: + +```sh +npx wrangler deploy +``` + +```sh output +https://ai-search-tutorial..workers.dev +``` + +## Next steps + + + diff --git a/src/content/docs/ai-search/get-started/wrangler.mdx b/src/content/docs/ai-search/get-started/wrangler.mdx index d1b61ddc52b..d0f741bfcf3 100644 --- a/src/content/docs/ai-search/get-started/wrangler.mdx +++ b/src/content/docs/ai-search/get-started/wrangler.mdx @@ -1,5 +1,5 @@ --- -title: Wrangler commands +title: CLI pcx_content_type: get-started sidebar: order: 3 From cba352654ebddc47eb590ae1522ba983675fe410 Mon Sep 17 00:00:00 2001 From: Anni Wang Date: Thu, 2 Jul 2026 18:13:32 -0700 Subject: [PATCH 4/4] small fixes --- src/content/docs/ai-search/get-started/python.mdx | 1 - src/content/docs/ai-search/get-started/workers.mdx | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/ai-search/get-started/python.mdx b/src/content/docs/ai-search/get-started/python.mdx index 79cde854981..aa4c928019f 100644 --- a/src/content/docs/ai-search/get-started/python.mdx +++ b/src/content/docs/ai-search/get-started/python.mdx @@ -122,7 +122,6 @@ results = client.aisearch.namespaces.instances.search( account_id=account_id, name="default", query="How does AI Search handle uploaded content?", - aisearch_options={"retrieval": {"max_num_results": 3}}, ) if results.chunks: diff --git a/src/content/docs/ai-search/get-started/workers.mdx b/src/content/docs/ai-search/get-started/workers.mdx index 5b6393e7315..fc2fb883757 100644 --- a/src/content/docs/ai-search/get-started/workers.mdx +++ b/src/content/docs/ai-search/get-started/workers.mdx @@ -129,7 +129,7 @@ Deploy your Worker to make it accessible on the Internet: npx wrangler deploy ``` -```sh output +```txt https://ai-search-tutorial..workers.dev ```