Versioning and deprecation · WireBloom Developers

What changes without notice, what needs a new major version, and how deprecations are announced.

The major version is in the path (/v1). The contract's info.version follows semver; the deployed build version is returned by GET /health.

Non-breaking changes

Shipped without notice: new endpoints, new optional request fields, new response fields, new enum values in responses, new problem types and new webhook event types (delivered only when subscribed). Clients must ignore unknown fields and tolerate unknown enum values.

Breaking changes

Removing or renaming fields or endpoints, changing types or semantics, making optional input required, tightening validation, changing defaults and changing auth or scope requirements. Breaking changes ship only in a new major version (/v2) and are marked BREAKING in the changelog.

Deprecation

A deprecated operation is marked deprecated: true in the contract and keeps working until its sunset date. Its responses carry:

Deprecation: @1790121600
Sunset: Wed, 31 Mar 2027 00:00:00 GMT
Link: <https://developers.wirebloom.com/deprecations#createPayment>; rel="deprecation"

Deprecation (RFC 9745): when the operation was deprecated, as @<unix seconds>.
Sunset (RFC 8594): when it stops working, at least 6 months after the deprecation for integrator-facing operations.
Link with rel="deprecation": the entry on the deprecations page, with the migration path.

Usage of deprecated operations by API keys is reported to the operator. Webhook payloads carry apiVersion.

Contract releases

Each contract release is listed in the changelog with what integrators must do. The published contract is downloadable as openapi.json and is also served by every environment at GET /v1/openapi.json.