monday.com boards are where users input all of their data. As such, it is one of the core components of the platform, and one of the main objects you will need to be familiar with.

A board’s structure is composed of rows (called items), groups of rows (called groups), and columns. The data of the board is stored in the items on the board as well as in the updates sections of each item. Each board has one or more owners and subscribers.

Additionally, there are three different board types (main, shareable, and private) and each board can have different sets of permissions.

Boards queries

Required scope: boards:read

You can use boards at the root of your query, or you can nest them within another query to return something. Querying boards can return one or a collection of boards.

query {
  boards (ids: 12345678) {
    name
    state
    board_folder_id
    items (limit:100) {
      id
      name
      column_values {
        text
      }
    }
  }
}
let query = 'query { boards (ids: 12345678) { name state board_folder_id 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

The following board arguments can reduce the number of boards returned.

ArgumentDescription
limit IntThe number of boards returned. The default is 25.
page IntThe page number returned, should you implement pagination. Starts at 1.
ids [Int]A list of the unique board identifier(s).
board_kind BoardKindThe board's kind: public, private, or share.
state StateThe state of the board: all, active, archived, or deleted. The default is active.
order_by BoardsOrderByThe order in which to retrieve your boards: created_at or used_at.
workspace_ids [Int]A list of workspace ids that the boards are contained in.
newest_first Boolean (DEPRECATED)Lists the most recently created boards at the top.

Fields

Fields are used to return specific properties in an object. The following fields will determine what information is returned from your boards query. Some fields will have their own arguments.

FieldField descriptionSupported arguments
activity_logs [ActivityLogType]A list of the activity log events for the queried board(s).limit Int
page Int
user_ids [Int]
column_ids String
group_ids String
item_ids Int
from ISO8601DateTime
to ISO8601DateTime
board_folder_id IntThe unique identifier of the folder that contains the board(s).
board_kind BoardKind!The board's kind: public, private, or share.
columns [Column]A list of the board's visible columns.ids [String]
name StringThe board's name.
description StringThe board's description.
groups [Group]A list of the board's visible groups.ids [String]
id ID!The unique identifier of the board.
items [Item]A list of the item(s) on the board.ids [Int]
limit Int
page Int
newest_first Boolean
items_count IntThe number of items on the board.
name String!The name of the board.
owner User! (DEPRECATED)The user who created the board.
owners [User]!The owners of the board.
permissions String!The permissions on the board: everyone, collaborators, assignee, or owners.
pos String (DEPRECATED)The position of the board.
state State!The state of the board: all, active, archived, or deleted.
subscribers [User]!A list of the subscribers on the board.
tags [Tag]A list of the specific tags on the board.
top_group Group!The group at the top of the board.
type BoardObjectTypeThe type of the board: board, sub items board, or document.
updated_at ISO8601DateTimeThe last time the board was updated.
updates [Update]A list of the updates on the board.limit Int
page Int
views [BoardView]A list of the board views on the board.ids [Int]
type String
workspace WorkspaceThe workspace that contains the board (null for Main workspace).
workspace_id IntThe unique identifier for the board's workspace (null for Main workspace).
creator User!The creator of the board.
communication JSONGets the board's communication value - typically a meeting ID.
item_terminology String!The nickname for items on the board. Can be a predefined or custom value.

Boards mutations

Required scope: boards:write

Create a board

🚧

Mutation-specific rate limit

The create_board 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.

This method allows you to create a new board. After the mutation runs you can query back all the board data as shown in the querying boards section above.

To see the template ID's for your personal templates, activate the "Developer Mode" feature in your monday.labs. You will then be able to see your template ID's in the template preview screen. For our built-in templates, the template ID will be the board ID of the board created from the template.

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)));

You can find the Postman request to create a board here.

Arguments for create a board

The following arguments define the new board's characteristics.

