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

# blocks.list

> List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Text, previews, lengths, and formatting hints use the VISIBLE model: pending tracked deletions are excluded (matching how edit refs resolve), and inline atoms render as a single placeholder character. Supports pagination via offset/limit, optional nodeType filtering, and single-story scoping via `in: <StoryLocator>`.

## Summary

List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Text, previews, lengths, and formatting hints use the VISIBLE model: pending tracked deletions are excluded (matching how edit refs resolve), and inline atoms render as a single placeholder character. Supports pagination via offset/limit, optional nodeType filtering, and single-story scoping via `in: <StoryLocator>`.

* Operation ID: `blocks.list`
* API member path: `editor.doc.blocks.list(...)`
* Mutates document: `no`
* Idempotency: `idempotent`
* Supports tracked mode: `no`
* Supports dry run: `no`
* Deterministic target resolution: `yes`

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

| Field         | Type         | Required | Description  |
| ------------- | ------------ | -------- | ------------ |
| `in`          | StoryLocator | no       | StoryLocator |
| `includeText` | boolean      | no       |              |
| `limit`       | number       | no       |              |
| `nodeTypes`   | enum\[]      | no       |              |
| `offset`      | number       | no       |              |

### Example request

```json theme={null}
{
  "in": {
    "kind": "story",
    "storyType": "body"
  },
  "offset": 0
}
```

## Output fields

| Field      | Type      | Required | Description |
| ---------- | --------- | -------- | ----------- |
| `blocks`   | object\[] | yes      |             |
| `revision` | string    | yes      |             |
| `total`    | number    | yes      |             |

### Example response

```json theme={null}
{
  "blocks": [
    {
      "nodeId": "node-def456",
      "nodeType": "paragraph",
      "ordinal": 1,
      "text": "Hello, world.",
      "textPreview": "example"
    }
  ],
  "revision": "example",
  "total": 1
}
```

## Pre-apply throws

* `INVALID_INPUT`
* `STORY_NOT_FOUND`
* `STORY_MISMATCH`
* `STORY_NOT_SUPPORTED`
* `CROSS_STORY_PLAN`
* `MATERIALIZATION_FAILED`

## Non-applied failure codes

* None

## Raw schemas

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

<Accordion title="Raw output schema">
  ```json theme={null}
  {
    "additionalProperties": false,
    "properties": {
      "blocks": {
        "items": {
          "additionalProperties": false,
          "properties": {
            "alignment": {
              "description": "Paragraph alignment.",
              "type": "string"
            },
            "bold": {
              "description": "True if text is bold.",
              "type": "boolean"
            },
            "color": {
              "description": "Text color when explicitly set (e.g. '#000000').",
              "type": "string"
            },
            "fontFamily": {
              "description": "Font family from first text run.",
              "type": "string"
            },
            "fontSize": {
              "description": "Font size from first text run.",
              "type": "number"
            },
            "headingLevel": {
              "description": "Heading level (1-6).",
              "type": "number"
            },
            "indent": {
              "additionalProperties": false,
              "description": "Direct paragraph indentation in twips (only non-zero fields present).",
              "properties": {
                "firstLine": {
                  "type": "number"
                },
                "hanging": {
                  "type": "number"
                },
                "left": {
                  "type": "number"
                },
                "right": {
                  "type": "number"
                }
              },
              "type": "object"
            },
            "isEmpty": {
              "type": "boolean"
            },
            "nodeId": {
              "description": "Block ID for targeting with other tools.",
              "type": "string"
            },
            "nodeType": {
              "enum": [
                "paragraph",
                "heading",
                "listItem",
                "table",
                "tableRow",
                "tableCell",
                "tableOfContents",
                "image",
                "sdt"
              ]
            },
            "numbering": {
              "additionalProperties": false,
              "description": "Computed numbering rendering (marker/path/kind) for numbered list items and numbered headings — e.g. the rendered clause label \"2.3.\". Absent for non-numbered blocks.",
              "properties": {
                "kind": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "marker": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "path": {
                  "oneOf": [
                    {
                      "items": {
                        "type": "number"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "type": "object"
            },
            "ordinal": {
              "type": "number"
            },
            "paragraphNumbering": {
              "additionalProperties": false,
              "description": "Numbering reference (numId + level) for numbered blocks, including numbered headings. Absent for non-numbered blocks.",
              "properties": {
                "level": {
                  "type": "number"
                },
                "numId": {
                  "type": "number"
                }
              },
              "type": "object"
            },
            "ref": {
              "description": "Ref handle for this block. Pass directly to superdoc_format or superdoc_edit ref param. Only present for non-empty blocks.",
              "type": "string"
            },
            "styleId": {
              "description": "Named paragraph style.",
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "text": {
              "description": "Full flattened block text when requested with includeText.",
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "textPreview": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "ordinal",
            "nodeId",
            "nodeType"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "revision": {
        "type": "string"
      },
      "total": {
        "type": "number"
      }
    },
    "required": [
      "total",
      "blocks",
      "revision"
    ],
    "type": "object"
  }
  ```
</Accordion>