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, 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, check out this blog post on date-based 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.
What's included in /2026-03/
You can see which API's are included in /2026-03/ at 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 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 joining the discussion in our community.