These are the promises behind every notice we send you. There are three, plus
the rules that decide when one of them applies.
API and proxy
You get at least 90 days’ notice before a breaking change to the API or
the proxy.
How the API is versioned
The version is in the path: every endpoint is under /api/v1. There is one
version, v1, and no version header or dated pin to set. Every request
already names its version, so nothing moves under a client that has never
chosen one.
A breaking change ships as a new endpoint or a new version, never as a change
to an existing /api/v1 endpoint. If a v2 ever ships, v1 keeps working
unchanged for at least 90 days after we announce it.
What counts as a breaking change
- Removing or renaming an endpoint, a request or response field, or an error
code.
- Changing a field’s type, or the default used when you leave a field out.
- Making an optional request field required.
- Tightening validation, so a request that used to be accepted is refused.
- Changing the status code returned for an existing condition.
- Changing what an existing field means, even if its type stays the same.
What changes without notice
These ship whenever they are ready and are listed in the
changelog:
- New endpoints.
- New optional request fields.
- New response fields and headers.
- New error codes for new conditions, and new values in fields that list
things, such as threat types.
- Loosened validation.
- Changes to what a scan detects. Detection improves continuously; the shape
of the request and response does not change with it.
Write clients that ignore fields they do not recognise and handle an unknown
error code as a generic failure.
How a deprecation is signalled
A deprecated endpoint is marked as deprecated in the
API reference, and every response from it
carries a Deprecation: true header and a Sunset header with the date it
will be removed. It is listed in the table below.
SDKs
The SDKs use semantic versioning: anything in an SDK’s public interface is
removed or renamed only in a new major version. When a new major version of an SDK ships, the previous
major version gets security fixes for 12 months.
Moving from 1.x to 2.0 of the Python SDK, the Node.js SDK or the CLI:
Upgrade to SDK and CLI 2.0 lists every removed
call and what to use instead.
Self-hosted
A Release of the self-hosted platform is supported while it is less than 90
days old. Security fixes ship in new Releases, never as backports to
older ones: to get a fix, upgrade.
Deprecations and removals
Where you hear about it
- A change that needs you to act comes as an email to the owners and
admins of each affected organization and to the technical contact on each
self-host licence, whatever your marketing email preferences, and is also
listed in the changelog.
- What changed for you is in the changelog, dated by the
release that delivered it. It has an RSS feed. Filter it by the product you
use, or show only breaking changes and
deprecations. An entry that needs you to act
is marked Breaking change or Deprecation and says what to do.
- What to do when you upgrade a self-hosted deployment or roll out the
desktop agent is on Platform upgrade notes and
Shadow AI desktop agent upgrade notes.
Last modified on October 31, 2026
