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 newsuppression_reason, a new webhook event type) — clients must handle unknown values with a generic fallback. - Adding new variants to
oneOf/anyOfunions. - New fields in the error
detailsobject; newHS_*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
oneOfvariant. - 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
| Component | Version |
|---|---|
API contract (info.version) | Same as the platform version (semver; currently 1.0.0) |
| Server SDKs | Track the platform version; the API_VERSION constant tells which contract they were generated from |
| Client SDKs | Their own semver; bound to the /sdk/v1 contract |
| Webhook payload | No 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.
Pagination, filtering and sorting
Cursor-based listing (limit, cursor, next_cursor, has_more), cursor format and validity, filter[...] and sort parameters, and helpers in the SDKs for iterating over all pages.
System and health
System and health — 4 operations (GET /, GET /status.json, GET /healthz, …). Generated from the OpenAPI 3.1.0 contract.