# Lumbox API Deprecation & Sunset Policy

> How Lumbox versions, deprecates, and retires API surface. Machine-readable spec: https://lumbox.co/openapi.json

## Versioning

The Lumbox REST API is versioned in the URL path (`https://api.lumbox.co/v1`). Breaking changes ship under a new path prefix (`/v2`, ...). Additive, backward-compatible changes (new endpoints, new optional fields) are made within the current version without a version bump.

## Deprecation signals

When an endpoint or field is scheduled for removal, every response from it carries:

- `Deprecation: true` (RFC 9745) - the endpoint is deprecated.
- `Sunset: <HTTP-date>` (RFC 8594) - the date after which it may stop working.
- `Link: <url>; rel="deprecation"` - a link to migration notes.

## Timeline

- Deprecated surface is announced here and in the changelog at least **90 days** before its `Sunset` date.
- A whole API version (e.g. `/v1`) is supported for at least **12 months** after its successor ships.
- Security or abuse issues may shorten these windows; such cases are communicated directly to affected accounts.

## What agents should do

- Treat a `Deprecation: true` header as a signal to migrate; follow the `Link: rel="deprecation"` for the replacement.
- Stop relying on an endpoint before its `Sunset` date.
- Pin to the version prefix in the path; never assume an unversioned URL.

## Contact

Questions about a deprecation: support@lumbox.co.