> ## Documentation Index
> Fetch the complete documentation index at: https://www.fluenterp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and deprecation

> What can change under /api/v1, and how Fluent announces a removal.

## Versioning

The major version is in the URL path:

```text theme={null}
https://www.fluenterp.com/api/v1
```

`v1` is a compatibility boundary. Within it, Fluent may:

* add a new endpoint,
* add an optional request parameter or body field,
* add a field to a response object,
* add a value to a non-exhaustive enumeration such as a document type.

Within `v1`, Fluent will not remove or rename a response field, make an optional request field required, change a field's type, or change the meaning of an existing status code. A change that cannot be made additively ships as a new major version — `/api/v2` — and `v1` keeps working.

Clients should ignore response fields they do not recognize, and should not infer database structure from flexible record or document payloads.

## Deprecation

When an endpoint or a field is going away, Fluent announces it in three places:

1. The affected responses carry [`Deprecation`](https://www.rfc-editor.org/rfc/rfc9745.html) and [`Sunset`](https://www.rfc-editor.org/rfc/rfc8594.html) headers.
2. The OpenAPI description marks the operation `deprecated: true`.
3. The change is described in these docs, alongside the replacement.

```http theme={null}
Deprecation: @1793491200
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: <https://www.fluenterp.com/docs/api-reference/versioning>; rel="deprecation"
```

`Deprecation` is the moment the endpoint became deprecated — it may be in the past. `Sunset` is the moment it stops answering. There are **at least 180 days** between the two for any endpoint in `v1`, so an integration that reads these headers always has a full quarter and more to migrate.

No endpoint in `/api/v1` is currently deprecated. An agent can confirm that programmatically: the [API index](https://www.fluenterp.com/api/v1) reports the current version and the deprecation conventions, and responses carry no `Sunset` header.

<Tip>
  Log `Deprecation` and `Sunset` alongside your rate-limit headers. Both are
  plain response headers, so noticing them costs nothing and removes the only
  class of breakage that arrives without warning.
</Tip>