ArgumentDescription
board_name String!The name of the created board.
board_kind BoardKind!The created board's kind: public, private, or share.
folder_id IntThe board's folder ID.
workspace_id IntThe board's workspace ID.
template_id IntThe board's template ID.
board_owner_ids [Int]A list of the IDs of the users who will be board owners.
board_subscriber_ids [Int]A list of the IDs of the users who will subscribe to the board.
description StringThe board's description.
board_subscriber_teams_ids `[Int]A list of the IDs of the teams who will subscribe to the board.
template_id IntThe board's template ID.

📘

NOTE

When creating a private or shareable board, the user that creates the board via API will be added as the board's owner automatically. This will also be the case if the argument board_owner_ids is not used.

Archive a board

This method allows you to archive a board. After the mutation runs you can query back all the board data as shown in the querying boards section above.

mutation {
    archive_board (board_id: 123456789) {
        id
    }
}
let query = 'mutation { archive_board (board_id: 123456789) { 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 for archive a board

The following argument determines which board will be archived.

ArgumentDescription
board_id Int!The board's unique identifier.

Duplicate a board

🚧

Mutation-specific rate limit

The duplicate_board 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.

This method allows you to duplicate a board. After the mutation runs you can query back all the board data as shown in the querying boards section above.

This mutation duplicates a board with all of its items and groups to a specific workspace and/or folder of your choice.

This query will return data of the board created as well as whether the process is synchronous or asynchronous. Please note that an asynchronous duplication process may take some time to complete, therefore the initial returned data may be partial.

mutation {
    duplicate_board(board_id:123456789, duplicate_type: duplicate_board_with_structure) {
        board {
            id
        }
    }
}
let query = 'mutation { duplicate_board(board_id:123456789, 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 for duplicate a board

The following arguments define the type of board duplication.

ArgumentDescription
board_id Int!The board's unique identifier.
duplicate_type DuplicateBoardType!The duplication type: duplicate_board_with_structure, duplicate_board_with_pulses, or duplicate_board_with_pulses_and_updates.
board_name StringThe duplicated board's name. If omitted, it will be automatically generated.
workspace_id IntThe destination workspace. If omitted, it will default to the original board's workspace.
folder_id IntThe 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.
keep_subscribers BooleanAbility to duplicate the subscribers to the new board. Defaults to false.

Update a board

This method allows you to update a board.

mutation {
  update_board(board_id: 123456789, board_attribute: description, new_value: "This is my new description")
}
let query = 'mutation { update_board(board_id: 123456789, 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 for update board

The following arguments determine which board to update and specify the new value.

ArgumentDescription
board_id Int!The board's unique identifier.
board_attribute `BoardAttributes!The board's attribute to update: name, description, or communication.
new_value String!The new attribute value.

Delete a board

This method allows you to delete a board.

mutation {
    delete_board (board_id: 123456789) {
        id
    }
}
let query = 'mutation { delete_board (board_id: 123456789) { 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 for delete a board

The following argument determines which board will be deleted.

ArgumentDescription
board_id Int!The board's unique identifier.

Add teams to a board

This method allows you to add a teams to a board.

mutation {
  add_teams_to_board (board_id:123456789, team_ids: [12345,54321]) {
    id
    name
  }
}
let query = 'mutation { add_teams_to_board (board_id: 123456789, team_ids: [12345,54321]) { 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 for add teams to a board

The following arguments define the teams to add to the board.

ArgumentDescription
board_id Int!The board's unique identifier.
team_ids [Int]!Team IDs to subscribe to the board.

Add users to a board

This method allows you to add users to a board.

You can define if the users will be added as regular subscribers or as owners of the board.

mutation {
    add_users_to_board (board_id: 123456789, user_ids: [123456, 234567, 345678], kind: owner) {
        id
    }
}

Arguments for add users to a board

The following arguments define the users added to the board.

ArgumentDescription
board_id Int!The board's unique identifier.
user_ids [Int]!User IDs to subscribe to the board.
kind BoardSubscriberKindThe subscriber's kind: subscriber or owner.

Add subscribers to a board (DEPRECATED)

This method allows you to add subscribers to a board. After the mutation runs you can query back all the board data as shown in the querying boards section above.

You can define if the users will be added as regular subscribers or as owners of the board.

mutation {
    add_subscribers_to_board (board_id: 123456789, user_ids: [123456, 234567, 345678], kind: owner) {
        id
    }
}
let query = 'mutation { add_subscribers_to_board (board_id: 123456789, user_ids: [123456, 234567, 345678], 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 for add subscribers to a board

The following arguments define the subscribers added to the board.

ArgumentDescription
board_id Int!The board's unique identifier.
user_ids [Int]!User IDs to subscribe to the board.
kind BoardSubscriberKindThe subscriber's kind: subscriber or owner.

Delete subscribers from a board

This method allows you to delete subscribers from a board. After the mutation runs you can query back all the board data as shown in the querying boards section above.

mutation {
    delete_subscribers_from_board(board_id: 123456789, user_ids: [123456, 234567, 345678]) {
        id
    }
}
let query = 'mutation { delete_subscribers_from_board(board_id: 123456789, user_ids: [123456, 234567, 345678]) { 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 for delete subscribers from a board

The following arguments define the subscribers removed from the board.

ArgumentDescription
board_id Int!The board's unique identifier.
user_ids [Int]!User IDs to unsubscribe from the board.

📘

Have questions?

Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.

Don’t forget to search before opening a new topic!