---
title: "Versioning and deprecation policy"
description: "How the Flowie Exchange API changes over time: additive versus breaking changes, the /v2 rule, Sunset headers and the 12-month deprecation window."
canonical: "https://docs.get-flowie.com/deprecation-policy.md"
---

# Versioning and deprecation policy — Flowie Exchange API

How the Flowie Exchange API changes over time, and what you can rely on when you
build against it.

Contract: <https://docs.get-flowie.com/openapi.json> · Developer portal:
<https://docs.get-flowie.com/developers.md>

## Versioning

The API is versioned in the URL path. **`/v1` is current and stable.**

- **Breaking changes ship as a new path version** (`/v2`), never by mutating an
  existing one. A client pinned to `/v1` keeps working.
- **Additive changes land within a version.** New optional request fields, new
  response fields and new endpoints can appear in `/v1` at any time.

### What counts as breaking

Removing an endpoint, field or enum value; renaming any of them; making an
optional request field required; narrowing an accepted type; or changing the
meaning of an existing value.

### What does not count as breaking

Adding an endpoint; adding an optional request field; adding a response field or
a new enum value; relaxing a validation rule; performance and infrastructure
changes.

**Parse defensively.** Ignore response fields you do not recognise and do not
treat an unknown enum value as an error — that is the single most common way an
integration breaks on a change that is additive by design.

## Deprecation

When an operation or field is to be retired:

1. It is marked `deprecated: true` in the OpenAPI contract, so any generated
   client and any agent reading the spec can see it without reading prose.
2. The change is recorded in the changelog: <https://docs.get-flowie.com/changelog.md>
3. The replacement is documented alongside it. A deprecation notice always names
   what to use instead.
4. Advance notice is given in the changelog before a version is retired. Nothing
   in `/v1` is removed without that notice appearing first.

Deprecated does not mean broken: a deprecated operation keeps working while it
carries the marker.

> **Note for the API owner:** this page deliberately states no fixed notice
> period (for example "12 months"), because that is a commercial commitment
> rather than a technical fact. If Flowie wants to publish a specific guarantee,
> add it to step 4 — the rest of this page already reflects how the API behaves.

## How to track changes

| What | Where |
|---|---|
| Machine-readable contract | <https://docs.get-flowie.com/openapi.json> |
| Changelog | <https://docs.get-flowie.com/changelog.md> |
| Full docs corpus for agents | <https://docs.get-flowie.com/llms-full.txt> |
| Service status | <https://flowie.betteruptime.com/> |

The most reliable way to detect a change is to diff `openapi.json` in CI rather
than to watch this page. Deprecations appear there first, and an agent can read
the `deprecated` flag directly.

## Questions

support@flowie.fr — include the `X-Request-Id` from any affected response.