REST API

Use the AI Search REST API to manage instances and sync jobs over HTTP.

Authentication

All requests require an API token with AI Search:Edit and AI Search:Run permissions.

1. In the Cloudflare dashboard, go to My Profile > API Tokens.

   Go to API Tokens

2. Select Create Token.

3. Select Create Custom Token.

4. Enter a Token name, for example AI Search Manager.

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.

Include the token in the Authorization header for all requests:

Authorization: Bearer <API_TOKEN>

API paths

AI Search APIs are available at two base paths:

Path	Description
/accounts/{account_id}/ai-search/instances/{id}	Operates on a specific instance
/accounts/{account_id}/ai-search/namespaces/{namespace}/instances/{id}	Operates on instances within a namespace

The available operations are the same for both paths. For the namespace-scoped API, refer to the Namespace API reference.

Instances

Create, list, get, update, and delete AI Search instances. For the full specification, refer to the Instances API reference.

Operation	Method	Description
Create	POST	Create a new instance
List	GET	List all instances
Get	GET	Get an instance by ID
Update	PUT	Update instance configuration
Delete	DELETE	Delete an instance
Stats	GET	Get indexing statistics

Example: Create an instance

Create an instance in the default namespace:

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-instance"
  }'

Jobs

Trigger and monitor sync jobs that scan your data source and index new or updated content. For the full specification, refer to the Jobs API reference.

Operation	Method	Description
Create	POST	Trigger a new sync job
List	GET	List all jobs for an instance
Get	GET	Get job details
Logs	GET	View job logs

Example: Trigger a sync job

Start a new sync job for an instance:

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/jobs" \
  -H "Authorization: Bearer <API_TOKEN>"