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 [Int]The specific docs to return. Please note that this argument's type is [ID!] in API versions 2023-10 and later.
limit IntThe number of docs to get. The default is 25.
object_ids [Int]The unique identifiers of associated boards or objects. This is the same ID in the URL and the doc column values. Please note that this argument's type is [ID!] in API versions 2023-10 and later.
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 [Int]The unique identifiers of the specific workspaces to return. Please note that this argument's type is [ID] in API versions 2023-10 and later.

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 IntThe unique identifier of the folder that contains the doc. Returns null for the first level. Please note that this field's type is ID in API versions 2023-10 and later.
doc_kind BoardKind!The document's kind: public, private, or share.
id Int!The document's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later.
name String!The document's name.
object_id Int!The associated board or object's unique identifier. This is the same ID in the URL and the doc column values. Please note that this field's type is ID! in API versions 2023-10 and later.
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 IntThe unique identifier of the workspace that contains the doc. Returns null for the Main workspace. Please note that this field's type is ID in API versions 2023-10 and later.
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

Required scope: docs:write

Create a doc

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

📘

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