---
title: Vooks API deprecation and sunset policy
description: When the Vooks Public Catalog API can break, how much warning you get, and the headers that announce it.
canonical: https://www.vooks.com/deprecation-policy
last-updated: 2026-11-04
source: https://www.vooks.com/llms.txt
---

# Deprecation and sunset policy

This is the promise the Vooks Public Catalog API makes about when things change. It is
a commitment, not a description of current intent.

## Versioning

The major version is in the path: `https://www.vooks.com/api/v1`.

Within a major version, fields are only ever **added**, never removed and never
retyped. Parse defensively and ignore what you do not recognise, and a `v1` integration
written today keeps working.

## What counts as breaking

Removing a field, changing its type, changing the meaning of an existing value, removing
an endpoint, or making an optional parameter required. Any of these ships as a new major
version at `/api/v2`. The old version is never changed in place.

## The guarantee

- When `/api/v2` ships, `/api/v1` begins returning a **`Deprecation`** header
  ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html)) giving the date it was
  deprecated.
- It also returns a **`Sunset`** header
  ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)) giving the date it stops
  serving.
- `/api/v1` keeps serving for **at least 180 days** after that `Deprecation` header
  first appears. We will not shorten that window.
- Every response carries `Link: <https://www.vooks.com/deprecation-policy>;
  rel="deprecation"`, so this page is reachable from any response without reading docs.

## How to watch for it

```bash
curl -sI https://www.vooks.com/api/v1 | grep -iE '^(deprecation|sunset)'
```

Empty output means the version you are calling has no retirement date.

**No version has been deprecated to date.** The absence of those two headers is itself
the signal that `/api/v1` is current.

## Status codes on a retired version

After the sunset date, `/api/v1` answers `410 Gone` with an RFC 9457 problem document
whose `code` is `version_retired` and whose `detail` names the current version. It does
not silently redirect, because an agent that followed a redirect to a different shape
would parse a response it was not written for.

## Elsewhere

- [Developer guide](https://www.vooks.com/developers)
- [OpenAPI 3.1 description](https://www.vooks.com/openapi.json)