Versioning

The API is at v1. We make changes within v1 only when they are additive and non-breaking.

What we treat as non-breaking

You can rely on us doing any of the following without notice:

• Adding new endpoints.
• Adding new optional fields to request bodies and query strings.
• Adding new fields to response bodies, including inside existing objects. Your parser must ignore unknown fields.
• Adding new values to enum-style fields — for example, a new webhook action type. Your code must tolerate unknown values.

What we treat as breaking

We won’t do any of the following silently. A breaking change requires a new version (v2):

• Removing or renaming an endpoint, field, parameter, or enum value.
• Changing a field’s type or semantics.
• Tightening validation in a way that previously valid requests start failing.

Deprecation policy

When we plan to remove or break something:

1. We announce the deprecation in the changelog and, where practical, in the response itself (for example, a Deprecation HTTP header).
2. The deprecated behavior keeps working for a documented minimum window.
3. After the window ends, the deprecated behavior is removed in the next major version.

We don’t rewrite history within a major version. Once v1 is stable, the contract isn’t tightened retroactively.