Skip to main content

Versioning policy

The Evenhand REST API is versioned in the URL path. The current version is v1, served at https://app.evenhandhq.com/api/v1.

What we promise about v1​

  • v1 is supported. It will be served and maintained for the lifetime of the platform's brokerage REST surface.
  • At least 12 months notice before any breaking change to v1. If a breaking change is unavoidable, we ship a new major version (v2) and operate both in parallel for the notice window.
  • Backwards-compatible additions can land in v1 at any time without prior notice.

What counts as a breaking change​

The following changes require a new major version:

  • Removing an endpoint or operation.
  • Removing or renaming a field on a request or response object.
  • Tightening a field — making an optional field required, narrowing an enum, shrinking a numeric range, requiring a previously optional header.
  • Changing the type or semantics of an existing field.
  • Changing the shape of the error envelope ({ error: { code, message, details? } }) or the meaning of an existing canonical error code.
  • Changing authentication, scopes, or rate-limit semantics in a way that rejects previously accepted requests.

What does not count as a breaking change​

These can land in v1 without notice. Build clients that tolerate them.

  • Adding a new endpoint.
  • Adding a new optional field to a request body.
  • Adding a new field to a response object.
  • Adding a new value to an enum, where the existing client behavior on unknown values is "ignore" or "treat as default."
  • Adding a new optional query parameter.
  • Adding a new scope (existing keys keep their existing scope set; new scopes apply only to keys explicitly issued with them).
  • Adding a new canonical error code in a category your client already handles.
  • Performance improvements, infrastructure changes, message-text edits.

Client guidance​

To stay forward-compatible inside v1:

  • Ignore unknown response fields. Do not fail on them.
  • Switch on error.code, not on error.message. Messages can change.
  • Treat unknown enum values as their default, or surface them as opaque strings — never crash on them.
  • Pin to v1 explicitly in the URL. Do not write code that strips the version segment.

Future versions​

v2 is reserved for a future contract-breaking release. There is no v2 today and none planned in the immediate roadmap. When v2 ships, this page will document the migration window, the endpoint-by-endpoint diff, and the deprecation timeline for v1.