> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.noyax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> API versions, backward compatibility and retiring old versions.

The API version is part of the URL:

```
https://api.noyax.com/api/v1/customers
                         ^^
```

An integration built on a version **does not break** while that version is supported. When a breaking change is needed, a new version (`v2`) is released and the old version keeps working for a while.

## What can change within a version?

The following changes are backward compatible and can be released in the current version without notice. Build your integration to tolerate them:

* New endpoints
* New **optional** request fields
* New response fields (ignore fields you do not recognize)
* Different wording of error messages (base your logic on HTTP status codes, not message text)
* A different order of fields in responses

## What requires a new version?

* Removing or renaming a field or endpoint
* Adding a new **required** field
* Changing the type or meaning of a field
* Making validation rules stricter
* Changing default behavior

## Version lifecycle

| Status         | Meaning                                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| **Active**     | Recommended version. New features are released here                                                            |
| **Deprecated** | Keeps working but gets no new features. The removal date is announced in the [release notes](/en/v1/changelog) |
| **Removed**    | No longer responds                                                                                             |

A version keeps working for **at least 6 months** after it is marked deprecated.

## Headers

Responses from endpoints report the supported versions in the `api-supported-versions` header. When the version you use is deprecated, the `api-deprecated-versions` header is returned too. Watch this header to detect when you need to migrate:

```http theme={null}
api-supported-versions: 1.0
```

## Versions

| Version | Status |
| ------- | ------ |
| `v1`    | Active |