Workdocs are comprised of many different components called document blocks. These can contain various content types like text, code, lists, titles, images, videos, and quotes.

As a developer working with monday.com, it is important to familiarize yourself with the blocks API so you know how to access the content inside of docs. This document will walk you through the available queries and mutations to read and modify the blocks object via the API.

Queries

Required scope: docs:read

Querying blocks will return metadata about one or a collection of blocks. The method accepts various arguments and returns an array.

You can only query blocks by nesting it within a docs query, so it can't be used at the root.

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 is the ID that appears in the top-left corner of the doc 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

Required scope: docs:write

Create document block

The create_doc_block mutation allows you to create a new doc block via the API. You can also specify what fields to query back from the new doc block when you run the mutation.

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.

ArgumentDescription
after_block_id StringThe block's ID 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.
type DocBlockContentType!The block's content type: normal_text, large_title, medium_title, small_title, quote, bulleted_list, numbered_list, check_list, or code.
content JSON!The block's content.

Content argument

The content must follow proper JSON formatting and contain all necessary attributes when creating a new block.

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.

Update document block

The update_doc_block mutation allows you to update a doc block via the API. You can also specify what fields to query back from the updated doc block when you run the mutation.

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

The content must follow proper JSON formatting and contain all necessary attributes when creating a new block.

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

The delete_doc_block mutation allows you to delete a doc block via the API. You can also specify what fields to query back from the deleted doc block when you run the mutation.

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.

πŸ“˜

Join our developer community!

We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