Learn how to read and create monday docs using the platform API
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.
Queries
Required scope: docs:read
- Returns an array containing metadata about a collection of docs
- Can only be queried directly at the root
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.
Argument | Description | Enum Values |
---|---|---|
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 Int | The 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 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
You can use the following field(s) to specify what information your docs
query will return.
Field | 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. | |
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. | |
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
Create a doc
Required scope: docs:write
The create_doc
mutation allows you to create a new doc in a document column or workspace. 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
Argument | Description | Supported fields |
---|---|---|
location CreateDocInput! | The new document's location. | board CreateDocBoardInput workspace CreateDocWorkspaceInput |
Create a doc column
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.
Argument | Description |
---|---|
after_column_id ID | The unique identifier of the column after which the new column will be created. |
board_id ID! | The unique identifier of the board where the new column should be created. |
column_type ColumnType! | The type of column to create. |
defaults JSON | The new column's defaults. |
description String | The new column's description. |
id String | The column's user-specified unique identifier. 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. |
Add content to doc from markdown
Required scope: docs:write
The add_content_to_doc_from_markdown
mutation adds markdown content to an existing monday doc. The markdown will be parsed and converted into the corresponding block types. It returns the DocBlocksFromMarkdownResult
type which allows you to specify what fields to query back when you run it.
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
You can use the following arguments to specify what markdown content to convert and where to add it.
Argument | 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
Required scope: docs:write
The import_doc_from_html
mutation imports HTML content into a new monday doc. The HTML will be parsed and converted into the corresponding block types (currently only supports style/format text blocks). It returns the ImportDocFromHtmlResult
type which allows you to specify what fields to query back when you run it.
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
You can use the following arguments to specify what HTML content to convert.
Argument | 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
Required scope: docs:write
The update_doc_name
mutation allows you to update an existing document's name/title via the API. The response is a JSON object containing the updated name.
mutation {
update_doc_name(
docId: 12345,
name: "The new document name."
)
}
let query = 'mutation { update_doc_name (docId: 12345, name: "The new document name.")}';
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 specify the updated document's name.
Argument | Description |
---|---|
docId Int! | The document's unique identifier. |
name String! | The document's new name. |
Duplicate doc
Required scope: docs:write
The duplicate_doc
mutation allows you to create an exact copy of an existing monday.com document (including all its content and structure) via the API. The response is a JSON object containing the new document's ID.
mutation {
duplicate_doc(
docId: 12345,
duplicateType: duplicate_doc_with_content_and_updates
)
}
let query = 'mutation { duplicate_doc (docId: 12345, duplicateType: duplicate_doc_with_content_and_updates)}';
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 which document to duplicate.
Argument | 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
Required scope: docs:write
The delete_doc
mutation allows you to delete an existing document via the API. The response is a JSON object that confirms whether the deletion was successful and returns the deleted document's unique identifier.
mutation {
delete_doc (
docId: 12345
)
}
let query = 'mutation { delete_doc (docId: 12345)}';
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 which document to delete.
Argument | Description |
---|---|
docId ID! | The document's unique identifier. |