mutations.apply
Execute a mutation plan atomically against the document.
doc.mutations.apply(…)Expected result
Returns a PlanReceipt with per-step results for the atomically applied mutation plan.
Inputs
atomictruerequiredMust be true. All steps execute as one atomic transaction.
changeMode"direct" | "tracked"requiredRequired. Use 'direct' for immediate edits or 'tracked' for suggestions. Must always be provided.
stepstext.rewrite | text.insert | text.delete | format.apply | assert[]requiredOrdered 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
inStoryLocatorStory 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"requiredstoryType"body"requiredheaderFooterSlot
kind"story"requiredstoryType"headerFooterSlot"requiredsectionSectionAddressrequiredFields
kind"section"requiredsectionIdstringrequiredheaderFooterKind"header" | "footer"requiredvariant"default" | "first" | "even"requiredresolution"effective" | "explicit"onWrite"materializeIfInherited" | "editResolvedPart" | "error"headerFooterPart
kind"story"requiredstoryType"headerFooterPart"requiredrefIdstringrequiredfootnote
kind"story"requiredstoryType"footnote"requirednoteIdstringrequiredendnote
kind"story"requiredstoryType"endnote"requirednoteIdstringrequiredtextbox
kind"story"requiredstoryType"textbox"requiredtextboxIdstringrequiredexpectedRevisionstringDocument revision for optimistic concurrency. Mutation fails if document was modified since this revision.
Result
Output fields
successtruerequiredrevisionobjectrequiredFields
beforestringrequiredafterstringrequiredstepsobject[]requiredtrackedChangesTrackedChangeAddress[]invalidatedRefsAffectedRef[]timingobjectrequiredFields
totalMsnumberrequiredFailures
Pre-apply throws
REVISION_MISMATCHMATCH_NOT_FOUNDAMBIGUOUS_MATCH
21 more codes
STYLE_CONFLICTPRECONDITION_FAILEDINVALID_INPUTCROSS_BLOCK_MATCHSPAN_FRAGMENTEDTARGET_MOVEDPLAN_CONFLICT_OVERLAPINVALID_STEP_COMBINATIONREVISION_CHANGED_SINCE_COMPILEINVALID_INSERTION_CONTEXTDOCUMENT_IDENTITY_CONFLICTCAPABILITY_UNAVAILABLEDUPLICATE_IDRAW_MODE_REQUIREDPRESERVE_ONLY_VIOLATIONCAPABILITY_UNSUPPORTEDSTORY_NOT_FOUNDSTORY_MISMATCHSTORY_NOT_SUPPORTEDCROSS_STORY_PLANMATERIALIZATION_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