# Versioning

Source: https://docs.foodshot.ai/policies/versioning

> How the API changes, and how much notice you get.

The version is part of the path: every path starts with `/v1`.

## Our rules

* **Changes within /v1 are additive.** We add, we don't break.
* **A new engine ships as an opt-in /v2.** When FoodShot moves to a new image engine, it comes as a new version that you choose to move to. v1 keeps working.
* **At least 90 days' notice** before a version is retired.
* **One exception.** If the engine behind v1 is retired upstream, v1 moves to the closest equivalent, tested on a fixed photo set, with as much notice as we get.
* **Styles** get at least 30 days' notice before they are retired, in their `retires_at` field.
* **How we tell you.** We email your technical contact about every change that needs your attention, with the notice periods above.

## What can change within v1

We may add endpoints, optional request fields, response fields, event types, error codes, styles and style categories, and raise limits.

We won't remove or rename a field, an endpoint or an event type, change what a field means, or make an optional request field required.

We may add values to these fields:

* `error.code`, for errors and for failed generations;
* `delivery.status` of a generation;
* `angle` and `category` of a style;
* `kind` of a credit lot;
* `type` of a webhook event.

These stay as they are: a generation's `status`, `environment`, `output.content_type` and `object`.

Build for it:

* Ignore response fields you don't know.
* Answer `2xx` to webhook event types you don't know.
* Handle an unknown error code by its HTTP status, and an unknown failure code like `generation_failed`.
* Accept unknown values in the fields above, for example with a default.