# Versioning

Source: https://docs.revoplyai.com/get-started/versioning/

> What we may change without notice, what counts as breaking, and how webhook payload versions and the REST API version work.

## Changes that are not breaking [#changes-that-are-not-breaking]

These can happen at any time, without a new version. Write your integration so it
tolerates them:

* new fields in an event, a response or an object inside them;
* new event types (you receive only the types an endpoint subscribes to);
* new values in a vocabulary: `channelType`, a handover `reason`, a flow run's `endReason`,
  a flow trigger `status`;
* new optional request headers or fields;
* different wording in `detail` and other text meant for people. Branch on codes, never on
  text.

## Webhook payload versions [#webhook-payload-versions]

Every event carries `apiVersion`, the shape of its `data`. The current version is
`2026-10`.

* A change a receiver could misread (a field removed, renamed or given another meaning)
  gets a new dated version.
* A new version is opt-in per endpoint: an endpoint keeps receiving the version it has
  until you move it.
* An old version keeps being sent for at least six months after the new one is
  published, and its retirement is announced.

## The REST API [#the-rest-api]

The REST API, when it is published, is versioned in its path: `https://api.revoplyai.com/v1`.

* A breaking change is released as a new major version (`/v2`), never into `/v1`.
* A new major version is announced at least 90 days in advance, and the previous version
  keeps working for at least six months after the new one is released.
* Responses from a version being retired carry `Deprecation` and `Sunset` headers.

## Notice [#notice]

Deprecations and new versions are announced in the [changelog](/resources/changelog/) and
emailed to account owners whose integrations are affected.