V2
Delete Block
Move a block to trash and return its soft-delete result.
Delete Block
When to use
Use this endpoint to remove a content block from its parent while keeping it recoverable.
Note: Delete endpoints are intentionally omitted from the machine-readable OpenAPI specification and are not projected to MCP or CLI. This page documents the HTTP endpoint.
Endpoint
| Item | Value |
|---|---|
| Method | DELETE |
| Path | /v2/blocks/:block_id |
| Request body | None |
| Response | Soft-deleted block result |
| Scope | blocks.write |
block_id must be the UUID of a writable block.
Response
{
"object": "block",
"id": "99999999-9999-4999-8999-999999999999",
"in_trash": true
}
Behavior
- Deletion is soft. Only the target block is archived; its parent relationship and child list are preserved so the subtree can be restored.
- Descendants become unavailable with the root block but are not physically deleted.
- V2 API does not expose permanent block deletion.
- Repeating the request for an already archived block still succeeds.
Errors
401 unauthorized: token is invalid or expired.403 forbidden: missingblocks.writeor no write access to the block.404 not_found: block does not exist.