> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and deprecation

> How the API changes within v1, what counts as breaking, and how much notice you get

The API has one version today, **v1**, and the version is part of every URL:

```text theme={null}
https://api.healos.ai/ext-api/v1
```

Nothing in v1 is deprecated. Every change is recorded in the
[Changelog](https://docs.healos.ai/changelog.md).

## Changes that ship without notice

Within v1 we only **add** things. These changes ship at any time and appear in
the changelog afterwards:

* new endpoints;
* new optional request fields and query parameters;
* new fields in responses;
* new values in response enums, such as a new `status` or webhook event type;
* new scopes. Existing keys don't get them, except keys with `*` (full access).

Build your client so these never break it:

* Ignore response fields you don't know.
* Handle an unknown enum value, for example by logging it and treating it as
  "other", instead of failing.
* Branch on the HTTP status and on `code` where one is given, not on the
  `error` text, which can change. See [Error catalog](https://docs.healos.ai/errors.md).

## Breaking changes

A breaking change is one that can stop a working integration:

* removing or renaming a field, endpoint or enum value;
* making an optional field required, or adding a new required field;
* changing a field's type or an endpoint's status codes;
* rejecting input that used to be accepted.

Breaking changes go into a **new version** (for example `/ext-api/v2`), not
into v1. When that happens:

1. We announce it in the [Changelog](https://docs.healos.ai/changelog.md) **before** it ships, with
   what changes and what to do.
2. The old behaviour keeps working for **at least 6 months** after its
   replacement ships.
3. A deprecated endpoint says so on its reference page, and its responses
   carry `Deprecation` and `Sunset` headers ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594))
   with the date it stops working.

### Security fixes

The one exception is a fix that closes a security or abuse problem. We may
then reject input that was never meant to work, without a new version or
advance notice, and record it in the changelog the same day. The
[input limits of October 27, 2026](https://docs.healos.ai/changelog.md) (page size cap, request size
limits and file content checks) are an example.

## The OpenAPI document

The [OpenAPI document](https://docs.healos.ai/api-reference.md) describes v1. Its `info.version` tracks
changes to the document itself, not the API version in the URL.

## The CLI

The [`healos` CLI](https://docs.healos.ai/cli) has its own version numbers on npm
(`@healos/cli`). Its releases are listed in the [Changelog](https://docs.healos.ai/changelog.md).
Update it by running the install command again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.