API Versioning & Deprecation Policy

The Curate-Me platform uses path-based versioning for all APIs. This page describes the versioning scheme, stability guarantees, and deprecation process.

Current Version

All production traffic should target v1. There is no v2 at this time.

Versioning Scheme

The version segment appears in the URL path immediately after the host:

https://api.curate-me.ai/v1/openai/chat/completions
                         ^^
https://api.curate-me.ai/api/v1/admin/runners
                             ^^

When a new major version is released, the previous version continues to be served at its original path for the duration of the deprecation window (see below).

Stability Guarantees

What will NOT change within a major version

• Existing response fields will not be removed or renamed.
• Existing endpoint paths will not be removed or relocated.
• Field types will not change (e.g., a string field will not become an integer).
• Authentication mechanisms will not change.
• Error code values (error.code) will not be removed or renamed.

What MAY change within a major version

These are considered non-breaking and can ship at any time:

• New optional fields added to request or response bodies.
• New endpoints added under the same version prefix.
• New event types added to webhooks and streaming responses.
• New values added to existing enums (e.g., a new governance denial reason).
• New response headers.
• Relaxed validation (accepting inputs that were previously rejected).
• Improvements to error messages (the human-readable message field).
• Performance and latency improvements.

Breaking vs Non-Breaking Changes

Deprecation Timeline

When a feature, field, or endpoint is scheduled for removal, we follow a structured deprecation process:

1. Announcement

Deprecated features are announced in the Changelog and flagged in the OpenAPI specification with deprecated: true.

2. Response Headers

Deprecated endpoints include two headers in every response:

X-CM-Deprecated: true
Sunset: Sat, 01 Nov 2026 00:00:00 GMT

• X-CM-Deprecated signals that the endpoint is deprecated.
• Sunset (RFC 8594) indicates the date after which the endpoint may stop functioning.

3. Deprecation Window

All deprecated features have a minimum 6-month deprecation window from the date of announcement. During this window, the endpoint continues to function normally but returns the deprecation headers.

4. Removal

After the deprecation window closes, the endpoint returns:

HTTP/1.1 410 Gone

{
  "error": {
    "code": "ENDPOINT_REMOVED",
    "message": "This endpoint was deprecated on 2026-05-01 and removed on 2026-11-01. Use /v2/... instead.",
    "details": {
      "migration_guide": "https://docs.curate-me.ai/guides/v2-migration"
    }
  }
}

SDK Version Compatibility

SDKs pin to a major API version. Non-breaking additions (new fields, new endpoints) are absorbed in minor SDK releases without requiring changes to your code. When a new major API version is released, a corresponding major SDK version will be published.

Staying Informed

• Changelog: Check docs.curate-me.ai/changelog for all API changes.
• Sunset header: Monitor the Sunset response header on endpoints you use.
• Webhook event: Subscribe to the api.deprecation_notice event to receive programmatic notifications when endpoints you use are deprecated. (Coming soon.)
• OpenAPI spec: Deprecated endpoints and fields are marked with deprecated: true in the OpenAPI specification.