Document blocks

Learn how to read, create, update, and delete document blocks inside of monday docs using the platform API

Workdocs are comprised of various components called document blocks, or blocks. Blocks contain different types of content, including text, code, lists, titles, images, videos, and quotes.

Queries

You can retrieve document block data via the API through the blocks query.

  • Required scope: docs:read
  • Returns an array containing metadata about one or a collection of blocks
  • Can only be nested with a docs query
query {
  docs (ids:1234567) {
    blocks {
      id
      type
      content
    }
  }
}
let query = 'query { docs (ids: 1234567) { blocks { id type content }}}';

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     'query' : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to reduce the number of results returned in your blocks query.

ArgumentDescription
limit IntThe number of docs to get. The default is 25.
page IntThe page number to return. Starts at 1.

Fields

You can use the following field(s) to specify what information your blocks query will return.

FieldDescription
created_at DateThe block's creation date. Returned in YYYY-MM-DD format.
created_by UserThe block's creator.
doc_id IDThe document's unique identifier. In the UI, this ID appears in the top-left corner of the document when developer mode is activated.
id String!The block's unique identifier.
parent_block_id StringThe parent block's unique identifier. First-level blocks will return null.
position FloatThe block's position in the document.
type StringThe block's content type.
updated_at DateThe date the block was last updated. Returned in YYYY-MM-DD format.
content JSONThe block's content.

Content field

The content field will return different information based on the block type. You can view a sample payload for each block type below, but keep in mind that the API will return payloads in a slightly different format using escaped JSON.

