API Versioning

Cresora maintains two concurrent API streams: stable and preview.

Stable stream (/api/v1)

The stable stream contains endpoints that are production-ready with a backward-compatibility commitment:

• Existing fields are never removed without a deprecation period
• Breaking changes require a new major version (/api/v2)
• New optional fields may be added at any time without a version bump

Preview stream (/api/v1-preview)

The preview stream exposes endpoints under active development:

• No backward-compatibility commitment — schemas may change between releases
• Endpoints are behind feature flags; your key needs the flag to call them
• ISVs without the feature flag can read the reference but cannot execute the endpoints
• Preview endpoints are marked with x-stability: preview in the OpenAPI spec

Promotion lifecycle

internal-only → preview → stable

When a preview endpoint is promoted to stable, Cresora:

1. Publishes it in the stable spec with the same path and schema
2. Keeps the preview path alive for a 30-day migration window
3. Fires a deprecation notice via the changelog and email

Deprecation policy

When a stable endpoint or field is deprecated:

• A deprecation notice appears in the changelog and in API responses via Deprecation / Sunset headers
• A minimum 6-month runway is given before removal
• The field or endpoint is marked deprecated: true in the OpenAPI spec

Changelog

All API changes — new endpoints, deprecations, breaking changes, and preview promotions — are published in the Changelog → within 24 hours of release. Subscribe to the RSS feed → to be notified automatically.