Versioning and change policy
Release notes
Every change to the platform lands in the changelog, and the policy below governs what can change and how much warning you get. The full dated history lives at /changelog; this page is the contract behind it.
Versioning
The API is versioned in the URL (/v1/, /v2/) for breaking changes only. Within a major version: new fields and endpoints may appear at any time (additive), existing fields never change type or meaning, and error codes never change semantics. Your client must tolerate unknown fields in responses — that is the one requirement we place on integrations.
Deprecation policy
| change class | minimum notice |
|---|---|
| Breaking API change (new major) | 12 months of parallel operation |
| Endpoint or field deprecation | 6 months, with Sunset headers on responses |
| Model family retirement | 6 months; benchmarked successor named at announcement |
| Model release within a family | 2 weeks in preview channel before default flips |
| Pricing changes | 30 days, never retroactive within a billing period |
Model releases
Model updates ship behind the benchmarks gate: a release candidate must clear the internal suite (see /models/benchmarks) before promotion, and TraceReplay must hold at 100% — existing traces replay identically across releases, unconditionally. Pin a snapshot (e.g. y0-fast-2026-05) if you need a frozen model; bare aliases track the current release.
Where to watch
- /changelog — every dated entry, filterable by area
- Sunset and Deprecation response headers on anything scheduled to go
- key.near_expiry and usage webhooks for account-level changes
- The RSS feed at /changelog/feed.xml for tooling