Document apiReferenceMutations

mutations.preview

Dry-run a mutation plan, returning resolved targets without applying changes.

read-onlyidempotent
doc.mutations.preview(…)

Expected result

Returns a MutationsPreviewOutput with resolved targets and step details without applying changes.

Inputs

atomictruerequired

Must be true. All steps execute as one atomic transaction.

changeMode"direct" | "tracked"required

Required. Use 'direct' for immediate edits or 'tracked' for suggestions. Must always be provided.

stepstext.rewrite | text.insert | text.delete | format.apply | assert[]required

Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, or assert) and a 'where' targeting clause.

2 additional input fields
inStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
Fields
kind"section"required
sectionIdstringrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
expectedRevisionstring

Document revision for optimistic concurrency. Mutation fails if document was modified since this revision.

Result

Output fields
evaluatedRevisionstringrequired
stepsobject[]required
validbooleanrequired
failuresobject[]

Failures

Pre-apply throws

  • REVISION_MISMATCH
  • MATCH_NOT_FOUND
  • AMBIGUOUS_MATCH
17 more codes
  • STYLE_CONFLICT
  • PRECONDITION_FAILED
  • INVALID_INPUT
  • CROSS_BLOCK_MATCH
  • SPAN_FRAGMENTED
  • TARGET_MOVED
  • PLAN_CONFLICT_OVERLAP
  • INVALID_STEP_COMBINATION
  • REVISION_CHANGED_SINCE_COMPILE
  • INVALID_INSERTION_CONTEXT
  • DOCUMENT_IDENTITY_CONFLICT
  • CAPABILITY_UNAVAILABLE
  • STORY_NOT_FOUND
  • STORY_MISMATCH
  • STORY_NOT_SUPPORTED
  • CROSS_STORY_PLAN
  • MATERIALIZATION_FAILED

Raw schemas

Open the generated JSON artifact for the exact input, output, success, and failure schemas represented by this contract version.

View raw JSON schemas