API Versioning

How to handle versioning in the Sanity API

Every Sanity API request is pinned to a version, written as a date. That version fixes the API's behavior, so your code keeps working the same way as the service evolves.

Every Sanity client takes the version as a configuration option, including the official Sanity JavaScript client. A client configured with 2026-07-28 uses the most recent API version released on or before July 28, 2026.

const {createClient} = require('@sanity/client')

const client = createClient({
  projectId: 'YOUR_PROJECT_ID',
  dataset: 'YOUR_DATASET',
  apiVersion: '2026-07-28', // a static UTC date string
  token: '<sanity-auth-token>', // or leave blank for unauthenticated usage
  useCdn: true, // `false` if you want to ensure fresh data
})

The URL of every API call includes an explicit version as the first path segment. The following call uses API version v2026-06-24:

https://example.api.sanity.io/v2026-06-24/data/query/production?query=*

From time to time, we may need to make breaking changes to our API functionality. We try very hard to avoid this, but it is sometimes necessary to fix bugs. A versioned API lets us make those improvements without breaking existing code.

To the best of our ability, we try to ensure that old versions of the API don't change, even as our services evolve. This may sometimes include "wrong" behavior that we choose to maintain if we deem that the fix might negatively impact users.

As long as we don't see the change as a breaking change, we may choose to introduce it also in older versions of the API.

Version dates are ISO 8601-formatted and use the UTC time zone. Any past or present date is valid, and today's date always resolves to the latest version, so there's no need to check the release history.

Stripe inspired us to use dates instead of incremental version numbers (although our initial version is v1). We much prefer to release frequent small improvements rather than saving them up for a huge v2 release. This allows us to get fixes into the hands of our users much sooner and makes it easier for our users to upgrade incrementally. With new versions released regularly, we believe it is more informative to use dates rather than rapidly increasing numbers.

Clients should be configured with an explicit, static API version. See the individual clients' documentation for details on how to do this. When starting new projects, clients should typically be given today's UTC date to get the most recent bugfixes and improvements. Older clients which do not support versioning will default to v1, our initial and outdated API version.

Write the date as a literal string. Computing it at runtime (for example from new Date()) means your API version changes every day, so a change to the API can alter your app's behavior without you deploying anything. A hardcoded date pins the behavior until you decide to move it.

The apiVersion property of the JavaScript client is optional. Omit it and the client issues a deprecation warning, then defaults to v1 of the API. Passing the property with an undefined value throws an error instead.

When using the HTTP API, the version number is prefixed with the v character. The JavaScript client accepts the version with or without the prefix, and adds it when building the request URL.

To upgrade an application to a newer API version, first read our list of API changes to determine which (if any) modifications must be made to the application. Then, with a local instance of the application, set the newer API version for the client, make the necessary changes to the code, and then test the application either locally or in a staging environment. Once you are confident that the application correctly handles the new API version you can deploy it to production.

We recommend making multiple smaller upgrades rather than a single larger upgrade, to reduce the chance of anything breaking and make the job more manageable, but this is up to you to decide.

The special version X is used to test experimental changes. This version may change at any time in any way and is used at your own risk. Not only will it be backward-incompatible, but it may also cause data loss and other problems.

When using a version that isn't considered completely stable, the API will return a warning message in the X-Sanity-Warning header.

At times we will have to deprecate and then remove certain older versions of the API. We will always give appropriate notice when this is necessary.

In addition to notices on our website and to your registered email address, these versions will receive a warning through the X-Sanity-Warning header and also be tagged as deprecated via an X-Sanity-Deprecated: true HTTP header. Once an API version is removed, all calls to that version will return errors with code 410.

We consider the following changes to be backward-compatible and may therefore introduce them retroactively in old API versions. This list is not exhaustive.

• Adding new object attributes in JSON responses (outside of documents or query results)
• Changing the order of object attributes in JSON responses
• Adding new _-prefixed metadata attributes to stored or modified documents
• Adding new functionality to GROQ, such as operators, functions, and data types
• Adding new, optional parameters to API calls
• Adding new HTTP headers in responses
• Adding new endpoints to the API, or new methods to existing API endpoints