{
  "id": "7f8c145-989f-48bb-b7f8-dc8f91690g42",
  "type": "normal text", // "normal text", "large title", "medium title", "small title", or "quote"
  "content": {
    "alignment": "left", // "left", "center", or "right"
    "direction": "ltr", // "ltr" or "rtl"
    "deltaFormat": [{
      "insert": "document block text",
      "attributes": { // description of the text
        "bold": true, // bold text
        "underline": true, // underlined text
        "strike": true, // text with strike through
        "color": "var(--color-saladish)", // text with font color
        "background": "var(--color-river-selected)" // text with background color
      }
    }]
  }
}
{
	"id": "7f8c145-989f-48bb-b7f8-dc8f91690g42",
	"type": "check list", // "bulleted list", "numbered list", or "check list"
	"content": {
		"alignment": "right", // "left", "right", or "center"
		"direction": "rtl", // "ltr" or "rtl"
		"deltaFormat": [{
			"insert": "block 1"
		}],
		"indentation": 1,
		"checked": true // checks or unchecks a box
	}
}
{
	"id": "7f8c145-989f-48bb-b7f8-dc8f91690g42",
	"type": "table", // "table" or "layout"
	"content": {
		"cells": [ // the table's rows
			[{
					"blockId": "7f8c145-989f-48bb-b7f8-dc8f91690g42" // ID of the child block
				},
				{
					"blockId": "8g9d256-090g-59cc-c8g9-ed9g02701h53" // ID of the child block
				}
			]
		],
		"alignment": "right", // "left", "right", or "center"
		"direction": "rtl", // "ltr" or "rtl"
		"columnsStyle": [{ // size of the column by percent - the sum of these values has to be 100
				"width": 50
			},
			{
				"width": 50
			}
		]
	}
}
{
  "id": "7f8c145-989f-48bb-b7f8-dc8f91690g42",
  "type": "notice box", 
  "content": {
  	"theme": "info", // "tips", "warning", or "general"
  	"direction": "ltr", // "ltr" or "rtl"
  	"alignment": "left" // "left", "right", or "center"
  }
}
{
	"id": "7f8c145-989f-48bb-b7f8-dc8f91690g42",
	"type": "gif",
	"content": {
		"id": "123abc456def",
		"url": "https://media2.giphy.com/media/123abc456def/311x.gif?cid=1d9492h43&rid=200w.gif&ct=g",
		"width": 278,
		"alignment": "center", // "left", "right", or "center"
		"direction": "ltr", // "ltr" or "rtl"
		"aspectRatio": ""
	}
}
{
	"id": "7f8c145-989f-48bb-b7f8-dc8f91690g42",
	"type": "image",
	"content": {
		"url": "https://monday.monday.com/test/resources/123456789/testimage.png",
		"width": "900",
		"assetId": 123456789,
		"alignment": "center", // "left", "right", or "center"
		"direction": "ltr", // "ltr" or "rtl"
		"aspectRatio": "2380x1230"
	}
}
{
	"id": "7f8c145-989f-48bb-b7f8-dc8f91690g42",
	"type": "image",
	"content": {
		"width": 123, // changes the size of the image
		"publicUrl": "https://www.test.com/static/download/testimage.png",
		"direction": "rtl", // "ltr" or "rtl"
		"alignment": "right" // "left", "right", or "center"
	}
}
{
	"id": "7f8c145-989f-48bb-b7f8-dc8f91690g42",
	"type": "video",
	"content": {
		"url": "https://monday.monday.com/test/987654321/testvideo.mov",
		"width": 613,
		"assetId": 987654321,
		"alignment": "center", // "left", "right", or "center"
		"direction": "ltr", // "ltr" or "rtl"
		"aspectRatio": null
	}
}
{
	"id": "7f8c145-989f-48bb-b7f8-dc8f91690g42",
	"type": "video",
	"content": {
		"url": null,
		"width": 450,
		"rawUrl": "https://www.youtube.com/watch?v=123abc",
		"assetId": null,
		"alignment": "left", // "left", "right", or "center"
		"direction": "ltr", // "ltr" or "rtl"
		"embedData": {
			"embedlyData": {
				"url": "https://www.youtube.com/watch?v=123abc",
				"html": "<iframe class=\"embedly-embed\" src=\"//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2F123abc&display_name=YouTube&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D123abc&image=http%3A%2F%2Fi.ytimg.com%2Fvi%2F123abc%2Fhqdefault.jpg&key=60f4bf4bdbb750b6b09783043556f314&type=text%2Fhtml&schema=youtube\" width=\"854\" height=\"480\" scrolling=\"no\" title=\"YouTube embed\" frameborder=\"0\" allow=\"autoplay; fullscreen\" allowfullscreen=\"true\"></iframe>",
				"type": "video",
				"title": "Sample video title",
				"width": 854,
				"height": 480,
				"version": "1.0",
				"author_url": "https://www.youtube.com/monday.com",
				"author_name": "monday.com",
				"description": "This is a sample monday.com video",
				"provider_url": "http://youtube.com",
				"provider_name": "YouTube",
				"thumbnail_url": "http://i.ytimg.com/vi/3lrXMmciw2N/hqdefault.jpg",
				"thumbnail_width": 480,
				"thumbnail_height": 360
			}
		}
	}
}

Mutations

The API allows you to create, update, and delete document blocks using the following mutations.

Create doc block

Required scope: docs:write

The create_doc_block mutation creates a new doc block via the API. You can specify which fields to return from the new doc block in the mutation response.

Alternatively, you can add a new document block using the SDK.

mutation {
  create_doc_block (type: normal_text, doc_id: 1234567, after_block_id: "7f8c145-989f-48bb-b7f8-dc8f91690g42", content: "{\"alignment\":\"left\",\"direction\":\"ltr\",\"deltaFormat\":[{\"insert\":\"new block\"}]}") {
    id
  }
}
let query = 'mutation {  create_doc_block (type: normal_text, doc_id: 1234567, after_block_id: "7f8c145-989f-48bb-b7f8-dc8f91690g42", content: \"{\\\"alignment\\\":\\\"left\\\",\\\"direction\\\":\\\"ltr\\\",\\\"deltaFormat\\\":[{\\\"insert\\\":\\\"new block\\\"}]}\") { id }}';

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     'query' : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to define the new doc block's characteristics.

