# Introducing date-based API versioning **URL:** \ **Category:** Developer Announcements\ **Tags:** api, announcement\ **Created:** [March 30, 2026, 7:46pm UTC](https://community.hubspot.com/t/introducing-date-based-api-versioning/147831 "2026-03-30T19:46:45Z")\ **Posts on this page:** 4\ **Page:** 1
**Author:** ![Dadams](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/dadams/32/21752_2.png) [@Dadams](https://community.hubspot.com/u/Dadams)\ **Post date:** [March 30, 2026, 7:46pm UTC](https://community.hubspot.com/t/introducing-date-based-api-versioning/147831/1 "2026-03-30T19:46:45Z")
Today we’re introducing a new versioning system for our APIs, using a `/YYYY-MM/` format (like `/2026-03/`) instead of v1, v2, v3, v4 to denote the month in which the API was shipped. This date-based versioning gives developers a predictable way to manage API updates and breaking changes. Initially [announced for CRM APIs for Fall Spotlight 2025](https://developers.hubspot.com/changelog/new-and-improved-apis-fall-spotlight-2025), this has now been released for most recent versions of our APIs. ### Why does it matter? If you’re a developer working with HubSpot APIs, you currently face unpredictable breaking changes, inconsistent version numbers across different APIs, and short deprecation windows that make it hard to plan updates. With date-based versioning, you can: - **Plan with confidence** - breaking changes only happen twice a year (March and September), and you get 18 months of support for each version instead of the previous 90-day minimum deprecation notice - **Reduce maintenance overhead** - immutable API versions mean your integrations won’t break unexpectedly, and you can migrate to newer versions on your own timeline - **Navigate APIs more easily** - consistent date-based naming across all APIs replaces the confusing mix of v1, v2, v3, and v4 versions - **Leverage AI tools more effectively** - the predictable pattern makes it easier for LLMs and AI agents to work with HubSpot APIs For more background on why we’re making these updates, and how these changes tie into the wider [HubSpot Developer Platform](https://developers.hubspot.com/docs/developer-tooling/overview), check out [this blog post on date-based versioning](https://developers.hubspot.com/blog/a-developers-guide-to-hubspots-date-based-api-versioning). ### How does it work? #### Release schedule New date-based API versions launch twice a year: - March (e.g., `/2026-03/`) coinciding with Spring Spotlight - September (e.g., `/2026-09/`) coinciding with INBOUND Each version is immutable once released, receiving only critical bug fixes and security updates during a minimum support window of 18 months. HubSpot teams can still release enhancements throughout the year via public betas. Beta APIs will be part of the next release. For example, with the release of `/2026-03/`, beta APIs will use version `/2026-09-beta/`. Versions become unsupported after the 18 month support window. Unsupported versions may continue to function but are not guaranteed to get critical updates, and may not remain stable or available. You can continue to use any supported version and migrate to newer versions on your own timeline, though we strongly recommend upgrading to the current version when a version becomes unsupported. For more details about the release and support schedules see the [versioning documentation](https://developers.hubspot.com/docs/developer-tooling/platform/versioning#api-versioning). #### What’s included in /2026-03/ You can see which API’s are included in `/2026-03/` at [2026-03 API reference - HubSpot docs](https://developers.hubspot.com/docs/api-reference/latest/overview). These APIs are based on the latest v3 or v4 APIs, so if you were already using the latest version of an API you can update to the date-based version by updating the URL you are using. The `/2025-09/` [CRM APIs announced at INBOUND 25](https://developers.hubspot.com/changelog/new-and-improved-apis-fall-spotlight-2025) are still supported and will become unsupported with the release of `/2027-03/`. Current v4 APIs will be supported until March 2027, and will become unsupported with the release of `/2027-03/`. Current v1-v3 APIs will continue to work as well, with the support timeline to be announced at a later date. Questions or comments? Please let us know by replying below. ---
**Author:** ![TReynaud](https://avatars.discourse-cdn.com/v4/letter/t/cab0a1/32.png) [@TReynaud](https://community.hubspot.com/u/TReynaud)\ **Post date:** [April 21, 2026, 9:54am UTC](https://community.hubspot.com/t/introducing-date-based-api-versioning/147831/2 "2026-04-21T09:54:10Z")
@Dadams all CRM enpoints on the 2026.03 API return a 404… ---
**Author:** ![Dadams](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/dadams/32/21752_2.png) [@Dadams](https://community.hubspot.com/u/Dadams)\ **Post date:** [April 21, 2026, 5:27pm UTC](https://community.hubspot.com/t/introducing-date-based-api-versioning/147831/3 "2026-04-21T17:27:46Z")
Can you share a specific URL you’re seeing this with? I tried testing a few of the CRM endpoints on my side and wasn’t seeing any issues. ---
**Author:** ![Sachavskyi](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/sachavskyi/32/39641_2.png) [@Sachavskyi](https://community.hubspot.com/u/Sachavskyi)\ **Post date:** [June 5, 2026, 1:28pm UTC](https://community.hubspot.com/t/introducing-date-based-api-versioning/147831/4 "2026-06-05T13:28:18Z")
@Dadams I wanted to migrate my application from /v3/ to /2026-03/ but I don’t see equivalents for the next /v3/ (and /v4/) requests. Here’s what I tried in each case (all 404 unless noted): - `GET /marketing/v3/forms` — tried `/marketing/2026-03/forms`, `/marketing/forms/2026-03`, `/forms/2026-03`, `/marketing-forms/2026-03/forms`, `/forms-api/2026-03/forms` - `GET /events/v3/events/event-types` — tried `/events/2026-03/events/event-types`, `/events/events/2026-03/event-types`, `/events-event-types/2026-03/event-types` - `GET /comments/v3/comments` — tried `/comments/2026-03/comments`, `/comments/comments/2026-03`, `/crm-comments/2026-03/comments`, `/blog-comments/2026-03` - `GET /ctas/v3/ctas`, `GET /ctas/v3/placements` — tried `/ctas/2026-03/ctas`, `/ctas/ctas/2026-03`, `/marketing-ctas/2026-03/ctas`, `/cta/2026-03` - `GET /business-units/v3/business-units/user/` — tried `/business-units/2026-03/business-units/user/`, `/business-units/business-units/2026-03/user/`, `/business-units-api/2026-03` - `POST /collector/v3/graphql` — tried `/collector/2026-03/graphql` - `GET|POST /filemanager/api/v3/files` (incl. `/upload`, `/set-access/batch`) — tried `/files/2026-03/files` (405), `/filemanager/2026-03/files`, `/filemanager/api/2026-03/files` Could you confirm the correct /2026-03/ paths if they exist, or let me know if any of these are not planned for date-based versioning? Thanks!