blocks.list

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

Summary

List top-level blocks in document order with IDs, types, and text previews. 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, isEmpty), and the current document revision.

Input fields

Field	Type	Required	Description
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": [
    {
      "isEmpty": true,
      "nodeId": "node-def456",
      "nodeType": "paragraph",
      "ordinal": 1,
      "textPreview": "example"
    }
  ],
  "revision": "example",
  "total": 1
}

Pre-apply throws

• INVALID_INPUT

Non-applied failure codes

• None

Raw schemas

Raw input schema

{
  "additionalProperties": false,
  "properties": {
    "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 (e.g. '#000000'). Defaults to black when not set.",
            "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"
              }
            ]
          },
          "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"
}