Reference

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

• Engine: engine construction, verbs, transactions, evaluation, errors, actor resolution, and persisted-model governance. See the advanced exports below for lower-level helpers.
• Definitions and instances: 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.
• Subworkflows: spawning, child lifecycle, and propagation.
• Global document references: resource-qualified references and deployment helpers. See expandResourceAliases and refsOf below.

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 requires the reviewed current reader floor as a literal. Reuse this authored object when config and Blueprint entry points share a deployment.

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 this writer can emit. In version 0.30 it is 8.

requiredDefinitionReaderModel(definitions) returns the minimum reader model required by a batch of authored definitions. Role-constrained assignment fields raise the result to 8.

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.

• The reactive session: reactive state and commands.
• CLI: deployment and administration commands.
• MCP server: agent tools and configuration.
• Studio plugin: Studio setup and workflow UI.
• Custom Studio integrations: Studio-bound engine, hooks, and a Document Action example.
• App SDK: building workflow interfaces with the App SDK.
• Reusable UI components: assignment, date, progress, member, and workflow-diagram controls.

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