API Versioning
This guide walks through current versions, types of versions, the release schedule, and how to make a request to a specific version.
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
Type | Name |
---|---|
Stable | 2023-04 |
Deprecated | 2023-01 |
Preview | 2023-07 |
Types of versions
The three API versions we support include:
- 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.
- 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.
- 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
.
Stable version | Release date | Deprecated version supported until |
---|---|---|
2023-04 | April 1, 2023 | October 1, 2024 |
2023-07 | July 1, 2023 | January 1, 2024 |
2023-10 | October 1, 2023 | April 1, 2024 |
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:
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:
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!
- We announce the release of a new API called
new_API
in version2024-01
. You can accessnew_API
three months before the stable version release when2024-01
is the preview version by passing2024-01
in theAPI-Version
header. If you don't include theAPI-Version
header, you will get an error stating that the field does not exist. - We announce the release of the
test
field in version2024-01
, which you can access up to three months in advance in the preview version. Let's say you forget to include theAPI-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 passpreview
in the header to access the new field! - We announce the deprecation of the
example
field in version2024-01
. You can access theexample
field until April 1, 2024, since we support each deprecated version for three months. If you pass2024-04
in your request, you can no longer access theexample
field. - Let's say that all of your requests contain
2023-10
in theAPI-Version
header. We announce a breaking change that switches theid
field type fromInt
toID
in version2024-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! 😎
Updated 10 days ago