# One Care Portal API Versioning and Deprecation Policy

## Stable versions

Public API versions appear in the URL, such as `/api/v1/`. Backward-compatible additions may ship within a version. Breaking request or response changes require a new major URL version.

## Deprecation notice

One Care Portal provides at least 180 days of notice before retiring a stable public API version. Deprecated responses use the HTTP `Deprecation` header and a `Link` relation to migration documentation. Once a retirement date is set, responses also include the HTTP `Sunset` header.

## Migration

The OpenAPI specification identifies deprecated operations and successor versions. After sunset, retired endpoints return HTTP 410 with an RFC 9457 JSON problem containing a successor link and resolution hint.

## Current status

`v1` is current. The legacy `/api/ai` alias remains supported and links to `/api/v1/catalog`; no retirement date is currently scheduled.