blocks.list

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

{
  "in": {
    "kind": "story",
    "storyType": "body"
  },
  "offset": 0
}

Output fields

Field	Type	Required
`blocks`	object[]	yes
`revision`	string	yes
`total`	number	yes

Example response

{
  "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

Raw input schema

{
  "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"
}

Raw output schema

{
  "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"
}

Getting Started

Editor

Document Engine

AI

Solutions

Resources

Summary

Expected result

Input fields

Example request

Output fields

Example response

Pre-apply throws

Non-applied failure codes

Raw schemas

​Summary

​Expected result

​Input fields

​Example request

​Output fields

​Example response

​Pre-apply throws

​Non-applied failure codes

​Raw schemas

Summary

Expected result

Input fields

Example request

Output fields

Example response

Pre-apply throws

Non-applied failure codes

Raw schemas