Migration and Versioning Policy
The public API preserves compatibility within v1. Breaking changes require an explicit policy review, a changelog entry, and a migration path.
Compatibility commitments
- Additive fields and endpoints may ship within
v1. - Existing response fields will not change meaning within
v1. - Required request fields will not be added to existing
v1writes without a compatibility plan. - The SDK and MCP surfaces are checked against the same OpenAPI scope and operation model.
What this means for you
- Tolerate new, unrecognized fields in responses (do not fail on them).
- Pin the SDK to a known version and upgrade deliberately.
- Watch the Changelog for additive changes.
Source policy
The breaking-change policy is maintained at docs/developer-platform/openapi-breaking-change-policy.md and enforced by contract checks.