# Versioning

> Code you write against `/v2` keeps working: anything that would break it comes as a new version, announced first.

Source: https://developers.mnml.ai/docs/versioning

## What can change in v2

Within `/v2`, changes are additive: a new endpoint, a new optional field in a request, a new field in an answer, a new engine, a new value in a list such as `mode` or a job’s `error.code`. Write your code to ignore fields it does not know and to handle a value it has not seen.

## What would need v3

Removing or renaming a field, changing its type, making an optional field required, or changing what a status code means. Any of these comes as `/v3`, alongside `/v2`, never as a quiet change to `/v2`.

## How a retirement is announced

A route on its way out answers with `Deprecation: true`, a `Sunset` date once one is set, and a `Link` to what replaces it, and the [changelog](https://developers.mnml.ai/changelog) says so.

## The contract

The API describes itself at `https://api.mnml.ai/v2/openapi.json`. The reference on this site is generated from that file, so a field the docs show is one the server takes. Engines and prices are data, not version changes: read them from [GET /v2/engines](https://developers.mnml.ai/docs/engines) rather than hard-coding them.