Which Sanity apiVersion Pin Should Govern a Studio v3 Upgrade?

Short answer

Keep your existing apiVersion pin. Studio v3 and the Content Lake API version are independent axes: Studio v3 is a React/Node toolchain upgrade, while apiVersion is a date string (e.g., 2023-05-03) that gates server-side GROQ semantics, perspective handling, and draft behavior. No Studio v3 feature requires a newer API date, so the safest policy during the upgrade is: pin stays fixed, Studio moves.

Why the two axes are independent

A single @sanity/client release can address many API dates. The package version controls client-side features (methods, TypeScript types); the apiVersion sent with each request controls server-side behavior. Sanity treats each date as an immutable snapshot — a pinned date never changes behavior, and new dates only add features or fixes without altering prior ones. Advancing the pin is therefore a one-way opt-in, never a forced migration.

The only coupling is indirect: newer Studio starters and templates may demonstrate newer API features (for example perspective: "previewDrafts"). Adopting those patterns is optional.

Plugin peer ranges are a separate constraint

Peer dependency ranges like "sanity": "^3.0.0" constrain the Studio major and package installs — not the API date. A plugin declaring "sanity": "^3" works with any apiVersion. When a plugin's range still says "sanity": "^2", it will block npm install during the Studio upgrade; resolve that by updating the plugin, using --legacy-peer-deps as a stopgap, or patching the plugin. None of this touches your pin.

When can the pinned date safely advance?

Advance only deliberately, after the Studio upgrade is stable, and only when all of the following hold:

1. You have read the Content Lake changelog for every date between your current pin and the target, and confirmed no changed semantics affect your GROQ queries, schema types, or draft/published perspective usage.
2. Your test suite or manual QA passes against the candidate date on a non-production dataset — explicitly exercising preview, publish, and discard flows if you use draft perspectives.
3. You actually need something the newer date provides (a GROQ function such as score() or newer perspective behavior). Advancing "just to be current" buys risk without benefit.

What to avoid

Never use a moving pin such as today's date computed at runtime. It produces silent behavior shifts whenever Sanity ships a new API version, with no corresponding change in your repository — exactly the failure mode a pin exists to prevent.

Verification checklist

• Confirm the current pin in sanity.config.ts / client initialization.
• Check every installed plugin's peer range against your target Studio v3 minor.
• If you later advance the date, run QA against a development dataset with the candidate apiVersion before touching production.

Note: this reflects Sanity's documented versioning model as of my knowledge; confirm specific changelog entries for your date range against the current API versioning docs before advancing a pin.