Skip to content

Commit 22e3333

Browse files
aninibreadaninibread
committed
ai search new bindings
1 parent 9a5f87f commit 22e3333

12 files changed

Lines changed: 808 additions & 139 deletions

File tree

‎src/content/changelog/ai-search/2026-03-06-new-ai-search-binding.mdx‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: New AI Search Workers binding with improved API design
3+
description: Access AI Search instances with the new env.AI.aiSearch() binding for better namespace separation and programmatic instance management.
4+
products:
5+
- ai-search
6+
date: 2026-03-06
7+
---
8+
9+
The new `env.AI.aiSearch()` [Workers binding](/ai-search/usage/workers-binding/) provides a cleaner API for [AI Search](/ai-search/) operations with separate account-level and instance-level methods.
10+
11+
## What is new
12+
13+
- **Account-level operations**: List all instances, get an instance by name, or create new instances programmatically
14+
- **Instance-level operations**: Search, generate chat completions, or delete instances
15+
- **Messages-based API**: Uses a `messages` array format consistent with chat completion APIs
16+
- **Full TypeScript support**: Complete type definitions for all methods and responses
17+
18+
## Example
19+
20+
Query an AI Search instance and return the results:
21+
22+
```ts
23+
export type Env = {
24+
AI: Ai;
25+
};
26+
27+
export default {
28+
async fetch(request, env, ctx): Promise<Response> {
29+
// Get an AI Search instance by name
30+
const aisearch = env.AI.aiSearch().get("my-instance");
31+
32+
// Search for relevant content
33+
const results = await aisearch.search({
34+
messages: [{ role: "user", content: "How do I configure caching?" }],
35+
});
36+
37+
// Return matching chunks as JSON
38+
return Response.json(results);
39+
},
40+
} satisfies ExportedHandler<Env>;
41+
```
42+
43+
## Requirements
44+
45+
To use the new binding, update your packages to the following minimum versions:
46+
47+
| Package | Minimum version | Purpose |
48+
| --------------------------- | --------------- | --------------------------- |
49+
| `@cloudflare/workers-types` | `4.20260304.0` | TypeScript type definitions |
50+
| `wrangler` | `4.68.1` | Local development support |
51+
52+
## Backwards compatibility
53+
54+
The previous `env.AI.autorag()` binding is deprecated but will continue to work indefinitely. Existing code does not need to be migrated.
55+
56+
For full documentation, refer to the [Workers binding guide](/ai-search/usage/workers-binding/).

‎src/content/docs/ai-search/instances-api/index.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
pcx_content_type: navigation
3+
title: Instances API
4+
sidebar:
5+
order: 4
6+
group:
7+
hideIndex: true
8+
---
9+
10+
import { DirectoryListing } from "~/components";
11+
12+
Programmatically create, list, and delete AI Search instances.
13+
14+
<DirectoryListing />

