> ## Documentation Index
> Fetch the complete documentation index at: https://developers.myhero.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 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…

`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

**action** `string, enum: 'apply' | 'preview'` *required*

The action to perform. One of: apply, preview.

**expectedRevision** `string`

Document revision for optimistic concurrency. Mutation fails if document was modified since this revision. Only for action 'preview'. Omit for other actions.

**atomic** `boolean` *required*

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

**changeMode** `string, enum: 'direct' | 'tracked'` *required*

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

**steps** `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.

**force** `boolean`

Bypass confirmation checks. Only for action 'apply'. Omit for other actions.

**documentId** `string` *required*

The HERO documentId of the docx to target.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.