Reference

Find the authoritative API and type reference for each Workflows domain. Exact contracts live at the bottom of the corresponding concept page.

Use the package references for exported types, functions, options, and defaults. The guides linked on this page explain how those APIs work together.

The CLI command reference covers commands and flags. Connect an agent over MCP covers tool inputs and results.

• Engine: engine construction, verbs, transactions, evaluation, errors, actor resolution, and persisted-model governance. See the advanced exports for lower-level helpers.
• Definitions, instances, and stages: definition and instance shapes.
• History and audit trail: retrieving instance history and the complete HistoryEntry event reference.
• Stages and transitions: stage, visit, and transition contracts.
• Fields: field declarations, stored field types, progress, initial values, validation, and editability.
• Conditions: condition syntax, variables, and evaluation contexts.
• Activities and actions: declarations, evaluation, and projected firing consequences.
• Operations: state-changing operations and value expressions.
• Effects and runtimes: declarations, handlers, draining, mid-dispatch field reports, and completion.
• Guards and enforcement: guard declarations and lifecycle.
• Actors, tokens, and what's actually enforced: which identity a call acts as, where a condition can read the caller, and which checks actually hold.
• Subworkflows: spawning, child lifecycle, and propagation.
• Global document references: resource-qualified references and deployment helpers. See expandResourceAliases and refsOf.

Deployments, tags, and resources: deployment identity, storage partitioning, resource aliases, and the WorkflowDeploymentInput contract.

These lower-level exports support custom integrations, deployment tooling, and persisted-model diagnostics.

WorkflowConfigInput is the authoring shape accepted by defineWorkflowConfig. Every deployment is a WorkflowDeploymentInput.

WorkflowDeploymentInput is the authored deployment shape. Its expectedMinReaderModel literal acknowledges the model verified across the runtimes sharing its resource. Reuse the authored deployment when configuration and Blueprint entry points share it. See Deployments, tags, and resources for its fields.

WorkflowConfig is the parsed shape returned by defineWorkflowConfig. It can hold an unverified acknowledgement until a deployment is selected.

WorkflowDeployment is one parsed deployment. Do not pass it back to an authoring API that requires WorkflowDeploymentInput.

AcknowledgedWorkflowDeployment is exported by @sanity/workflow-engine. It is a parsed deployment whose reader-floor acknowledgement has been validated against the definitions a command will submit.

OUTCOME_MARKS maps each ConditionOutcome to the glyph used by condition checklists: ✓ for satisfied, ✗ for unsatisfied, and ? for unevaluable. Use it when a custom integration renders structured condition results instead of checklistLines output.

NEUTRAL_MARK is the bullet used for a condition checklist that has no live verdict. Use it for definition-only explanations where satisfied or unsatisfied marks would imply that the condition was evaluated against a running instance.

actorFulfillsRole({actorRoles, required, aliases}) tests whether an actor holds a required role directly or through the definition’s role aliases.

resolveActor(directory, actor) resolves a person actor through a ProjectUserDirectory. It returns resolved, missing, or inaccessible; agent and system actors return not-person without a user lookup.

ClientProjectUser is the project API user record used by actor resolution. userLoginProvider(user) returns user.provider when present, otherwise user.loginProvider. It returns undefined when no user or provider is available. Use this helper because the project user endpoints use different field names for the same display-only value.

DATA_MODEL_CHANGES is the frozen manifest of governed persisted-model changes, including each change’s document types, compatibility class, introduced model, minimum reader model, applicability, and summary.

requiredModelFeatures(documentType, document) returns the manifest entries whose feature detectors apply to one canonical stored definition or instance.

requiredReaderModel(documentType, document) returns the oldest engine data model that can safely interpret that stored definition or instance. It returns 0 when no governed feature raises the floor.

DATA_MODEL_MAX_READER is the highest reader-floor acknowledgement supported by the installed engine. Workflows 0.33 and later support model 10. Keep deployment acknowledgements as reviewed literals; do not import this constant as a substitute for checking your runtimes.

requiredDefinitionReaderModel(definitions) returns the reader model required by a batch of definitions. The baseline is 4. Role-constrained plural assignments need 8; singular assignments and guards spanning multiple action groups need 9. Required content references and effect retries need 10. Use the highest requirement in the batch. See Upgrade Workflows packages for the rollout sequence.

assertReaderModelAcknowledgement(value, {requiredMinReaderModel, context?}) asserts that a reviewed numeric literal meets the submitted definitions’ required floor without exceeding the writer’s supported maximum. It throws ReaderModelAcknowledgementError when the value is missing, malformed, below requiredMinReaderModel, or above DATA_MODEL_MAX_READER. The optional context labels the failing caller.

isRevisionConflict(error) identifies a likely lost optimistic lock for one known revision-guarded write. A bare 409 can also be a create-ID collision, so narrow the operation before using this predicate.

expandResourceAliases(definition, resourceAliases) returns the workflow definition with logical @alias: references expanded to physical GDRs. It validates alias names and rejects missing or malformed standalone aliases.

refsOf(definition) returns the definition’s outgoing spawn dependencies as LogicalRef[], where each row is {name: string, version?: number | 'latest'}.

deployedTagsGroq() returns a cross-partition GROQ query that lists the distinct tags with deployed definitions, sorted in ascending order. Run it with a client scoped to the workflow resource. It reports observed deployments, so tags with no deployed definitions are absent.

definitionTagsGroq() returns the same kind of tag query narrowed to one definition. Pass {definition} as the query parameters. A definition deployed under several tags produces several results; the query reports that ambiguity and does not choose a tag for you.

@sanity/workflow-studio-plugin provides the plugin factory, configuration types, structure helpers, and reusable workflow tables. See Add Workflows to Sanity Studio for setup and custom table integration.

WorkflowPluginConfig is the options object passed to workflowStudioPlugin. Every property is read-only.

A mapping row binds one Studio document type to one deployed definition, replacing whatever discovery derived for that exact docType and definition pair, or adding the pair when discovery did not produce it. One document type may appear on several rows. Two rows for the same pair throw while sanity.config.ts is evaluated, so the Studio does not start.

• The reactive session: reactive state and commands.
• Configure and deploy workflow definitions: installing the CLI, authenticating, the config file, and the deploy.
• Workflow CLI command reference: every command with its arguments, flags, JSON payloads, and exit codes.
• Connect an agent over MCP: agent tools and configuration.
• Add Workflows to Sanity Studio: Studio setup and workflow UI.
• Create a workflow-powered Document Action: build a custom workflow control on the Studio adapter.
• Build a workflow interface with the App SDK: render live workflow state and commit actions in your own application.
• Reusable UI components: assignment, date, progress, member, and workflow-diagram controls.

• Test your workflows: the in-memory test bench and test patterns.
• Limits: current product and runtime limits.