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

# Versioning and changes

> How the Mage API changes over time: what ships within v1, what waits for v2, how deprecations are announced, and what a client must tolerate.

The version is in the path: every endpoint lives under `/v1`. Within a version, changes are additive; a change that would break an existing client ships as a new version while the old one keeps working.

## What ships within a version

* New endpoints.
* New optional request fields, and new option tokens on existing fields.
* New response fields, and new models in the catalog.
* New error codes.

## What waits for a new version

* Removing or renaming a field, an endpoint, or a status.
* Changing a field's type or meaning.
* Tightening validation so that a request that was accepted is refused.

## What a client must tolerate

* Ignore response fields you do not know.
* Treat an error code you do not know by its HTTP status.
* Expect the catalog to change: models appear when they launch, and a retired one answers `410 architecture_retired`.
* The set of statuses is fixed within a version.

## Deprecation

When a version is scheduled to retire, its responses carry `Deprecation` and `Sunset` headers for at least six months before the date, and the date is announced in the [release notes](/release-notes). Nothing is deprecated today.