Skip to content
Unlock seamless workflows and faster delivery with our latest releases - Join the deep dive

API versioning in Javascript Client

In order to promote incremental changes, the Sanity API is versioned based on ISO dates (YYYY-MM-DD) in the UTC timezone.

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 (i.e., 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 v2021-08-31, and it works, you can be assured it will continue to work even as new API versions are released.

Protip

Recommended: apiVersion: '2021-08-31'

Not recommended: apiVersion: new Date().toISOString().slice(0, 10)

In future versions, specifying an API version will be required. For now, to maintain backward compatibility, not specifying a version will trigger a deprecation warning and fall back to using v1.

Gotcha

When using the HTTP API, the version number is prefixed with the v character (v1, v2021-08-31, etc.). In the JavaScript client, no prefix is needed (apiVersion: '2021-08-31').

Example usage

import sanityClient from '@sanity/client'

const client = sanityClient({
  projectId: 'your-project-id',
  dataset: 'production',
  apiVersion: '2021-08-31', // 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
})

Updated on August 31, 2021

Was this article helpful?