Skip to main content

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.

​
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

FieldTypeRequiredDescription
includeTextbooleanno
limitnumberno
nodeTypesenum[]no
offsetnumberno

​
Example request

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

​
Output fields

FieldTypeRequiredDescription
blocksobject[]yes
revisionstringyes
totalnumberyes

​
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

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

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