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.
Argument | Description |
---|---|
limit Int | The number of docs to get. The default is 25. |
page Int | The page number to return. Starts at 1. |
Fields
You can use the following field(s) 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.
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.
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
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
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 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.
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. 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
Argument | Description |
---|---|
block_id String! | The block's unique identifier. |