Workdocs serve as a central place for teams to plan and execute work in a collaborative format. They are like virtual whiteboards that allow you to jot down notes, create charts, and populate items on a board from the text you type. Docs enable teams to collaborate in real-time without overwriting each other's work. Users can even implement built-in features like widgets, templates, and apps to enhance their docs.

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

Queries

Required scope: docs:read

Querying docs will return metadata about a collection of docs. This method accepts various arguments and returns an array.

You can only query docs directly at the root, so it can't be nested within another query.

query {
  docs (object_ids: 123456789, limit: 1) {
    id
    object_id
    settings
    created_by {
      id
      name
    }
  }
}
let query = "query { docs (ids: 123456789, limit: 1) { id object_id settings created_by { id name }}}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   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 docs query.

ArgumentDescription
ids [ID!]The specific docs to return. In the UI, this is the ID that appears in the top-left corner of the doc when developer mode is activated.
limit IntThe number of docs to get. The default is 25.
object_ids [ID!]The unique identifiers of associated boards or objects. In the UI, this is the ID that appears in the URL and the doc column values.
order_by DocsOrderByThe order in which to retrieve your boards: created_at or used_at. The default shows created_at with the newest docs listed first. This argument will not be applied if you query docs by specific ids.
page IntThe page number to return. Starts at 1.
workspace_ids [ID]The unique identifiers of the specific workspaces to return.

Fields

You can use the following field(s) to specify what information your docs query will return. Please note that some fields will have their own arguments.

FieldDescriptionSupported arguments
blocks [DocumentBlock]The document's content blocks.limit Int
page Int
created_at DateThe document's creation date.
created_by UserThe document's creator.
doc_folder_id IDThe unique identifier of the folder that contains the doc. Returns null for the first level.
doc_kind BoardKind!The document's kind: public, private, or share.
id ID!The 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.
name String!The document's name.
object_id ID!The associated board or object's unique identifier. In the UI, this is the ID that appears in the URL and the doc column values.
relative_url StringThe document's relative URL.
url StringThe document's direct URL.
workspace WorkspaceThe workspace that contains this document. Returns null for the Main workspace.
workspace_id IDThe unique identifier of the workspace that contains the doc. Returns null for the Main workspace.
settings JSONThe document's settings.

Settings field

The settings field returns document-level settings. You can view a sample payload below, but keep in mind that the API will return payloads in a slightly different format using escaped JSON.

{
  "fontSize": "small", // "small", "normal", or "large"
  "hasTitle": true, // true or false
  "coverPhoto": {
    "isEnabled": true, // true or false
    "imageUrl": "", 
    "fromTop": 0
 	 },
  "fontFamily": "Serif", // "Serif", "Mono", or "Default"
  "isPageLayout": true, // true or false
  "backgroundColor": "var(--color-sofia_pink-selected)", 
  "isFullWidthMode": false, // true or false
  "backgroundPattern": null, // "sticky-note", "notepad", or "cubes-notepad"
  "showTableOfContent": true // true or false
}

Mutations

Create a doc

Required scope: docs:write

The create_doc mutation allows you to create a new doc in a document column or workspace via the API. You can also specify what fields to query back from the new doc when you run the mutation.

mutation {
  create_doc (location: {workspace: { workspace_id: 12345678, name:"New doc", kind: private}}) {
    id
  }
}
let query = 'mutation { create_doc (location: {workspace: {workspace_id: 12345678, name: "New doc", kind:private}}) { 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

ArgumentDescriptionSupported arguments
location CreateDocInput!The new document's location.board CreateDocBoardInput
workspace CreateDocWorkspaceInput

Create a doc column

πŸ‘

Only available in API version 2024-04

This mutation is only available in API versions 2024-04 and later.

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

mutation {
  create_column (board_id: 1234567890, column_type: doc, title: "Task info") {
    id
  }
}
let query = 'mutation {  create_column (board_id: 1234567890, column_type: doc, title: "Task info") { 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 column's characteristics.

ArgumentDescription
after_column_id IDThe unique identifier of the column after which the new column will be created.
board_id ID!The board's unique identifier where the new column should be created.
column_type ColumnType!The type of column to create.
defaults JSONThe new column's defaults.
description StringThe new column's description.
id StringThe column's user-specified unique identifier. Please note that the mutation will fail if it does not meet any of the following requirements:
- [1-20] characters in length (inclusive)
- Only lowercase letters (a-z) and underscores (_)
- Must be unique (no other column on the board can have the same ID)
- Can't reuse column IDs, even if the column has been deleted from the board
- Can't be null, blank, or an empty string
title String!The new column's title.

πŸ“˜

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! 😎