topic Re: OpenAPI specs in APIs & Integrations

How can I manage and update OpenAPI specs for integrations in HubSpot?

PCronin9 — Tue, 28 Oct 2025 14:26:13 GMT

What’s the best way to manage and update OpenAPI specifications for HubSpot integrations?

Our integration is built in Go, using a third-party tool to generate client libraries from HubSpot’s published OpenAPI specs.

After a few weeks of mostly successful operation, we're looking to make the system more robust by automatically updating client libraries when new OpenAPI spec versions are released.

However, I'm uncertain about several points after reviewing the documentation and forum:

The canonical source for available OpenAPI specs appears to be https://developers.hubspot.com/docs/api-reference/overview but the v4 CRM Objects API exists without being mentioned there or in developer docs—why is that?
What’s the difference between the “LATEST” and “STABLE” stages shown in v1/apis? Why is v4 CRM associations listed as STABLE, while v3 is LATEST, when v4 is supposed to be the newest?
I expected semantic versioning in spec updates, but noticed changes to the OpenAPI specs occurring without the API version (e.g., "v3") changing.
Where are spec changes announced, and how can I track when to regenerate client libraries?
Is it possible to get previous versions of OpenAPI specs, specifically older v3 CRM specs?
The v4 CRM Associations developer docs describe a "Basic List" endpoint that seems missing from the v4 CRM associations OpenAPI spec. Can someone explain this discrepancy?
Lastly, I reported a bug, was told it was fixed by support, but the issue has resurfaced without clear communication about what was changed.

Our integration is written in Go, and as such we use a third-party tool to generate client libraries using HubSpot's published OpenAPI specs. Now that it's been running (mostly) successfully for a few weeks, we're ready to build in some additional robustness to our system, such as updating client libraries when updates to the OpenAPI specs become available, and I've found a few things that I haven't been able to answer as a result of reading existing docs and scouring the forum:

1. It seems the canonical place for knowing which OpenAPI specs are available is at https://developers.hubspot.com/docs/api-reference/overview. But if this is canonical, why does a v4 CRM Objects API: https://developers.hubspot.com/docs/api-reference/crm-associations-v4/basic/delete-crm-v4-objects-objectType-objectId-associations-toObjectType-toObjectId also exist, but is mentioned neither in the endpoint's response, nor mentioned in the developer API docs?

2. What is the difference between the LATEST and STABLE "stages" included in the response from the v1/apis endpoint mentioned above? In particular, why is the v4 CRM associations API listed as STABLE while the v3 CRM associations API is listed as LATEST? The dev API docs tout the v4 as the newest one.

3. I would expect updates in the OpenAPI specs to be versioned, such as with semantic versioning. However I have observed at least one change to the OpenAPI specs, while the API version remained at "v3".

4. Are changes to the OpenAPI specs announced any where? How can I find out if I need to regenerate my client libraries?

5. Is it possible to access older versions of OpenAPI specs? Specifically, previous versions of the various v3 CRM OpenAPI specs, not v2, v1, etc.

6. I noted that the v4 CRM Associations dev docs include a "Basic List" endpoint that returns the existing associations between a particular object type/id and another object type. However that endpoint doesn't exist in the OpenAPI spec for the v4 CRM associations. Why is that?

7. I worked with customer support to get this bug fixed: "OpenAPI Spec Bug" , and I was told it was fixed (although I was not actually told what change was made), but I ran into the same issue recently, so I don't think it's actually fixed.

Any insight would be appreciated.

Moderator Note: this post was reviewed for relevancy and optimized for clarity on October 22, 2025. Thank you for your contributions to the HubSpot Community!

Re: How can I manage and update OpenAPI specs for integrations in HubSpot?

himanshurauthan — Thu, 30 Oct 2025 16:17:06 GMT

Hello @PCronin9

Why does a v4 CRM Objects API also exist, but is mentioned neither in the endpoint's response, nor mentioned in the developer API docs?

The v4 CRM Objects API is a newer version of the API that is still under development. It is not yet fully supported, and that is why it is not mentioned in the endpoint's response or the developer API docs.

What is the difference between the LATEST and STABLE "stages" included in the response from the v1/apis endpoint mentioned above?

The LATEST stage indicates that the API is the newest version and is recommended for use. The STABLE stage indicates that the API is a stable version that is fully supported.

The v4 CRM associations API is listed as STABLE because it is a newer version of the API that is more feature-rich than the v3 CRM associations API. However, the v3 CRM associations API is still fully supported and is listed as LATEST because it is the most widely used version of the API.

Why have I observed at least one change to the OpenAPI specs, while the API version remained at "v3"?

HubSpot occasionally makes changes to the OpenAPI specs without changing the API version. This is typically done to make minor changes or to fix bugs.

Are changes to the OpenAPI specs announced any where? How can I find out if I need to regenerate my client libraries?

