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

ObjectField
Accountid
AccountProductid
Boardboard_folder_id
Boardworkspace_id
Documentdoc_folder_id
Documentid
Documentobject_id
Documentworkspace_id
DocumentBlockdoc_id
Folderid
Folderowner_id
Tagid
Teamid
Userid
Webhookboard_id
Workspaceid

Impacted arguments

BeforeAfter
ids [Int]ids [ID!]
object_ids [Int]object_ids [ID!]
workspace_ids [Int]workspace_ids [ID]

In API version 2023-10, you can no longer send empty parentheses in queries. If you try, the query will return an error. Check out the code sample below to see a query that was previously supported and find out how you can update it so it won't throw an error!

Previously supported sample query

query {
  boards () {
    id
  }
}

Updated sample query

query {
  boards (ids:1234567890) {
    id
  }
}
query {
  boards (limit:10) {
    id
  }
}

Strings must be sent with quotation marks, so you can no longer send arguments without them in API versions 2023-10 and later. If you send strings without quotation marks, it will result in an error.

Check out the code samples below to see queries and mutations that were previously supported, and find out how you can update them so they won't throw an error!

Previously supported code samples

mutation {
  create_column(board_id: 1234567890, title:Country, description: "This is my country column", column_type:country) {
    id
    title
    description
  }
}
query {
  users (name: Test) {
    id
  }
}
query {
  items (ids: 1231234123) {
    column_values (ids: task_status) {
      value
    }
  }
}

Updated code samples

mutation{
  create_column(board_id: 1234567890, title:"Country", description: "This is my country column", column_type:country) {
    id
    title
    description
  }
}
query {
  users (name: "Test") {
    id
  }
}
query {
  items (ids: 1231234123) {
    column_values (ids: "task_status") {
      value
    }
  }
}

The newest_first argument for boards queries will be deprecated in API version 2023-10. You can instead use the order_by argument and sort by the creation date, so the most recently created boards will be listed first.

Sample query

query {
  boards (ids: 1234567890, order_by: created_at) {
    id
  }
}

You can use the new linked_items field to return an item's linked items. The response is an array that contains the unique identifiers of the linked items.

This field is only available in API versions 2023-10 and later!

Sample query

query {
  items (ids: 9876543210) {
    linked_items (linked_board_id:1234567890, link_to_item_column_id:"connect_boards") {
      id
    }
  }
}

Sample response

{
  "data": {
    "items": [
      {
        "linked_items": [
          {
            "id": "1122334455"
          },
          {
            "id": "5544332211"
          }
        ]
      }
    ]
  },
  "account_id": 12345678
}

The new move_item_to_board mutation allows you to easily move an item between boards via the API. If an item has subitems, they will also move with the item. Please note that if you do not provide column mapping, the system will try to map the item according to the column name and type.

The mutation is only available in API versions 2023-10 and later!

Sample mutation

mutation {
  move_item_to_board (board_id:1234567890, group_id: "new_group", item_id:9876543210) {
    id
  }
}

Breaking changes

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

  • New column values fields and typed column values

  • Deprecated the items_by_column_values and items_by_multiple_column_values objects, replacing 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

We just added the create_doc mutation that allows you to create a new doc in a document column!

mutation {
  create_doc (location: { board: {item_id: 1234567890, column_id: "monday_doc"}}) {
    id
  }
}