docx_mutations
All steps succeed or all fail; no partial application. Execute multiple operations atomically in one batch. Use this for any workflow needing 2+ changes. Supported step types: text (text.rewrite, text.insert, text.delete), format (format.apply), create (create.heading, create.paragraph, create.table), assert. Each step has an id, an op, a “where” clause for targeting ({by:“select”, select:{…}, require:“first”|“exactlyOne”|“all”} or {by:“ref”, ref:”…”} or {by:“block”, nodeType:“paragraph”, nodeId:”…”}), and “args” with operation-specific parameters. Use {by:“block”, nodeType, nodeId} when you want to rewrite, delete, format, or anchor against a whole known block from docx_get_content action “blocks” without relying on text matching. For full-paragraph or full-clause rewrites, first call docx_get_content with action:“blocks” and includeText:true, then rewrite the matching block by nodeId. Use {by:“select”} only for substring edits, discovery, or insertion relative to a sentence fragment; do NOT use a shortened text selector to replace an entire known block. For create steps, “where” targets an existing anchor block and args.position (“before” or “after”) controls placement. Sequential creates targeting the same anchor maintain correct order via internal position mapping. For format.apply with require “all”, use a node selector to format every heading or paragraph at once: {by:“select”, select:{type:“node”, nodeType:“heading”}, require:“all”}. Selectors resolve at compile time (before execution). This means format.apply steps CANNOT target content created by earlier create steps in the same batch. Split creates and formatting into separate batches: first a mutations call with creates, then a mutations call with format.apply. Action “preview” dry-runs the plan. Action “apply” executes it. If a selector matches nothing, the failure reports the step id plus selector details so you can retry with a shorter or more distinctive anchor. Do NOT create two steps that target overlapping text in the same block; combine them into a single text.rewrite step.
Parameters
string, enum: 'apply' | 'preview'
required
The action to perform. One of: apply, preview.
string
Document revision for optimistic concurrency. Mutation fails if document was modified since this revision. Only for action ‘preview’. Omit for other actions.
boolean
required
Must be true. All steps execute as one atomic transaction.
string, enum: 'direct' | 'tracked'
required
Required. Use ‘direct’ for immediate edits or ‘tracked’ for suggestions. Must always be provided.
array<any>
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.
boolean
Bypass confirmation checks. Only for action ‘apply’. Omit for other actions.
string
required
The HERO documentId of the docx to target.