API versioning in the JavaScript client
In order to promote incremental changes, the Sanity API is versioned based on ISO dates (YYYY-MM-DD) in the UTC time zone.
Gotcha
The apiVersion property of the JavaScript client is currently optional. If no value is provided, the client will issue a deprecation warning and default to using v1 of the API.
Unless you know of a specific API version you want to use, you'll want to set it to today's UTC date. By doing this, you'll get all the latest bug fixes and features, while preventing any timezone confusion and locking the API to prevent breaking changes.
What does the apiVersion date mean?
Essentially, the date you enter for the apiVersion will use the API as it worked on that date. You can confidently use features that were added on or before that date, and any breaking changes implemented after that date will not affect your use of the API.
Note: While it's tempting to use a date that's been set dynamically as an API version, this can be a risky idea. Using a static (that is, hard coded) date, you pin your project to a specific version of the API, which prevents any sudden changes that can break your implementation. If you hard code your API to v2026-07-28, and it works, you can be assured it will continue to work even as new API versions are released.
Protip
Recommended: apiVersion: '2026-07-28'
Not recommended: apiVersion: new Date().toISOString().slice(0, 10)
Gotcha
When using the HTTP API, the version number is prefixed with the v character (v1, v2026-07-28, etc.). In the JavaScript client, no prefix is needed (apiVersion: '2026-07-28').
Example usage
import {createClient} from '@sanity/client'
const client = createClient({
projectId: '<your-project-id>',
dataset: 'production',
apiVersion: '2026-07-28', // use a UTC date string
token: 'sanity-auth-token', // or leave blank for unauthenticated usage
useCdn: true, // `false` if you want to ensure fresh data
})Was this page helpful?
Feedback submitted, thanks for helping us improve the docs. Have you tried these alternatives?