Skip to main content

Versioning

Choose the REST major agreed during onboarding. The version is explicit in every request path, for example /v1/market/status. Each major has its own guides, endpoint reference and problem catalogue.

Use API version in the header to choose the documentation you are reading. The version marked current opens by default. A version in the URL takes precedence, so bookmarks continue to show the version they refer to. Changing the selector updates the guides, reference, search results and OpenAPI download; it does not change your integration's requests.

Several majors can be available at once. A new major does not automatically retire an older one. The selector lists the documentation published for your environment; consult your onboarding contact to confirm which API versions your integration can use.

Compatibility and upgrades​

The API contract defines the requests you can send, the responses you can receive and the behavior you can rely on. How a change affects that contract determines whether it updates the current API version or introduces a new one.

Breaking changes​

A breaking change is incompatible with the existing contract and can require an integration that follows it to change its code or behavior. Examples include:

  • Removing or renaming an endpoint or response field.
  • Making previously optional request input mandatory, or changing a field's type, format or meaning.
  • Changing documented error behavior or adding a possible response value to a fixed set of allowed values, such as a closed status enum.
  • Changing externally observable business behavior, such as lifecycle transitions or calculation rules.

Portfolio Exchange introduces breaking changes in a new REST API major version, for example from /v1/... to /v2/.... The existing major retains its contract. To adopt the new version, follow its migration guidance and test your integration before switching request URLs.

Non-breaking changes​

A non-breaking change preserves the existing contract, so integrations that follow it continue to work without changes. Examples include:

  • Adding a new endpoint without changing existing endpoints.
  • Adding an optional request parameter that preserves existing behavior when omitted.
  • Adding an optional response field while preserving the existing fields and their meaning.
  • Improving documentation or internal implementation without changing the published contract or observable behavior.

Non-breaking changes update the current REST API major version. For example, compatible additions to V1 remain under /v1/.... You do not need to move to a new version to keep using existing operations.

Clients must ignore response fields they do not recognize so that additive changes remain compatible. Continue to validate the fields and values required by your chosen major's contract.

Release notes and migration guidance​

All API changes, both breaking and non-breaking, will be communicated to integrated clients through release notes. The notes explain what changed, which API versions are affected and any action clients need to take. Breaking changes also include migration guidance for the new major version.

Webhook contracts, when available, have their own versions independent of REST API majors.