Document blocks

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

Document blocks queries

Required scope: docs:read

Document blocks cannot be used at the root of the query, so you must nest them within a docs query. Querying document blocks can return one or a collection of blocks.

query {
  docs (ids:1234567) {
    blocks {
      id
      type
      content
    }
  }
}
let query = 'query { docs (ids: [123]) { 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

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

Fields

FieldDescription
created_at DateThe block's creation date. Returned in YYYY-MM-DD format.
created_by UserThe blocks creator.
doc_id IntThe document's unique identifier.
id String!The block's unique identifier.
parent_block_id StringThe parent block's unique identifier. First-level blocks will have null value.
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
            }
        }
    }
}

Document blocks mutations

Required scope: docs:write

Create document block

This mutation allows you to create a new doc block. You can also add a new document block using the SDK.

mutation {
  create_doc_block (type: normal_text, after_block_id: "7f8c145-989f-48bb-b7f8-dc8f91690g42", content: "\"{\\\"alignment\\\":\\\"left\\\",\\\"direction\\\":\\\"ltr\\\",\\\"deltaFormat\\\":[{\\\"insert\\\":\\\"text\\\",\\\"attributes\\\":{\\\"bold\\\":true}},{\\\"insert\\\":\\\"with\\\",\\\"attributes\\\":{\\\" es\\\":{\\\"strike\\\":true}},{\\\"insert\\\":\\\"style, and the rest of it\\\",\\\"attributes\\\":{\\\"code\\\":true}},{\\\"insert\\\":\\\":\\\"}],\\\"indentation\\\":1}\"") {
    id
  }
}
let query = 'mutation {  create_doc_block (type: "text", after_block_id: "7f8c145-989f-48bb-b7f8-dc8f91690g42", content: "\"{\\\"alignment\\\":\\\"left\\\",\\\"direction\\\":\\\"ltr\\\",\\\"deltaFormat\\\":[{\\\"insert\\\":\\\"text\\\",\\\"attributes\\\":{\\\"bold\\\":true}},{\\\"insert\\\":\\\"with\\\",\\\"attributes\\\":{\\\" es\\\":{\\\"strike\\\":true}},{\\\"insert\\\":\\\"style, and the rest of it\\\",\\\"attributes\\\":{\\\"code\\\":true}},{\\\"insert\\\":\\\":\\\"}],\\\"indentation\\\":1}\"") { 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 for create document block

ArgumentDescription
doc_id Int!The document's unique identifier.
after_block_id StringUsed to specify where in the doc the new block should go. Provide the block's ID that will be above the new block. Without this argument, the new block will appear at the top of the doc.
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

This mutation allows you to update a doc block. You can also 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\\\":\\\"text\\\",\\\"attributes\\\":{\\\"bold\\\":true}},{\\\"insert\\\":\\\"with\\\",\\\"attributes\\\":{\\\" es\\\":{\\\"strike\\\":true}},{\\\"insert\\\":\\\"style, and the rest of it\\\",\\\"attributes\\\":{\\\"code\\\":true}},{\\\"insert\\\":\\\":\\\"}],\\\"indentation\\\":1}\"") {
    id
  }
}
let query = 'mutation { update_doc_block (block_id: "7f8c145-989f-48bb-b7f8-dc8f91690g42", content: "\"{\\\"alignment\\\":\\\"left\\\",\\\"direction\\\":\\\"ltr\\\",\\\"deltaFormat\\\":[{\\\"insert\\\":\\\"text\\\",\\\"attributes\\\":{\\\"bold\\\":true}},{\\\"insert\\\":\\\"with\\\",\\\"attributes\\\":{\\\" es\\\":{\\\"strike\\\":true}},{\\\"insert\\\":\\\"style, and the rest of it\\\",\\\"attributes\\\":{\\\"code\\\":true}},{\\\"insert\\\":\\\":\\\"}],\\\"indentation\\\":1}\"") { 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 for update document block

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

This mutation allows you to delete a doc block.

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 for delete document block

ArgumentDescription
block_id String!The block's unique identifier.

📘

Have questions?

Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.

Don’t forget to search before opening a new topic!