Versioning and deprecation

Additive changes ship at any time and are listed in the changelog:

• New endpoints.
• New fields in responses and webhook payloads.
• New optional request fields, query parameters and headers.
• New values for enums, error codes and webhook event types.

Build your client to ignore fields it does not know and to handle an unknown enum value or error code.

A breaking change comes as a new version in the path, or is announced in advance by email to account owners and in the changelog. Breaking means:

• A field, parameter or endpoint is removed or renamed.
• A field's type or meaning changes.
• An optional field or step becomes required.

1. A deprecated endpoint or field is marked in the reference and the changelog, with the date it stops working.
2. It keeps working until that date.

openapi.yaml describes /v1; its info.version is 1.x.y, with the major number matching the path.