# blocks.list

> List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Supports pagination via offset/limit, optional nodeType filtering, and single-story scoping via `in: StoryLocator`.



- Member path: `doc.blocks.list(…)`
- Mutates document: no
- Idempotency: `idempotent`
- Supports tracked mode: no
- Supports dry run: no

## Expected result

Returns a BlocksListResult with total block count, an ordered array of block entries (ordinal, nodeId, nodeType, textPreview, optional text, isEmpty), and the current document revision.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "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"
      ]
    }
  },
  "type": "object",
  "properties": {
    "in": {
      "$ref": "#/$defs/StoryLocator"
    },
    "offset": {
      "type": "number",
      "minimum": 0,
      "description": "Number of blocks to skip. Default: 0."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "description": "Maximum blocks to return. Omit for all blocks."
    },
    "nodeTypes": {
      "type": "array",
      "items": {
        "enum": [
          "paragraph",
          "heading",
          "listItem",
          "table",
          "tableRow",
          "tableCell",
          "tableOfContents",
          "image",
          "sdt"
        ]
      },
      "description": "Filter by block types (e.g. ['paragraph', 'heading']). Omit for all types."
    },
    "includeText": {
      "type": "boolean",
      "description": "When true, includes the full flattened block text in each block entry."
    }
  },
  "additionalProperties": false
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "type": "object",
  "properties": {
    "total": {
      "type": "number"
    },
    "blocks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ordinal": {
            "type": "number"
          },
          "nodeId": {
            "type": "string",
            "description": "Block ID for targeting with other tools."
          },
          "nodeType": {
            "enum": [
              "paragraph",
              "heading",
              "listItem",
              "table",
              "tableRow",
              "tableCell",
              "tableOfContents",
              "image",
              "sdt"
            ]
          },
          "textPreview": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "text": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Full flattened block text when requested with includeText."
          },
          "isEmpty": {
            "type": "boolean"
          },
          "styleId": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Named paragraph style."
          },
          "fontFamily": {
            "type": "string",
            "description": "Font family from first text run."
          },
          "fontSize": {
            "type": "number",
            "description": "Font size from first text run."
          },
          "bold": {
            "type": "boolean",
            "description": "True if text is bold."
          },
          "color": {
            "type": "string",
            "description": "Text color when explicitly set (e.g. '#000000')."
          },
          "alignment": {
            "type": "string",
            "description": "Paragraph alignment."
          },
          "headingLevel": {
            "type": "number",
            "description": "Heading level (1-6)."
          },
          "paragraphNumbering": {
            "type": "object",
            "description": "Numbering reference (numId + level) for numbered blocks, including numbered headings. Absent for non-numbered blocks.",
            "properties": {
              "numId": {
                "type": "number"
              },
              "level": {
                "type": "number"
              }
            },
            "additionalProperties": false
          },
          "numbering": {
            "type": "object",
            "properties": {
              "marker": {
                "type": "string"
              },
              "path": {
                "type": "array",
                "items": {
                  "type": "number"
                }
              },
              "kind": {
                "enum": [
                  "ordered",
                  "bullet"
                ]
              }
            },
            "additionalProperties": false,
            "required": [
              "marker",
              "path",
              "kind"
            ]
          },
          "ref": {
            "type": "string",
            "description": "Ref handle for this block. Pass directly to superdoc_format or superdoc_edit ref param. Only present for non-empty blocks."
          }
        },
        "additionalProperties": false,
        "required": [
          "ordinal",
          "nodeId",
          "nodeType"
        ]
      }
    },
    "revision": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "total",
    "blocks",
    "revision"
  ]
}
```

## Pre-apply throws

- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied receipt codes

- None