> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/api-v1/versioning.md).

# Versioning

API v1 is versioned **in the path**: every endpoint lives under `https://swapper.finance/api/v1`. The version you call is the contract you get.

## What stays stable within v1

Breaking changes are only ever made in a **new version** (`/v2`, …), which would run alongside v1. Within v1, Swapper will not:

* remove or rename an endpoint, parameter, or response field;
* change the type or meaning of an existing field;
* make an optional parameter required;
* rename or repurpose an existing [error code](https://docs.swapper.finance/api-v1/errors.md).

## What can change within v1

**Additive changes** ship within v1 without notice:

* new response fields;
* new optional parameters;
* new endpoints;
* new [error codes](https://docs.swapper.finance/api-v1/errors.md);
* new chains and tokens in the catalog.

Build your client to tolerate them:

* **ignore fields you don't recognize** — don't fail on, or strictly validate against, unknown JSON properties;
* treat an **unknown error code** by its HTTP status class;
* don't hard-code the chain or token list — read it from [`/v1/chains` and `/v1/tokens`](https://docs.swapper.finance/api-v1/endpoints/chains-and-tokens.md).

## Deprecation policy

When something in v1 is going to be retired:

* responses from the affected endpoint carry a **`Deprecation`** header, and a **`Sunset`** header with the date it stops working;
* the change is announced in these docs;
* you get **at least 6 months' notice** between the announcement and the sunset date.

Watch for these headers in your logs or monitoring so a deprecation never surprises you.

## Checking the version

`GET https://swapper.finance/api/v1` returns:

```json
{ "version": "v1" }
```
