API Versioning

Versioning is an important approach to continuously evolve our API without disrupting existing functionality. It enables developers to make updates and improvements while maintaining a stable and predictable behavior.

We guarantee at least three different versions of the API at the same time and release a new version every quarter. You can read more about the latest versions in our release notes.

The current versions are:

2024-04
Release candidate
2024-01
Current
2023-10
Maintenance

Version types

There are at least three types of API versions at any given time: release candidate, current, and maintenance. Two are stable, and the other is an unstable preview version. This guarantees that anything you build on the current version will not change for at least 6 months.

TypeDescription
Release candidate (RC)
  • Provides early access to the latest features and improvements
  • Unstable and should not be used in production applications
  • Previously known as the Preview version
  • Current
  • Only bug fixes with no breaking changes
  • Stable and can be used in production applications
  • Used as the default version when no header is passed
  • Anything built using this won't change for at least six months
  • Previously known as the Stable version
  • Maintenance
  • Only bug fixes with no breaking changes
  • Stable and can be used in production applications (recommended to only use it when you are unable to migrate to the current version on time)
  • Previously known as the Deprecated version
  • Life cycle

    Each version moves through the following lifecycle:

    • Release a new RC (every quarter)
    • RC --> Current (after 3 months)
    • Current --> Maintenance (after 3 months)
    • Maintenance --> Deprecated (will be announced at least 3 months in advance)

    Release schedule

    New RCs are released every three months at the start of each quarter at 12:00 AM UTC.

    Version names are not semantic but instead refer to the year and month in which they become the default/current version. For example, the January/Q1 2024 current version would be called 2024-01.

    Version nameRCCurrent (default)MaintenanceDeprecated
    2023-07April 1st, 2023July 1st, 2023October 1st, 2023January 15th, 2024
    2023-10July 1st, 2023October 1st, 2023January 15th, 2023TBD
    2024-01October 1st, 2023January 15th, 2024April 1st, 2024TBD
    2024-04January 1st, 2024April 1st, 2024July 1st, 2024TBD

    How to access different versions

    You can access different versions of the API using a header in an HTTP request, through the SDK, or in the API playground.

    πŸ‘

    Passing the version name in your request

    We strongly encourage production applications to pass a version name in each API call. If you don't, your app will always get the Current version. Passing a version name makes your app less susceptible to breaking changes and gives you more time to migrate to a new version.

    Using the API-Version header in an HTTP request

    You can select which API version you want to use by sending the version name in the API-Version header.

    fetch ("https://api.monday.com/v2", {
      method: 'post',
      headers: {
        'Content-Type': 'application/json',
        'Authorization' : 'YOUR_API_KEY_HERE'
        'API-Version' : '2024-01'
       },
       body: JSON.stringify({
         'query' : 'query{version {kind value} }'
       })
      });
    
    curl --location --request POST 'https://api.monday.com/v2' \
    --header 'API-Version: 2024-01' \
    --header 'Authorization: YOUR_API_KEY_HERE' \
    --header 'Content-Type: application/json' \
    --data-raw '{"query":"query { version { kind value } }"}'
    

    All API responses include the API-Version header to indicate the version used during the call, or you can query the version object to return the same data. If you'd like to see all available API versions, you can query the versions object.

    Using the SDK

    We support two ways to set the API version when using the Javascript SDK: setting the default version or passing the version for a specific call.

    import mondaySdk from "monday-sdk-js";
    
    const monday = mondaySdk();
    monday.setApiVersion("2024-01");
    
    const data = await monday.api('query { me { id } }', {
      apiVersion: '2024-01'
    })
    

    API playground

    You can also use the API playground to access and test different versions of the API by clicking the clock going in reverse icon in the middle of the screen.

    This will open the version selector where you can test queries and mutations with any of the versions listed.

    Versioning examples

    Versioning is a powerful way to improve the API, but understanding which version to request and when can be confusing. We've compiled these hypothetical scenarios to help you better understand the flow!

    1. We announce the release of a new API called new_API in version 2024-01. You can access new_API as soon as 2024-01 is released as the RC by passing 2024-01 in the API-Version header. If you don't include the API-Version header, it will automatically call the Current version and you will get an error stating that the field does not exist.
    2. We announce the deprecation of the example field in version 2023-07. You can access the example field until January 15th, 2024 when 2023-07 is deprecated. Once you start passing 2024-04 in your request, you will no longer have access to the example field.

    Important terms

    API versioning differs across the board, so frequently used terms may mean something slightly different in each case. This section walks through some of the most important concepts and terms we use, and more importantly, covers exactly what they mean!

    TermDescription
    StableIndicates that a version can reliably be used in production. Addresses only non-breaking bug fixes, regressions, and critical bugs that require breaking changes.
    DefaultThe version that will be called when no header or the default header is passed in an API call.
    UnstableIndicates that a version cannot reliably be used in production. Addresses both breaking and non-breaking changes.
    DeprecatedIndicates that a version is no longer supported. Any calls made to a deprecated version will use the Maintenance version.
    Version nameThe version's unique identifier (e.g., 2023-10). We recommend passing the version name in your calls.
    Version typeThe type of version:release-candidate, current, or maintenance.

    Troubleshooting

    Have questions about versioning? Have no fear! Keep reading to learn more about common issues below and how to resolve them.

    Unsupported versions

    • Any request to a version of the API that has been deprecated will get the Maintenance version. If you request a version that does not exist (e.g. 2024-02 instead of 2024-01), you will get the Current version.

    Invalid requests

    • You will get an InvalidVersionException error if your request is not formatted properly (e.g. 2023 instead of 2023-04). Refer to our release schedule to see all version names and ensure it is properly formatted in your call!
    • If you make an API call using a field that doesn't exist in a specific version, you will get an error stating that the field does not exist (see below). Make sure you're accessing the updated version by passing the version name in your call!
    {
      "errors": [
        {
          "message": "Field 'new_field' doesn't exist on type 'Boards'",
          "locations": [
            {
              "line": 4,
              "column": 5
            }
          ],
          "path": [
            "query",
            "boards",
            "new_field"
          ],
          "extensions": {
            "code": "undefinedField",
            "typeName": "Boards",
            "fieldName": "new_field"
          }
        }
      ],
      "account_id": 1
    }
    

    πŸ“˜

    Join our developer community!

    We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