---
title: "Deprecation policy"
description: "Which API changes need a new version, which do not, and where each change is listed."
url: https://docs.fluveo.com/start/deprecation/
---

> Index of every page: https://docs.fluveo.com/llms.txt. Integrating Fluveo? Read https://docs.fluveo.com/agents/integrate.md first.

# Deprecation policy

Which API changes need a new version, which do not, and where each change is listed.

The `/v1` API is versioned by date, and Fluveo serves one version today: `2026-05-27.dahlia` ([Versioning](https://docs.fluveo.com/start/versioning.md)). This page says which changes can land inside that version, which need a new one, and where Fluveo lists each change.

## What needs a new version

Removing something the API serves, or changing the shape of what it returns, needs a new version. The two exceptions are a correction toward the version's own shape and the removal of something the version does not define, both explained below. The additions listed in the table can land inside the version.

| Change | Where it can land |
| --- | --- |
| A new operation | Inside `2026-05-27.dahlia` |
| A new optional parameter of an operation | Inside `2026-05-27.dahlia` |
| A new optional field of an object | Inside `2026-05-27.dahlia` |
| A new response status of an operation, such as a success answer where the operation only refused before | Inside `2026-05-27.dahlia` |
| The expanded object of a field that `expand[]` did not expand before | Inside `2026-05-27.dahlia` |
| A correction that brings an answer in line with the shape `2026-05-27.dahlia` defines | Inside `2026-05-27.dahlia`, see [Corrections](https://docs.fluveo.com/start/deprecation.md#corrections) |
| Removing an operation, a parameter or a field that `2026-05-27.dahlia` does not define | Inside `2026-05-27.dahlia`, see [Additions outside the version](https://docs.fluveo.com/start/deprecation.md#outside) |
| Removing any other operation, parameter, field or response status | Only in a new version |
| Changing the shape of a field or an object in any other way | Only in a new version |

## Corrections

`2026-05-27.dahlia` defines a shape for every object and every answer. Where a Fluveo answer still differs from that shape, Fluveo can correct it inside the version, even when the correction changes an answer your code reads. A correction changes only the place where the answer differed, and never adds a new difference.

## Additions outside the version

Fluveo serves a few operations, parameters and fields that `2026-05-27.dahlia` does not define. One of them leaves the API only by a decision Fluveo records, and it can leave inside the version.

## Where changes are listed

Fluveo lists changes to the API and to these docs in the [changelog](https://docs.fluveo.com/changelog.md), under the day each one landed, in UTC.

## Write code that additions do not break

- Read the fields your code needs and ignore every field it does not know. An object can gain an optional field inside the version.
- Judge an answer by its status class first: `2xx` is a success, `4xx` and `5xx` are errors. An operation can gain a response status inside the version.
- Decide what to do from `error.code`, or from `error.type` when `code` is null. Never parse `error.message`.
- A webhook endpoint with `enabled_events[]=*` receives every event type. Answer `2xx` to a type your code does not handle, and take no other action for it ([Webhooks](https://docs.fluveo.com/webhooks.md#respond)).

> **For AI agents:**
>
> Ignore unknown fields in any object. Treat any 2xx as success. Branch on error.code, or on error.type when code is null, never on error.message. Answer 2xx to an event type you do not handle.

## Next

- [Changelog](https://docs.fluveo.com/changelog.md): Read what changed in the API and in these docs, by date.
- [Versioning](https://docs.fluveo.com/start/versioning.md): Learn which API version answers your requests.