---
title: "API versioning and deprecation policy"
description: "How the Linkbreakers REST API is versioned, which changes ship within v1, and how an operation is retired: at least 180 days of notice through Deprecation and Sunset headers and the OpenAPI document."
canonical: "https://linkbreakers.com/help/article/api-versioning-and-deprecation-policy"
last-updated: 2026-11-16
---

# API versioning and deprecation policy

> How the Linkbreakers REST API is versioned, which changes ship within v1, and how an operation is retired: at least 180 days of notice through Deprecation and Sunset headers and the OpenAPI document.

## Short answer

The Linkbreakers REST API is versioned in the URL path (`/v1`). Within a version we only make additive changes. When an operation has to go, we deprecate it first, announce it in the responses themselves, and keep it working for at least **180 days**.

## Quick summary

- The version is part of the path: `https://api.linkbreakers.com/v1/...`
- Within `v1`, changes are additive only. Clients should ignore unknown fields and enum values
- Breaking changes ship under a new path version (`/v2`), never inside `v1`
- A deprecated operation keeps working for at least 180 days and says so on every response with `Deprecation`, `Sunset` and `Link` header fields
- The OpenAPI document marks it `deprecated: true` with `x-deprecated-on`, `x-sunset` and `x-successor`

## What counts as non-breaking

These can ship within `v1` at any time:

- New operations
- New optional request fields and query parameters
- New fields in responses
- New enum values
- New error codes for new failure cases
- Relaxed validation

Write clients that ignore fields and enum values they do not know, so these changes never break them.

## What counts as breaking

These never ship within `v1`:

- Removing or renaming an operation, field or enum value
- Making an optional field required
- Changing a field's type or meaning
- Tightening validation for requests that are valid today

They ship under a new path version (`/v2`), and the `v1` operations they replace follow the deprecation process below.

## How an operation is retired

### 1. Deprecation

The operation keeps working. In the [OpenAPI document](https://api.linkbreakers.com/openapi.json) it is marked `deprecated: true`, with:

- `x-deprecated-on`: the date it was deprecated
- `x-sunset`: the earliest date it may stop working
- `x-successor`: the operation to move to

Every response from it carries:

```http
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://linkbreakers.com/help/article/api-versioning-and-deprecation-policy>; rel="deprecation"
```

`Deprecation` follows RFC 9745 (a Unix timestamp), `Sunset` follows RFC 8594 (an HTTP date) and `Link` points to this page.

### 2. Sunset

The sunset date is at least 180 days after the deprecation date, and it is known from the first deprecated response. After it, the operation may answer `410 Gone`.

## Renamed paths

When an operation's path is renamed, the former path keeps answering as an alias with the same `Deprecation`, `Sunset` and `Link` header fields, and the service's own OpenAPI document flags it deprecated with `x-sunset` and `x-successor`. The public OpenAPI document names only the current path.

A former path stays only while someone uses it. One that no client calls for 14 days is removed, even before its sunset date, and a path nobody called in the 14 days before the rename never gets an alias at all.

No former path answers today. The paths renamed on 2026-11-15 and 2026-11-16, such as `POST /v1/visitor/identify` (now `POST /v1/visitors:identify`) and `GET /v1/allowances` (now `GET /v1/workspace/usage`), had no outside caller left and were removed; each SDK's changelog lists them.

Operation names (the `operationId` of each operation, which the SDKs and the CLI name their methods and commands after) were renamed on 2026-11-15 too, for example `AllowancesService_ListAllowances` became `PlanUsageService_List`, since moved to `WorkspacesService_GetUsage`. Each SDK's changelog lists them under release 1.198.1.

## Removed with no outside caller

The same traffic rule applies to whole operations and fields: when nobody outside called something in the last 14 days, it is removed rather than deprecated.

| Removed on | What | Use instead |
|---|---|---|
| 2026-11-16 | `POST /v1/media`, the upload that took the file base64 in the request (MCP `media_create`) | `POST /v1/media/uploads`, a `PUT` to the returned URL, then `POST /v1/media/{id}:complete` ([how](https://linkbreakers.com/help/article/manage-media-through-the-api-and-mcp)) |
| 2026-11-16 | `centralImageData` on `POST /v1/qrcode-designs` and `PATCH /v1/qrcode-designs/{id}`, the logo base64 in the request | `centralImageMediaId`: an image of your media library, or a public upload (`POST /v1/media/public-uploads`) for a design created without a token |

A file reaches Linkbreakers one way, uploaded straight to storage, and every field that takes a file takes the media id that upload gives.

## SDKs

The [SDKs](https://linkbreakers.com/help/article/linkbreakers-developer-ecosystem-overview) are generated from the OpenAPI document, so a deprecated operation is marked deprecated in each language.

## How to stay ahead

- Log or alert on any response that carries a `Deprecation` header field
- Read `info.x-api-versioning` in the OpenAPI document: it states the strategy, the current version and the minimum notice in days
- Check `deprecated: true` operations in the OpenAPI document when you upgrade an SDK

## Limits and caveats

- The 180 days are a minimum. A deprecation can run longer, never shorter
- The policy covers the operations in the OpenAPI document

## Frequently asked questions

### Will v1 be turned off?

Not without a v2 to move to and at least 180 days of notice through the headers above.

### Are new response fields a breaking change?

No. New fields can appear in any response at any time. Ignore the ones you do not use.

### Is any operation deprecated today?

No. No operation is deprecated and no former path answers today. When one is, it is flagged in the OpenAPI document and on every one of its responses, and listed under [Renamed paths](#renamed-paths).

## Related

- [REST API documentation](https://linkbreakers.com/developers)
- [How to use the Linkbreakers API](https://linkbreakers.com/help/article/how-to-use-the-linkbreakers-api)
- [API token scopes](https://linkbreakers.com/help/article/api-token-scopes)
