Versioning
The Houzz Pro API is designed to evolve without breaking the integrations built against it. This guide explains how versions are numbered, which specification to build against, and how changes are communicated.
Path version
Every endpoint is prefixed with a path version — currently /v1:
https://pro-api.houzz.com/api/v1/projects
Breaking changes are introduced under a new path prefix (for example, a
future /v2). A /v1 endpoint's contract will not be broken out from under you;
when incompatible changes are unavoidable, they ship under a new version and
/v1 continues to work during the migration window.
Semantic versioning of the spec
The API is described by an OpenAPI specification whose info.version follows
Semantic Versioning (MAJOR.MINOR.PATCH):
| Bump | When it happens |
|---|---|
| MAJOR | A backwards-incompatible change: a removed or renamed endpoint or field, a narrowed enum, a changed HTTP status code, or a newly required field. |
| MINOR | A backwards-compatible addition: a new endpoint, a new optional field, a widened enum, or a new resource. |
| PATCH | Documentation-only changes — descriptions and summaries, with no change to the JSON contract. |
You can safely upgrade across MINOR and PATCH releases. Additive changes mean your client should tolerate unknown fields: if you ignore properties you do not recognize, new optional fields will never break you.
While the API is pre-1.0.0, a breaking change may occasionally ship in a MINOR
release. Whenever that happens, the change notes call it out explicitly as
BREAKING. Once the API reaches 1.0.0, breaking changes are reserved for a
new path version.
Stable spec vs. preview
Two specifications are published:
| Spec | What it is |
|---|---|
| Stable | The released contract. Frozen between releases. This is what Houzz promises to honor — build against it. |
| Preview | A forward-looking snapshot that reflects endpoints and fields Houzz is actively developing. It may change before it is released. |
Because the platform ships continuously, the live server may already return endpoints or fields that appear only in the preview spec. Anything present in preview but not in the stable spec is not yet part of the contract and may change or be withdrawn before release. Do not depend on preview-only behavior in production.
Consuming a stable spec
Pin your tooling and generated clients to a specific released version, not to a moving "latest" reference. Consuming a tagged, stable spec guarantees your generated types and validation match the contract you tested against, and shields you from in-progress changes.
The interactive API Reference always renders the current stable spec. When you generate a client or import the spec into your own tooling, reference the tagged release you want to target rather than a live/rolling URL.
Finalize the canonical published spec URL. The spec is served unauthenticated at https://pro-api.houzz.com/api/openapi.json today; a hosted copy at developer.houzz.com is planned.
How breaking changes are communicated
- Every release ships with change notes written for partners in plain language, describing what changed and what (if anything) you need to do.
- Backwards-incompatible changes are called out explicitly and, once the API is stable, are delivered under a new path version with an overlapping support window rather than by altering an existing version in place.
- New optional fields and new endpoints can appear in a MINOR release at any time. Build clients that ignore unrecognized fields so these additions are always safe.
A changelog page will be published on this portal after the first release. A subscribe/mailing-list option may be added later.