API versioning is a powerful approach to ensure the continuous evolution of our API without breaking current functionality. Here at monday, we support three different versions of the API at any given time that are released each quarter. Doing so allows our developers to make updates and improvements while maintaining a stable and predictable API for third-party developers and customers.

Current versions

Types of versions

The three API versions we support include:

1. Stable: The current version of the API. We do not introduce any changes to this version besides bug fixes, so you can reliably build on this version's available features and updates.
2. Deprecated: The stable version from the previous quarter. We support each stable version for three months before it becomes the deprecated version, after which we provide an additional three months of support. In total, we support each stable version for six months after its release. Once a version is deprecated, users trying to access it will get the latest deprecated version instead.
3. Preview: The next stable version. The preview version provides access to API updates that are not yet available in other versions, so you can access each preview version three months before it becomes the stable version. Our developers will continue introducing bug fixes and minor, non-breaking changes throughout the quarter, but we do not add breaking changes to this version. Therefore, you can reliably build on the available features and updates.

Release schedule

New stable versions are released each quarter. They are named according to the year and first month of the quarter it is released. For example, the stable version released in Q1 2023 would be called 2023-01.

Both stable and preview versions are released at 12:00 AM UTC on the scheduled release date. You can find information and updates about new releases in the changelog, community, and release notes:

• API changelog
• Developer community

Deprecation strategy

Each deprecation is communicated at least three months in advance. Whenever we release a new API that replaces a previous one, we will continue supporting the old API for six months after the release of the new one. All deprecations are documented or announced in the changelog, community, documentation, release notes, and GraphQL schema:

• API changelog
• Developer community
• API reference documentation
• GraphQL schema

Making a request

You can select which API version you want to use by sending the API-Version header. There you can send either the date of the version (i.e., 2023-04) or the type of version you'd like to use (i.e., stable or preview). You will automatically get the stable version if you do not include the API-Version header.

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
    'API-Version' : '2023-04'
   },
   body: JSON.stringify({
     'query' : 'query{version {kind value} }'
   })
  });

curl --location --request POST 'http://api.monday.com/v2' \
--header 'API-Version: 2023-04' \
--header 'Authorization: Bearer ...' \
--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.

query {
  version {
    kind
    value
  }
}

let query = 'query { version { kind value }}';

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
    'API-version' : '2023-04'
   },
   body: JSON.stringify({
     'query' : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Invalid requests

You will get an InvalidVersionException error if your request is not formatted properly (i.e., 2023 instead of 2023-04). If you request a version that does not exist (i.e., 2023-05), you will get the current stable version.

Any request to a version of the API that is no longer supported will get the most recently deprecated version. Let's say you request 2023-01 in August 2023. Since support for that version ended July 1, 2023, you would get 2023-04 since it is the most recently deprecated version. On the contrary, you will get the newest version available if you request a version that has yet to be released.

If you make an API call using a field that doesn't exist in a specific version (either it hasn't been released yet or it has been deprecated), you will get an error stating that the field does not exist.

{
  "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
}

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 three months before the stable version release when 2024-01 is the preview version by passing 2024-01 in the API-Version header. If you don't include the API-Version header, you will get an error stating that the field does not exist.
2. We announce the release of the test field in version 2024-01, which you can access up to three months in advance in the preview version. Let's say you forget to include the API-Version header when making a request, so you automatically will get the current stable version where the new field is not yet available. Remember to pass preview in the header to access the new field!
3. We announce the deprecation of the example field in version 2024-01. You can access the example field until April 1, 2024, since we support each deprecated version for three months. If you pass 2024-04 in your request, you can no longer access the example field.
4. Let's say that all of your requests contain 2023-10 in the API-Version header. We announce a breaking change that switches the id field type from Int to ID in version 2024-01. Fast forward to July 2024, when you make another request but forgot to update the header. You would get the most recently deprecated version (2024-01), where the breaking change would be live.

📘

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! 😎