AI Search item lookup can now target an exact object key!

Hi, it's Shii! Here's a small but handy API update for anyone using AI Search.

Cloudflare Changelog developers.cloudflare.com

What was announced?

Cloudflare's changelog announced that the AI Search list items endpoint now supports a key query parameter. AI Search lets you upload files to an instance, or connect a data source like an R2 bucket, so your content becomes searchable with natural language. Each file becomes an item identified by an object key, its filename or path.

With the new key parameter, if you already know the object key, you can fetch that single item directly without paging through the full list. The existing item_id parameter works when you know the ID; this new one covers the opposite case, when you know the key but not the ID.

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

Note that keys are unique per data source, so if the same key exists across multiple sources, you need to combine it with the source parameter (for example, source=builtin) to disambiguate.

The story so far

Until now, if you wanted to find a single item by its object key, the only option was to page through the list items endpoint until you found it. The more items an instance had, the more requests you had to make to reach the one you wanted, which was a bit of a hassle.

What changes

Now you can reach the item you want in one shot just by passing the key parameter. If your own system already tracks file paths or IDs, you can pass them straight into the query without writing your own pagination logic. It's a small thing, but it simplifies apps built on top of AI Search.

Wrap-up

• The list items endpoint now supports a key parameter
• If you know the object key, you can fetch a single item without paging through the full list
• Combine it with source when the same key exists across multiple data sources

If you're building on AI Search and often need to check the state of a specific file, this is a quietly welcome improvement!