---
title: "API stability and lifecycle"
description: "Understand CRACI API version prefixes, compatibility, and deprecation timelines"
source: "https://docs.craci.com/reference/api-lifecycle/"
---

API endpoint prefixes communicate their stability tier and retirement
commitments. Use stable endpoints for production integrations whenever they are
available.

## Compatibility

We do not introduce backwards-incompatible changes to an endpoint while it is
served. Additive changes, such as new optional response fields, may be
introduced without changing its version.

When a change cannot be made compatibly, we publish it at a new versioned path.

## Stability tiers

Stable endpoints use the `/v1/` prefix and are recommended for production
integrations. They receive at least one month of retirement notice.

Preview endpoints use prefixes such as `/v1preview1/`. They are intended to
become stable, but still may be revised. They receive at least one week of
retirement notice.

The number at the end of a preview prefix distinguishes successive preview
versions. For example, an incompatible revision can be published under
`/v1preview2/`.

Experimental endpoints use prefixes such as `/v1experimental1/`. We provide
no guarantees for experimental endpoints; they may change or be removed
without notice.

## Deprecation and retirement

We mark preview and stable endpoints as deprecated before retiring them,
following the minimum notice period for their stability tier.

Responses from a deprecated endpoint include both lifecycle headers:

- The [RFC 9745 `Deprecation` header](https://www.rfc-editor.org/rfc/rfc9745), for example
  `Deprecation: @1782863999`, communicates when the endpoint became or will
  become deprecated.
- The [RFC 8594 `Sunset` header](https://www.rfc-editor.org/rfc/rfc8594), for
  example `Sunset: Wed, 11 Nov 2026 23:59:59 GMT`, communicates when the
  endpoint is scheduled for retirement. The endpoint is guaranteed to be
  served until that time.

Migrate to the replacement endpoint before the sunset time. The endpoint may
stop being served after that time has passed.