# Lists operations > List inspection and list mutations. 44 operations. Names, descriptions, and behavior flags come from the canonical contract. ## Operations - [`lists.list`](/document-api/reference/lists/list) (read): List all list nodes in the document, optionally filtered by scope. - [`lists.get`](/document-api/reference/lists/get) (read): Retrieve a specific list node by target. - [`lists.insert`](/document-api/reference/lists/insert) (mutates, tracked): Insert a new list item before or after an existing list item. The new item inherits the target list context. - [`lists.create`](/document-api/reference/lists/create) (mutates): Create 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. - [`lists.attach`](/document-api/reference/lists/attach) (mutates, tracked): Convert non-list paragraphs to list items under an existing list sequence. - [`lists.detach`](/document-api/reference/lists/detach) (mutates): Remove numbering properties from list items, converting them to plain paragraphs. - [`lists.delete`](/document-api/reference/lists/delete) (mutates): Delete 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. - [`lists.indent`](/document-api/reference/lists/indent) (mutates, tracked): Increase the indentation level of a list item. - [`lists.outdent`](/document-api/reference/lists/outdent) (mutates, tracked): Decrease the indentation level of a list item. - [`lists.join`](/document-api/reference/lists/join) (mutates): Merge two adjacent list sequences into one. - [`lists.canJoin`](/document-api/reference/lists/can-join) (read): Check whether two adjacent list sequences can be joined. - [`lists.separate`](/document-api/reference/lists/separate) (mutates): Split a list sequence at the target item, creating a new sequence from that point forward. - [`lists.merge`](/document-api/reference/lists/merge) (mutates): Compound: 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. - [`lists.split`](/document-api/reference/lists/split) (mutates): Compound: 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). - [`lists.setLevel`](/document-api/reference/lists/set-level) (mutates): Set the absolute nesting level (0..8) of a list item. - [`lists.setValue`](/document-api/reference/lists/set-value) (mutates): Set an explicit numbering value at the target item. Mid-sequence targets are atomically separated first. - [`lists.continuePrevious`](/document-api/reference/lists/continue-previous) (mutates): Continue numbering from the nearest compatible previous list sequence. - [`lists.canContinuePrevious`](/document-api/reference/lists/can-continue-previous) (read): Check whether the target sequence can continue numbering from a previous compatible sequence. - [`lists.setLevelRestart`](/document-api/reference/lists/set-level-restart) (mutates): Set the restart behavior for a specific list level. - [`lists.convertToText`](/document-api/reference/lists/convert-to-text) (mutates): Convert list items to plain paragraphs, optionally prepending the rendered marker text. - [`lists.applyTemplate`](/document-api/reference/lists/apply-template) (mutates): Advanced alias for lists.applyStyle. Apply a captured ListTemplate to the target list (abstract-scoped, no clone-on-write). - [`lists.applyPreset`](/document-api/reference/lists/apply-preset) (mutates): Apply a built-in list formatting preset to the target list. - [`lists.setType`](/document-api/reference/lists/set-type) (mutates): Convert a list to ordered or bullet and merge adjacent compatible sequences to preserve continuous numbering. - [`lists.captureTemplate`](/document-api/reference/lists/capture-template) (read): Advanced alias for lists.getStyle. Capture list formatting from the abstract definition only (does not merge lvlOverride formatting). - [`lists.setLevelNumbering`](/document-api/reference/lists/set-level-numbering) (mutates): Advanced alias for lists.setLevelNumberStyle/setLevelText/setLevelStart. Set format, pattern, and start in one call (abstract-scoped, no clone-on-write). - [`lists.setLevelBullet`](/document-api/reference/lists/set-level-bullet) (mutates): Set the bullet marker text for a specific list level. - [`lists.setLevelPictureBullet`](/document-api/reference/lists/set-level-picture-bullet) (mutates): Set a picture bullet for a specific list level by its OOXML lvlPicBulletId. - [`lists.setLevelAlignment`](/document-api/reference/lists/set-level-alignment) (mutates): Set the marker alignment (left, center, right) for a specific list level. - [`lists.setLevelIndents`](/document-api/reference/lists/set-level-indents) (mutates): Set the paragraph indentation values (left, hanging, firstLine) for a specific list level. - [`lists.setLevelTrailingCharacter`](/document-api/reference/lists/set-level-trailing-character) (mutates): Set the trailing character (tab, space, nothing) after the marker for a specific list level. - [`lists.setLevelMarkerFont`](/document-api/reference/lists/set-level-marker-font) (mutates): Set the font family used for the marker character at a specific list level. - [`lists.clearLevelOverrides`](/document-api/reference/lists/clear-level-overrides) (mutates): Remove instance-level overrides for a specific list level, restoring abstract definition values. - [`lists.getStyle`](/document-api/reference/lists/get-style) (read): Read the effective reusable style of a list, including instance-level overrides. Returns a ListStyle that can be applied to other lists via lists.applyStyle. - [`lists.applyStyle`](/document-api/reference/lists/apply-style) (mutates): Apply 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. - [`lists.restartAt`](/document-api/reference/lists/restart-at) (mutates): Restart numbering at the target list item with a specific value. If the item is mid-sequence, it is separated first. - [`lists.setLevelNumberStyle`](/document-api/reference/lists/set-level-number-style) (mutates): Set the numbering style (e.g. decimal, lowerLetter, upperRoman) for a specific list level. Rejects "bullet": use setLevelBullet instead. Sequence-local: clones shared definitions. - [`lists.setLevelText`](/document-api/reference/lists/set-level-text) (mutates): Set the level text pattern (e.g. "%1.", "(%1)") for a specific list level. Uses OOXML level-placeholder syntax. Sequence-local: clones shared definitions. - [`lists.setLevelStart`](/document-api/reference/lists/set-level-start) (mutates): Set the start value for a specific list level. Rejects bullet levels and non-positive values. Sequence-local: clones shared definitions. - [`lists.setLevelLayout`](/document-api/reference/lists/set-level-layout) (mutates): Set 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. - [`lists.getState`](/document-api/reference/lists/get-state) (read): Read 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`. - [`lists.apply`](/document-api/reference/lists/apply) (mutates, tracked): Apply 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`. - [`lists.continue`](/document-api/reference/lists/continue) (mutates, tracked): Continue 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`. - [`lists.restart`](/document-api/reference/lists/restart) (mutates, tracked): Restart numbering at a list item. Creates a new `` that references the existing `` with a ``. Distant paragraphs sharing the old numId are intentionally untouched. Available on v2-backed sessions only; v1-backed sessions currently return `CAPABILITY_UNAVAILABLE`. - [`lists.remove`](/document-api/reference/lists/remove) (mutates, tracked): Strip the `` 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`.