The deprecated items field on the groups object will be removed and replaced with items_page in API version 2023-10. Please see our previous announcement for more information about the items_page field.

Due to the new year's holiday, we are delaying the API versioning release dates – the last day you have to migrate your apps is now January 15th, 2024.

Thereofre, the following will happen on January 16th at 9:00 AM GMT:

• Version 2024-01 will be released for preview
• Version 2023-07 will be deprecated
• You will no longer get 2023-07 as the default version when sending a request without a header

We previously announced an upgrade to the API playground when accessing it through your monday.com account, but those upgrades are now also available in our public API!

You can access the public playground here and entering your API access token. Happy testing!

We've added warning messages to a number of our API calls!

Our GraphQL API will now return an extensions object with a list of warnings, when you try using an object that is going to be deprecated or changed soon.

Please store these values to give clarity on what functions need to be changed. This is especially relevant for apps migrating to API version 2023-10.

📘

Note: Do not rely solely on warnings to understand what is updating – you should always use our API changelog and release notes as the source of truth.

Example usage

Let's say I use the items_by_column_values query, which will be deprecated in 2023-10:

query {
  items_by_column_values(board_id:12345, column_id:numbers, column_value:"5000") {
    id
    name
  }
}

The response will contain an extensions object, with a warning that this is being deprecated. It also contains metadata such as what part of my query is deprecated, and a code to explain the cause of the warning.

Here's what it looks like:

{
  "data": {
    "items_by_column_values": [
      {
        "id": "4579863854",
        "name": "Develop messaging"
      }
    ]
  },
  "extensions": {
    "warnings": [
      {
        "message": "Replaced by Query.items_page_by_column_values since 2023-10",
        "locations": [
          {
            "line": 2,
            "column": 3
          }
        ],
        "path": [
          "query",
          "items_by_column_values"
        ],
        "extensions": {
          "code": "deprecatedField",
          "typeName": "Query",
          "fieldName": "items_by_column_values"
        }
      }
    ]
  },
  "account_id": 12345
}

Have questions? Post them in our developer community!

Using the create_doc mutation, you can now create a new document in a workspace (not just a monday doc column)!

This mutation is available in API versions 2023-07 and later. Check it out!

mutation {  
  create_doc (location: {workspace: { workspace_id: 1234567, name:"New doc", kind: private}}) {  
    id  
  }  
}

We will be reindexing our API documentation search feature tonight at 11:00 PM CDT (4:00 AM UTC, 7:00 AM IDT on July 13th, 2023). During this period, the documentation and changelog search will not work. This update will not impact the API documentation itself.

We expect full functionality to be restored within 2 hours but will provide additional updates if the outage will last longer than expected.

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
}