Versioning
The API follows semantic versioning:
- The major is in the URL.
/v1/is major version 1. A change that could break a working integration never ships insidev1; it ships as/v2/. - The full version is
MAJOR.MINOR.PATCH, for example1.6.0:info.versionin/openapi.yaml, the heading of each changelog entry and theX-API-Versionheader of every answer. Log it with your requests. - The numbers continue after
1.3.0, the last version of the retired partner endpointPOST /api/partner/v1/leads: this API started at1.4.0. That endpoint's history is at the end of the changelog.
What changes the version
| Change | Version |
|---|---|
| Clearer docs; a fix that makes the API do what the docs already said | PATCH (1.6.0 → 1.6.1) |
| Something added: an optional request field, a response field, an endpoint, a scope, an error code for a new situation | MINOR (1.6.0 → 1.7.0) |
| Stricter validation within v1 (below) | MINOR with a Tightened entry |
| Anything that can break a working integration | new major (/v2/) |
Breaking: removing or renaming a field, a new required request field, accepting fewer values for a field, removing an error code or status, a different code for an existing situation, a changed type, authentication or base URL.
Read answers tolerantly: ignore fields, headers and enum values you do not know, and treat an unknown error.code by its HTTP status. That is what lets us add things within v1.
Beta
The platform and the API are in beta. The rules on these pages are binding, and the contract check below still blocks breaking changes inside /v1/. What beta means: features arrive often, and validation can be tightened without notice.
Stricter validation within v1
Sometimes the API accepts input it cannot handle well. Rejecting it is stricter, but it protects your data rather than changing what a correct integration sends. Such a change ships as a MINOR release and is effective at release. Its changelog entry under Tightened says exactly what is now rejected and with which error; there is no separate email.
The same applies, rarely, to data protection on the answer side: a response field may become null in situations where we may no longer show it (for example creator_name on offers before payment, 1.11.0). The field stays in every answer; the spec marks it with x-nullable-since and the Tightened entry says when it is null.
API Terms of Use
The legal rules for using the API are the API Terms of Use, a versioned agreement of its own (api_terms), separate from this contract versioning. A new version is announced with the event agreement.published and in the changelog. A material change that is worse for you takes effect 30 days after we publish it; a change required by law, or needed for security or to stop abuse, takes effect on publication. Accepting the terms is described under Authentication → API Terms.
Retiring a major
When /v2/ goes live, /v1/ stops on the same day: every request answers 410 version_sunset, with Deprecation, Sunset and Link headers pointing to the migration guide. There is no notice period, so watch the changelog.
How we keep to this
The published contract is checked automatically before every release against the last recorded version: an addition needs a MINOR version, stricter validation needs a Tightened entry, and a breaking change cannot be released under /v1/ at all.