PushizoDocs
API reference

Versioning and compatibility

The /v1 compatibility promise, backward-compatible addition rules, breaking change policy and the new version path, deprecation, OpenAPI/SDK versions and the changelog.

The public API lives under /v1 and is kept backward compatible: existing integrations keep working without a version upgrade.

What counts as compatible (may ship without notice)

  • New endpoints, new optional request fields, new query parameters.
  • New fields in responses (clients must ignore unknown fields).
  • New enum values in responses (e.g. a new status, a new suppression_reason, a new webhook event type) — clients must handle unknown values with a generic fallback.
  • Adding new variants to oneOf/anyOf unions.
  • New fields in the error details object; new HS_* codes (the HTTP status follows the existing rules).

What counts as breaking (requires a new version path)

  • Removing or renaming a field/endpoint, changing a type, making an optional field required.
  • Adding a required field to an existing oneOf variant.
  • Changing the authentication or error envelope format.

Breaking changes are published under /v2; /v1 is supported for at least 12 months and the deprecation date is announced in advance in the changelog. Deprecated operations are marked deprecated in OpenAPI and shown in the reference with a "deprecated" badge.

Contract check

api/openapi.yaml is versioned in the repository; the contract check in CI (npm run ci:local) compares every change against the previous baseline and verifies that it contains additions only; an intentional breaking change requires a new version + a new baseline. Because the generated server SDKs (Python, Go, Java, .NET, Ruby) are derived from the same contract, new endpoints are added to all languages at once; renamed SDK methods are kept under the old name as deprecated aliases.

Version numbers

ComponentVersion
API contract (info.version)Same as the platform version (semver; currently 1.0.0)
Server SDKsTrack the platform version; the API_VERSION constant tells which contract they were generated from
Client SDKsTheir own semver; bound to the /sdk/v1 contract
Webhook payloadNo version field; the event structure changes by addition only, and new event types are explicitly added to the subscription

All user-facing changes: API changelog and release notes. The service info endpoint GET / returns the running version.

On this page