--- title: API description: Create AI Search instances programmatically using the REST API. image: https://developers.cloudflare.com/dev-products-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/ai-search/get-started/api.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # API This guide walks you through creating an AI Search instance programmatically using the REST API. This requires setting up a [service API token](https://developers.cloudflare.com/ai-search/configuration/service-api-token/) for system-to-system authentication. Already have a service token? If you have created an AI Search instance via the dashboard at least once, your account already has a [service API token](https://developers.cloudflare.com/ai-search/configuration/service-api-token/) registered. The `token_id` parameter is optional and you can skip to [Step 5: Create an AI Search instance](#5-create-an-ai-search-instance). ## Prerequisites AI Search integrates with R2 for storing your data. You must have an active R2 subscription before creating your first AI Search instance. [ Go to **R2 Overview** ](https://dash.cloudflare.com/?to=/:account/r2/overview) ## 1\. Create an API token with token creation permissions AI Search requires a service API token to access R2 and other resources on your behalf. To create this service token programmatically, you first need an [API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) with permission to create other tokens. 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 `Token Creator`. 5. Under **Permissions**, select **User** \> **API Tokens** \> **Edit**. 6. Select **Continue to summary**, then select **Create Token**. 7. Copy and save the token value. This is your `API_TOKEN` for the next step. Note The steps above create a user-owned token. You can also create an account-owned token. Refer to [Create tokens via API](https://developers.cloudflare.com/fundamentals/api/how-to/create-via-api/) for more information. ## 2\. Create a service API token Use the [Create token API](https://developers.cloudflare.com/api/resources/user/subresources/tokens/methods/create/) to create a [service API token](https://developers.cloudflare.com/ai-search/configuration/service-api-token/). This token allows AI Search to access resources in your account on your behalf, such as R2, Vectorize, and Workers AI. 1. Run the following request to create a service API token. Replace `` with the token from step 1 and `` with your [account ID](https://developers.cloudflare.com/fundamentals/account/find-account-and-zone-ids/). Terminal window ``` curl -X POST "https://api.cloudflare.com/client/v4/user/tokens" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ --data '{ "name": "AI Search Service API Token", "policies": [ { "effect": "allow", "resources": { "com.cloudflare.api.account.": "*" }, "permission_groups": [ { "id": "9e9b428a0bcd46fd80e580b46a69963c" } ] } ] }' ``` This creates a token with the AI Search Index Engine permission (`9e9b428a0bcd46fd80e580b46a69963c`) which grants access to run AI Search Index Engine. 2. Save the `id` (``) and `value` (``) from the response. You will need these values in the next step. Example response: ``` { "result": { "id": "", "name": "AI Search Service API Token", "status": "active", "issued_on": "2025-12-24T22:14:16Z", "modified_on": "2025-12-24T22:14:16Z", "last_used_on": null, "value": "", "policies": [ { "id": "f56e6d5054e147e09ebe5c514f8a0f93", "effect": "allow", "resources": { "com.cloudflare.api.account.": "*" }, "permission_groups": [ { "id": "9e9b428a0bcd46fd80e580b46a69963c", "name": "AI Search Index Engine" } ] } ] }, "success": true, "errors": [], "messages": [] } ``` ## 3\. Create an AI Search API token To register the service token and create AI Search instances, you need an API token with AI Search edit 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 Manager`. 5. Under **Permissions**, select **Account** \> **AI Search** \> **Edit**. 6. Select **Continue to summary**, then select **Create Token**. 7. Copy and save the token value. This is your `AI_SEARCH_API_TOKEN`. ## 4\. Register the service token with AI Search Use the [Create token API for AI Search](https://developers.cloudflare.com/api/resources/ai%5Fsearch/subresources/tokens/methods/create/) to register the service token you created in step 2. 1. Run the following request to register the service token. Replace `` and `` with the values from step 2. Terminal window ``` curl -X POST "https://api.cloudflare.com/client/v4/accounts//ai-search/tokens" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ --data '{ "cf_api_id": "", "cf_api_key": "", "name": "AI Search Service Token" }' ``` 2. Save the `id` (``) from the response. You will need this value to create instances. Example response: ``` { "success": true, "result": { "id": "", "name": "AI Search Service Token", "cf_api_id": "", "created_at": "2025-12-25 01:52:28", "modified_at": "2025-12-25 01:52:28", "enabled": true } } ``` ## 5\. Create an AI Search instance Use the [Create instance API](https://developers.cloudflare.com/api/resources/ai%5Fsearch/subresources/instances/methods/create/) to create an AI Search instance. Replace `` with your [account ID](https://developers.cloudflare.com/fundamentals/account/find-account-and-zone-ids/) and `` with the token from [step 3](#3-create-an-ai-search-api-token). 1. Choose your data source type and run the corresponding request. **[R2 bucket](https://developers.cloudflare.com/ai-search/configuration/data-source/r2/):** Terminal window ``` curl -X POST "https://api.cloudflare.com/client/v4/accounts//ai-search/instances" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ --data '{ "id": "my-r2-rag", "token_id": "", "type": "r2", "source": "" }' ``` **[Website](https://developers.cloudflare.com/ai-search/configuration/data-source/website/):** Terminal window ``` curl -X POST "https://api.cloudflare.com/client/v4/accounts//ai-search/instances" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ --data '{ "id": "my-web-rag", "token_id": "", "type": "web-crawler", "source": "" }' ``` 2. Wait for indexing to complete. You can monitor progress in the [Cloudflare dashboard ↗](https://dash.cloudflare.com/?to=/:account/ai/ai-search). Note The `token_id` field is optional if you have previously created an AI Search instance, either via the [dashboard](https://developers.cloudflare.com/ai-search/get-started/dashboard/) or via API with `token_id` included. ## Try it out Once indexing is complete, you can run your first query. You can check indexing status on the **Overview** tab of your instance. 1. Go to **Compute & AI** \> **AI Search**. 2. Select your instance. 3. Select the **Playground** tab. 4. Select **Search with AI** or **Search**. 5. Enter a query to test the response. ## Add to your application There are multiple ways you can connect AI Search to your application: [ Workers Binding ](https://developers.cloudflare.com/ai-search/usage/workers-binding/) Query AI Search directly from your Workers code. [ REST API ](https://developers.cloudflare.com/ai-search/usage/rest-api/) Query AI Search using HTTP requests. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/ai-search/","name":"AI Search"}},{"@type":"ListItem","position":3,"item":{"@id":"/ai-search/get-started/","name":"Get started"}},{"@type":"ListItem","position":4,"item":{"@id":"/ai-search/get-started/api/","name":"API"}}]} ```