# API Versioning & Breaking Changes

How Apideck evolves its Unified APIs: the backward-compatibility policy, the 6-month
deprecation runway, and what counts as a breaking change.

The full policy lives at [https://developers.apideck.com/versioning](https://developers.apideck.com/versioning).

## How the API evolves

There is one live schema — no version headers, no version branches, and no per-account
pinning. Changes ship additively wherever possible: a new field, enum value, parameter,
or endpoint lands alongside what already exists. The narrow set of changes that can't be
made additively go through a fixed deprecation process — every approved breaking change
gets a six-month grace period before it takes effect, is published to the changelog, and
affected customers are contacted proactively.

## Lifecycle of a breaking change

1. **Proposed** — written up with rationale and customer impact; where a
   backward-compatible path exists, the additive half ships immediately.
2. **Reviewed** — every six months the product team approves, defers, or drops open
   proposals. Only an approved change starts a deprecation countdown.
3. **Grace period & cleanup** — a 6-month runway during which the current behaviour
   keeps working; at the end of the runway the old behaviour is removed.

## What counts as breaking

| Change | Breaking? |
|---|---|
| Adding a new optional property | No |
| Adding a new model, resource, or endpoint | No |
| Adding a new enum value | No — treat response enums as open sets and keep SDKs current |
| Removing a property | Yes |
| Removing an enum value | Yes |
| Restricting a property (tighter validation or format) | Yes |
| Making a request field optional → required | Yes |
| Making a response field required → optional | Yes |
| Behaviour change with no schema diff | Yes — announced in the changelog, since schema diffs can't catch it |

Renames, type changes, and meaning changes decompose into an additive step (a new
property) plus a breaking removal scheduled into a deprecation runway.

## Migration paths

Most breaking changes run old and new in parallel during the runway, so migration is
gradual. Hard cuts (HTTP status code changes, response ordering, rate limits, deletion
semantics) can't run in parallel — for those the grace period is pure notice and the
published end date is an atomic flip.

## How to detect upcoming changes

- Pending breaking changes are listed in the [changelog](https://developers.apideck.com/changelog.md)'s
  breaking-changes section for the full grace period.
- Each pending change carries a machine-readable `x-apideck-sunsetting` block on the
  affected operation, property, or parameter in the
  [OpenAPI specs](https://github.com/apideck-libraries/openapi-specs), so deprecations
  can be detected programmatically.
- Sunsetting operations, properties, and parameters are flagged in the rendered API
  reference and its markdown mirror.
- During the grace period Apideck proactively contacts affected customers.

## Related

- [Changelog](https://developers.apideck.com/changelog.md)
- [Building with LLMs](https://developers.apideck.com/building-with-llms.md)