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 trueif 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. | descriptiontitle | 
| 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. | 
