The text field for mirror, dependency, and connect board columns will return an empty result when querying the field directly through the column_values object in API version 2023-10. For example:

query {
  boards {
    items_page {
      items {
        column_values (ids: "mirror") {
          text
        }
      }
    }
  }
}

These queries create a significant load since those specific columns must resolve values in multiple boards. Instead, you can use the new display_value field to return the column's textual value.

query {
  boards {  
    items_page {  
      items {  
        column_values {  
          ...on MirrorValue {
            display_value
          }
          ...on DependencyValue {
            display_value
          }
          ...on BoardRelationValue {
            display_value
          }
        }  
      }  
    }  
  }  
}

We released API version 2023-10 on July 1st! It features many new and exciting updates, as well as a handful of breaking changes.

We put together this guide (complete with a detailed explanation for each change) to help make the transition to the new version easier. Check out all of the changes below, and make sure to click on each item's respective link to see the full details about each update!

After checking out the updates, we would love to hear from you! Your opinions and feedback are vital to building, maintaining, and improving our API. Feel free to submit your feedback using this form.

Here's what's new

Breaking changes

• Removed the deprecated items field on boards queries, replaced it with items_page

• New column values fields and typed column values

• Removed the deprecated items_by_column_values and items_by_multiple_column_values objects, replaced them with items_page_by_column_values

• The column_type field on the create_column mutation is now a required field

• Empty parentheses are no longer supported

• Quotation marks for strings are now required

• Removed the deprecated pos fields on boards and columns queries

• The type field on columns queries has changed from String! to ColumnType!

• Deprecated the newest_first argument on boards queries

• Many of the ID arguments and fields have changed from Int to ID type

• Text field returns empty results for mirror, dependency, and connect boards columns

Non-breaking changes

• New move_item_to_board mutation

• New linked_items field on items queries

• New edit_update and delete_update webhooks

• The value argument in the change_simple_column_value mutation is now nullable

• The complexity of the text field for mirror, link, and dependency columns increased

The deprecated items field on the boards object will be removed and replaced with items_page in API version 2023-10.

Why?

We recently announced our new data infrastructure, mondayDB, which allows for higher item limits on boards while simultaneously improving performance time. With mondayDB, the goal is essentially to retrieve significantly larger boards faster.

The evolution of our data infrastructure also requires improvements to our API and how we retrieve items from boards. The items field enabled developers to query ALL items on a board, and it is no longer scalable with increased board sizes (due to mondayDB).

Due to the nature of the monday.com platform, we understand how vital it is to have another way to retrieve specific items from boards - that's where the new items_page object comes in. It contains a set of parameters that allow you to filter items on a board and only return those that meet specific criteria. It also utilizes cursor-based pagination to return paginated results, ultimately minimizing the number of items to retrieve.

Now what?

We also understand the magnitude of this change and that it will likely impact every one of our developers. That's why we are providing a 6-month window to migrate from items to items_page.

On top of our guide that covers the basics of the new items_page object, we've also compiled (and will continue to update) a list of use cases to help you further understand how to use the new filtering capabilities.

Throughout the 6-month migration window, we will also share valuable resources here in our changelog, as well as in our developers' community to help make the transition as smooth as possible. If you have any questions at any point during the migration, please reach out to us.

In API version 2023-10, the complexity of the text field for mirror, dependency, and connect boards columns has increased when using the new typed column values.

Check out the before and after connect board column examples below to see this update in action!

Please note that the exact complexity cost will be decided in the near future. The values depicted in the examples below are not the final complexity costs.

Before

Sample query

query {
  items (ids:1234567890) {
    column_values (ids: "connect_boards") {
        text
    }
  }
  complexity {
    query
  }
}

Sample response

{
  "data": {
    "items": [],
    "complexity": {
      "query": 21
    }
  },
  "account_id": 12345678
}

After

Sample query

query {
  items (ids:1234567890) {
    column_values {
      ... on BoardRelationValue {
        text
      }
    }
  }
  complexity {
    query
  }
}

Sample response

{
  "data": {
    "items": [],
    "complexity": {
      "query": 30
    }
  },
  "account_id": 12345678
}

API version 2023-10 contains a major update to the column values object, or what we like to call, column values v2. The object itself remains the same, but we introduced new fields that allow for more simple, intuitive, and expressive filtering. The five core fields include:

On top of the new fields, we added implementations that enable you to query subfields for a specific column type using GraphQL fragments, or queries that will only run if a specific type is returned. Each column is of a different type, so they all have unique fields to return data specific to that column.

Let's take a look at the LocationValue type that you can use to return location column-specific fields in your query. In addition to the five core fields mentioned above, you can also return the address, city, city_short, country, country_short, lat, lng, place_id, street, street_number, street_number_short, street_short, and updated_at fields.

Sample query

query {
  items (ids:[1234567890, 9876543210]) {
    column_values {
      ... on LocationValue {
        country
        street
        street_number
      }
    }
  }
}

The type field on columns queries will change from a string to ColumnType! in API version 2023-10. The columns field on boards queries, which takes the types argument, will also change from a string to [ColumnType!].

This update also impacts the output value for specific columns. In API version 2023-07, the type of each column was inconsistent in read and write operations. To align this behavior, the API will now return an enum value that better matches the input value in 2023-10.

The column_type argument will be required for the create_column mutation in API version 2023-10. You can pass one of the enum values listed here to create a specific type of column.

Sample mutation

mutation{
  create_column(board_id: 1234567890, title: "Country", description: "This is my country column", column_type:country) {
    id
    title
    description
  }
}

In API version 2023-10, the value argument in the change_simple_column_value mutation is nullable to enable column value deletion.

To clear the column, simply pass null value in the value argument.

mutation {
  change_simple_column_value (board_id:1234567890, item_id:9876543210, column_id:"date", value:null) {
    id
  }
}

The deprecated items_by_column_values and items_by_multiple_column_values objects will be removed and replaced with the new items_page_by_column_values object in API version 2023-10.

The new object provides a simple and intuitive way to query an item's column values. It combines two old objects into one while simultaneously keeping the behaviors nearly the same. It utilizes string values per column to search and return items with specific values, as well as cursor-based pagination to filter through large data sets.

It supports limited column types, but we will gradually add support for additional types over time. Certain columns also have restrictions that impact the scope of the object's querying abilities.

The items_page_by_column_values object enables you to query simple values and works best for simple use cases. We also added the new items_page object that has very powerful filtering capabilities and can be used for your advanced filtering needs!

In API version 2023-10, many of the ID arguments and fields that were integers have become ID type. This includes, but is not limited to, board_id, item_id, parent_item_id, parent_id, team_id, id, update_id, workspace_id, user_id, ids, and doc_folder_id.

The type ID is alphanumeric and accepts both strings and integers as valid inputs, but it will only return strings. Though it accepts both, we advise against treating them as integers and storing them in your database as text.

Let's take the docs object for example. The tables below show the impacted arguments and fields, what type they were before the update, and what they look like after the update.

Fields that are changing from Int to ID

Impacted arguments