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.

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.

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.

*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.

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.

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.

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.

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.

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.

📘

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! 😎