> ## 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] 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] 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"
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.