# Versioning and deprecation

> How the Kustomer API is versioned, how deprecations are marked, and how to build clients that keep working as the API grows.

Source: https://developer.kustomer.com/docs/concepts/versioning

The Kustomer API is versioned in the path. Nearly every endpoint is under `/v1`, and it evolves in place by adding to it. A new major version of an endpoint gets a new path, and the old one keeps working alongside it.

## Path versions

| Version | Status                                                        | Example                            |
| ------- | ------------------------------------------------------------- | ---------------------------------- |
| `/v1`   | Current. Almost every endpoint.                               | `GET /v1/customers/{id}`           |
| `/v2`   | Available for specific endpoints whose response changed shape | `GET /v2/conversations/{id}/times` |

The `/v2` endpoints are listed in the [Core resources v2](https://developer.kustomer.com/api/core-resources-v2) reference. When a `/v2` endpoint exists, prefer it for new code.

## Changes you should expect

The API grows without a version bump. Build your client to tolerate these:

- **New endpoints and new optional request fields.**
- **New attributes in responses.** Ignore fields you don't recognize instead of failing validation.
- **New enum values**, such as a new message `channel` or event type. Handle unknown values gracefully, for example by logging and skipping.
- **New event types** on webhooks. Subscribe to the specific events you need, and ignore others.
- **New error `code` values.** Fall back to the HTTP status.

```ts title="Node.js"
// Tolerant parsing: pick what you need, ignore the rest.
const { id, attributes } = body.data
const conversation = {
  id,
  name: attributes.name ?? '',
  status: ['open', 'snoozed', 'done'].includes(attributes.status) ? attributes.status : 'unknown',
}
```

## Deprecation

Deprecated operations are labeled **Deprecated** in the [API reference](https://developer.kustomer.com/api). They keep working, but new integrations shouldn't use them. Check the operation's description for the recommended alternative.

Changes and deprecations are announced in the [changelog](https://developer.kustomer.com/changelog), which you can also read as [Markdown](https://developer.kustomer.com/changelog.md).

## Other versioned surfaces

| Surface                                                                          | How it's versioned                                                                        |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [Chat SDKs](https://developer.kustomer.com/docs/chat)                            | Semantic versions per platform, distributed through npm, Swift Package Manager and Maven. |
| [Apps](https://developer.kustomer.com/docs/apps/versioning)                      | Each app definition has a `version`. Orgs upgrade installed apps to new versions.         |
| [Webhook payloads](https://developer.kustomer.com/docs/events/outbound-webhooks) | Follow the API's resource shapes, so the same tolerance rules apply.                      |