# Versioning and deprecation

> What version 1 may and may not change, and how long a version is kept once the next one ships.

Source: https://developers-staging.foodpilot.tech/build/app-api/versioning

In this page you will learn which changes to expect inside version 1, and what the platform promises before it removes anything.

## The contract

Version 1 of the App API and of the webhooks is a **frozen contract**: the OpenAPI document of `/api/app/v1` and one JSON Schema per webhook topic. The platform checks every change of its code against them, and refuses a change that breaks them. You can [download the OpenAPI document](/openapi-3.0.json) and generate your client from it.

## What can change inside version 1

Only additions:

- a new operation, a new optional parameter, a new field in an answer or in a webhook's `data`, a new value in a documented list of values;
- a new webhook topic, a new scope, a new extension slot.

So your code must ignore a field it does not know, accept a value it does not know, and not rely on the order of fields.

## What does not change

Within version 1, nothing is removed, renamed or made stricter: no operation, field or topic disappears, no type becomes narrower, no optional input becomes required. A change of that kind is a version 2, on a new path (`/api/app/v2`) with its own envelope version.

## Deprecation

- A version 2 does not remove version 1. Version 1 is kept for **12 months** after version 2 ships.
- A deprecated operation answers `Deprecation` and `Sunset` headers, so your client can notice before the day.
- Publishers are told by email, through the partner space, when a deprecation starts.
