Versioning

The current version is v1. It appears in the URL: /api/v1/.... There is no header-based version selector.

What counts as breaking

The following changes will only ship in a new major version (v2, v3):

• Removing an endpoint.
• Removing or renaming a field on a response object.
• Changing a field’s type.
• Tightening a validation rule that would reject payloads previously accepted.
• Changing a webhook payload shape or event type.

What we ship freely inside a version

The following are treated as additive and can appear in v1 without notice:

• New endpoints.
• New optional request fields.
• New response fields.
• New content_type or platform values.
• New webhook events. Existing subscriptions will not receive new events until you edit the subscription’s events list.

Write your clients to ignore unknown fields.

Deprecation policy

When a v1 endpoint or field is scheduled for removal in v2, we will:

1. Announce it in the changelog with at least 90 days lead time.
2. Send an email to every workspace with usage of the deprecated surface.
3. Emit a Warning header on responses that use the deprecated surface.

Rollout of a hypothetical v2

Both versions will run in parallel for a minimum of six months. v1 continues to receive security fixes for that entire window.