monday.com boards are where users input all of their data, making them one of the core platform components. The board's structure consists of items(rows), groups (groups of rows), and columns, and the board's data is stored in items and their respective updates sections.

Queries

You can use the boards query to retrieve board data via the API.

Required scope:boards:read
Returns an array containing metadata about one or a collection of boards
Can be queried directly at the root or nested within another query (e.g., items)

query {
  boards(
    ids: [1234567890]
    hierarchy_type: [classic, multi_level]
  ) {
    name
    state
    permissions
    items_page {
      items {
        id
        name
      }
    }
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken});

const query = `query { boards (ids: [1234567890]) { name state permissions items_page { items { id name }}}}`
const response = await mondayApiClient.request(query);

Arguments

You can use the following arguments 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`
hierarchy_type `[BoardHierarchy!]`	The board hierarchy type to filter by. If omitted, only `classic` boards will be returned unless specific board IDs are provided.	`classic` `multi_level`
ids `[ID!]`	The specific board IDs to return.
limit `Int`	The number of boards to return. The default is 25.
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 the board to return. The default is `active`.	`active` `all` `archived` `deleted`
workspace_ids `[ID]`	The specific workspace IDs that contain the boards to return.

Fields

You can use the following fields to specify what information your boards query will return.

Field	Description	Enum Values
access_level `BoardAccessLevel!`	The user's board permission level.	`edit` `view`
activity_logs `[ActivityLogType]`	The activity log events for the queried board(s).
board_folder_id `ID`	The unique identifier of the folder that contains the board(s). Returns `null` if the board is not in a folder.
board_kind `BoardKind!`	The board's type.	`private` `public` `share`
columns `[Column]`	The board's visible columns.
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.
hierarchy_type `BoardHierarchy`	The board's hierarchy type.	`classic` `multi_level`
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_count `Int`	The number of items on the board.
items_page `ItemsResponse!`	The board's items. Can be used to retrieve all items on a board.
name `String!`	The board's name.
object_type_unique_key `String`	A unique identifier for the board's object type. May return `null` for boards without a specific object type classification.
owner `User!` (DEPRECATED)	The user who created the board.
owners `[User]!`	The board's owners.
permissions `String!`	The board's permissions.	`assignee` `collaborators` `everyone` `owners`
state `State!`	The board's state.	`active` `all` `archived` `deleted`
subscribers `[User]!`	The board's subscribers.
tags `[Tag]`	The board's tags.
team_owners `[Team!]`	The board's team owners.
team_subscribers `[Team!]`	The board's team subscribers. A value of `-1` indicates that the "everyone at account" team is subscribed to this board.
top_group `Group!`	The group at the top of the board.
type `BoardObjectType`	The board's object type.	`board` `custom_object` `document` `sub_items_board`
updated_at `ISO8601DateTime`	The last time the board was updated.
updates `[Update]`	The board's updates.
url `String!`	The board's URL.
views `[BoardView]`	The board's views.
workspace `Workspace`	The workspace that contains the board. Returns `null` for the Main workspace.
workspace_id `ID`	The unique identifier of the board's workspace. Returns `null` for the Main workspace.

Mutations

The API allows you to create, update, and delete boards using the following mutations. These operations let you programmatically control a board's full lifecycle.

Create board

Required scope:boards:write

The create_board mutation creates a new board via the API. You can specify which fields to return in the mutation response.

Keep in mind that the user who 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.

🚧
This mutation has an additional rate limit of 40 mutations per minute.

mutation {
  create_board(
    board_name: "my board"
    board_kind: public
    item_nickname: { preset_type: "item" }
  ) { 
    id 
  }
}

Arguments

You can use the following arguments to define the new board's characteristics.

Argument	Description	Enum Values	Supported Fields
board_kind `BoardKind!`	The type of board to create.	`private` `public` `share`
board_name `String!`	The new board's name.
board_owner_ids `[ID!]`	A list of the IDs of the users who will be board owners.
board_owner_team_ids `[ID!]`	A list of the IDs of the teams that will be board owners.
board_subscriber_ids `[ID!]`	A list of the IDs of the users who will subscribe to the board.
board_subscriber_teams_ids `[ID!]`	A list of the IDs of the teams that will subscribe to the board.
description `String`	The new board's description.
empty `Boolean`	Creates an empty board without any default items.
folder_id `ID`	The board's folder ID.
item_nickname `ItemNicknameInput`	The nickname configuration for items on the board. When provided, the configuration is applied to the new board's items.		plural `String` preset_type `String` singular `String`
template_id `ID`	The board's template ID.*
workspace_id `ID`	The board's workspace ID.

*You can see your personal template IDs in the template preview screen by activating Developer Mode in monday.labs. For built-in templates, the template ID will be the board ID of the board created from the template.

Set board permission

Required scope:boards:write

The set_board_permissionmutation sets or updates a board's default role/permissions via the API. It returns the SetBoardPermissionResponse type which allows you to specify which fields to return in the mutation response.

To use this mutation, you must:

Be a board owner
Be on an enterprise plan

mutation {
  set_board_permission(
    board_id: 1234567890
    basic_role_name: viewer
  ) {
    edit_permissions
    failed_actions
  }
}

Arguments

You can use the following arguments to define the board's default permissions.

Argument	Description	Enum values
basic_role_name `BoardBasicRoleName!`	The role's name.	`contributor` (can edit content) `editor` (can edit content and structure) `viewer` (read-only)
board_id `ID!`	The board's unique identifier.

Duplicate board

Required scope:boards:write

The duplicate_board mutation duplicates a board with all of its items and groups to a specific workspace or folder of your choice via the API. You can specify which fields to return in the mutation response.

This action indicates 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.

🚧
This mutation has an additional rate limit of 40 mutations per minute.

mutation {
  duplicate_board(
    board_id: 1234567890
    duplicate_type: duplicate_board_with_structure
  ) {
    board {
      id
    }
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `mutation ($board: ID!) { duplicate_board(board_id: $board, duplicate_type: duplicate_board_with_structure) { board { id }}}`
const variables = {
  board: 9571351437
}
const response = await mondayApiClient.request(query, variables);

Arguments

You can use the following arguments to specify which board to duplicate and what properties to include.

Argument	Description	Enum Values
board_id `ID!`	The board's unique identifier.
board_name `String`	The board's name. If omitted, it will be automatically generated.
duplicate_type `DuplicateBoardType!`	The duplication type.	`duplicate_board_with_pulses` (duplicate structure and items) `duplicate_board_with_pulses_and_updates` (duplicate structure, items, and updates) `duplicate_board_with_structure` (duplicate structure)
folder_id `ID`	The destination folder within the destination workspace. Required if you are duplicating to another workspace. If omitted, it will default to the original board's folder.
keep_subscribers `Boolean`	Whether to duplicate the subscribers to the new board. Defaults to false.
workspace_id `ID`	The destination workspace. If omitted, it will default to the original board's workspace.

Update board

Required scope:boards:write

The update_board mutation updates a board via the API. The response is a JSON object that confirms whether the update was successful and returns the updated board metadata.

mutation {
  update_board(
    board_id: 1234567890
    board_attribute: description
    new_value: "This is my new description"
  ) 
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `mutation ($desc: String!) { update_board (board_id: 1234567890, board_attribute: description, new_value: $desc)}`
const variables = {
  desc: "This is my new description"
}
const response = await mondayApiClient.request(query, variables);

Arguments

You can use the following arguments to specify which board to update and its new value.

Argument	Description	Enum values
board_attribute `BoardAttributes!`	The board's attribute to update.	`communication` `description` `name`
board_id `ID!`	The board's unique identifier.
new_value `String!`	The new attribute value.

Update board hierarchy

Required scope:boards:write

The update_board_hierarchymutation updates a board's position, workspace, or product via the API. It returns the UpdateBoardHierarchyResult type which allows you to specify which fields to return in the mutation response.

mutation {
  update_board_hierarchy(
    board_id: 1234567890,
    attributes: {
      account_product_id: 54321
      workspace_id: 12345
      folder_id: 9876543210
      position: {
        object_id: "15",
        object_type: Overview,
        is_after: true
      }
    }
  ) {
    success
  }
}

Arguments

You can use the following arguments to specify which board and attributes to update.

Argument	Description	Supported fields
attributes `UpdateBoardHierarchyAttributesInput!`	The board's attributes to update.	account_product_id `ID` folder_id `ID` position `DynamicPosition` workspace_id `ID`
board_id `ID!`	The board's unique identifier.

Archive board

Required scope:boards:write

The archive_board mutation archives a board via the API. You can specify which fields to return in the mutation response.

mutation {
  archive_board(
    board_id: 1234567890
  ) {
    id
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });
const query = `mutation ($board: ID!) { archive_board (board_id: $board) { id }}`
const variables = {
  board: 1234567
}
const response = await mondayApiClient.request(query, variables);

Arguments

You can use the following argument to specify which board to archive.

Argument	Description
board_id `ID!`	The board's unique identifier.

Delete board

Required scope:boards:write

The delete_board mutation deletes a board via the API. You can specify which fields to return in the mutation response.

mutation {
  delete_board(
    board_id: 1234567890
  ) {
    id
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `mutation ($board: ID!) { delete_board (board_id: $board) { id }}`
const variables = {
  board: 1234567
}
const response = await mondayApiClient.request(query, variables);

Arguments

You can use the following argument to specify which board to delete.

Argument	Description
board_id `ID!`	The board's unique identifier.