ReferenceLists
Lists operations
List inspection and list mutations.
44 operations. Names, descriptions, and behavior flags come from the canonical contract.
Operations
lists.applyApply a numbering definition to a paragraph. When `/word/numbering.xml` is absent it is materialized atomically together with the package content-type override and document relationship. Seeds bullet or ordered single-level definitions when no `reuseNumId` is provided. Available on v2-backed sessions only; v1-backed sessions currently return `CAPABILITY_UNAVAILABLE`.mutatestrackedlists.applyPresetApply a built-in list formatting preset to the target list.mutateslists.applyStyleApply a reusable list style to the target list. Sequence-local: if the abstract definition is shared with other lists, it is cloned first to avoid affecting them.mutateslists.applyTemplateAdvanced alias for lists.applyStyle. Apply a captured ListTemplate to the target list (abstract-scoped, no clone-on-write).mutateslists.attachConvert non-list paragraphs to list items under an existing list sequence.mutatestrackedlists.canContinuePreviousCheck whether the target sequence can continue numbering from a previous compatible sequence.readlists.canJoinCheck whether two adjacent list sequences can be joined.readlists.captureTemplateAdvanced alias for lists.getStyle. Capture list formatting from the abstract definition only (does not merge lvlOverride formatting).readlists.clearLevelOverridesRemove instance-level overrides for a specific list level, restoring abstract definition values.mutateslists.continueContinue from the previous compatible list item in the same story. Adopts the previous paragraph's numId+ilvl. Rejects with named reasons when no compatible previous item exists or when an intervening structural boundary blocks the continuation. Available on v2-backed sessions only; v1-backed sessions currently return `CAPABILITY_UNAVAILABLE`.mutatestrackedlists.continuePreviousContinue numbering from the nearest compatible previous list sequence.mutateslists.convertToTextConvert list items to plain paragraphs, optionally prepending the rendered marker text.mutateslists.createCreate a new list from one or more paragraphs. Supports optional preset or style for new sequences. When sequence.mode is "continuePrevious", preset and style are not allowed: the new items inherit formatting from the previous sequence.mutateslists.deleteDelete the entire list that contains the targeted list item. Removes ALL items in the same numbered sequence (the contiguous run of list items sharing the target's numbering) AND their text content from the document. Pass any single list item from the list as `target`; the op walks adjacent siblings to find the full list. Use this for "remove the list" / "delete this list" intents and for the cleanup step of a list-to-table conversion.mutateslists.detachRemove numbering properties from list items, converting them to plain paragraphs.mutateslists.getRetrieve a specific list node by target.readlists.getStateRead the numbering-aware list state for a paragraph (numId, ilvl, abstract reference, level format). Returns null when the target is not a list item. Available on v2-backed sessions only; v1-backed sessions currently return `CAPABILITY_UNAVAILABLE`.readlists.getStyleRead the effective reusable style of a list, including instance-level overrides. Returns a ListStyle that can be applied to other lists via lists.applyStyle.readlists.indentIncrease the indentation level of a list item.mutatestrackedlists.insertInsert a new list item before or after an existing list item. The new item inherits the target list context.mutatestrackedlists.joinMerge two adjacent list sequences into one.mutateslists.listList all list nodes in the document, optionally filtered by scope.readlists.mergeCompound: merge two adjacent list sequences into one. Reassigns numId on the absorbed sequence (no strict abstractNumId check: absorbed items adopt the absorbing definition) and deletes empty paragraphs between the two sequences. Use this instead of lists.join for the user-facing "merge these lists" intent.mutateslists.outdentDecrease the indentation level of a list item.mutatestrackedlists.removeStrip the `<w:numPr>` from a list-item paragraph. The numbering definition in `/word/numbering.xml` is intentionally NOT modified; orphan cleanup is handled by the export-side stripper. Available on v2-backed sessions only; v1-backed sessions currently return `CAPABILITY_UNAVAILABLE`.mutatestrackedlists.restartRestart numbering at a list item. Creates a new `<w:num>` that references the existing `<w:abstractNumId>` with a `<w:lvlOverride><w:startOverride/></w:lvlOverride>`. Distant paragraphs sharing the old numId are intentionally untouched. Available on v2-backed sessions only; v1-backed sessions currently return `CAPABILITY_UNAVAILABLE`.mutatestrackedlists.restartAtRestart numbering at the target list item with a specific value. If the item is mid-sequence, it is separated first.mutateslists.separateSplit a list sequence at the target item, creating a new sequence from that point forward.mutateslists.setLevelSet the absolute nesting level (0..8) of a list item.mutateslists.setLevelAlignmentSet the marker alignment (left, center, right) for a specific list level.mutateslists.setLevelBulletSet the bullet marker text for a specific list level.mutateslists.setLevelIndentsSet the paragraph indentation values (left, hanging, firstLine) for a specific list level.mutateslists.setLevelLayoutSet the layout properties (alignment, indentation, trailing character, tab stop) for a specific list level. Accepts partial updates: omitted fields are left unchanged. Sequence-local: clones shared definitions.mutateslists.setLevelMarkerFontSet the font family used for the marker character at a specific list level.mutateslists.setLevelNumberingAdvanced alias for lists.setLevelNumberStyle/setLevelText/setLevelStart. Set format, pattern, and start in one call (abstract-scoped, no clone-on-write).mutateslists.setLevelNumberStyleSet the numbering style (e.g. decimal, lowerLetter, upperRoman) for a specific list level. Rejects "bullet": use setLevelBullet instead. Sequence-local: clones shared definitions.mutateslists.setLevelPictureBulletSet a picture bullet for a specific list level by its OOXML lvlPicBulletId.mutateslists.setLevelRestartSet the restart behavior for a specific list level.mutateslists.setLevelStartSet the start value for a specific list level. Rejects bullet levels and non-positive values. Sequence-local: clones shared definitions.mutateslists.setLevelTextSet the level text pattern (e.g. "%1.", "(%1)") for a specific list level. Uses OOXML level-placeholder syntax. Sequence-local: clones shared definitions.mutateslists.setLevelTrailingCharacterSet the trailing character (tab, space, nothing) after the marker for a specific list level.mutateslists.setTypeConvert a list to ordered or bullet and merge adjacent compatible sequences to preserve continuous numbering.mutateslists.setValueSet an explicit numbering value at the target item. Mid-sequence targets are atomically separated first.mutateslists.splitCompound: split a list sequence at the target item into two independent sequences. Runs lists.separate then (by default) lists.setValue(1) so the new half starts numbering fresh at 1. Pass restartNumbering:false for raw separate semantics (new half continues the previous count).mutates