API versioning

The entire API is versioned in the path: everything lives under api/v1. There is exactly one current version.

Additive changes are safe — build for them

Within v1, the contract evolves additively. Expect, without notice:

• New optional request fields (e.g. the fingerprint components map was added this way — omitting it keeps the old behavior).
• New response fields. Deserialize leniently; never fail on properties you don’t recognise.
• New webhook event types and new fields inside event data — the payload is non-strict by contract.
• New error codes — treat unknown codes as a generic failure of their HTTP status.
• New endpoints, new enum values, new scopes.

A client that ignores what it doesn’t understand never breaks on an additive change.

What would be breaking

Removing or renaming a field, changing a field’s type or semantics, tightening validation on existing input, or removing an endpoint. These don’t happen inside v1 — they would ship as a new version path (api/v2), with v1 continuing to run alongside during a documented migration window.

Deprecations

When something is slated for replacement, it’s announced in the release notes before behavior changes, marked deprecated in the REST API reference, and kept working until the next major version.