Content Lake v2025-02-19: 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.

Breaking changes

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.

Highlights

Perspective changes

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.

New query perspectives

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.

New includeAllVersions parameter

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

/listen

/doc

New path prefix for versions

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.

Gotcha

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.

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

Additional Actions

The Actions API now includes actions for managing Content Releases. Along with this, actions such as sanity.action.document.discard and sanity.action.document.replaceDraft have been deprecated in favor of sanity.action.document.version.discard and sanity.action.document.version.replace.

See the Actions API reference for more details.

New GROQ functions

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.

New lastRevision parameter

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.

Fix for empty key projection bug

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

For example:

Input

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

response

{
"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"
}
}