Workdocs serve as a central place for teams to plan and execute work collaboratively. They're 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, such as widgets, templates, and apps, to enhance their docs.

Queries

Get docs

Required scope:docs:read
Returns an array containing metadata about a collection of docs
Can only be queried directly at the root; can't be nested within another query

query {
  docs(
    object_ids: [123456789]
    limit: 1
  ) {
    id
    object_id
    settings
    created_by {
      id
      name
    }
  }
}

Arguments

Argument	Type	Description	Enum Values
ids	`[ID!]`	The document's unique internal identifier. In the UI, this is the ID that appears in the top-left corner of the doc when developer mode is activated. It's also the value returned when querying `docs`.
limit	`Int`	The number of docs to get. The default is 25.
object_ids	`[ID!]`	The document's unique identifier(s). In the UI, this is the ID that appears in the URL and the doc column values.
order_by	`DocsOrderBy`	The order in which to retrieve your boards. The default shows created_at with the newest docs listed first. This argument will not be applied if you query docs by specific `ids`.	`created_at` `used_at`
page	`Int`	The page number to return. Starts at 1.
workspace_ids	`[ID]`	The unique identifiers of the specific workspaces to return.

Fields

Field	Type	Description	Enum Values
blocks	`[DocumentBlock]`	The document's content blocks.
created_at	`Date`	The document's creation date.
created_by	`User`	The document's creator.
doc_folder_id	`ID`	The unique identifier of the folder that contains the doc. Returns `null` for the first level.
doc_kind	`BoardKind!`	The document's kind.	`private` `public` `share`
id	`ID!`	The document's unique identifier. In the UI, this ID appears in the top-left corner of the doc when developer mode is activated. Can be passed in the `ids` argument.
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	`String`	The document's relative URL.
updated_at	`Date`	The document's last updated date.
url	`String`	The document's direct URL.
workspace	`Workspace`	The workspace that contains this document. Returns `null` for the Main workspace.
workspace_id	`ID`	The unique identifier of the workspace that contains the doc. Returns `null` for the Main workspace.
settings	`JSON`	The 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 doc

Creates a new doc in a document column or workspace. Returns Document.

mutation {
  create_doc(
    location: {
      workspace: {
        workspace_id: 12345678
        name: "New doc"
        kind: private
      }
    }
  ) {
    id
  }
}

Arguments

Argument	Type	Description
location	`CreateDocInput!`	The new document's location.

Add content to doc from markdown

Adds markdown content to an existing monday doc. The markdown will be parsed and converted into the corresponding block types. Returns DocBlocksFromMarkdownResult.

mutation {
  add_content_to_doc_from_markdown(
    docId: 123456, 
    markdown: "# Markdown Example\n\n**Bold text**, *italic text*, and `inline code`.\n\n- Item one\n- Item two\n\n> A simple blockquote."
  ) {
    success
    block_ids
    error
  }
}