ArgumentDescriptionEnum values
after_block_id StringThe unique identifier of the block that will be above the new block. Used to specify where in the doc the new block should go. Without this argument, the new block will appear at the top of the doc.
doc_id ID!The document's unique identifier.
parent_block_id StringThe parent block's ID under which the new block will be created.
type DocBlockContentType!The block's content type.bulleted_list
check_list
code
divider
image
large_title
layout
medium_title
normal_text
notice_box, numbered_list
page_break
quote
small_title
table
video
content JSON!The block's content.

Content argument

When creating a new block, the content must follow proper JSON formatting and contain all necessary attributes.

For text blocks and most other block types, all attributes are optional. You can use the same fields and attributes returned when you query the block's content.

Tables have two required attributes: column_count and row_count. Tables can have up to 25 rows and 10 columns. You cannot update table dimensions after setting them. The column_style attribute is optional, but you can use it to specify the size of each cell. The sum of each cell's width must equal 100.

Layouts require the column_count field, which determines the size of your layout. You can use the optional column_style attribute to determine the size of each cell in the layout. The sum of each cell's width must equal 100.

Create doc blocks

🚧 Only available in API versions 2025-10 and later

Required scope: docs:write

The create_doc_blocks mutation creates up to 25 doc blocks in bulk via the API. It returns the [DocumentBlockV2!] type which allows you to specify what fields to query back when you run it.

mutation {
  create_doc_blocks(
    docId: 12345
    blocksInput: [
      {
        text_block: {
          text_block_type: QUOTE
          delta_format: [
            {
              insert: {
                text: "The best way to predict the future is to create it."
              }
              attributes: {
                italic: true
                color: "#666666"
              }
            }
            {
              insert: {
                text: "Peter Drucker"
              }
              attributes: {
                bold: true
                color: "#999999"
              }
            }
          ]
        }
      }
      {
        text_block: {
          text_block_type: LARGE_TITLE
          delta_format: [
            {
              insert: {
                text: "This quote highlights the power of action and ownership."
              }
            }
          ]
        }
      }
      {
        notice_box_block: {
          theme: TIPS
        }
      }
      {
        list_block: {
          list_block_type: BULLETED_LIST
          delta_format: [
            {
              insert: {
                text: "Set clear objectives"
              }
            }
          ]
        }
      }
      {
        list_block: {
          list_block_type: BULLETED_LIST
          delta_format: [
            {
              insert: {
                text: "Take small, consistent steps"
              }
            }
          ]
        }
      }
      {
        list_block: {
          list_block_type: BULLETED_LIST
          delta_format: [
            {
              insert: {
                text: "Review and adjust regularly"
              }
            }
          ]
        }
      }
      {
        page_break_block: {}
      }
    ]
  ) {
    doc_id
    id
    type
    position
    content {
      ... on TextBlockContent {
        delta_format {
          insert {
            text
          }
        }
      }
      ... on ListBlockContent {
        delta_format {
          insert {
            text
          }
        }
      }
    }
  }
}

