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

# Versioning and deprecation

> How an operation moves from beta to stable, how a deprecation is announced, and how a breaking change ships.

Every operation in the [OpenAPI document](https://api.enrik.ai/v1/openapi.json) states its
stability in `x-stability-level`, and every change to it is in the [changelog](https://docs.enrik.ai/api-reference/changelog.md).
Today every operation is `beta`, and none is deprecated.

## Stability levels

* **`beta`**: the operation may change, or be removed, in place. Every change is a changelog entry
  that says what a client must do. New operations start here.
* **`stable`**: the operation only gains. It may gain an optional request field, a response field, a
  value of an extensible enum (`x-extensible-enum`), a new error code or a new operation beside it.
  Anything else is a breaking change and ships as a new operation (see below). It is removed only
  after a deprecation and its sunset.

Read the document's `x-extensible-enum` values as the ones known today: handle a value you do not
know, and ignore a response field you do not know.

An operation is promoted from `beta` to `stable` on its own, when all of these hold:

1. It has been live for at least 30 days, and its contract has not changed in the last 14.
2. It declares its real error responses and examples.
3. Its main path is covered by an end-to-end test of the API key surface.
4. Its growing vocabularies are extensible enums or open objects.
5. It is documented here: its endpoint page, and a guide when it is part of a multi-step flow.

A promotion is a changelog entry. A stable operation is never demoted to beta.

## Deprecation

An operation on its way out is marked in the OpenAPI document:

* `deprecated: true`;
* `x-deprecated-since`: the day it was deprecated, `YYYY-MM-DD`;
* `x-sunset`: the first day it may be gone, once its removal is scheduled;
* `x-replacement`: the `operationId` of the operation to move to, when there is one.

Every response of a deprecated operation, errors included, carries the same in its headers:

```http theme={null}
Deprecation: @1791504000
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://docs.enrik.ai/api-reference/changelog>; rel="deprecation"; type="text/html"
```

* `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) is the day it was
  deprecated, in seconds since 1970-01-01 UTC.
* `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) is the first day it may be gone.
  It is absent while no removal is scheduled.
* The `deprecation` link points to this changelog, which names the deprecation and what to use
  instead. On the API host it follows the `Link` values every response carries.

A stable operation is deprecated with a sunset at least 183 days after the deprecation reaches
production. A beta operation may be deprecated before its sunset is set. After the sunset, the
operation is removed and its path answers `404`.

To notice a deprecation early, log the `Deprecation` header when a response carries it, and move to
the replacement before the sunset. The [TypeScript SDK](https://docs.enrik.ai/api-reference/typescript-sdk) warns once per
process when it sends a deprecated operation, and its types mark the operation `@deprecated`.

## Breaking changes and /v2

A breaking change to a stable operation ships as a new operation with its own `operationId`, under
`/v2`: for example `companiesV2.list` at `GET /v2/companies`. The `/v1` operation stays as it is,
is deprecated with `x-replacement` naming the new one, and is removed only after its sunset. Both
are in the document at the same time, so you move one call at a time.

## SDK versions

`@enrik/sdk` stays at `0.x` while the API is in beta. It becomes `1.0.0` when the v1 operations
become stable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.