Delete Block
delete_blockDelete a block by ID and return snapshots of removed content, including descendants and parent unlink by default. Use options to keep descendants orphaned or prune connectors.
Instructions
Delete a block by id and return snapshots of the removed content. Removes descendants and unlinks from the parent's sys:children by default; set deleteChildren=false to keep descendants orphaned (for re-parenting), or pruneConnectors=true to also drop surface connectors referencing any deleted id. Refuses affine:page — use delete_doc for whole docs.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"docId": "<docId>",
"blockId": "<blockId>"
},
"name": "delete_block"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| docId | Yes | Document ID | |
| blockId | Yes | Block id to delete. | |
| workspaceId | No | Workspace ID (optional if default set) | |
| deleteChildren | No | Also delete descendants (default true). | |
| pruneConnectors | No | Also delete connectors bound to any deleted id (default false). | |
| expectedRevision | No | Optional read_doc revision of this primary document. Reject stale content before writing. Covers document content, not workspace metadata; requires all writers to share one MCP server. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | No | ||
| code | No | ||
| error | No | ||
| reason | No | ||
| blockId | No | ||
| deleted | No | ||
| details | No | ||
| causeCode | No | ||
| retryable | No | ||
| deletedIds | No | ||
| deletedBlock | No | ||
| deletedBlocks | No | ||
| prunedConnectors | No | ||
| recoveryGuidance | No |