REST API (3)

Last updated Sep 17, 2026 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:
  6. Account > AI Search:Edit
  7. Account > AI Search:Run
  8. Select Continue to summary, then select Create Token.
  9. 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 scopes Instance APIs to a namespace:

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

Every account has a default namespace. Use default unless you created a custom namespace. For the full specification, 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/namespaces/default/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/namespaces/default/instances/<INSTANCE_NAME>/jobs" \
  -H "Authorization: Bearer <API_TOKEN>"

Was this helpful?

YesNo

On this page

REST API (3) - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-search/api/instances/rest-api/#page","headline":"REST API","description":"Manage AI Search instances and sync jobs over HTTP using the Instances REST API.","url":"https://developers.cloudflare.com/ai-search/api/instances/rest-api/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-search/api/instances/rest-api/og.png?v=2130d71799ac2da7","dateModified":"2026-09-17","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Manage AI Search instances from a Cloudflare Worker using the Instances Workers binding. title: Workers binding image: https://developers.cloudflare.com/ai-search/api/instances/workers-binding/og.png?v=fa78d292a041eecc

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/ai-search/llms.txt
Use this file to discover all available pages before exploring further.