Update Document
update_docUpdate existing monday.com documents by renaming, adding markdown content, editing or creating blocks, deleting or replacing blocks, and adding comments with block-level or text-selection anchoring.
Instructions
Update an existing monday.com document. Provide doc_id (preferred) or object_id, plus an ordered operations array (executed sequentially, stops on first failure).
OPERATIONS:
set_name: Rename the document.
add_markdown_content: Append markdown as blocks (or insert after a block). Best for text, headings, lists, simple tables — no block IDs needed.
update_block: Update content of an existing text, code, or list_item block in-place.
create_block: Create a new block at a precise position. Use parent_block_id to nest inside notice_box, table cell, or layout cell.
delete_block: Remove any block. The ONLY option for BOARD, WIDGET, DOC embed, and GIPHY blocks.
replace_block: Delete a block and create a new one in its place (use when update_block is not supported).
add_comment: Create a new comment or reply on the document (doc-level, block-level, or text-selection).
WHEN TO USE EACH OPERATION:
text / code / list_item → update_block. Use replace_block to change subtype (e.g. NORMAL_TEXT→LARGE_TITLE)
divider / table / image / video / notice_box / layout → replace_block (properties immutable after creation)
BOARD / WIDGET / DOC / GIPHY → delete_block only
GETTING BLOCK IDs: Call read_docs with include_blocks: true — returns id, type, position, and content per block.
BLOCK CONTENT (delta_format): Array of insert ops. Last op MUST be {insert: {text: "\n"}}.
Plain: [{insert: {text: "Hello"}}, {insert: {text: "\n"}}]
Bold: [{insert: {text: "Hi"}, attributes: {bold: true}}, {insert: {text: "\n"}}]
Mention user/doc/board: [{insert: {text: "Hey "}}, {insert: {mention: {id: 12345, type: "USER"}}}, {insert: {text: "\n"}}] — type is USER, DOC, or BOARD. id is numeric (user IDs from list_users_and_teams)
Inline column value: [{insert: {column_value: {item_id: 111, column_id: "status"}}}, {insert: {text: "\n"}}]
Supported attributes: bold, italic, underline, strike, code, link, color, background (not applicable to mention/column_value ops)
IMAGE WITH ASSET: For asset-based images, use create_block with block_type "image" and asset_id (instead of public_url). add_markdown_content does NOT support asset images — for mixed content, alternate add_markdown_content (text) and create_block (image) operations in sequence.
COMMENTS:
add_comment: Create a new comment or reply on the document. Three scopes:
Doc-level (no block_id): comment appears on the doc as a whole.
Block-level (block_id only): comment is anchored to a specific block. The block shows a comment indicator in the UI.
Text-selection (block_id + selection_from + selection_length): comment is anchored to a specific character range inside a text/code/list_item block. That text is highlighted with a comment marker. Block-level and text-selection comments only work on blocks with text content (text, code, list_item, title, quote). They do NOT work on: divider, page_break, table, layout, notice_box, image, video, or giphy blocks. Get block IDs from read_docs with include_blocks: true. Format body with HTML, not markdown. Use mentions_list for @mentions.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | No | The document ID (the id field from read_docs). Takes priority over object_id if both are provided. | |
| object_id | No | The document object ID (the object_id field from read_docs, visible in the document URL). Resolved to doc_id. | |
| operations | Yes | Ordered list of operations to perform. Executed sequentially. Stops at first failure. Operation types: - set_name: Rename the document. - add_markdown_content: Append markdown as blocks (simplest for text/lists/tables). - update_block: Change content of an existing text/code/list/divider block. - create_block: Create a new block at a specific position (supports text, list_item, code, divider, page_break, image, video, notice_box, table, layout). - delete_block: Permanently remove a block. Works for ALL block types including BOARD, WIDGET, DOC embed, GIPHY. - replace_block: Delete a block and create a new one in its place. Use for: changing image/video source, table restructure, notice_box theme change. - add_comment: Create a new comment or reply on the document. Use parent_update_id to reply to an existing comment. Format text with HTML. Uses the doc's backing board item. WHEN TO USE WHICH: - Adding new text sections → add_markdown_content - Adding asset-based images → create_block with block_type "image" and asset_id (add_markdown_content does NOT support asset images) - Mixed content with asset images → alternate add_markdown_content (for text) and create_block (for each image) in sequence - Editing existing text block → update_block - Changing an image URL → replace_block (image URL is immutable after creation) - Changing video URL → replace_block - Restructuring a table → replace_block - BOARD/WIDGET/DOC/GIPHY blocks → delete_block only (no public API to create these) NESTING CONTENT IN CONTAINERS: - notice_box: Fully supported. Create the notice_box first, then in a separate call create child blocks with parent_block_id set to the notice_box ID. You cannot reference a block ID created in the same call. - table: Cell-level API nesting is NOT supported. To create a table with content, use add_markdown_content with a markdown table (e.g. "| H1 | H2 |\n| --- | --- |\n| A | B |"). This creates a pre-populated table in one shot. Empty tables created via create_block cannot have their cells populated through the API. - layout: Cell-level API nesting is NOT supported and there is no markdown equivalent. Layouts can only be created empty via create_block. No workaround exists to populate layout columns through the API. Deleting a container does NOT delete its children — delete children first for clean removal. Block IDs are available in the blocks array returned by read_docs. |