API Versioning
The stable /api/v1 stream, planned operations, and how contract changes are announced.
Cresora publishes one callable API stream — stable, at /api/v1 — plus a reference
for planned operations that are documented ahead of release.
Stable stream (/api/v1)
The stable stream contains endpoints that are production-ready with a backward-compatibility commitment:
- Existing fields are not removed without an announced deprecation
- Breaking changes require a new major version (
/api/v2— none exists today; a request for any version other thanv1is rejected withDeprecation/Sunsetheaders) - New optional fields may be added at any time without a version bump
Planned operations
Some operations are published in the reference before they are released, marked
x-cresora-status: planned in the contract and badged "Reserved — not yet available"
on their reference pages. They exist so you can review the intended shape while planning
an integration. Three facts to build on:
- They are not callable, by anyone. A planned operation has no route on any host and
returns
404(or501, for reserved discriminator variants such astype: AUTHORIZATION) until it is released. There is no separate base URL for them. - No flag unlocks them. The
enabled_featuresonGET /capabilitiesgate released features per partner account; they never expose an unreleased endpoint. There is no preview program to enroll in. - The badge is the contract. When an operation loses its "Reserved" badge and appears
in the stable
/api/v1reference, it is served; the changelog entry for that day records the addition.
Their schemas may still change before release — review them, don't code against them. The planned-operations reference renders the full contract including these operations.
Deprecation
When a stable endpoint or field is deprecated:
- It is marked
deprecated: truein the OpenAPI spec - The change is announced in the changelog
There is no published deprecation SLA yet: no fixed migration window or minimum runway has been committed. Watch the changelog — removals appear there as dated entries the day the contract changes.
Changelog
All contract changes — additions, removals, moves, and breaking changes — are recorded in the Changelog → as dated entries generated from the contract diff, within a day of the spec being published. Subscribe to the RSS feed → to be notified automatically.