Content Releases API

Programmatically manage Content Releases with the API and clients.

Content Releases allow teams to organize and schedule updates across multiple documents. Teams can plan, preview, and validate significant changes in advance, ensuring seamless and conflict-free content deployment.

This document explores interacting with Content Releases using Sanity's APIs. For details on using Content Releases in Sanity Studio, or customizing the experience follow these links:

User guide

Content Releases user interface and workflow guide

Configure content releases

Configure the studio and visual editing experience

Paid feature

Content Releases is available for all projects on the Growth plan and up.

APIs that interact with Content Releases require API version 2025-02-19 or later.

Releases and document versions

Releases are Sanity documents with a type of system.release. They contain information about the release such as the title, release type, and state.

Protip

Users of content resources and custom roles can restrict access by targeting the system.release document type, as well as any documents that match the version Id format.

Releases and documents connect by a document ID system similar to the drafts. syntax. For releases, document IDs start with the versions. prefix. For example, if a document with an ID of movie_70981 is published, has a draft, and exists in a future release, it could end up with the following versions:

The published version: movie_70981
A draft version: drafts.movie_70981
A release version: versions.<release-name>.movie_70981

Releases have an automatically generated name, not to be confused with the user-supplied title. This name matches the end of the ID. For example, a release name of rSC2jjcUJ results in an _id of _.releases.rSC2jjcUJ.

Release states

The current status of a release is known as the release state. A release may have the following states:

active: The general state of a release that is not within one of the other states. This is the default state of a new release.
scheduled: A state resulting from calling the sanity.action.release.schedule action on the release or scheduling the release in Studio.
published: A state resulting from either calling the sanity.action.release.publish action, publishing the release in Studio, or when a scheduled release is published due to reaching its publishAt time.
archived: A state resulting from calling the sanity.action.release.archive action or archiving the release in Studio.
deleted: A state resulting from calling the sanity.action.release.delete action on an archived release or deleting the release in Studio.

Additional transient states exist to indicate the asynchronous points when releases move between states:

scheduling/unscheduling: Intermediate states which will exist when moving to/from the scheduled state.
archiving/unarchiving: Intermediate states which will exist when moving to/from the archived state.
publishing: Intermediate state which will exist before reaching the published state. Note that a scheduled release will also transition through publishing.

Query releases and versions

Releases are Sanity documents and respect the existing query and mutation APIs. For examples on querying and interacting with releases and their documents, explore the guide below.

Content Release patterns

Common patterns for querying and interacting with releases and their documents

Additional resources

Actions API

The Actions API provides release and version-specific actions for creating and manipulating releases. It powers the release workflows in Studio and is the preferred method for manipulating releases.

GROQ functions

GROQ queries can utilize the releases::all(), sanity::partOfRelease(), and sanity::versionOf() functions to retrieve release information.

@sanity/id-utils

This utility library helps parse and convert between the various Id formats.

Updated on March 19, 2025