Versioning

The version number

The API contract has one version, major.minor.patch, shown at the top of the API reference and in the OpenAPI document's info.version. Every published version is in the changelog.

Change	Version
a correction to the documentation, with no change in behaviour	patch
something added: a new operation, a new optional query parameter, a new field in a response, a new value your client is told to tolerate	minor
something removed or changed in meaning: an operation, a field, a parameter, a status code a client relies on	major

Version 1.1.0 (2026-10-18) is the contract of the first production release and is frozen. The first change after launch - your organization's own cookie and storage-key classifications - is published as 1.2.0; the next change to it is 1.3.0 or a patch.

The version of the contract is not the version of the software: Page Lookout is updated far more often than its contract changes, and most updates change nothing a client can see.

What your client should tolerate

A minor version must never break a client that follows these rules:

ignore fields you do not know, in responses and in webhook bodies;
treat a details.reason you do not recognise like the status code it came with;
treat a module value, or an evidence kind, you do not recognise as an opaque string: a minor version can add a module (and so a moduleOutcomes row, a byModule entry and findings that name it) or a kind of evidence, so do not map them with a closed list that throws;
do not rely on the order of fields in an object, or of rows beyond the order an operation documents;
read the numbers of the rate limit from the RateLimit-* headers rather than hard-coding them.

Breaking changes

A breaking change is made only in a new major version, and never without notice:

The old behaviour is deprecated first: the operation or field is marked deprecated in the reference, the changelog says what replaces it, and the admins of every organization with an API key or a webhook endpoint are told by e-mail.
It keeps working for at least 6 months after that notice.
Only then is it removed, in the next major version.

A change needed to fix a security problem may have to move faster; if it does, the notice says why.

Webhook payload versions

Webhook bodies carry their own version, apiVersion (currently 1), which follows the same rules: a new field does not change it, and receivers must ignore fields they do not know. A breaking change to a body is a new apiVersion. Today every endpoint receives version 1; a new payload version will be opt-in per endpoint and announced at least 6 months in advance. See Webhooks.