# Versioning and deprecations

What may change inside /v1, how you hear about it, and how a /v2 would run alongside.

> **In a nutshell:** Inside /v1 PaalChat only adds - new endpoints, optional fields, response fields, events and error codes. Anything that would break you waits for /v2. Deprecated endpoints keep working for at least six months and say so in Deprecation and Sunset headers.

Every response carries `X-PaalChat-API-Version: v1`. The version is in the URL
(`/api/v1/...`), so nothing changes under you without a new URL.

## What may change inside v1

These are **not** breaking, and may happen at any time - build your client to tolerate them:

- New endpoints, and new optional request fields or query parameters.
- New fields in responses and in callback `data` (ignore fields you don't know).
- New callback events (endpoints only get the events they subscribe to - or all, if
  they subscribe to none, so ignore event names you don't know).
- New `error.code` values (handle unknown codes by their HTTP status).
- New values in documented open lists - for example message `type`, a template's
  `status`, or `whatsapp.connection` events.
- Longer limits (larger maximum lengths, higher rate limits).

## What waits for a new version

These would break existing clients, so they only happen in `/v2`:

- Removing or renaming an endpoint, a field or an event.
- Changing a field's type or meaning, or making an optional field required.
- Changing the error envelope, authentication, or callback signing.
- Narrowing what is accepted (shorter limits, stricter formats) where valid calls
  would start failing.

## Deprecations

When something in `/v1` is to go away (because `/v2` has a better way):

1. It is announced in the [changelog](/docs/changelog) and marked deprecated in the
   [API reference](/docs/api).
2. Its responses carry `Deprecation` (when it was deprecated), `Sunset` (when it stops
   working) and a `Link` to the migration notes. Log these headers in your client.
3. It keeps working for **at least six months** after the announcement.

## A new version

`/v2` would run **alongside** `/v1`, with the same keys, businesses and data - you move
endpoint by endpoint. `/v1` stays available for at least twelve months after `/v2`
is released, and its sunset date is announced at least six months ahead.