Workflows
Model, run, and observe content workflows on the Content Lake: definitions, stages, activities, and effects, from editorial review to full automation.
Workflows
What Workflows is, the core concepts behind it, and which surface to build on.
Quick start: run your first workflow
Define your first workflow in TypeScript, deploy it, and move a Sanity document through its stages.
Configure and deploy workflow definitions
Install and authenticate the workflow CLI, write the sanity.workflow.ts config that binds your definitions to a Sanity resource, and deploy them to one environment or several.
Run Workflows with Sanity Functions
Use GROQ-triggered and scheduled Sanity Functions to start workflows, reevaluate conditions, and process queued effects.
Add Workflows to Sanity Studio
Install the Workflows plugin in a Sanity Studio, bind it to your deployed definitions, and put workflows in front of editors.
How early access works
What building on Workflows during early access commits you to: one fixed 0.x stack, a stricter contract for stored documents, what the Content Lake does not yet enforce, and the runtime you supply.
Definitions, instances, and stages
A definition describes a process. An instance is one run of it, pinned to the definition version it started under and sitting in exactly one stage.
Fields
Fields carry the typed data belonging to a workflow instance.
Activities and actions
An activity is work scoped to one stage visit. Actions resolve it, write instance state, and queue effects, fired by a caller or automatically by the engine.
Conditions
Write GROQ conditions over the engine’s bounded instance snapshot: what the snapshot holds, which sites bind the caller, named predicates, and the start filter and requirements.
Operations
The write vocabulary: a small set of ops that mutate an instance’s fields and statuses, carried by actions and by effect completions.
Subworkflows
How a large process composes out of smaller ones: an action spawns a child workflow per row of a query, and a trigger resolves the parent’s activity once they all settle.
Global document references
Why every document pointer in a workflow carries its location, and how resource aliases keep deployed definitions portable across environments.
Engine
The library that evaluates and commits Workflow instances.
Effects and runtimes
Why the engine queues effects instead of running them, and where the runtime lives: the verbs your code calls, and the drainer that delivers queued work.
Guards and enforcement
Declare a guard that restricts which mutations a document accepts while an instance occupies a stage, and know what honors it today.
Actors, tokens, and what's actually enforced
Who the engine acts as, where a condition can read the caller, and which of the engine’s checks would stop a client that bypasses it.
History and audit trail
Understand the durable event history stored on every Workflows instance, what it records, and where its provenance boundary ends.
Evaluation insights
Explain condition outcomes and field proposals from a Workflows evaluation.
Workflows in Sanity Studio
See where your work stands, complete the tasks a workflow is waiting on, find work assigned to you, and understand a held publish.
Build a workflow interface with the App SDK
Render live workflow state and commit actions from your own App SDK application: mount a session, handle its states, render activities and fields from the evaluation, and list instances.
The reactive session
How a reactive session projects one workflow instance for a UI: what keeps it current, what each session state means, and when a preview becomes a commit.
Reusable UI components
Add assignment, date, member, and workflow-diagram controls to a custom Workflows interface.
Create a workflow-powered Document Action
Build a custom Submit for review Document Action in Sanity Studio with the @sanity/workflow-studio adapter: read the document's workflow, respect the evaluated verdict, and commit the action.
Custom reactive adapters
Connect Workflows to an unsupported host or data layer by implementing the store-agnostic reactive observer contract.
Connect an agent over MCP
Install and authenticate the Workflows MCP server, register it with your agent, address a workflow environment, and see which tools change state.
Test your workflows
Run the real workflow engine in memory: drive every path of a workflow, control the clock, simulate guard enforcement, and assert on exactly what happens.
Coordinate content across projects and datasets
Run one workflow over content that lives in other projects, datasets, Media Libraries, or Canvas, and prove the routing before you rely on it.
Upgrade Workflows packages
Take a new Workflows release without breaking in-flight instances: the lockstep set, what the reader-model literal claims, and the readers-first order.
Reference
Find the authoritative API and type reference for each Workflows domain. Exact contracts live at the bottom of the corresponding concept page.
Workflow CLI command reference
Every Workflows CLI command with its flags, selectors, JSON output, and exit behavior, for deploying definitions and driving instances.
Limits
The engine’s operational caps and defaults: what each protects, and where to tune the ones you can.
Workflows release notes
Curated overviews of recent Workflows prerelease package waves.
Cookbook
Worked, runnable workflow examples for Sanity: editorial review, AI content pipelines, coordinated releases, and more, each a complete definition.
Cookbook: Editorial review
A four-stage editorial review workflow for Sanity: assignment, drafting, review, and published, driven by human actions in the Studio.
Cookbook: AI content pipeline
An AI content pipeline built on Workflows: effect handlers call generation APIs while editors approve results through workflow actions.
Cookbook: Coordinated release
A release workflow that coordinates approvals across many documents and hands the atomic go-live to a Content Release.
Cookbook: Client–server asset intake
Start an image-review workflow from an app, then let a server import or discard the staged file.
Cookbook: Handle workflows when referenced content is deleted
Apply an application-owned lifecycle policy when content watched by an Workflow is deleted.