REST API

Use the AI Search REST API to upload, list, and manage individual documents within an instance.

Note

The Items API uploads files to an instance's built-in storage. For more details, refer to Built-in storage.

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.

Items

Upload, list, get, delete, and download items within an instance. For the full specification, refer to the Items API reference.

Operation	Method	Description
Upload	POST	Upload a document for indexing
List	GET	List all items in an instance
Get	GET	Get item info by ID
Delete	DELETE	Delete an item
Download	GET	Download the original file

Example: Upload a document

Upload a file to an instance:

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/items" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -F "file=@/path/to/your/file.pdf"

Example: List items

List all items in an instance:

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