REST API

import { Render } from "~/components";

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

API paths

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

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.