Version policy

Vision versions each contract boundary on its own, so an App can improve without forcing every integration to move.

What is versioned

Layer	Example	How it is versioned
URL path	/api/crm/v1, /vision-core/v1	Major version. Changes only for a breaking redesign.
OpenAPI document	CRM 9.3.0	Semantic version per App: patch for wording, minor for additions, major for breaking changes.
Payload schema	schemaVersion: "vision-crm-error.v1"	Named and numbered per payload; a new number is a new shape.
Token vocabulary	vision-service-credential.v1	Changed only with a migration window.
Webhook events	vision-webhook-event.v1	Event names carry their own version suffix.
SDK	@vision/sdk	Semantic version; a major SDK release follows a breaking API change.

Compatible changes

These can ship at any time without a new major version, and your integration must tolerate them:

• new operations, endpoints, optional request fields and query parameters;
• new response fields (ignore fields you do not know);
• new enum values in responses (handle an unknown value as "other");
• new error codes (fall back on HTTP status and retryable);
• new scopes and new webhook event types;
• longer limits, higher rate limits, and clearer messages.

Breaking changes

These need a new major version of the affected contract:

• removing or renaming an operation, field, parameter or enum value;
• making an optional request field required, or tightening validation;
• changing a field's type, meaning or default;
• changing authentication, scope requirements, signatures or token claims;
• changing pagination, ordering or idempotency semantics.

Deprecation

When something is deprecated, Vision:

1. announces it in the changelog with the replacement and a removal date;
2. marks it deprecated: true in the OpenAPI document;
3. sends Deprecation and Sunset response headers (RFC 9745 and RFC 8594) on the affected operation;
4. keeps it working until the sunset date.

Changelog

Every published change to a contract appears in the changelog, generated from the difference between the previous and new OpenAPI document of each App: added and removed operations, parameters and fields, each flagged additive or breaking. Subscribe with the RSS feed or JSON feed.

Preview contracts

Every contract on this site is currently preview. Preview contracts follow the rules above on a best-effort basis but may make breaking changes with a changelog entry and shorter notice. A contract becomes stable when its App page says so; from then on the deprecation process above applies in full.