Content Releases APIs and new perspective defaults

This release introduces new features and changes to support Content Releases. For more details on Content Releases, see the Studio release notes.

The following items may break behavior in your applications. See the details below for further explanations and migration paths.

• The default perspective has changed to only display published content.
• Raw perspective requests now include versions. prefixed documents in addition to drafts. and published documents.
• A bug in GROQ queries that caused empty keys to expand has been fixed. If you are relying on this behavior, see the details below.

versions.** documents are not returned in API versions prior to 2025-02-19. You must opt-in to this version to query versions-prefixed documents.

The default perspective has changed from raw to published. This includes:

• /query now uses perspective=published by default.
• GraphQL now uses perspective=published by default.

To return to the previous behavior, set perspective to raw.

In addition to the existing named perspective values, you can also pass one or more release IDs to the query endpoint's perspective parameter. For example: perspective=release-a,release-b,release-c. This will give you a view on your dataset as if release-c had been published, followed by release-b and finally release-a. This is generalisation of the existing previewDrafts functionality to support Content Releases.

Learn more in the Content Releases API documentation.

The following endpoints now include a boolean includeAllVersions parameter. Set it to true and use an authenticated request to include all versions.

• /listen
• /doc

Prior to 2025-02-19, queries on /query and similar APIs returned published documents and drafts.** documents when using the raw or previewDrafts perspectives. In 2025-02-19 and later, a versions.** path is introduced for Content Release document versions.

If you rely on path prefixes alone, you'll want to use perspectives instead to control which documents are returned by queries.

The Actions API now includes actions for managing Content Releases. See the Actions API reference for more details.

• sanity::versionOf(documentID): Checks for versions of a provided document ID. Use inside a filter to return matching documents. For example: *[sanity::versionOf("abc123")].
• sanity::partOfRelease(releaseID): Checks whether a document is part of a given release. For example, fetch all the version documents in release rel-summer using *[sanity::partOfReleases("rel-summer").
• releases::all(): Returns all releases.

Learn more about these in the GROQ functions reference documentation.

The document history API now accepts a lastRevision parameter, which returns the current data for an existing document, or the last state before deletion for a deleted document.

This version also introduces a fix to a GROQ bug whereby empty keys in projections would expand into the object.

For example:

{
  "": {
    "a": "b"
  }
}

{
  "a": "b"
}

This is corrected in 2025-02-19, and instead the query will return the following:

{
  "": {
    "a": "b"
  }
}

To replicate the older behavior in the new API version, update the empty string with the ellipsis operator (...). For example:

{
  ... {
    "a": "b"
  }
}