‎src/content/docs/ai-search/instances-api/rest-api.mdx‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
pcx_content_type: reference
3+
title: REST API
4+
sidebar:
5+
order: 2
6+
---
7+
8+
Use the AI Search REST API to programmatically manage instances and indexing jobs.
9+
10+
## Authentication
11+
12+
All requests require an API token with AI Search edit permissions. Include the token in the `Authorization` header:
13+
14+
```txt
15+
Authorization: Bearer <API_TOKEN>
16+
```
17+
18+
### Create an API token
19+
20+
1. In the Cloudflare dashboard, go to **My Profile** > **API Tokens**.
21+
2. Select **Create Token**.
22+
3. Select **Create Custom Token**.
23+
4. Enter a **Token name**, for example `AI Search Manager`.
24+
5. Under **Permissions**, select **Account** > **AI Search** > **Edit**.
25+
6. Select **Continue to summary**, then select **Create Token**.
26+
7. Copy and save the token value.
27+
28+
## Instance endpoints
29+
30+
Manage AI Search instances in your account.
31+
32+
| Description | Method | Endpoint |
33+
| ------------------------------------------------------------------------------------- | -------- | ------------------------------------------------- |
34+
| [List all instances](/api/resources/ai_search/subresources/instances/methods/list/) | `GET` | `/accounts/{account_id}/ai-search/instances` |
35+
| [Create an instance](/api/resources/ai_search/subresources/instances/methods/create/) | `POST` | `/accounts/{account_id}/ai-search/instances` |
36+
| [Get an instance](/api/resources/ai_search/subresources/instances/methods/read/) | `GET` | `/accounts/{account_id}/ai-search/instances/{id}` |
37+
| [Update an instance](/api/resources/ai_search/subresources/instances/methods/update/) | `PUT` | `/accounts/{account_id}/ai-search/instances/{id}` |
38+
| [Delete an instance](/api/resources/ai_search/subresources/instances/methods/delete/) | `DELETE` | `/accounts/{account_id}/ai-search/instances/{id}` |
39+
40+
### Example: Create an instance
41+
42+
```bash
43+
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/instances" \
44+
-H "Authorization: Bearer $API_TOKEN" \
45+
-H "Content-Type: application/json" \
46+
-d '{
47+
"id": "docs-search",
48+
"type": "web-crawler",
49+
"source": "example.com"
50+
}'
51+
```
52+
53+
## Jobs endpoints
54+
55+
Trigger and monitor [sync jobs](/ai-search/configuration/indexing/#jobs) that scan your data source and index new or updated content.
56+
57+
| Description | Method | Endpoint |
58+
| -------------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------------------- |
59+
| [List jobs](/api/resources/ai_search/subresources/instances/subresources/jobs/methods/list/) | `GET` | `/accounts/{account_id}/ai-search/instances/{id}/jobs` |
60+
| [Create a job](/api/resources/ai_search/subresources/instances/subresources/jobs/methods/create/) | `POST` | `/accounts/{account_id}/ai-search/instances/{id}/jobs` |
61+
| [Get job details](/api/resources/ai_search/subresources/instances/subresources/jobs/methods/read/) | `GET` | `/accounts/{account_id}/ai-search/instances/{id}/jobs/{job_id}` |
62+
| [List job logs](/api/resources/ai_search/subresources/instances/subresources/jobs/methods/logs/) | `GET` | `/accounts/{account_id}/ai-search/instances/{id}/jobs/{job_id}/logs` |
63+
64+
### Example: Trigger a sync job and check status
65+
66+
Create a new indexing job:
67+
68+
```bash
69+
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/instances/$INSTANCE_ID/jobs" \
70+
-H "Authorization: Bearer $API_TOKEN"
71+
```
72+
73+
Check the job status:
74+
75+
```bash
76+
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/instances/$INSTANCE_ID/jobs/$JOB_ID" \
77+
-H "Authorization: Bearer $API_TOKEN"
78+
```
79+
80+
## API reference
81+
82+
For complete API specifications including all parameters and response fields, refer to the [AI Search API reference](/api/resources/ai_search/).

‎src/content/docs/ai-search/instances-api/workers-binding.mdx‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
pcx_content_type: reference
3+
title: Workers Binding
4+
sidebar:
5+
order: 1
6+
---
7+
8+
import { Render, WranglerConfig, MetaInfo, Type } from "~/components";
9+
10+
Use the `env.AI.aiSearch()` binding to programmatically manage AI Search instances from your [Cloudflare Worker](/workers/).
11+
12+
To use AI Search with Workers, add an AI binding to your Wrangler configuration:
13+
14+
<WranglerConfig>
15+
16+
```jsonc
17+
{
18+
"ai": {
19+
"binding": "AI",
20+
},
21+
}
22+
```
23+
24+
</WranglerConfig>
25+
26+
## Requirements
27+
28+
| Package | Minimum version |
29+
| --------------------------- | --------------- |
30+
| `@cloudflare/workers-types` | `4.20260304.0` |
31+
| `wrangler` | `4.68.1` |
32+
33+
## `create()`
34+
35+
Create a new AI Search instance programmatically. Use this to set up instances for multi-tenant applications or automate infrastructure management.
36+
37+
```ts
38+
const aisearch = await env.AI.aiSearch().create({
39+
id: "docs-search",
40+
type: "web-crawler",
41+
source: "example.com",
42+
source_params: {
43+
include_items: ["/docs/**"],
44+
},
45+
rewrite_query: true,
46+
reranking: true,
47+
});
48+
```
49+
50+
After creating an instance, the data source must be indexed before you can search it. Indexing runs automatically.
51+
52+
### Parameters
53+
54+
<Render file="v2-create-instance-params" product="ai-search" />
55+
56+
## `list()`
57+
58+
List all AI Search instances in your account.
59+
60+
```ts
61+
const instances = await env.AI.aiSearch().list();
62+
63+
for (const instance of instances) {
64+
console.log(instance.id, instance.type, instance.source);
65+
}
66+
```
67+
68+
### Response
69+
70+
Returns an array of AI Search instance objects:
71+
72+
| Field | Type | Description |
73+
| -------- | ------- | --------------------------------------------- |
74+
| `id` | string | The instance identifier. |
75+
| `type` | string | The data source type (`r2` or `web-crawler`). |
76+
| `source` | string | The data source location. |
77+
| `enable` | boolean | Whether the instance is enabled. |
78+
79+
## `delete()`
80+
81+
Delete an AI Search instance.
82+
83+
```ts
84+
const aisearch = env.AI.aiSearch().get("my-instance");
85+
await aisearch.delete();
86+
```
87+
88+
:::caution
89+
Deleting an instance permanently removes all indexed data. This action cannot be undone.
90+
:::

‎src/content/docs/ai-search/usage/rest-api.mdx‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ sidebar:
55
order: 4
66
---
77

8+
import { LinkCard } from "@astrojs/starlight/components";
89
import {
910
Badge,
1011
Description,
@@ -14,7 +15,7 @@ import {
1415
WranglerConfig,
1516
MetaInfo,
1617
Type,
17-
DashButton
18+
DashButton,
1819
} from "~/components";
1920

2021
This guide will instruct you through how to use the AI Search REST API to make a query to your AI Search.
@@ -115,3 +116,11 @@ You can get your `ACCOUNT_ID` by navigating to Workers & Pages on the dashboard,
115116
### Response
116117

117118
<Render file="search-response" product="ai-search" />
119+
120+
## Related
121+
122+
<LinkCard
123+
title="Instances API"
124+
description="Programmatically create, list, or delete AI Search instances."
125+
href="/ai-search/instances-api/"
126+
/>

0 commit comments

Comments
 (0)