Versioning

Overview

The current stable version is v1, embedded in the URL path (https://api.zof.ai/v1). Non-breaking additions ship without version bumps.

Breaking changes are announced via changelog and minimum 90-day deprecation for enterprise contracts unless security-critical.

Step-by-step procedure

Key concepts

Non-breaking change

New optional JSON fields, new endpoints, or expanded enum values.

Breaking change

Removed fields, changed semantics, or deleted endpoints requiring migration.

Sunset header

Deprecated endpoints may return Sunset HTTP header with retirement date.

Best practices

• Pin integrations to /v1 explicitly
• Subscribe to release notes for API changes
• Test pipeline integrations in staging before key rotation events

Verify compatibility with representative requests

Record the API and client versions your integration was validated against. Before changing either, compare the supported contract for authentication, field names, optional values, pagination, errors, and asynchronous operation states.

Use representative saved fixtures with sensitive values removed to check success and failure handling. Preserve a rollback path appropriate to the service and confirm any published deprecation timeline with the account team rather than assuming a fixed support window.