# API Versioning and Deprecation Policy

Source: https://wraps.dev/docs/reference/versioning

What you can rely on staying put, what can change under you, and how much warning you get before anything is removed.

## How the API is versioned

Copy for AI

The Wraps Platform API is versioned in the URL. The current version is served at `https://api.wraps.dev` and described by the [OpenAPI document](https://api.wraps.dev/swagger/json), whose `info.version` names the version you are reading.

A breaking change ships as a new version at a new path. The old version keeps working for the notice period below — it is never changed underneath you.

## What counts as a breaking change

Copy for AI

These ship only in a new version:

-   Removing an endpoint, or changing its path or method
-   Removing a field from a response, or changing its type
-   Adding a required request field, or making an optional one required
-   Narrowing an accepted value — tightening a format, dropping an enum member
-   Changing the status code or error \`code\` a given failure returns
-   Changing authentication or the scopes an endpoint requires

## What does not count as a breaking change

Copy for AI

These ship into the current version at any time, so build a client that tolerates them:

-   Adding a new endpoint
-   Adding an optional request field
-   Adding a field to a response — always parse responses permissively
-   Adding a new value to an enum you only read (never one you match exhaustively on)
-   Adding a response header
-   Changing the prose of an \`error\` message, while its \`code\` stays put

## How a deprecation is signaled

Copy for AI

A deprecated endpoint keeps working and starts announcing itself on every response.

| Header | Meaning |
| --- | --- |
| `Deprecation` | An HTTP date (RFC 9745). The endpoint is deprecated as of this moment. |
| `Sunset` | An HTTP date (RFC 8594). The endpoint stops responding after it. |
| `Link; rel="deprecation"` | This page, explaining the policy. |
| `Link; rel="successor-version"` | What to call instead, when there is a direct replacement. |

response headers

```
HTTP/1.1 200 OKDeprecation: Sat, 01 Aug 2026 00:00:00 GMTSunset: Sun, 01 Aug 2027 00:00:00 GMTLink: <https://wraps.dev/docs/reference/versioning>; rel="deprecation"; type="text/html"Link: <https://api.wraps.dev/contacts>; rel="successor-version"
```

The same endpoints are marked `deprecated: true` in the OpenAPI document, so a generated client sees it at build time rather than at runtime.

## Notice periods

Copy for AI

| Change | Minimum notice |
| --- | --- |
| Endpoint or field deprecation | 6 months between the `Deprecation` date and the `Sunset` date |
| Security fix that must break a contract | As much notice as the vulnerability allows, announced to affected organizations directly |

Deprecations are announced in the [changelog](https://wraps.dev/changelog) and emailed to organization owners. Nothing is removed without a `Sunset` date having passed.

## What an integration should do

Copy for AI

-   Read `code`, not `error`, when branching on a failure. The `code` values are stable and enumerated in the OpenAPI document; the prose is not.
-   Ignore response fields you do not recognize instead of rejecting the response.
-   Log the `Deprecation` and `Sunset` headers if they appear. That is the only signal that arrives before something you depend on stops working.
-   Pin the OpenAPI document you generate clients from, and re-generate deliberately.

[Error codes](https://wraps.dev/docs/reference/errors) [Rate limits](https://wraps.dev/docs/reference/rate-limits) [API reference](https://wraps.dev/docs/reference/api)