ConverterHQDevelopers
Documentation

Environments, versioning and deprecations

Promote safely from sandbox to production and understand the compatibility contract of API v1.

Sandbox and production

Test and live credentials are isolated. Build against sandbox first, exercise webhooks and failure paths, then promote configuration deliberately. Never infer environment from a key string in business logic; configure the API base URL explicitly.

API v1 contract

Once GA is cut, the committed public OpenAPI v1 baseline is the compatibility contract. CI rejects incompatible schema changes before deployment.

Compatible additions

New optional fields, endpoints, enum values where clients are expected to tolerate extension, capabilities and conversion options may be added without a major version. Clients should ignore unknown response fields. Pair-specific settings follow the same rule: ConverterHQ may add new optional options, but an existing v1 option will not be removed, become required, change type or default semantics, lose enum values, or have its accepted range narrowed.

Deprecations

Breaking behavior requires an explicit migration path rather than silent mutation. Deprecation notices belong in the changelog and relevant reference pages, with concrete replacement guidance.