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

# Versioning & deprecation

> How the Crevio API is versioned, what we promise not to break, and how a deprecation is announced — the Deprecation and Sunset response headers, and the timeline behind them.

**Crevio versions its API in the URL path, and never removes anything without announcing it in the response itself.** An integration written against `/v1` today keeps working; when something is on its way out, the responses tell you before the docs do.

## The version is in the path

Every REST endpoint lives under a version prefix:

```
https://api.crevio.co/v1/products
```

There is one live version, `v1`. The [MCP server](/docs/developer/mcp/connection) and the [`@crevio/sdk`](/docs/developer/guides/sdk) client speak the same version — the SDK pins it for you.

## What is a breaking change

We treat these as breaking, and they only ship in a new version prefix:

* Removing an endpoint, a field, or an enum value
* Renaming an endpoint, a field, or an `operationId`
* Making an optional request field required, or narrowing an accepted type
* Changing the type or meaning of an existing response field
* Removing or repurposing a webhook event

These are **not** breaking, and can ship to `v1` at any time — write clients that tolerate them:

* Adding a new endpoint, an optional request field, or a response field
* Adding a new enum value to a field already documented as extensible
* Adding a new webhook event type
* Changing the wording of an error `message` (the `type` and `code` are stable)
* Changing the ordering of results where no order is documented

<Tip>
  Ignore response fields you do not recognise rather than failing on them. The
  SDK already does this.
</Tip>

## How a deprecation is announced

When an endpoint or field is scheduled for removal, every response from it carries two standard headers:

| Header        | Meaning                                                                                                                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Deprecation` | A structured-field date ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) — an `@` followed by a Unix timestamp — marking when the resource became deprecated. Its presence alone is the signal. |
| `Sunset`      | An HTTP date ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) after which the resource stops responding.                                                                                        |
| `Link`        | A `rel="deprecation"` link to the documentation explaining the replacement.                                                                                                                         |

```http theme={null}
HTTP/1.1 200 OK
Deprecation: @1775001600
Sunset: Thu, 01 Oct 2026 00:00:00 GMT
Link: <https://crevio.co/docs/developer/guides/versioning>; rel="deprecation"
```

The guarantee: **at least six months between `Deprecation` and `Sunset`**, and the replacement is live and documented before the `Deprecation` header appears. Nothing is removed without both headers having been served for that whole window.

<Warning>
  Agents and long-running integrations should log the presence of a `Deprecation`
  header and surface it. It is the only warning you get that is delivered in-band.
</Warning>

## Checking programmatically

```bash theme={null}
curl -sI https://api.crevio.co/v1/products \
  -H "Authorization: Bearer $CREVIO_API_KEY" \
  | grep -iE 'deprecation|sunset'
```

No output means nothing you are calling is scheduled for removal.

## Machine-readable surfaces

The [OpenAPI description](/docs/developer/guides/api-overview) marks a deprecated operation or field with `"deprecated": true` before the header ever appears, so a generated client can warn at build time:

```
https://crevio.co/docs/developer/api-reference/openapi.json
```