Learn how to read, create, update, and delete monday docs using the platform API
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_atused_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 publicshare |
| 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
}Get board view docs
Only available in API versions
2027-01and later
- Required scope:
docs:read - Returns an array containing the docs that are rendered as views of a board
- Can only be queried directly at the root; can't be nested within another query
query {
board_view_docs(
board_id: 1234567890
view_id: 9876543210
) {
id
object_id
name
}
}Arguments
| Argument | Type | Description |
|---|---|---|
| board_id | ID! | The unique identifier of the board that holds the doc views. |
| view_id | ID | The unique identifier of a single doc board view. When omitted, every doc view of the board is returned. |
Fields
The query returns Document objects, with the same fields as the docs query.
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. | privatepublicshare |
| 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-04and 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)
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)
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)
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)
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)
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. |
