Get help on Discord

Why don't Vision plugin API version numbers match documentation?

15 replies
Last updated: Sep 9, 2021
Is there a reason the API version numbers in the Vision plugin don’t match the numbers specified here: https://www.sanity.io/docs/api-versioning . Maybe I’m missing something?
AI Update

You're not missing anything - there does appear to be a discrepancy between what you see in the Vision plugin's API version dropdown and the comprehensive list of API versions in the API Versioning documentation.

Here's what I can confirm from the documentation:

About Sanity's API versioning: According to the API Versioning docs, Sanity uses a date-based versioning system where "you don't have to use specific dates, any past or present date is valid, and today's date will always give you the latest version." The documentation lists several important milestone versions like v2021-03-25, v2021-10-21, and v2025-02-19, each introducing significant changes to GROQ behavior or API functionality.

About the Vision plugin: The Vision plugin documentation confirms that Vision "allows you to query against different datasets within your project and select different API versions," but it doesn't specifically document which versions appear in the dropdown or why.

What's likely happening: The Vision plugin dropdown probably shows a curated subset of the most significant API versions rather than all possible date-based versions. However, I couldn't find official documentation confirming this is intentional behavior versus potentially outdated plugin versions.

What you can do: Even if a newer API version like v2025-02-19 doesn't appear in Vision's dropdown, you can still use it by:

  1. Configuring it in your Vision plugin settings:
visionTool({
  defaultApiVersion: '2025-02-19'
})
  1. Setting it in your Sanity client configuration for your actual application queries

If you're seeing significantly outdated versions in the dropdown, it might be worth updating your @sanity/vision package to the latest version with npm install @sanity/vision@latest.

If the mismatch is causing confusion or you need specific newer API versions available in the dropdown, I'd recommend reaching out to Sanity support or posting in the Sanity community to confirm whether this is expected behavior or if there's a configuration option to show more versions.

Show original thread
15 replies
Oh ok, I think I understand.v1 = outdated
vX = current, most recent

Is there a reason v2021-03-25 is there? Is that also essentially v1?
I missed the experimental section of that page, thx for the help!
vX is the experimental version that's likely to change or be unstable. So proceed with caution! The v2021-03-25 version will be your best bet in terms of getting the most recent, stable version.
Thats the version that follows the date incremented version numbers that we use now.
Oh ok, where do we following what is considered the most recent stable version?
I thought the current stable is what was listed at the top of
https://www.sanity.io/docs/api-versioning#71d69d9f4146 . For instance, currently 
v2021-06-07
Ah, yeah I see how that's confusing. Using v2021-03-25 in Vision will be what you want. On your frontend when configuring a client you'd use the current date to make sure you're getting the right one. We'll add in a note to the docs to make that more clear!
Sorry, I’m not sure I follow 😞. If v2021-03-25 is the most recent stable, and we’re recommended to use the current date (such as today), would we be getting v2021-06-07 or v2021-03-25?
Is v2021-06-07 the most recent experimental version and v2021-03-25 is the most recent stable?
Sorry, let me see if I can clarify: using v2021-06-07, for example, would use the most recent, stable API version released on or before June 7, 2021. v2021-03-25 would would use the most recent, stable API version released on or before March 25, 2021. You'll only end up using an experimental version if you use vX.
I think the reason it's a bit confusing is that the version number notation is "overloaded"; it's used both in a "filter" capacity in the URL, where it means " give me the most recent <= {date}", and as names for actual versions, where it means "the version released at {date}" :)
In this particular case, both v2021-03-25 and v2021-06-07 requests result in the actual version v2021-03-25 (since there's no newer stable version)
In this particular case, both v2021-03-25 and v2021-06-07 requests result in the actual version v2021-03-25 (since there's no newer stable version)
Ah right, thank you both! I think my confusion came from the docs. I thought there was some relevance to the date of v2021-06-07 but it sounds like that was just an arbitrary date example. The reason I made this thread originally was because the Vision plugin explicitly references v2021-03-25, but the docs reference v2021-06-07 (the arbitrary example date).
Thanks again!!
I have this confusion everytime, may be add some info in brackets?
eg:vX (beta)v2021-03-25 (latest, stable)
v1 (old)

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.

Get started for freeExplore the demo

Was this answer helpful?