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

# Versioning & Deprecation Policy

> The commitments behind API version lifecycles

<Info>
  **Quick Summary:** Majors are URL-versioned. Inside a major, changes are additive-only. A retiring major gets a written notice period, machine-readable deprecation headers on every response, and a hard sunset date — after which it answers 410.
</Info>

<Warning>
  The support and notice windows below are pending final Product sign-off and will be confirmed before v1 general availability.
</Warning>

## The policy

| Commitment                 | Rule                                                                                                                                                                       |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Version scheme             | Major version in the URL (`/api/v1/`). No date-based or header-based versioning.                                                                                           |
| Inside a major             | Additive-only. Adding endpoints, optional request fields, response fields and enum values is allowed at any time.                                                          |
| Breaking change definition | Removing or renaming a path, parameter or field; changing a type; narrowing an enum; making something optional required; changing a status code; renaming an operation id. |
| Support window             | A deprecated major keeps working for **12 months** after its successor ships *(pending sign-off)*.                                                                         |
| Notice period              | Deprecation is announced at least **6 months** before sunset *(pending sign-off)*.                                                                                         |
| Machine-readable signals   | Every response of a deprecated version carries `Deprecation` (RFC 9745), `Sunset` (RFC 8594) and `Link rel="deprecation"` headers.                                         |
| After sunset               | Every route of the version returns 410 [version-gone](/api-docs/errors/version-gone) with a migration link.                                                                |
| Rate limit changes         | Allowance reductions are announced to credential holders with lead time; increases may happen at any time.                                                                 |

## What you should build

Log a warning whenever a response carries a `Deprecation` header. That single line of client code converts every future migration from a surprise into a scheduled task.