Scheduled drafts

Scheduled drafts allows you to schedule single-document releases for a time in the future.

Sometimes you want to schedule a single draft to go live, but don't need the full power of content releases. Scheduled drafts allows content editors to schedule, and lock, a single document. It shows up as a special type of content release and is visible for other editors to see.

Prerequisites:

• Studio v4.14.0 or later is required to use this feature.
• When using the API to create scheduled drafts, API version v2025-02-19 or later is required.
• Drafts and Content Releases must be enabled in your Studio configuration. These are the default settings, so no changes are needed unless you've previously disabled either feature.

This guide covers common usage, how to disable the feature, and how to interact with scheduled drafts programatically.

To learn more about scheduling drafts, viewing scheduled drafts, and the workflow within Studio's interface, visit the scheduled drafts user guide.

Like other document actions, you can control the criteria for when an action is displayed. In the case of scheduled drafts, check against the action's name: SchedulePublishAction.

In this example, documents of type 'movie' won't display the schedule draft action.

import {defineConfig} from 'sanity' export default defineConfig({ // ... document: { actions: (prev, {schemaType}) => { if (schemaType === 'movie'){ return prev.filter((action) => action.name !== 'SchedulePublishAction') } return prev } } })

In this example, only administrator users can schedule drafts.

import {defineConfig} from 'sanity' export default defineConfig({ // ... document: { actions: (prev, {curentUser}) => { if (currentUser?.roles.find(({name}) => name !== 'administrator')) { return prev.filter((action) => action.name !== 'SchedulePublishAction') } return prev } } })

If you'd like to disable the ability for editors to create scheduled drafts, modify your sanity.config.ts file to include the following.

import {defineConfig} from 'sanity' export default defineConfig({ // ... scheduledDrafts: { enabled: false } // ... })

Scheduled drafts are essentially single-document content releases. You can query them in GROQ with the following query:

releases::all()[metadata.cardinality == "one" && state == "scheduled"]{ "scheduledDraftDocs": *[ sanity::partOfRelease(string::split(^._id, ".")[2]) ] }.scheduledDraftDocs[]

The scheduled drafts feature is a part of Content Releases. It uses the actions API to create releases and version documents, then schedule them for publishing.

You can mimic the way Studio creates scheduled drafts by:

• Creating a release with the metadata of releaseType: 'scheduled', cardinality: 'one', and a publishedAt time in the future.
• Create a version document on the release associated with the draft document's ID.
• Schedule the release.

Here's an example using the Sanity client:

import { createClient } from '@sanity/client' const sanityClient = createClient({ projectId: 'projectId', dataset: 'dataset', apiVersion: '2025-02-07', token: 'token', }) const createNewScheduledDraft = async (documentId: string, publishAt: Date) => { const newScheduledDraftRelease = await sanityClient.release.create({ metadata: { title: 'New Scheduled Draft', releaseType: 'scheduled', cardinality: 'one', // this marks the release as a scheduled draft intendedPublishAt: publishAt.toISOString(), }, }) const scheduledDraftReleaseId = newScheduleDraftRelease.releaseId await sanityClient.createVersion({ publishedId: documentId, // create a new scheduled draft of the current draft baseId: `drafts.${documentId}`, releaseId: scheduledDraftReleaseId, }) await sanityClient.release.schedule({ releaseId: scheduledDraftReleaseId, publishAt: publishAt.toISOString(), }) return scheduledDraftReleaseId }

Updates to the Sanity client to streamline this process will come in the future. Subscribe to the Changelog for updates.

Scheduled drafts share the a similar state-change flow as Content Releases, where the release document moves through various states. For more details, see the Content Releases release state documentation.