Document apiReferenceBlocks

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, optional nodeType filtering, and single-story scoping via `in: StoryLocator`.

read-onlyidempotent
doc.blocks.list(…)

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.

Inputs

inStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
Fields
kind"section"required
sectionIdstringrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
offsetnumber

Number of blocks to skip. Default: 0.

limitnumber

Maximum blocks to return. Omit for all blocks.

nodeTypes"paragraph" | "heading" | "listItem" | "table" | "tableRow" | "tableCell" | "tableOfContents" | "image" | "sdt"[]

Filter by block types (e.g. ['paragraph', 'heading']). Omit for all types.

includeTextboolean

When true, includes the full flattened block text in each block entry.

Result

Output fields
totalnumberrequired
blocksobject[]required
revisionstringrequired

Failures

Pre-apply throws

  • INVALID_INPUT
  • STORY_NOT_FOUND
  • STORY_MISMATCH
3 more codes
  • STORY_NOT_SUPPORTED
  • CROSS_STORY_PLAN
  • MATERIALIZATION_FAILED

Raw schemas

Open the generated JSON artifact for the exact input, output, success, and failure schemas represented by this contract version.

View raw JSON schemas