# Versioning

What can change in v1 and what never will, and how to write code that keeps working as the API grows.

The version is in every path: `/v1`. Everything you build on v1 keeps working for as long as v1 exists.

## What v1 may add

v1 only grows. Within it, we may add:

- new endpoints and new events;
- new optional fields in what you send;
- new fields in what we answer;
- new values in a list of values, like a new order status or a new error code.

So read answers loosely: ignore fields you do not know, and treat an unknown value as "something else" rather than an error. The SDKs already do both: an unknown field is kept aside and an unknown value is kept as it came.

## What v1 never does

- remove or rename a field;
- change a field's type, unit or meaning;
- make an optional field required, or refuse something it accepted;
- change the error code of a situation.

Anything that needs one of these waits for a v2, which will run beside v1 for a long time before v1 ends.

## Seeing the version

`GET /v1` answers the exact version of the API (`1.MINOR.PATCH`), and so does `info.version` in the [OpenAPI document](https://docs.phoenixperpsfunding.com/openapi.json). The SDKs' major version is the API's: every SDK 1.x speaks `/v1`.
