monday.com dashboards compile data from one or more boards into a centralized high-level overview. They're made up of apps and widgets that visually display key metrics like project progress, budgets, workloads, and much more!

Mutations

The API allows you to create and update dashboards and widgets via the API using the following mutations.

Create dashboard

The create_dashboard mutation creates a new dashboard via the API. It returns the Dashboard type which allows you to specify which fields to return in the mutation response.

mutation {
  create_dashboard(
    board_ids: ["1234567890", "9876543210"]
    board_folder_id: 543210
    kind: PRIVATE
    name: "Team Performance"
    workspace_id: -1
  ) {
    id
    name
    kind
    workspace_id
  }
}

{
  "data": {
    "create_dashboard": {
      "id": "12345",
      "name": "Team Performance",
      "kind": "PRIVATE",
      "workspace_id": -1
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

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

Argument	Description	Enum Values
board_ids `[ID!]!`	The unique identifier of the board(s) to create dashboards for.
board_folder_id `ID`	The unique identifier of the folder to create the dashboard in.
kind `DashboardKind`	The dashboard's visibility. The default is `PRIVATE`.	`PRIVATE` `PUBLIC`
name `String!`	The dashboard's name. Up to 255 characters.
workspace_id `ID!`	The unique identifier of the workspace to create the dashboard in.

Create widget

The create_widget mutation creates a new widget via the API. It returns the WidgetModel type which allows you to specify which fields to return in the mutation response.

mutation CreateNumberWidget($settings: JSON!) {
  create_widget(
    parent: {
      kind: BOARD_VIEW
      id: 54321
    }
    kind: NUMBER
    name: "High Cost Sum (>$1000)"
    settings: $settings
    filter: {
      operator: and
      rules: [
        {
          column_id: "cost"
          operator: greater_than
          compare_value: [1000]
        }
      ]
    }
  ) {
    id
    name
    kind
  }
}

// Pass these variables with the sample mutation

{
  "settings": {
    "counter_data": {
      "calculation_type": "columns",
      "column_ids_per_board": {
        "1234567890": ["cost"]
      },
      "counter_type": "sum",
      "counter_unit": {
        "symbol": "$",
        "direction": "left"
      }
    },
    "prefix": "Total",
    "suffix": "in high-cost flights",
    "number_format": "currency"
  }
}

{
  "data": {
    "create_widget": {
      "id": 123456789,
      "name": "High Cost Sum (>$1000)",
      "kind": "NUMBER"
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

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

Argument	Description	Supported Fields
filter `ItemsQueryGroup`	The optional filter to apply to the widget. Only works with board views.	groups `[ItemsQueryGroup!]` operator `ItemsQueryOperator` rules `[ItemsQueryRule!]`
kind `ExternalWidget!`	The type of widget to create.
name `String!`	The widget's name that's displayed in the UI.
parent `WidgetParentInput!`	The widget's parent container.	id `Int!` kind `WidgetParentKind!`
settings `JSON!`	The widget's type-specific settings. Query `all_widgets_schema` to see available properties.

Update dashboard

The update_dashboard mutation updates a dashboard via the API. It returns the Dashboard type which allows you to specify which fields to return in the mutation response.

mutation {
  update_dashboard(
    id: 12345
		board_folder_id: 9876543210
    kind: PUBLIC
    name: "Team Performance Q4"
    workspace_id: -1
  ) {
		id
    name
    kind
    workspace_id
  }
}

{
  "data": {
    "update_dashboard": {
      "id": "12345",
      "name": "Team Performance Q4",
      "kind": "PUBLIC",
      "workspace_id": -1
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

You can use the following arguments to define the updated dashboard's characteristics.

Argument	Description	Enum Values
board_folder_id `ID`	The unique identifier of the folder to move the dashboard to.
id `ID!`	The unique identifier of the dashboard to update.
kind `DashboardKind`	The dashboard's updated kind.	`PRIVATE` `PUBLIC`
name `String`	The dashboard's updated name.
workspace_id `ID`	The unique identifier of the workspace to update the dashboard in.

Update overview hierarchy

The udpate_overview_hierarchy mutation updates a dashboard's position or location via the API. It returns the UpdateOverviewHierarchy type which allows you to specify which fields to return in the mutation response.

mutation {
  update_overview_hierarchy(
    overview_id: 12345
    attributes: {
      workspace_id: -1
      position: {
        is_after: true
        object_id: "9876543210"
        object_type: Board
      }
    }
  ) {
    success
    message
    overview {
      workspace_id
      name
      state
      creator {
        id
      }
    }
  }
}

{
  "data": {
    "update_overview_hierarchy": {
      "success": true,
      "message": "Overview position updated successfully",
      "overview": {
        "workspace_id": "-1",
        "name": "New Dashboard",
				"state": "1",
        "creator": {
          "id": "1234567890"
        }
      }
    }
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

You can use the following arguments to define the updated dashboard's characteristics.

Argument	Description	Supported Fields
attributes `UpdateOverviewHierarchyAttributes`	The dashboard's updated position and location attributes.	account_product_id `ID` folder_id `ID` position `DynamicPosition` workspace_id `ID`
overview_id `ID!`	The dashboard's unique identifier.

Delete dashboard

The delete_dashboard mutation deletes a dashboard via the API. It returns a Boolean indicating whether the deletion was successful.

mutation {
  delete_dashboard(id: 12345)
}

{
  "data": {
    "delete_dashboard": true
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

You can use the following argument to define which dashboard to delete.

Argument	Description
id `ID!`	The unique identifier of the dashboard to delete.

Delete widget

The delete_widget mutation deletes a widget via the API. It returns a Boolean indicating whether the deletion was successful.

mutation {
  delete_widget(id: 12345)
}

{
  "data": {
    "delete_widget": true
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

You can use the following argument to define which widget to delete.

Argument	Description
id `ID!`	The unique identifier of the widget to delete.