Versioning
The major version is in the path: /v1. Within a major version, changes are additive.
What does not break you
These can happen inside /v1 at any time:
- A new endpoint.
- A new optional query parameter or request field.
- A new field in a response. Ignore fields you do not know.
- A new error
codewithin an existingtype. Branch ontype. - A new webhook event type. Ignore events you do not handle.
What counts as breaking
Removing or renaming a field, endpoint or parameter, changing a field's type or meaning, making an optional input required, or changing an error's type. A breaking change ships only under a new major version path; /v1 keeps its behaviour.
Release phases
| Phase | Who can call it | Can it change? | In the reference? |
|---|---|---|---|
| Generally available | Anyone with a key that has the scope | Additive changes only | Yes |
| Private preview | Organizations we invite | Yes, without notice | No; described on an Early access page |
Current status
| Area | Phase |
|---|---|
GET /v1/health | Generally available |
| Surveys API | Private preview |
Every change is dated in the Changelog.