Skip to main content
The API has one version today, v1, and the version is part of every URL:
Nothing in v1 is deprecated. Every change is recorded in the Changelog.

​
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.

​
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 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) 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 (page size cap, request size limits and file content checks) are an example.

​
The OpenAPI document

The OpenAPI document describes v1. Its info.version tracks changes to the document itself, not the API version in the URL.

​
The CLI

The healos CLI has its own version numbers on npm (@healos/cli). Its releases are listed in the Changelog. Update it by running the install command again.