# Versioning and deprecation

> How the API changes. What counts as a breaking change, how long you get notice, and where to find every change.

Last updated: 2026-10-30. Source: https://docs.smartchat.marketing/en/concepts/versioning/

## Versions

The path has a major version: `/v1`. Inside a major version the API only changes in ways that do not break your code. The date version in the header `SmartChat-Version` (today `2026-10-25`) tells you which state of the API answered.

## What may change without notice (not breaking)

- New fields in answers. Ignore fields you do not know.
- New optional parameters.
- New error codes inside the existing classes (`error_type`). Handle unknown codes by their `error_type`.
- New webhook events and new values in lists that the docs call open.

## What is breaking

Removing a field, changing the meaning of a field, a new required parameter, removing a call or a value you can send. A breaking change is only made in a new major version (`/v2`).

## Deprecation

When a call or field will be removed:

1. It is marked in the [changelog](https://docs.smartchat.marketing/en/changelog/) and on its reference page.
2. Answers carry the headers `Deprecation: true` and `Sunset` (the date of removal).
3. You get at least **6 months** between the announcement and the removal.

## Changelog

Every change is listed in the [changelog](https://docs.smartchat.marketing/en/changelog/), newest first, with the kind of change: `added`, `changed`, `deprecated`, `removed`, `fixed` or `security`. The OpenAPI file is the one description of the API. Before every release it is compared with the last released one; an unannounced breaking change fails that check.