Document apiReferenceMutations

mutations.apply

Execute a mutation plan atomically against the document.

mutates documenttracked modenon-idempotent
doc.mutations.apply(…)

Expected result

Returns a PlanReceipt with per-step results for the atomically applied mutation plan.

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.

3 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.

Result

Output fields
status"NO_OP"
changeTagstring

Caller correlation for this commit only; never persisted or replayed on Undo/Redo.

temporaryobject
Fields
idstringrequired
phase"begin" | "replace" | "rollback" | "commit"required
tagstringrequired
onNativeEdit"cancel" | "preserve"
cancelledBy"native-edit"
appliedChangeMode"direct" | "tracked"
idstring
insertedEntityAddress[]
updatedEntityAddress[]
removedEntityAddress[]
invalidatedRefsAffectedRef[]
remappedRefsAffectedRefRemapping[]
affectedStoriesStoryLocator[]
textRangeShiftsTextRangeShift[]
trackedTextRangeShiftsTrackedTextRangeShift[]
txIdstring
warningsReviewWarning[]
effectsReceiptEffects
Fields
insertedTextTextMutationEffect[]
insertedBlocksBlockMutationEffect[]
resultTextTextTarget
Fields
captureStatestring

Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing.

kind"text"required
segmentsTextSegment[]required
storyStoryLocator

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
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
coordinateSpaceTextCoordinateSpace
trackedChangeRefsTrackedChangeAddress[]
trackedChangeCountinteger
changedboolean
successtruerequired
revisionobjectrequired
Fields
beforestringrequired
afterstringrequired
stepsobject[]required
trackedChangesTrackedChangeAddress[]
timingobjectrequired
Fields
totalMsnumberrequired

Failures

Pre-apply throws

  • REVISION_MISMATCH
  • MATCH_NOT_FOUND
  • AMBIGUOUS_MATCH
21 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
  • DUPLICATE_ID
  • RAW_MODE_REQUIRED
  • PRESERVE_ONLY_VIOLATION
  • CAPABILITY_UNSUPPORTED
  • STORY_NOT_FOUND
  • STORY_MISMATCH
  • STORY_NOT_SUPPORTED
  • CROSS_STORY_PLAN
  • MATERIALIZATION_FAILED

Non-applied receipt codes

  • INVALID_CONTEXT

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