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

# Versioning

> What can change inside /v1, and how breaking changes are announced.

The major version is in the path: every endpoint sits under `/v1`, apart from API key management.
The release version, for example `0.1.0`, is `info.version` in the
[OpenAPI spec](https://lean.mintlify.site/api-reference/openapi.json), and each release is listed in the
[changelog](https://docs.lean.xyz/changelog.md).

## Changes that ship inside /v1

These are additive. They can arrive in any release with no notice, so write clients that
tolerate them:

* New endpoints.
* New optional request fields and query parameters.
* New fields in responses, including inside `error.details`.
* New values in open ended codes: `warnings[].code`, `details.reason`, `details.venue_code` and
  `status_reason.code`.
* New venues in order and preview `legs`, `balances` and `positions`.

Ignore fields you do not recognize. Treat an unknown code by its HTTP status, and an unknown venue
like any other venue.

## Breaking changes

A breaking change removes or renames a field, changes a field's type or meaning, makes an optional
field required, or changes the HTTP status or `error.code` of an existing case.

* **During the 0.x preview**, a breaking change can still ship inside `/v1`. Each one is listed in
  the changelog with the date it takes effect, and announced ahead of that date whenever possible.
* **From 1.0**, breaking changes ship only in a new path version such as `/v2`.

In every version, removing an endpoint or field follows [Deprecation](#deprecation).

## Deprecation

Removing an endpoint or field starts with a deprecation notice. It is removed at least 90 days
after the notice, never sooner. The notice is given in two places:

* An entry in the [changelog](https://docs.lean.xyz/changelog.md) naming what is deprecated, what replaces it, and the
  removal date.
* `Deprecation` and `Sunset` headers on every response from the affected endpoint. `Sunset` is the
  removal date. Watch for both headers in your client logs.

## Generated clients

The [TypeScript SDK](https://docs.lean.xyz/typescript-sdk.md), the [Rust SDK](https://docs.lean.xyz/rust-sdk.md), the Python SDK and the Postman collection are generated from the OpenAPI spec of
each release, so they always match it. Regenerate your own clients from the same spec.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.