> ## Documentation Index > Fetch the complete documentation index at: https://docs.closient.com/llms.txt > Use this file to discover all available pages before exploring further. # Versioning & Deprecation > How the Closient API announces a version change, deprecates an operation, and retires it at a sunset date. The Closient API changes without breaking you by surprise. Every response says which API version answered it, and an operation we plan to remove tells you so on every call, with a date and a replacement, long before it stops working. ## The API version Every response from an API operation carries: ```http theme={null} Closient-API-Version: 1.0.0 ``` It is the `info.version` of the OpenAPI document for that API. The paths stay under `/api/v1/` for the whole of major version 1: | Change | What happens | | - | - | | **Patch** (`1.0.0` → `1.0.1`) | Fixes and documentation. Nothing you rely on changes. | | **Minor** (`1.0.x` → `1.1.0`) | Additions: new operations, new optional fields, new response fields. Clients should ignore fields they don't recognise. | | **Major** (`1.x` → `2.0.0`) | A breaking change. It ships under new paths (`/api/v2/`) next to the old ones, and the old operations are deprecated with a sunset date following the policy below. | If a client built for major version 1 sees a `Closient-API-Version` whose major number is higher, the server runs a newer API than the client was built for. Upgrade the client. ## Deprecated operations An operation we intend to remove is marked `deprecated: true` in the [API reference](https://docs.closient.com/api-reference/overview.md), with an `x-closient-deprecation` object that holds the same dates and links as the headers. Every response from it, successful or not, carries three headers: ```http theme={null} Deprecation: @1793836800 Sunset: Thu, 01 Jul 2027 00:00:00 GMT Link: ; rel="deprecation"; type="text/html", ; rel="sunset"; type="text/html", ; rel="successor-version" ``` | Header | Standard | Meaning | | - | - | - | | `Deprecation` | [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) | When the operation was deprecated, as `@` followed by Unix seconds. A date in the future announces an upcoming deprecation. | | `Sunset` | [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) | When the operation stops working, as an HTTP date. It is absent until a retirement date is set. | | `Link` `rel="deprecation"` | RFC 9745 | The migration guide. | | `Link` `rel="sunset"` | RFC 8594 | The retirement policy. Present only when there is a `Sunset`. | | `Link` `rel="successor-version"` | [RFC 5829](https://www.rfc-editor.org/rfc/rfc5829) | The operation that replaces this one, with this call's identifiers filled in. | The `Link` entries are appended to any other links the response carries, such as pagination, so parse `Link` as a list per [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) rather than as a single value. ### Our commitments * **Notice.** An operation is deprecated before it gets a `Sunset` date, and the `Sunset` header appears on every response well before that date arrives. We don't move a published `Sunset` earlier. * **A replacement.** We don't deprecate an operation without a documented way to do the same job, named in `rel="successor-version"` or the migration guide. * **We watch who still calls it.** Every call to a deprecated operation is recorded, and we contact organizations that still depend on it before its sunset. ### After the sunset From the `Sunset` time on, the operation answers `410 Gone` without doing anything. (The one exception is an operation whose `x-closient-deprecation` says `retiresAtSunset: false`: it keeps working past its sunset, and the official clients warn at their loudest instead of failing.) The body is a standard [error response](https://docs.closient.com/errors.md) whose `detail` names the replacement, and the deprecation headers are still attached: ```json theme={null} { "type": "https://closient.com/docs/errors/gone", "title": "Gone", "status": 410, "detail": "POST /billing/api/v1/billing/resolver/7uDkL2pQx9WvRb3mNc4sYa/cancel was retired on 2027-07-01. Use /billing/api/v1/billing/resolver/7uDkL2pQx9WvRb3mNc4sYa/remove-billing instead. Migration guide: https://docs.closient.com/api-versioning", "error_code": "gone", "retryable": false } ``` Don't retry a `410`. ## Currently deprecated | Operation | Deprecated | Sunset | Use instead | | - | - | - | - | | `POST /billing/api/v1/billing/resolver/{organization_id}/cancel` | 2026-11-05 | Not set | `POST /billing/api/v1/billing/resolver/{organization_id}/remove-billing`. It removes billing at the end of the current period instead of cancelling immediately, and works for every organization. | ## What the official clients do The [CLI](https://docs.closient.com/cli.md), the Python SDK and the Terraform provider read these headers on every response: * **Warn once** per endpoint per session (CLI run, SDK client, Terraform provider process). The warning names the endpoint, the deprecation and sunset dates, the days left, the replacement and the migration guide. The CLI writes it to stderr, so stdout and `--json` output are unchanged. The SDK raises a `ClosientDeprecationWarning`. The Terraform provider adds a warning diagnostic. * **Escalate** when the sunset is 30 days away or less. * **Fail clearly** when a retired operation answers `410`, with an error that names the replacement and the migration guide instead of a bare HTTP failure. A successful response past its sunset is never turned into an error. * **Suggest an upgrade** when a newer client release exists, or when `Closient-API-Version` reports a newer major version. Set `CLOSIENT_QUIET_DEPRECATIONS=1` to silence the warnings, for example in CI logs. It never silences the error after a sunset. The clients send no telemetry: the server already records each deprecated call. ### Building your own client Do what the official clients do. Check for `Deprecation` and `Sunset` in the one place every response passes through. Treat a `Deprecation` value you can't parse as "deprecated, date unknown" rather than ignoring it, and treat a `Sunset` without `Deprecation` as a deprecation too. Log or alert once per endpoint, not on every call. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.