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

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

Field	Description
created_at `Date`	The block's creation date. Returned in YYYY-MM-DD format.
created_by `User`	The blocks creator.
doc_id `Int`	The document's unique identifier.
id `String!`	The block's unique identifier.
parent_block_id `String`	The parent block's unique identifier. First-level blocks will have null value.
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
            }
        }
    }
}

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

Argument	Description
doc_id `Int!`	The document's unique identifier.
after_block_id `String`	Used 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

Argument	Description
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.

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

Argument	Description
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!

Document blocks queries

Arguments

Fields

Content field

Document blocks mutations

Create document block

Arguments for create document block

Update document block

Arguments for update document block

Delete document block

Arguments for delete document block

📘Have questions?

📘
Have questions?