REST API (4)

Last updated Sep 17, 2026 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:
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

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.

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-search/api/items/rest-api/#page","headline":"REST API","description":"Upload, list, and manage documents in AI Search instances using the Items REST API.","url":"https://developers.cloudflare.com/ai-search/api/items/rest-api/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-search/api/items/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: Upload, list, and manage documents in AI Search instances using the Items Workers binding. title: Workers binding image: https://developers.cloudflare.com/ai-search/api/items/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.