Learn how to create, read, update, and delete columns on monday boards using the platform API
monday.com boards are formatted as a table with columns and rows of items. Each column has specific functionality and only stores relevant data. For example, a numbers column will store numerical values, a text column will store text values, and a time tracking column will store only time-based data based on log events.
Queries
You can use the columns query to retrieve column data via the API.
- Required scope:
boards:read - Returns an array containing metadata about one or a collection of columns
- Can only be nested within another query (e.g.,
boards); can't be queried directly at the root
query { boards(ids: [1234567890]) { columns { id title } } }import { ApiClient } from "@mondaydotcomorg/api"; const mondayApiClient = new ApiClient({ token: myToken }); const query = `query ($board: [ID!]) {boards (ids: $board) { columns { id title }}}` const variables = { board: 1234567 } const response = await mondayApiClient.request(query, variables);Arguments
You can use the following arguments to reduce the number of results returned in your columns query.
| Argument | Description |
|---|---|
ids [String] | The specific columns to return. Please use quotation marks when passing this ID as a string. |
types [ColumnType!] | The specific type of columns to return. |
Fields
You can use the following fields to specify what information your columns query will return.
| Field | Field Description |
|---|---|
archived Boolean! | Returns true if the column is archived. |
capabilities ColumnCapabilities! | Calculates and retrieves the column's rollup value. |
description String | The column's description. |
id ID! | The column's unique identifier. |
revision String! | The column's current revision. Used for optimistic concurrency control. |
settings JSON | The column's dynamic JSON settings. For multi-level boards, use this field to retrieve labels and color mappings for status rollup columns. |
title String! | The column's title. |
type ColumnType! | The column's type. |
width Int | The column's width. |
Mutations
The API allows you to create, update, and delete columns using the following mutations. These operations let you programmatically control a column's full lifecycle.
Create column
Required scope: boards:write
The create_column mutation creates a new column on a board via the API. You can specify which fields to return in the mutation response.
mutation { create_column( board_id: 1234567890 title:"Work Status" description: "This is my work status column" column_type:status ) { id title description } }import { ApiClient } from "@mondaydotcomorg/api"; const mondayApiClient = new ApiClient({ token: myToken }); const query = `mutation ($board: ID!, $title: String!, $desc: String!) { create_column(board_id: $board, title: $title, description: $desc, column_type:status){ id title description}}` const variables = { board: 1234567, title: "Work status", desc: "Current status of the task" } const response = await mondayApiClient.request(query, variables);Arguments
You can use the following arguments to define the new column's characteristics.
Argument | Description | Supported Fields |
|---|---|---|
after_column_id | The unique identifier of the column after which the new column will be created. | |
board_id | The unique identifier of the board where the new column should be created. | |
capabilities | The new column’s capabilities configuration. If omitted, defaults apply: on multi-level boards, numeric, date, timeline, and status columns are created with the calculated capability enabled; in all other cases, no capabilities are applied. To override this default on multi-level boards, pass an empty argument to create the column without capabilities. Only available in API versions |
|
column_type | The type of column to create. This determines which properties are valid in the | |
defaults | The new column’s defaults. Accepts a JSON object or string. Validated against the column-type schema; query | |
description | The new column’s description. | |
id | The column’s user-specified unique identifier. If not provided, a new ID will be auto-generated. If provided, it must meet the following requirements:
| |
title | The new column’s title. |
Create dropdown column
Required scope: boards:write
The create_dropdown_column mutation creates a new dropdown column with strongly typed settings via the API. You can specify which fields to return in the mutation response.
mutation { create_dropdown_column( board_id: 1234567890, id: "project_category", title: "Project Category", defaults: { label_limit_count: 1, limit_select: true, labels: [ {label: "HR"}, {label: "R&D"}, {label: "IT"} ] }, description: "The project's category." ) { description id title } }Arguments
You can use the following arguments to define the new dropdown column's characteristics.
Argument | Description | Supported Fields |
|---|---|---|
after_column_id | The unique identifier of the column after which the new dropdown column will be created. | |
board_id | The unique identifier of the board where the new dropdown column should be created. | |
defaults | The new dropdown column’s settings. |
|
description | The new dropdown column’s description. | |
id | The dropdown column’s user-specified unique identifier. If not provided, a new ID will be auto-generated. If provided, it must meet the following requirements:
| |
title | The new dropdown column’s title. |
Create status column
Required scope: boards:write
The create_status_column mutation creates a new status column with strongly typed settings via the API. You can specify which fields to return in the mutation response.
mutation { create_status_column( board_id: 1234567890, id: "project_status", title: "Project Status", defaults: { labels: [ { color: working_orange, label: "On Hold", index: 2}, { color: done_green, label: "Done", index: 1}, { color: sky, label: "Working On It", index: 3} ] }, description: "The project's status." ) { description id title } }Arguments
You can use the following arguments to define the new status column's characteristics.
Argument | Description | Supported Fields |
|---|---|---|
after_column_id | The unique identifier of the column after which the new status column will be created. | |
board_id | The unique identifier of the board where the new status column should be created. | |
capabilities | The new status column’s capabilities configuration. If omitted, defaults apply: on multi-level boards, numeric, date, timeline, and status columns are created with the calculated capability enabled. To override this default on multi-level boards, pass an empty argument to create the column without capabilities. |
|
defaults | The new status column’s settings. |
|
description | The new status column’s description. | |
id | The status column’s user-specified unique identifier. If not provided, a new ID will be auto-generated. If provided, it must meet the following requirements:
| |
title | The new status column’s title. |
Change column value
Required scope: boards:write
The change_column_value mutation changes a column with a JSON value via the API. You can specify which fields to return in the mutation response.
For multi-level boards, rollup column changes are blocked if the item has at least one subitem.
mutation { change_column_value( board_id: 1234567890 item_id: 9876543210 column_id: "email9", value: "{\"text\":\"[email protected]\",\"email\":\"[email protected]\"}" ) { id } }import { ApiClient } from "@mondaydotcomorg/api"; const mondayApiClient = new ApiClient({ token: myToken }); const query = `mutation ($board_id: ID!, $item_id: ID!, $column_id: String!, $column_value: JSON!) { change_column_value (board_id: $board_id, item_id: $item_id, column_id: $column_id, value: $column_value) {id}}`; const variables = { board_id: 9571351437, item_id: 9571351485, column_id: "email_mksr9hcd", // email column column_value: JSON.stringify({ text: "Dabba Baz", email: "[email protected]", }) }; const response = await mondayApiClient.request(query, variables);Arguments
You can use the following arguments to define which column to change and its new value.
| Argument | Description |
|---|---|
board_id ID! | The board's unique identifier. |
column_id String! | The column's unique identifier. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they are missing. Requires permission to change the board structure. |
item_id ID | The item's unique identifier. |
value JSON! | The new value of the column in JSON format. See Column Types Reference for each column type and its format. |
Change simple column value
Required scope: boards:write
The change_simple_column_value mutation changes a column with a string value via the API. You can specify which fields to return in the mutation response.
mutation { change_simple_column_value( board_id: 1234567890 item_id: 9876543210 column_id: "status" value: "Working on it" ) { id } }import { ApiClient } from "@mondaydotcomorg/api"; const mondayApiClient = new ApiClient({ token: myToken }); const query = `mutation ($board_id: ID!, $item_id: ID!, $column_id: String!, $column_value: String!) { change_simple_column_value (board_id: $board_id, item_id: $item_id, column_id: $column_id, value: $column_value) {id}}`; const variables = { board_id: 9571351437, item_id: 9571351485, column_id: "email_mksr9hcd", // Each column type has a different value structure // Check "Column types reference" section for different values column_value: "[email protected] [email protected]" }; const response = await mondayApiClient.request(query, variables);Arguments
You can use the following arguments to define which column to change and its new value.
| Argument | Description |
|---|---|
board_id ID! | The board's unique identifier. |
column_id String! | The column's unique identifier. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they are missing. Requires permission to change the board structure. |
item_id ID | The item's unique identifier. |
value String | The new simple value of the column. |
Change multiple column values
Required scope: boards:write
The change_multiple_column_values mutation changes multiple columns with a JSON value via the API. You can specify which fields to return in the mutation response.
Each column has a certain type, and different column types expect a different set of parameters to update their values. When sending data in the column_values argument, use a string and build it using this sample form: {\"text\": \"New text\", \"status\": {\"label\": \"Done\"}}
Pro tipYou can also use simple (
String) values in this mutation along with regular (JSON) values, or just simple values. Here's an example of setting a status with a simple value:{\"text\": \"New text\", \"status\": \"Done\"}
mutation { change_multiple_column_values( item_id: 1234567890 board_id: 9876543210 column_values: "{\"status\":{\"index\":1},\"date4\":{\"date\":\"2021-01-01\"},\"person\":{\"personsAndTeams\":[{\"id\":9603417,\"kind\":\"person\"}]}}" ) { id } }import { ApiClient } from "@mondaydotcomorg/api"; const mondayApiClient = new ApiClient({ token: myToken }); const query = `mutation ($board_id: ID!, $item_id: ID!, $column_value: JSON!) {change_multiple_column_values (item_id: $item_id, board_id: $board_id, column_values: $column_value) {id}}`; const variables = { board_id: 9571351437, item_id: 9571351485, column_id: "email_mksr9hcd", // Each column type has a different value structure // Check "Column types reference" section for different values column_value: JSON.stringify({ color_mksreyj6: "In progress", date_mksr13fh: "2025-08-27", multiple_person_mksr4ka7: "[email protected]", }) }; const response = await mondayApiClient.request(query, variables);Arguments
You can use the following arguments to define which columns to change and their new values.
| Argument | Definition |
|---|---|
board_id ID! | The unique identifier of the board that contains the columns to change. |
column_values JSON! | The updated column values. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they are missing. Requires permission to change the board structure. |
item_id ID | The unique identifier of the item to change. |
Change column title
Required scope: boards:write
The change_column_title mutation changes the title of an existing column via the API. You can specify which fields to return in the mutation response.
mutation { change_column_title( board_id: 1234567890 column_id: "status" title: "new_status" ) { id } }import { ApiClient } from "@mondaydotcomorg/api"; const mondayApiClient = new ApiClient({ token: myToken }); const query = `mutation ($board_id: ID!, $column_id: String!, $title: String!) {change_column_title (board_id: $board_id, column_id: $column_id, title: $title) {id}}`; const variables = { board_id: 9571351437, column_id: "status", title: "New title" }; const response = await mondayApiClient.request(query, variables);Arguments
You can use the following arguments to define which column's title to change and its new value.
| Argument | Definition |
|---|---|
board_id ID! | The unique identifier of the board that contains the column to change. |
column_id String! | The column's unique identifier. |
title String! | The column's new title. |
Update column
Required scope: boards:write
The update_column mutation updates a column via the API. The input is validated against the column type's schema before applying changes. You can specify which fields to return in the mutation response.
mutation { update_column( board_id: 1234567890 id: "status" title: "Work Status" revision: "a73d19e54f82c0b7d1e348f5ac92b6de" description: "This is my updated work status column" column_type:status ) { id title description } }{ "data": { "update_column": { "id": "status", "title": "Work Status", "description": "This is my work status column" } }, "extensions": { "request_id": "YOUR_REQUEST_ID" } }Arguments
You can use the following arguments to define which column to update.
Argument | Description | Supported Fields |
|---|---|---|
board_id | The unique identifier of the board where the updated column is located. | |
capabilities | The new column’s capabilities configuration. If omitted, defaults apply: on multi-level boards, numeric, date, timeline, and status columns are created with the calculated capability enabled; in all other cases, no capabilities are applied. To override this default on multi-level boards, pass an empty argument to create the column without capabilities. Only available in API versions |
|
column_type | The updated column’s type. This determines which properties are valid in the | |
description | The updated column’s description. | |
id | The updated column’s user-specified unique identifier. If not provided, a new ID will be auto-generated. If provided, it must meet the following requirements:
| |
revision | The column’s current revision. Used for optimistic concurrency control. | |
settings | The column’s type-specific settings in JSON. Query | |
title | The updated column’s title. |
Update dropdown column
Required scope: boards:write
The update_dropdown_column mutation updates a dropdown column with strongly typed settings via the API. You can specify which fields to return in the mutation response.
mutation { update_dropdown_column( board_id: 1234567890 id: "project_category" title: "Updated Project Category" revision: "09606bfd3334eb88084f310fb4aef0cb" description: "The project's updated category." ) { description id title } }Arguments
You can use the following arguments to define the updated dropdown column characteristics.
Argument | Description | Supported Fields |
|---|---|---|
board_id | The unique identifier of the board that contains the dropdown column. | |
description | The updated dropdown column’s description. | |
id | The unique identifier of the column to update. | |
revision | The column’s current revision. Used for optimistic concurrency control. | |
settings | The dropdown column’s updated configuration settings. | label_limit_count |
title | The updated dropdown column’s title. |
Update status column
Required scope: boards:write
The update_status_column mutation updates a status column with strongly typed settings via the API. You can specify which fields to return in the mutation response.
mutation { update_status_column( board_id: 1234567890 id: "project_status" title: "Updated Project Status" revision: "09606bfd3334eb88084f310fb4aef0cb" settings: { labels: [ { color: peach, label: "On Hold", index: 1, is_deactivated: true}, { color: river, label: "Done", index: 2}, { color: grass_green, label: "Working On It", index: 3} ] } description: "The project's updated status." ) { description id } }Arguments
You can use the following arguments to define the updated status column characteristics.
Argument | Description | Supported Fields |
|---|---|---|
board_id | The unique identifier of the board that contains the status column. | |
capabilities | The status column's updated capabilities configuration. If omitted, defaults apply: on multi-level boards, numeric, date, timeline, and status columns are created with the calculated capability enabled. To override this default on multi-level boards, pass an empty argument to create the column without capabilities. | calculated |
description | The updated status column's description. | |
id | The unique identifier of the column to update. | |
revision | The column's current revision. Used for optimistic concurrency control. | |
settings | The status column's updated configuration settings. | label_limit_count |
title | The updated status column's title. |
Change column metadata
Required scope: boards:write
The change_column_metadata mutation updates the title or description of an existing column. You can specify which fields to return in the mutation response.
mutation { change_column_metadata( board_id: 1234567890 column_id: "date4" column_property: description value: "This is my awesome date column" ) { id title description } }import { ApiClient } from "@mondaydotcomorg/api"; const mondayApiClient = new ApiClient({ token: myToken }); const query = `mutation ($board_id: ID!, $column_id: String!, $desc: String!) {change_column_metadata (board_id: $board_id, column_id: $column_id, column_property: description, value: $desc) {id}}`; const variables = { board_id: 9571351437, column_id: "status", desc: "New title" }; const response = await mondayApiClient.request(query, variables);Arguments
You can use the following arguments to define which column to change and its new value.
| Argument | Definition | Enum Values |
|---|---|---|
board_id ID! | The unique identifier of the board that contains the column to change. | |
column_id String! | The column's unique identifier. | |
column_property ColumnProperty | The property you want to change. | description title |
value String | The new value of that property. |
Delete column
Required scope: boards:write
The delete_column mutation deletes a single column from a board via the API. You can specify which fields to return in the mutation response.
mutation { delete_column( board_id: 1234567890 column_id: "status" ) { id } }import { ApiClient } from "@mondaydotcomorg/api"; const mondayApiClient = new ApiClient({ token: myToken }); const query = `mutation ($board_id: ID!, $column_id: String!) { delete_column(board_id: $board_id, column_id: $column_id) { id }}`; const variables = { board_id: 9571351437, column_id: "status", }; const response = await mondayApiClient.request(query, variables);Arguments
You can use the following arguments to define which column to delete.
| Argument | Description |
|---|---|
board_id ID! | The unique identifier of the board that contains the column to delete. |
column_id String! | The column's unique identifier. |
