Breaking-change policy
We do not ship breaking changes inside a major version. Every breaking change goes into a new major (/api/v2/, /api/v3/, …) and the previous major continues to work in parallel.
:::note How breaking changes are tracked internally
We use Conventional Commits on every change to the platform. Any commit with a BREAKING CHANGE: footer is what causes a new API major to be cut.
:::
What we consider breaking
| Change | Breaking? |
|---|---|
| Removing an endpoint | Yes |
| Renaming an endpoint path | Yes |
| Removing a field from a response | Yes |
| Renaming a field | Yes |
| Changing a field's type (e.g., string → integer) | Yes |
| Changing a field's value format (e.g., date string format) | Yes |
| Tightening validation (rejecting inputs that used to be accepted) | Yes |
| Changing the default value of a parameter that affects behavior | Yes |
| Removing an HTTP status code from an endpoint's documented outcomes | Yes |
| Reducing rate limits or quotas | Yes |
What we do NOT consider breaking
| Change | Breaking? |
|---|---|
| Adding a new endpoint | No |
| Adding a new optional query parameter | No |
| Adding a new optional field to a request body | No |
| Adding a new field to a response | No (your client should ignore unknown fields) |
Adding a new value to an open-ended enum (e.g., device_type) | No |
| Loosening validation (accepting more inputs) | No |
| Performance improvements that change response timing | No |
| Adding a new HTTP status code for a previously unhandled edge case | No |
| Adding a new optional header to responses | No |
| Increasing rate limits or quotas | No |
Implication: write a tolerant client
Because we add new fields, parameters, and enum values freely, your client should:
- Ignore fields you don't recognize rather than throwing.
- Tolerate new enum values in open-ended string fields — log them, but don't crash.
- Not assume a fixed list of response keys.
This is the same posture that lets a browser tolerate new HTML attributes — it's why the web survives change.
What if we get it wrong?
If we ever ship a change inside a major that turns out to be breaking for someone — i.e., a real integration breaks — we treat that as a bug, not a policy decision. Please contact support immediately; we will either roll the change back or accelerate a fix.
Summary checklist
- ✅ Breaking changes only happen across majors (
/api/v1/→/api/v2/). - ✅ Non-breaking changes (new fields, new endpoints, looser validation) ship continuously.
- ✅ Internally tracked via Conventional Commits +
BREAKING CHANGE:footers. - ✅ Write a tolerant client — ignore unknown fields, tolerate new enum values.