blocks.delete

Summary

Delete an entire block node (paragraph, heading, list item, table, image, or sdt) deterministically.

Operation ID: blocks.delete
API member path: editor.doc.blocks.delete(...)
Mutates document: yes
Idempotency: conditional
Supports tracked mode: yes
Supports dry run: yes
Deterministic target resolution: yes

Expected result

Returns a BlocksDeleteResult receipt confirming the block was removed, including a deletedBlock summary with ordinal, nodeType, and textPreview.

Input fields

Field	Type	Required	Description
`target`	DeletableBlockNodeAddress	yes	DeletableBlockNodeAddress
`target.kind`	`"block"`	yes	Constant: `"block"`
`target.nodeId`	string	yes
`target.nodeType`	enum	yes	`"paragraph"`, `"heading"`, `"listItem"`, `"table"`, `"sdt"`
`target.story`	StoryLocator	no	StoryLocator

Example request

{
  "target": {
    "kind": "block",
    "nodeId": "node-def456",
    "nodeType": "paragraph",
    "story": {
      "kind": "story",
      "storyType": "body"
    }
  }
}

Output fields

Field	Type	Required	Description
`affectedStories`	StoryLocator[]	no
`deleted`	DeletableBlockNodeAddress	yes	DeletableBlockNodeAddress
`deleted.kind`	`"block"`	yes	Constant: `"block"`
`deleted.nodeId`	string	yes
`deleted.nodeType`	enum	yes	`"paragraph"`, `"heading"`, `"listItem"`, `"table"`, `"sdt"`
`deleted.story`	StoryLocator	no	StoryLocator
`deletedBlock`	object	no
`deletedBlock.nodeId`	string	no
`deletedBlock.nodeType`	string	no
`deletedBlock.ordinal`	number	no
`deletedBlock.textPreview`	string \| null	no	One of: string, null
`invalidatedRefs`	AffectedRef[]	no
`success`	`true`	yes	Constant: `true`
`textRangeShifts`	TextRangeShift[]	no
`txId`	string	no

Example response

{
  "deleted": {
    "kind": "block",
    "nodeId": "node-def456",
    "nodeType": "paragraph",
    "story": {
      "kind": "story",
      "storyType": "body"
    }
  },
  "deletedBlock": {
    "nodeId": "node-def456",
    "ordinal": 1
  },
  "invalidatedRefs": [
    {
      "blockId": "block-abc123",
      "kind": "text",
      "range": {
        "end": 10,
        "start": 0
      },
      "story": {
        "kind": "story",
        "storyType": "body"
      }
    }
  ],
  "success": true
}

Pre-apply throws

TARGET_NOT_FOUND
AMBIGUOUS_TARGET
CAPABILITY_UNAVAILABLE
INVALID_TARGET
INVALID_INPUT
INTERNAL_ERROR
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": {
    "target": {
      "$ref": "#/$defs/DeletableBlockNodeAddress"
    }
  },
  "required": [
    "target"
  ],
  "type": "object"
}

Raw output schema

{
  "additionalProperties": false,
  "properties": {
    "affectedStories": {
      "items": {
        "$ref": "#/$defs/StoryLocator"
      },
      "type": "array"
    },
    "deleted": {
      "$ref": "#/$defs/DeletableBlockNodeAddress"
    },
    "deletedBlock": {
      "additionalProperties": false,
      "properties": {
        "nodeId": {
          "type": "string"
        },
        "nodeType": {
          "type": "string"
        },
        "ordinal": {
          "type": "number"
        },
        "textPreview": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "type": "object"
    },
    "invalidatedRefs": {
      "items": {
        "$ref": "#/$defs/AffectedRef"
      },
      "type": "array"
    },
    "success": {
      "const": true
    },
    "textRangeShifts": {
      "items": {
        "$ref": "#/$defs/TextRangeShift"
      },
      "type": "array"
    },
    "txId": {
      "type": "string"
    }
  },
  "required": [
    "success",
    "deleted"
  ],
  "type": "object"
}

Raw success schema

{
  "additionalProperties": false,
  "properties": {
    "affectedStories": {
      "items": {
        "$ref": "#/$defs/StoryLocator"
      },
      "type": "array"
    },
    "deleted": {
      "$ref": "#/$defs/DeletableBlockNodeAddress"
    },
    "deletedBlock": {
      "additionalProperties": false,
      "properties": {
        "nodeId": {
          "type": "string"
        },
        "nodeType": {
          "type": "string"
        },
        "ordinal": {
          "type": "number"
        },
        "textPreview": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "type": "object"
    },
    "invalidatedRefs": {
      "items": {
        "$ref": "#/$defs/AffectedRef"
      },
      "type": "array"
    },
    "success": {
      "const": true
    },
    "textRangeShifts": {
      "items": {
        "$ref": "#/$defs/TextRangeShift"
      },
      "type": "array"
    },
    "txId": {
      "type": "string"
    }
  },
  "required": [
    "success",
    "deleted"
  ],
  "type": "object"
}

Raw failure schema

{
  "additionalProperties": false,
  "properties": {
    "failure": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "enum": [
            "TARGET_NOT_FOUND",
            "AMBIGUOUS_TARGET",
            "CAPABILITY_UNAVAILABLE",
            "INVALID_TARGET",
            "INVALID_INPUT",
            "INTERNAL_ERROR",
            "STORY_NOT_FOUND",
            "STORY_MISMATCH",
            "STORY_NOT_SUPPORTED",
            "CROSS_STORY_PLAN",
            "MATERIALIZATION_FAILED"
          ]
        },
        "details": {},
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "success": {
      "const": false
    }
  },
  "required": [
    "success",
    "failure"
  ],
  "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