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 | structural.replace | assert | comments.patch | trackChanges.decide[]required

Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, structural.replace, assert, comments.patch, or trackChanges.decide). Core steps use 'where'; review steps use explicit native args and require direct body-only plans with relocations before decisions. Check runtime capabilities for operation-specific content and targeting restrictions.

4 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
authorobject

Display author for one tracked body text plan. Accepts only name; does not change the session user or inherit its email. Unsupported step combinations are rejected before mutation.

Fields
namestringrequired
expectedRevisionstring

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

detailobject
Fields
offsetnumber
limitnumber

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