HubSpot does not announce changes to the OpenAPI specs. However, you can check the endpoint's response or the developer API docs periodically to see if there have been any changes.

Is it possible to access older versions of OpenAPI specs? Specifically, previous versions of the various v3 CRM OpenAPI specs, not v2, v1, etc.

No, it is not possible to access older versions of OpenAPI specs. HubSpot only publishes the latest version of the OpenAPI specs for each API.

Why is the "Basic List" endpoint that returns the existing associations between a particular object type/id and another object type not included in the OpenAPI spec for the v4 CRM associations?

The "Basic List" endpoint is a new endpoint that is still under development. It is not yet fully supported, and that is why it is not included in the OpenAPI spec.

Why was the bug in the v4 CRM Associations dev docs not fixed?

HubSpot is aware of the bug in the v4 CRM Associations dev docs and is working on fixing it.

Moderator note: Community Champions, like Himanshurauthan, are not HubSpot employees, but enthusiastic volunteers committed to helping and supporting everyone in the community.
Alongside users, certified partners, and HubSpot employees, Champions play a key role in moderating the community and fostering a positive environment for all.

Re: OpenAPI specs

PCronin9 — Wed, 20 Sep 2023 15:40:22 GMT

Hi @himanshurauthan, I was hoping that someone from HubSpot could respond to my questions so our company could make business decisions based on the answers. Do you work for HubSpot, or are you perhaps authorized to speak for them?

Re: OpenAPI specs

mcrysler — Wed, 28 May 2025 21:50:11 GMT

None of the api spec links work for me. Is there a place I can download a yml or json file containing the available API specs? We are trying to build an integration and I need the specs, not just the developer documentation.

Re: OpenAPI specs

PCronin9 — Tue, 28 Oct 2025 14:19:21 GMT

Hi @mcrysler, from a Google search I found this page "HubSpot Developer Changelog", which suggests that https://developers.hubspot.com/docs/api-reference/overview is the new place.

That being said, professional to professional, I would definitely exercise caution around the OpenAPI specs.

I have experienced variations between the OpenAPI specs and endpoint behavior.

Reporting the discrepencies as issues, both on this form and through our customer support rep, no changes were made.

Re: OpenAPI specs

mcrysler — Fri, 30 May 2025 16:16:50 GMT

Why is that so difficult to find?? Thank you so much for the link and I appreciate the word of caution!

Re: OpenAPI specs

Jaycee_Lewis — Tue, 03 Jun 2025 16:51:22 GMT

Hey, @mcrysler @PCronin9 is this what you are looking for? https://github.com/HubSpot/HubSpot-public-api-spec-collection

Re: OpenAPI specs

PCronin9 — Tue, 03 Jun 2025 17:22:14 GMT

Yeah, thanks! I just saw the "New HubSpot Flows Workspace in Postman" article by way of the Developers email. Definitely a step in the right direction, and I'm surprised I hadn't known about it before.

I'll note that 3 of the 4 open issues seem to correlate with the issues I was experiencing, which is that OpenAPI specs differ from either the API docs or endpoint behavior. It is surprising to me that those differences are not primary concerns handled immediately. Based on that, it seems like the OpenAPI specs should be labeled as "beta" to provide a notice to developers that these aren't really getting the attention people might think they are.

Re: OpenAPI specs

frasermarlow — Thu, 31 Jul 2025 02:05:03 GMT

Thanks for the link. Sadly, when I pull from that endpoint I get
> Provided schema is not valid OpenAPI JSON schema
The JSON is correctly formatted, but OpenMetadata (at least) rejects the OpenAPI schema.

Re: OpenAPI specs

chighsmith — Thu, 31 Jul 2025 13:48:01 GMT

Hi @frasermarlow,

Welcome to the Community!

I have also not seen that error before. With that being said, I'd like to tag in some of our awesome Community Champions so see if they have any ideas - @HubSpot_Corey @Bortami and @WesQ do you have any suggestions on this?

-Cassie
Community Manager

Re: OpenAPI specs

PCronin9 — Thu, 31 Jul 2025 13:54:33 GMT

Whomever accepted this answer as "the solution," please do not do so. The only proper answers for my questions would need to come from decision makers who are involved with, or oversee the future of the OpenAPI spec efforts from within HubSpot. I don't think it's reasonable for HubSpot to rely on 3rd party community members to answer our questions as we're paying money to HubSpot, not to the 3rd party community members.

Re: OpenAPI specs

PCronin9 — Tue, 28 Oct 2025 14:33:19 GMT

Hi @Bérengère - I see you've accepted this answer as the solution. I think that the existence of the github repo is a step in the right direction, but I don't think the github repo answers almost any of the questions I asked. Could you please refrain from marking this answer as a solution, or, edit it to include answers to my questions please?