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 and optional nodeType filtering.

Summary

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

• 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
includeText	boolean	no
limit	number	no
nodeTypes	enum[]	no
offset	number	no

Example request

{
  "limit": 50,
  "offset": 0
}

Output fields

Field	Type	Required	Description
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

Non-applied failure codes

• None

Raw schemas

Raw input schema

{
  "additionalProperties": false,
  "properties": {
    "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"
          },
          "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"
            ]
          },
          "ordinal": {
            "type": "number"
          },
          "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"
}