Versioning & changes

The API is not versioned in the URL today: paths are the ones of this documentation (/v1/... is part of the path, not a version you choose). Webhook payloads carry apiVersion: "1".

What may change without notice

These additive changes are not breaking. Build your integration to tolerate them:

• new endpoints, new optional request fields or query parameters;
• new fields in responses and webhook payloads;
• new values in enums that are documented as open (statuses, event types, error codes);
• new webhook event types (you only receive the ones you subscribed to);
• changes of message texts, of the order of object keys, and of the format of opaque values (page tokens, authorization codes).

Ignore unknown fields, treat unknown statuses gracefully, and branch on error codes rather than messages.

Breaking changes

Removing or renaming a field or an endpoint, making an optional field required, changing a type or the meaning of a value, or changing the webhook signature scheme are breaking changes. They will be:

1. announced ahead of the change in the changelog and to the administrators of the organizations and applications concerned;
2. delivered with a transition period whenever possible (the previous behavior kept alongside the new one).

A versioning scheme for the API will be introduced before the first breaking change.

Stay informed

• The changelog lists every notable change.
• The OpenAPI document always describes the current API: diff it in your CI to spot changes.