# API compatibility and deprecation

> Build tolerant v1 clients and understand additive changes, previews, deprecation notices, and support windows.

Canonical guide: <https://api.blackpearl.com/docs/versioning>

Raw Markdown: <https://api.blackpearl.com/docs/raw/versioning.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

## The v1 compatibility boundary

`/v1` is the public API version. Every OpenAPI operation carries `x-stability: ga` or `x-stability: preview`; stability is classified per operation rather than inferred from the URL version. The checked-in contract is generated, semantically linted, and compared with the prior contract in CI using the same rules described here.

The platform can make these compatible additive changes within `/v1`:

- add an operation or optional request field;
- add an optional response field or response header;
- add a new documented error code or optional structured error detail;
- add a value to an enum; and
- add a preview capability or operation without changing a GA operation.

Clients must ignore unknown response object fields and unknown response headers. Treat enum values as open sets at runtime: preserve or surface an unknown value instead of crashing, even if generated types model the known values. Use a default branch for unknown `error.code` values and decide retry behavior conservatively from HTTP semantics and documentation.

## Changes that require another version

The platform will use a new URL version rather than silently making a GA `/v1` change that removes or renames an operation or field, newly requires previously optional input, changes a field's type or established meaning, removes or narrows enum values, removes a successful response representation, or changes authentication and project-ownership semantics incompatibly. A new version can run alongside `/v1` during migration.

Contract-diff CI automatically rejects mechanically detectable examples such as removed paths/operations/properties, newly required fields, narrowed enums, incompatible types, required parameters, required request bodies, and removed successful response codes or media types. Review is still required for semantic changes that a schema diff cannot identify.

## Preview and GA expectations

GA operations receive the compatibility and deprecation protections on this page. Preview operations are identified by `x-stability: preview` in OpenAPI and a Preview label in documentation. Preview shapes can change or be withdrawn before GA, with changes recorded in the changelog, and do not receive the GA support window. Moving a preview operation to GA establishes its compatibility baseline; moving a GA operation back to preview is not compatible.

## Deprecation and removal

An incompatible GA replacement is introduced under a new API version. The platform will support the superseded GA version for at least 12 months after its replacement reaches GA and will publish a deprecation notice at least 180 days before shutdown. The notice identifies affected operations, the replacement, migration guidance, and the earliest shutdown date. If the two windows imply different dates, the later date applies.

Security or legal emergencies can require faster protective action. When feasible, the platform will prefer a compatible mitigation and communicate the exception through the same documentation channels.

Review the published [API changelog](https://api.blackpearl.com/docs/api-changelog.md) for observable changes and the generated [OpenAPI contract](https://api.blackpearl.com/v1/openapi.json) for exact current shapes.