Edit the content body of an existing doc with block-level operations: insert_blocks, replace_block, delete_block and format_text. Content is provided as Markdown.

First call Get doc blocks (GET /v1/docs/:doc_id/blocks), then pass its version as expected_version and its block_refs in operations. If the doc has changed since, the edit is rejected with 409; fetch the blocks again and redo the edit. A successful edit also changes the version, so fetch the blocks again before the next edit — or make every change in one request.

The batch is atomic: if any operation fails, nothing changes. Operations apply in order, so an operation cannot target a block that an earlier operation in the batch replaced or deleted. Only blocks marked editable can be replaced, deleted or formatted; Dovetail modules (reference cards, reels, files, video, transcripts, mentions, citations) are never modified, moved or removed. Replacing or deleting a block with comments or highlights is rejected unless allow_annotation_loss is true. The doc's title is not part of its body; use Patch doc to change it.

🚧

Permissions

Please check you have the relevant permissions required to access this resource. This may include specific permissions on the object itself or its parent, or having the correct user role if you're making updates.

Required scope: insight:write