REST API

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

Authentication

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

In the Cloudflare dashboard, go to My Profile > API Tokens.
Go to API Tokens ↗
Select Create Token.
Select Create Custom Token.
Enter a Token name, for example AI Search Manager.
Under Permissions, add two permissions:
- Account > AI Search:Edit
- Account > AI Search:Run
Select Continue to summary, then select Create Token.
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

Item APIs are scoped 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.

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/namespaces/default/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/namespaces/default/instances/<INSTANCE_NAME>/items" \
  -H "Authorization: Bearer <API_TOKEN>"

To find a single item by its exact object key, pass the key query parameter:

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/default/instances/<INSTANCE_NAME>/items?key=docs/readme.md" \
  -H "Authorization: Bearer <API_TOKEN>"

Keys are unique per data source, so combine key with source (for example, source=builtin) to disambiguate when the same key exists across multiple sources.