Skip to content

REST API

Last updated View as Markdown Agent setup

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>"

Was this helpful?