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 use the blocks query to retrieve document block data via the API.

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) { # the ID returned when querying `docs`
    blocks {
      id
      type
      content
    }
  }
}

query {
  docs(object_ids:1234567) { # the ID in the URL
    blocks {
      id
      type
      content
    }
  }
}

Arguments

You can use the following arguments to reduce the number of results returned in your blocks query.

Argument	Description
limit `Int`	The number of blocks to get. The default is 25.
page `Int`	The page number to return. Starts at 1.

Fields

You can use the following fields to specify what information your blocks query will return.

Field	Description
created_at `Date`	The block's creation date. Returned in YYYY-MM-DD format.
created_by `User`	The block's creator.
doc_id `ID`	The 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 `String`	The parent block's unique identifier. First-level blocks will return `null`.
position `Float`	The block's position in the document.
type `String`	The block's content type.
updated_at `Date`	The date the block was last updated. Returned in YYYY-MM-DD format.
content `JSON`	The 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. These operations let you programmatically control a block's full lifecycle.

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 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
  }
}

Arguments

You can use the following arguments to define the new doc block's characteristics.

Argument	Description	Enum values
after_block_id `String`	The 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 `String`	The 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 versions 2026-04 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 which fields to return in the mutation response.

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

You can use the following arguments to define the new doc blocks' characteristics.

Argument	Description	Supported Fields
afterBlockId `String`	The 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 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
  }
}

Arguments

You can use the following arguments to define the updated doc block's characteristics.

Argument	Description
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: column_count and row_count. The maximum value for each is 5; you cannot change the values after they have been set. 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: column_count. 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 doc block

Required scope:docs:write

The delete_doc_block mutation deletes a doc block via the API. You can specify which fields to return in the mutation response.

mutation { 
  delete_doc_block(block_id: "7f8c145-989f-48bb-b7f8-dc8f91690g42") {
    id
  }
}

Arguments

You can use the following argument to specify which block to delete.

Argument	Description
block_id `String!`	The block's unique identifier.