# format.paragraph.applyBatch > Apply an explicit ordered paragraph action program target-major to 1..1000 unique existing targets in one story, atomically. Accepts 1..1000 closed actions, at most 32000 expanded writer calls and 1048576 JSON bytes, cumulative across batches in an atomic plan. Uses existing writer validation; omitted groups are preserved. No nested plans, per-action targets/options or dry run. Expected revision is consumed once at batch start; live freshness is checked again before publication. Shared sessions support direct identity-preserving writes only. - Member path: `doc.format.paragraph.applyBatch(…)` - Mutates document: yes - Idempotency: `conditional` - Supports tracked mode: conditional - Supports dry run: no ## Expected result Resolves to ParagraphBatchMutationResult with resolution.targets, applied mode and tracked refs when committed, or indexed failure details. An all-no-op batch succeeds without revision, publication or history. Standalone commits once; inside an atomic plan shares its one preparation, publication and Undo/Redo unit. ## Input schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "ParagraphAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "const": "paragraph" }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "body" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterPart" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "footnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "endnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "textbox" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "HeadingAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "const": "heading" }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "ListItemAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "const": "listItem" }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] } }, "type": "object", "properties": { "targets": { "type": "array", "items": { "oneOf": [ { "$ref": "#/$defs/ParagraphAddress" }, { "$ref": "#/$defs/HeadingAddress" }, { "$ref": "#/$defs/ListItemAddress" } ] }, "minItems": 1, "maxItems": 1000, "uniqueItems": true }, "operations": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "oneOf": [ { "type": "object", "properties": { "operationId": { "const": "styles.paragraph.setStyleRef" }, "input": { "type": "object", "properties": { "styleId": { "type": "string", "minLength": 1, "description": "Named paragraph style ID (e.g. 'Normal', 'Heading1'). Unlike setStyle, existing run formatting is preserved." } }, "additionalProperties": false, "required": [ "styleId" ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "styles.paragraph.clearStyle" }, "input": { "type": "object", "properties": {}, "additionalProperties": false, "required": [] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setAlignment" }, "input": { "type": "object", "properties": { "alignment": { "enum": [ "left", "center", "right", "justify" ], "description": "Visual paragraph alignment. In RTL paragraphs, 'left' stores w:jc='right' and 'right' stores w:jc='left' so Word displays the requested side." } }, "additionalProperties": false, "required": [ "alignment" ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.clearAlignment" }, "input": { "type": "object", "properties": {}, "additionalProperties": false, "required": [] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setSpacing" }, "input": { "type": "object", "properties": { "before": { "type": "integer", "minimum": 0, "description": "Space before paragraph in twips (20 twips = 1pt)." }, "after": { "type": "integer", "minimum": 0, "description": "Space after paragraph in twips (20 twips = 1pt)." }, "line": { "type": "integer", "minimum": 1, "description": "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule." }, "lineRule": { "enum": [ "auto", "exact", "atLeast" ], "description": "Line spacing rule. Required when 'line' is set." } }, "additionalProperties": false, "required": [], "anyOf": [ { "required": [ "before" ] }, { "required": [ "after" ] }, { "required": [ "line" ] }, { "required": [ "lineRule" ] } ], "if": { "required": [ "line" ] }, "then": { "required": [ "lineRule" ] } } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.clearSpacing" }, "input": { "type": "object", "properties": {}, "additionalProperties": false, "required": [] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setIndentation" }, "input": { "type": "object", "properties": { "left": { "type": "integer", "description": "Left indentation in twips (1440 = 1 inch)." }, "right": { "type": "integer", "description": "Right indentation in twips (1440 = 1 inch)." }, "firstLine": { "type": "integer", "minimum": 0, "description": "First line indent in twips. Cannot be combined with hanging." }, "hanging": { "type": "integer", "minimum": 0, "description": "Hanging indent in twips. Cannot be combined with firstLine." } }, "additionalProperties": false, "required": [], "anyOf": [ { "required": [ "left" ] }, { "required": [ "right" ] }, { "required": [ "firstLine" ] }, { "required": [ "hanging" ] } ], "not": { "required": [ "firstLine", "hanging" ] } } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.clearIndentation" }, "input": { "type": "object", "properties": {}, "additionalProperties": false, "required": [] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setKeepOptions" }, "input": { "type": "object", "properties": { "keepNext": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "keepLines": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "widowControl": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [], "anyOf": [ { "required": [ "keepNext" ] }, { "required": [ "keepLines" ] }, { "required": [ "widowControl" ] } ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setFlowOptions" }, "input": { "type": "object", "properties": { "contextualSpacing": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "pageBreakBefore": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "suppressAutoHyphens": { "type": "boolean" }, "autoSpaceDE": { "type": "boolean" }, "autoSpaceDN": { "type": "boolean" }, "adjustRightInd": { "type": "boolean" }, "snapToGrid": { "type": "boolean" } }, "additionalProperties": false, "required": [], "anyOf": [ { "required": [ "contextualSpacing" ] }, { "required": [ "pageBreakBefore" ] }, { "required": [ "suppressAutoHyphens" ] }, { "required": [ "autoSpaceDE" ] }, { "required": [ "autoSpaceDN" ] }, { "required": [ "adjustRightInd" ] }, { "required": [ "snapToGrid" ] } ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setOutlineLevel" }, "input": { "type": "object", "properties": { "outlineLevel": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 9 }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "outlineLevel" ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setBorder" }, "input": { "type": "object", "properties": { "side": { "enum": [ "top", "bottom", "left", "right", "between", "bar" ] }, "style": { "type": "string", "minLength": 1 }, "color": { "type": "string", "minLength": 1 }, "size": { "type": "integer", "minimum": 0 }, "space": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "side", "style" ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.clearBorder" }, "input": { "type": "object", "properties": { "side": { "enum": [ "top", "bottom", "left", "right", "between", "bar", "all" ] } }, "additionalProperties": false, "required": [ "side" ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setShading" }, "input": { "type": "object", "properties": { "fill": { "type": "string", "minLength": 1 }, "color": { "type": "string", "minLength": 1 }, "pattern": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [], "anyOf": [ { "required": [ "fill" ] }, { "required": [ "color" ] }, { "required": [ "pattern" ] } ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.clearShading" }, "input": { "type": "object", "properties": {}, "additionalProperties": false, "required": [] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setTabStop" }, "input": { "type": "object", "properties": { "position": { "type": "integer" }, "alignment": { "enum": [ "left", "center", "right", "decimal", "bar", "clear" ] }, "leader": { "enum": [ "none", "dot", "hyphen", "underscore", "heavy", "middleDot" ] } }, "additionalProperties": false, "required": [ "position", "alignment" ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.clearAllTabStops" }, "input": { "type": "object", "properties": {}, "additionalProperties": false, "required": [] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setDirection" }, "input": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "ltr", "rtl" ] }, "alignmentPolicy": { "type": "string", "enum": [ "preserve", "matchDirection" ] } }, "additionalProperties": false, "required": [ "direction" ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.clearDirection" }, "input": { "type": "object", "properties": {}, "additionalProperties": false, "required": [] } }, "additionalProperties": false, "required": [ "operationId", "input" ] }, { "type": "object", "properties": { "operationId": { "const": "format.paragraph.setMarkRunProps" }, "input": { "type": "object", "properties": { "markRunProps": { "type": "object", "properties": { "fontSizeCs": { "type": "number" }, "specVanish": { "type": "boolean" }, "fontSize": { "type": "number" }, "fonts": { "type": "object", "properties": { "ascii": { "type": "string", "minLength": 1 }, "hAnsi": { "type": "string", "minLength": 1 }, "eastAsia": { "type": "string", "minLength": 1 }, "cs": { "type": "string", "minLength": 1 }, "asciiTheme": { "type": "string", "minLength": 1 }, "hAnsiTheme": { "type": "string", "minLength": 1 }, "eastAsiaTheme": { "type": "string", "minLength": 1 }, "csTheme": { "type": "string", "minLength": 1 }, "hint": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "minProperties": 1 }, "fontFamily": { "type": "string", "minLength": 1 }, "lang": { "type": "object", "properties": { "val": { "type": "string", "minLength": 1 }, "eastAsia": { "type": "string", "minLength": 1 }, "bidi": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "minProperties": 1 }, "color": { "oneOf": [ { "type": "object", "properties": { "model": { "const": "rgb" }, "value": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [ "model", "value" ] }, { "type": "object", "properties": { "model": { "const": "theme" }, "theme": { "type": "string", "minLength": 1 }, "tint": { "type": "integer" }, "shade": { "type": "integer" } }, "additionalProperties": false, "required": [ "model", "theme" ] }, { "type": "object", "properties": { "model": { "const": "auto" } }, "additionalProperties": false, "required": [ "model" ] } ] }, "highlight": { "type": "string", "minLength": 1 }, "shading": { "type": "object", "properties": { "fill": { "oneOf": [ { "type": "object", "properties": { "model": { "const": "rgb" }, "value": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [ "model", "value" ] }, { "type": "object", "properties": { "model": { "const": "theme" }, "theme": { "type": "string", "minLength": 1 }, "tint": { "type": "integer" }, "shade": { "type": "integer" } }, "additionalProperties": false, "required": [ "model", "theme" ] }, { "type": "object", "properties": { "model": { "const": "auto" } }, "additionalProperties": false, "required": [ "model" ] } ] }, "color": { "oneOf": [ { "type": "object", "properties": { "model": { "const": "rgb" }, "value": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [ "model", "value" ] }, { "type": "object", "properties": { "model": { "const": "theme" }, "theme": { "type": "string", "minLength": 1 }, "tint": { "type": "integer" }, "shade": { "type": "integer" } }, "additionalProperties": false, "required": [ "model", "theme" ] }, { "type": "object", "properties": { "model": { "const": "auto" } }, "additionalProperties": false, "required": [ "model" ] } ] }, "pattern": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "minProperties": 1 }, "cs": { "type": "boolean" }, "rtl": { "type": "boolean" }, "bold": { "type": "boolean" }, "boldCs": { "type": "boolean" }, "italic": { "type": "boolean" }, "italicCs": { "type": "boolean" }, "underline": { "type": "object", "properties": { "style": { "type": "string", "minLength": 1 }, "color": { "oneOf": [ { "type": "object", "properties": { "model": { "const": "rgb" }, "value": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [ "model", "value" ] }, { "type": "object", "properties": { "model": { "const": "theme" }, "theme": { "type": "string", "minLength": 1 }, "tint": { "type": "integer" }, "shade": { "type": "integer" } }, "additionalProperties": false, "required": [ "model", "theme" ] }, { "type": "object", "properties": { "model": { "const": "auto" } }, "additionalProperties": false, "required": [ "model" ] } ] } }, "additionalProperties": false, "minProperties": 1 }, "strikethrough": { "type": "boolean" }, "doubleStrikethrough": { "type": "boolean" }, "caps": { "type": "boolean" }, "smallCaps": { "type": "boolean" }, "outline": { "type": "boolean" }, "shadow": { "type": "boolean" }, "emboss": { "type": "boolean" }, "imprint": { "type": "boolean" }, "verticalAlign": { "enum": [ "baseline", "superscript", "subscript" ] }, "characterSpacing": { "type": "number" }, "characterScale": { "type": "number" }, "kern": { "type": "number" }, "baselineShift": { "type": "number" }, "fitTextWidth": { "type": "number" }, "vanish": { "type": "boolean" }, "webHidden": { "type": "boolean" }, "border": { "type": "object", "properties": { "style": { "type": "string", "minLength": 1 }, "width": { "type": "number" }, "space": { "type": "number" }, "color": { "oneOf": [ { "type": "object", "properties": { "model": { "const": "rgb" }, "value": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [ "model", "value" ] }, { "type": "object", "properties": { "model": { "const": "theme" }, "theme": { "type": "string", "minLength": 1 }, "tint": { "type": "integer" }, "shade": { "type": "integer" } }, "additionalProperties": false, "required": [ "model", "theme" ] }, { "type": "object", "properties": { "model": { "const": "auto" } }, "additionalProperties": false, "required": [ "model" ] } ] }, "frame": { "type": "boolean" }, "shadow": { "type": "boolean" } }, "additionalProperties": false, "minProperties": 1 }, "textEffect": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "minProperties": 1, "description": "Paragraph-mark run properties (SDRunProps shape, e.g. fontSizeCs, specVanish)." } }, "additionalProperties": false, "required": [ "markRunProps" ] } }, "additionalProperties": false, "required": [ "operationId", "input" ] } ] } } }, "additionalProperties": false, "required": [ "targets", "operations" ], "description": "At most 32000 expanded writes and 1048576 JSON bytes, cumulative per atomic plan; targets must resolve to unique nodes in one existing story. No dry run." } ``` ## Output schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "ParagraphAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "const": "paragraph" }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "body" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterPart" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "footnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "endnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "textbox" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "HeadingAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "const": "heading" }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "ListItemAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "const": "listItem" }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "TrackedChangeAddress": { "type": "object", "properties": { "kind": { "const": "entity" }, "entityType": { "const": "trackedChange" }, "entityId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "entityType", "entityId" ] } }, "oneOf": [ { "type": "object", "properties": { "success": { "const": true }, "resolution": { "type": "object", "properties": { "targets": { "type": "array", "items": { "oneOf": [ { "$ref": "#/$defs/ParagraphAddress" }, { "$ref": "#/$defs/HeadingAddress" }, { "$ref": "#/$defs/ListItemAddress" } ] } } }, "additionalProperties": false, "required": [ "targets" ] }, "appliedChangeMode": { "enum": [ "direct", "tracked" ] }, "trackedChangeRefs": { "type": "array", "items": { "$ref": "#/$defs/TrackedChangeAddress" } } }, "additionalProperties": false, "required": [ "success", "resolution" ] }, { "type": "object", "properties": { "success": { "const": false }, "failure": { "type": "object", "properties": { "code": { "enum": [ "INVALID_INPUT", "TARGET_NOT_FOUND", "REVISION_MISMATCH", "PERMISSION_DENIED", "CAPABILITY_UNAVAILABLE", "PRECONDITION_FAILED" ] }, "message": { "type": "string" }, "details": {} }, "additionalProperties": false, "required": [ "code", "message" ] }, "resolution": { "type": "object", "properties": { "target": { "oneOf": [ { "$ref": "#/$defs/ParagraphAddress" }, { "$ref": "#/$defs/HeadingAddress" }, { "$ref": "#/$defs/ListItemAddress" } ] } }, "additionalProperties": false, "required": [ "target" ] } }, "additionalProperties": false, "required": [ "success", "failure" ] } ] } ``` ## Pre-apply throws - `TARGET_NOT_FOUND` - `INVALID_TARGET` - `CAPABILITY_UNAVAILABLE` ## Non-applied receipt codes - `INVALID_INPUT` - `TARGET_NOT_FOUND` - `REVISION_MISMATCH` - `PERMISSION_DENIED` - `CAPABILITY_UNAVAILABLE` - `PRECONDITION_FAILED`