The HubSpot Associations API is one of 93 APIs that HubSpot publishes on the network, described by a machine-readable OpenAPI specification.
It exposes 652 JSON Schema definitions — one of the deepest schema sets attached to any single API in the catalog.
Its base URL is https://api.example.com.
The placeholder
api.example.com is the reserved example domain from RFC 2606. It exists precisely so that documentation can show a URL that is guaranteed never to resolve to anything real.
It is in the published contract as the server.
A client generated from this specification will attempt to call api.example.com, get nothing, and surface a DNS failure. A developer recognises the string immediately and substitutes api.hubapi.com. An agent does not have that reflex — it has a contract that says this is where the API lives, and one round of failure with no hint about what to try instead.
This is a more forgivable failure than a plausible-looking wrong host, because at least example.com is unmistakably a placeholder. It is still a specification that cannot be used as published.
The 652 schemas are the real story
Set the host aside, because the rest of this entry is genuinely impressive.
652 JSON Schema definitions, published as individual artifacts alongside JSON Structure variants and code examples. That is a provider describing not just the operations but the complete shape of every object those operations move.
Associations are the right place to invest that effort. In HubSpot’s model, associations are the graph — the links between contacts, companies, deals, tickets, line items and custom objects. Getting an association wrong does not throw an error; it quietly attaches a deal to the wrong company and nobody notices until a report is wrong.
An API where the failure mode is silently correct-looking data is exactly the API you want fully schema-described, because validation at the client is the only place the mistake gets caught early.
The pattern this fits
This is the third contract-quality finding of the week, and they rhyme:
- Webex — 178 contracts, 0% callable, excellent governance
- Mailchimp — a plausible-looking host that is actually a template
- HubSpot Associations — 652 schemas and a reserved example domain
In every case the expensive work is done and the cheapest possible field is wrong. Nobody skipped the schemas because they were hard. They shipped api.example.com because no build step ever asked whether the server URL resolved.
That check is a few lines in CI. HubSpot publishes enough artifact discipline elsewhere that adding it would be trivial — and it would move this entry from unusable-as-published to genuinely first-rate.
Takeaway
652 JSON Schemas describing a data graph where silent errors are the dangerous ones, attached to an OpenAPI specification whose server is the RFC 2606 example domain. Enormous care in the hard part, no check on the trivial one.
Read the docs at developers.hubspot.com, and the provider entry at apis.io/providers/hubspot/.