Boards
monday.com boards are where users input all of their data, making them one of the core platform components. Items (rows), groups (groups of rows), and columns comprise the board's structure, and the board's data is stored in items and their respective updates sections. We support three types of boards that come with different sets of permissions: main, shareable, and private.
As a developer working with monday.com, it is important to familiarize yourself with the boards
API so you know how to access board data. This document will walk you through the available queries and mutations to read and modify the boards
object via the API.
Queries
Required scope: boards:read
Querying boards
will return metadata about one or a collection of boards. This method accepts various arguments and returns an array.
You can query boards
directly at the root or nest it within another query. Nesting boards
within a subitems
or items
query allows you to determine which board the item or subitem is on.
query {
boards (ids: 1234567890) {
name
state
id
permissions
}
}
let query = 'query { boards (ids: 1234567890) { name state id permissions }}';
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 reduce the number of results returned in your boards
query.
Argument | Description | Enum values |
---|---|---|
board_kind BoardKind | The type of board to return. | private public share |
ids [Int] | The specific board IDs to return. Please note that this argument's type is [ID!] in API versions 2023-10 and later. | |
limit Int | The number of boards to return. The default is 25. | |
newest_first Boolean (DEPRECATED) | Lists the most recently created boards at the top. Please note that this deprecated argument is removed in API version 2023-10 . | |
order_by BoardsOrderBy | The order in which to retrieve your boards. | created_at (desc.) used_at (desc.) |
page Int | The page number to return. Starts at 1. | |
state State | The state of board to return. The default is active. | active all archived deleted |
workspace_ids [Int] | The specific workspace IDs that contain the boards 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 boards
query will return. Please note that some fields will have their own arguments.
Field | Description | Supported arguments |
---|---|---|
activity_logs [ActivityLogType] | The activity log events for the queried board(s). | column_ids [String] from ISO8601DateTime group_ids [String] item_ids [Int] limit Int page Int to ISO8601DateTime user_ids [Int] |
board_folder_id Int | The unique identifier of the folder that contains the board(s). Returns null if the board is not in a folder. Please note that this field's type is ID in API versions 2023-10 and later. | |
board_kind BoardKind! | The type of board: public, private, or share. | |
columns [Column] | The board's visible columns. | ids [String] types [String] (Please note that this argument's type is [ColumnType!] in API version 2023-10 ) |
communication JSON | The board's communication value (typically a meeting ID). | |
creator User! | The board's creator. | |
description String | The board's description. | |
groups [Group] | The board's visible groups. | ids [String] |
id ID! | The board's unique identifier. | |
item_terminology String | The nickname for items on the board. Can be a predefined or custom value. | |
items [Item] | The board's item(s). Please note that this field is deprecated in API version 2023-10 . Use the items_page field instead. | exclude_nonactive Boolean ids [Int] limit Int newest_first Boolean page Int |
items_count Int | The number of items on the board. | |
items_page ItemsResponse! | The board's items. Please note that this field is only available in API version 2023-10 . | cursor String limit Int! query_params ItemsQuery |
name String! | The board's name. | |
owner User! (DEPRECATED) | The user who created the board. | |
owners [User]! | The board's owners. | |
permissions String! | The board's permissions: everyone, collaborators, assignee, or owners. | |
pos String (DEPRECATED) | The board's position. Please note that this deprecated field is removed in API version 2023-10 . | |
state State! | The board's state: all, active, archived, or deleted. | |
subscribers [User]! | The board's subscribers. | |
tags [Tag] | The specific tags on the board. | |
top_group Group! | The group at the top of the board. | |
type BoardObjectType | The board's object type: board, sub_items_board, document, or custom_object. | |
updated_at ISO8601DateTime | The last time the board was updated. | |
updates [Update] | The board's updates. | limit Int page Int |
views [BoardView] | The board's views. | ids [Int] type String |
workspace Workspace | The workspace that contains the board. Returns null for the Main workspace. | |
workspace_id Int | The unique identifier of the board's workspace. Returns null for the Main workspace. Please note that this field's type is ID in API versions 2023-10 and later. |
Mutations
Required scope: boards:write
Create a board
The create_board
mutation allows you to create a new board via the API. You can also specify what fields to query back from the new board when you run the mutation. Please note that the user that creates the board via the API will automatically be added as the board's owner when creating a private or shareable board or if the board_owners_ids
argument is missing.
Mutation-specific rate limit
This mutation has an additional rate limit of 40 mutations per minute. If you exceed this limit, you will receive 429 HTTP response code with a Call limit exceeded for CreateBoard error message.
Check out this mutation in action in our Postman library or follow along with these code samples!
mutation {
create_board (board_name: "my board", board_kind: public) {
id
}
}
let query = 'mutation { create_board (board_name: \"my board\", board_kind: public) { 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 board's characteristics.
Argument | Description |
---|---|
board_kind BoardKind! | The type of board to create: public, private, or share. |
board_name String! | The new board's name. |
board_owner_ids [Int] | A list of the IDs of the users who will be board owners. Please note that this argument's type is [ID!] in API versions 2023-10 and later. |
board_subscriber_ids [Int] | A list of the IDs of the users who will subscribe to the board. Please note that this argument's type is [ID!] in API versions 2023-10 and later. |
board_subscriber_teams_ids [Int] | A list of the IDs of the teams who will subscribe to the board. Please note that this argument's type is [ID!] in API versions 2023-10 and later. |
description String | The new board's description. |
folder_id Int | The board's folder ID. Please note that this argument's type is ID in API versions 2023-10 and later. |
template_id Int | The board's template ID.* Please note that this argument's type is ID in API versions 2023-10 and later. |
workspace_id Int | The board's workspace ID. Please note that this argument's type is ID in API versions 2023-10 and later. |
*You can see your personal template IDs in the template preview screen by activating Developer Mode in your monday.labs. For built-in templates, the template ID will be the board ID of the board created from the template.
Duplicate a board
The duplicate_board
mutation allows you to duplicate a board with all of its items and groups to a specific workspace or folder of your choice via the API.
Mutation-specific rate limit
This mutation has an additional rate limit of 40 mutations per minute. If you exceed this limit, you will receive 429 HTTP response code with a "Call limit exceeded for DuplicateBoard" error message.
You can also specify what fields to query back from the new board when you run the mutation. The query will also indicate whether the process is synchronous or asynchronous. Since an asynchronous duplication process may take some time to complete, the query may initially return partial data.
mutation {
duplicate_board(board_id: 1234567890, duplicate_type: duplicate_board_with_structure) {
board {
id
}
}
}
let query = 'mutation { duplicate_board(board_id: 1234567890, duplicate_type: duplicate_board_with_structure) { board { 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 specify which board to duplicate and what properties to include.
Argument | Description |
---|---|
board_id Int! | The board's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later. |
board_name String | The duplicated board's name. If omitted, it will be automatically generated. |
duplicate_type DuplicateBoardType! | The duplication type: duplicate_board_with_structure, duplicate_board_with_pulses, or duplicate_board_with_pulses_and_updates. |
folder_id Int | The destination folder within the destination workspace. The folder_id is required if you are duplicating to another workspace, otherwise, it is optional. If omitted, it will default to the original board's folder. Please note that this argument's type is ID in API versions 2023-10 and later. |
keep_subscribers Boolean | Ability to duplicate the subscribers to the new board. Defaults to false. |
workspace_id Int | The destination workspace. If omitted, it will default to the original board's workspace. Please note that this argument's type is ID in API versions 2023-10 and later. |
Update a board
The update_board
mutation allows you to update a board via the API.
mutation {
update_board(board_id: 1234567890, board_attribute: description, new_value: "This is my new description") {
id
}
}
let query = 'mutation { update_board(board_id: 1234567890, board_attribute: description, new_value: "This is my new description")}';
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 which board to update and its new value.
Argument | Description |
---|---|
board_attribute BoardAttributes! | The board's attribute to update: name, description, or communication. |
board_id Int! | The board's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later. |
new_value String! | The new attribute value. |
Archive a board
The archive_board
mutation allows you to archive a board via the API. You can also specify what fields to query back from the archived board when you run the mutation.
mutation {
archive_board (board_id: 1234567890) {
id
}
}
let query = 'mutation { archive_board (board_id: 1234567890) { 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 specify which board to archive.
Argument | Description |
---|---|
board_id Int! | The board's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later. |
Delete a board
The delete_board
mutation allows you to delete a board via the API. You can also specify what fields to query back from the deleted board when you run the mutation.
mutation {
delete_board (board_id: 1234567890) {
id
}
}
let query = 'mutation { delete_board (board_id: 1234567890) { 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 specify which board to delete.
Argument | Description |
---|---|
board_id Int! | The board's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later. |
Delete subscribers from a board
The delete_subscribers_from_board
mutation allows you to delete subscribers from a board via the API. You can also specify what fields to query back from the subscribers you delete from the board when you run the mutation.
mutation {
delete_subscribers_from_board(board_id: 1234567890, user_ids: [12345678, 87654321, 01234567]) {
id
}
}
let query = 'mutation { delete_subscribers_from_board(board_id: 1234567890, user_ids: [12345678, 87654321, 01234567]) { 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 specify which subscribers to delete from the board.
Argument | Description |
---|---|
board_id Int! | The board's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later. |
user_ids [Int]! | The user IDs to unsubscribe from the board. Please note that this argument's type is [ID!]! in API versions 2023-10 and later. |
Add subscribers to a board (DEPRECATED)
The add_subscribers_to_board
mutation allows you to add subscribers to a board via the API. You can use the add_users_to_board
mutation instead.
mutation {
add_subscribers_to_board (board_id: 1234567890, user_ids: [12345678, 87654321, 01234567], kind: owner) {
id
}
}
let query = 'mutation { add_subscribers_to_board (board_id: 1234567890, user_ids: [12345678, 87654321, 01234567], kind: owner) { 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 specify which users to subscribe to the board.
Argument | Description |
---|---|
board_id Int! | The board's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later. |
kind BoardSubscriberKind | The subscriber's kind: subscriber or owner. |
user_ids [Int]! | The user IDs to subscribe to the board. |
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! 😎
Updated 19 days ago