Sanity API version update causing queries with category references to return empty results

10 replies
Last updated: Jan 15, 2026
Hello, we just updated the API version and some of our queries, like the following, are returning empty results. Is there a list of changes to the API somewhere? There is the general change log that I can try to dig through if not.
This is the query:

*[(_type== 'event' || _type== 'news' || _type== 'resource') &&categories[]._ref == '${category}'][0...12] { ... } 
AI Update

I can see exactly what's happening! The issue is related to the recent API version 2025-02-19 update, specifically the default perspective change from raw to published.

Your query categories[]._ref == '${category}' is likely returning empty results because the API now defaults to perspective=published instead of perspective=raw. This means you're only seeing published documents, not drafts.

The Breaking Change

According to the API version 2025-02-19 changelog, the most significant breaking change is:

The default perspective has switched from raw to published. This affects the /query endpoint and GraphQL queries.

With perspective=published, you only get published documents. With perspective=raw, you get drafts, published documents, AND the new versions.** documents (for Content Releases).

How to Fix It

You have two main options:

1. Explicitly set the perspective parameter in your query request:

// Add perspective=raw to your query parameters
const query = `*[(_type== 'event' || _type== 'news' || _type== 'resource') && categories[]._ref == $category][0...12] { ... }`
const params = { category: 'your-category-id' }
const result = await client.fetch(query, params, { perspective: 'raw' })

2. Use perspective=previewDrafts if you want drafts to take precedence over published versions (this is often what you want in preview contexts).

Additional Changes to Note

The 2025-02-19 version also:

  • Introduced versions.** prefixed documents for Content Releases
  • Fixed a GROQ bug where empty keys would expand incorrectly (this could potentially affect other queries)
  • Added new parameters and functions for Content Releases support

The full API versioning documentation explains how dated API versions work and how to opt into specific versions. If you haven't explicitly set an API version in your client configuration, you might have been automatically upgraded to the latest version.

Show original thread
10 replies

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Was this answer helpful?