---
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-10-10
---

# 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`.

## 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. When one is, it is flagged in the OpenAPI document and on every one of its responses.

## 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)