{
  "data": {
    "add_content_to_doc_from_markdown": {
      "success": true,
      "block_ids": [
				"7fa2d9c4-1b3e-4c67-9f5a-2d9d84e3a912",
				"c4b6e2f1-59a7-4c12-b3de-8a1d4e0f42ac",
				"2d3f6b19-83e2-45cd-b9a1-7fe6493b0f56",
				"9b4d1f22-6c3a-4879-a82d-1e2c3f8d9a77",
				"e5c8f320-7a14-4d9c-b25e-9f1a2c4d8b33"
      ],
      "error": null
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

Argument	Type	Description
afterBlockId	`String`	The unique identifier of the block to insert the markdown content after.
docId	`ID!`	The unique identifier of the doc to add the content to.
markdown	`String!`	The markdown content to add and convert.

Import doc from html

Imports HTML content into a new monday doc. The HTML will be parsed and converted into the corresponding block types. We currently support the following block types: style/format text, emoji, quote, table, list, code, divider, and title/header text. Returns ImportDocFromHtmlResult.

mutation {
  import_doc_from_html(
    html: """
<!DOCTYPE html>
<html>
  <head>
    <title>Test Doc</title>
  </head>
  <body>
    <h1>Hello World</h1>
    <p>This is a <strong>fake HTML</strong> doc for testing.</p>
    <ul>
      <li>One</li>
      <li>Two</li>
      <li>Three</li>
    </ul>
  </body>
</html>
    """,
    workspaceId: 1234567890,
    title: "New Doc from HTML",
    folderId: 9876543210
  ) {
    error
    success
    doc_id
  }
}

{
  "data": {
    "import_doc_from_html": {
      "error": null,
      "success": true,
      "doc_id": "12345"
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

Argument	Type	Description	Enum Values
folderId	`ID`	The unique identifier of the folder to create the doc in. If omitted, the document will be created at the root level of the workspace.
html	`String!`	The HTML content to convert into a new doc.
kind	`DocKind`	The document's access level.	`private` `public` `share`
title	`String`	The new document's title. If omitted, the title will be inferred from the provided HTML content.
workspaceId	`ID!`	The unique identifier of the workspace to create the doc in.

Update doc name

Updates the name/title of an existing document. Returns a JSON object containing the updated name.

mutation {
  update_doc_name(
    docId: 12345, 
    name: "The new document name."
	)
}

Arguments

Argument	Type	Description
docId	`Int!`	The document's unique identifier.
name	`String!`	The document's new name.

Duplicate doc

Creates an exact copy of an existing monday.com document (including all its content and structure). Returns a JSON object containing the new document's ID.

mutation {
  duplicate_doc(
    docId: 12345, 
    duplicateType: duplicate_doc_with_content_and_updates
	)
}

Arguments

Argument	Type	Description	Enum Values
docId	`Int!`	The document's unique identifier.
duplicateType	`DuplicateType`	The document's duplication types.	`duplicate_doc_with_content` (only the document content) `duplicate_doc_with_content_and_updates` (both the content and associated updates)

Delete doc

Deletes an existing document. Returns a JSON object confirming whether the deletion was successful and the ID of the deleted document.

mutation {
  delete_doc (
    docId: 12345
	)
}

Arguments

Argument	Type	Description
docId	`ID!`	The document's unique identifier.

Version History

🚧
Only available in API versions 2026-04 and later

Get doc version history

Returns a list of restoring points (snapshots) for a document, grouped in 5-minute intervals. Each restoring point includes timestamps and user IDs of who made changes.

Required scope: docs:read

query {
  doc_version_history(
    doc_id: "1234567890"
    since: "2025-01-01T00:00:00Z"
  ) {
    doc_id
    restoring_points {
      date
      user_ids
      type
    }
  }
}

Arguments

Argument	Type	Description
doc_id	`ID!`	The document's unique identifier (object ID from the URL).
since	`String`	Optional ISO 8601 lower bound for filtering restoring points.
until	`String`	Optional ISO 8601 upper bound for filtering restoring points.

Fields (`DocVersionHistory`)

Field	Type	Description
doc_id	`ID`	The document's unique identifier.
restoring_points	`[DocRestoringPoint]`	A list of version snapshots for the document.

Fields (`DocRestoringPoint`)

Field	Type	Description
date	`String`	The ISO 8601 timestamp of the restoring point.
user_ids	`[String]`	The unique identifiers of users who made changes in this snapshot interval.
type	`String`	The type of restoring point. Returns `"publish"` for publish events, otherwise `null`.

Get doc version diff

Returns the blocks that were added, deleted, or changed between two restoring points. Only blocks with changes are included.

Required scope: docs:read

query {
  doc_version_diff(
    doc_id: "1234567890"
    date: "2026-01-08T10:24:02.469Z"
    prev_date: "2025-01-01T00:00:00Z"
  ) {
    doc_id
    date
    prev_date
    blocks {
      id
      type
      content
      summary
      parent_block_id
      changes {
        added
        deleted
        changed
      }
    }
  }
}

Arguments

Argument	Type	Description
doc_id	`ID!`	The document's unique identifier.
date	`String!`	The newer restoring point timestamp (ISO 8601).
prev_date	`String!`	The older restoring point timestamp (ISO 8601).

Fields (`DocVersionDiff`)

Field	Type	Description
doc_id	`ID`	The document's unique identifier.
date	`String`	The newer restoring point timestamp.
prev_date	`String`	The older restoring point timestamp.
blocks	`[DiffBlock]`	The blocks that changed between the two versions.

Fields (`DiffBlock`)

Field	Type	Description
id	`String`	The block's unique identifier.
type	`String`	The block type identifier.
content	`String`	The block's content (may include base64-encoded data).
summary	`String`	A human-readable summary of the change.
parent_block_id	`String`	The parent block's unique identifier, if nested.
changes	`BlockChanges`	An object describing what changed for this block.

Fields (`BlockChanges`)

Field	Type	Description
added	`Boolean`	Whether the block was added.
deleted	`Boolean`	Whether the block was deleted.
changed	`Boolean`	Whether the block content was changed.