Pular para o conteúdo

REST API

Atualizado em Ver como Markdown

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.

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

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/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.