{
  "data": {
    "create_doc_blocks": [
      {
        "doc_id": "12345",
        "id": "11111111-1111-1111-1111-111111111111",
        "type": "quote",
        "position": 100000,
        "content": [
          {
            "delta_format": [
              {
                "insert": {
                  "text": "The best way to predict the future is to create it."
                }
              },
              {
                "insert": {
                  "text": "Peter Drucker"
                }
              }
            ]
          }
        ]
      },
      {
        "doc_id": "12345",
        "id": "22222222-2222-2222-2222-222222222222",
        "type": "large title",
        "position": 141250,
        "content": [
          {
            "delta_format": [
              {
                "insert": {
                  "text": "This quote highlights the power of action and ownership."
                }
              }
            ]
          }
        ]
      },
      {
        "doc_id": "12345",
        "id": "33333333-3333-3333-3333-333333333333",
        "type": "notice box",
        "position": 189875,
        "content": [
          {}
        ]
      },
      {
        "doc_id": "12345",
        "id": "44444444-4444-4444-4444-444444444444",
        "type": "bulleted list",
        "position": 235420,
        "content": [
          {
            "delta_format": [
              {
                "insert": {
                  "text": "Set clear objectives"
                }
              }
            ]
          }
        ]
      },
      {
        "doc_id": "12345",
        "id": "55555555-5555-5555-5555-555555555555",
        "type": "bulleted list",
        "position": 287965,
        "content": [
          {
            "delta_format": [
              {
                "insert": {
                  "text": "Take small, consistent steps"
                }
              }
            ]
          }
        ]
      },
      {
        "doc_id": "12345",
        "id": "66666666-6666-6666-6666-666666666666",
        "type": "bulleted list",
        "position": 346780,
        "content": [
          {
            "delta_format": [
              {
                "insert": {
                  "text": "Review and adjust regularly"
                }
              }
            ]
          }
        ]
      },
      {
        "doc_id": "12345",
        "id": "77777777-7777-7777-7777-777777777777",
        "type": "page break",
        "position": 412555,
        "content": [
          {}
        ]
      }
    ]
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

ArgumentDescriptionSupported Fields
afterBlockId StringThe unique identifier of the block that will be above the new block. Used to specify where in the doc the new blocks should go. Without this argument, the new blocks will be inserted based on their parentBlockId or at the end of the document in the provided order.
blocksInput [CreateBlockInput!]!An array of block inputs. Each input must specify one block type. Maximum of 25 blocks per request.divider_block DividerBlockInput
image_block ImageBlockInput
layout_block LayoutBlockInput
list_block ListBlockInput
notice_box_block NoticeBoxBlockInput
page_break_block PageBreakBlockInput
table_block TableBlockInput
text_block TextBlockInput
video_block VideoBlockInput
docId ID!The document's unique identifier.

Update doc block

Required scope: docs:write

The update_doc_block mutation updates a doc block via the API. You can specify which fields to return from the updated doc block in the mutation response.

Alternatively, you can update a document block using the SDK.

mutation {
  update_doc_block (block_id: "7f8c145-989f-48bb-b7f8-dc8f91690g42", content: "{\"alignment\":\"left\",\"direction\":\"ltr\",\"deltaFormat\":[{\"insert\":\"new block\"}]}") {
    id
  }
}
let query = 'mutation { update_doc_block (block_id: "7f8c145-989f-48bb-b7f8-dc8f91690g42", content: \"{\\\"alignment\\\":\\\"left\\\",\\\"direction\\\":\\\"ltr\\\",\\\"deltaFormat\\\":[{\\\"insert\\\":\\\"new block\\\"}]}\") { id }}';

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     'query' : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to define the updated doc block's characteristics.

ArgumentDescription
block_id String!The block's unique identifier.
content JSON!The block's content.

Content argument

When updating a block, the content must follow proper JSON formatting and contain all necessary attributes.

For text blocks and most other block types, all attributes are optional. You can use the same fields and attributes returned when you query the block's content.

Tables have two required attributes. They need both the column_count and row_count attributes to determine the size of your table. The maximum value for each is 5; you cannot change the values after setting them. The column_style attribute is optional, but you can use it to specify the size of each cell. The sum of each cell's width must equal 100.

Layouts have one required attribute. They require the column_count field to determine the size of your layout. Optionally, you can also use the column_style attribute to determine the size of each cell in the layout. The sum of each cell's width must equal 100.

Delete document block

Required scope: docs:write

The delete_doc_block mutation deletes a doc block. You can specify which fields to return from the deleted doc blocks in the mutation response.

mutation { 
  delete_doc_block (block_id: "7f8c145-989f-48bb-b7f8-dc8f91690g42") {
    id
  }
}
let query = 'mutation { delete_doc_block (block_id: "block-4-1671991243355") { id }}';

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     'query' : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

ArgumentDescription
block_id String!The block's unique identifier.