First Leeward

Versioning & Compatibility

How the API evolves, what counts as a backwards-compatible change, and how to build a resilient integration.

Every request carries a Leeward-Version header (see Overview). Backwards-incompatible changes ship under a new version, so your integration keeps working until you choose to upgrade. Within a single version we continuously ship backwards-compatible improvements, and your integration should be built to absorb them without changes.

Backwards-compatible changes

The following can happen at any time, within your current version, and are not considered breaking. Build your integration to tolerate them:

  • Adding new API endpoints and resources.
  • Adding new optional request parameters and request body fields.
  • Adding new fields to existing responses and webhook payloads.
  • Adding new values to an existing enum (for example a new policy type or decline reason code).
  • Adding a new variant to a discriminated union (for example a new policy type with its own config shape).
  • Adding new webhook event types.
  • Adding new, more specific error codes, as long as the condition could not previously be resolved by your code at runtime.
  • Changing the length or format of opaque identifiers (treat all IDs as variable-length strings).

Breaking changes

These ship only under a new Leeward-Version:

  • Removing or renaming a field, parameter, or endpoint.
  • Changing the type of an existing field, or the meaning of an existing value.
  • Removing a value from an enum, or changing what an existing value means.
  • Making a previously optional field or parameter required.