API Versioning & Deprecation Policy

Where the API stands today, and how we intend to handle versioning once a second version ever exists.

Current API version: v1

Every endpoint is reached under /api/v1/.... This is the only version that has ever existed, there is nothing to migrate between yet. When a v2 ships, it will be announced here with a clear migration guide and advance notice well before v1 is ever deprecated.

Today vs. planned: everything below "Planned policy" describes how we intend to handle a future breaking change. None of it is active yet, because there has never been a second API version to deprecate. Nothing in this section (deprecation headers, notice emails, sunset dates) is sent or enforced by the API today.

Today

The API has a single version, reached at /api/v1/.... It has never changed in a backward-incompatible way, so there has never been a deprecation, a sunset, or a version-related breaking change to communicate.

Planned policy (not yet active)

This is the policy we intend to follow once a v2 becomes necessary. Treat it as a preview of our intended approach, not a description of current behavior.

What would count as a breaking change

Change TypeImpact LevelIntended Handling
Adding new optional request fieldsNon-breakingReleased without a new version.
Adding new response fields / JSON keysNon-breakingReleased without a new version. Clients should ignore fields they don't recognize.
Removing or renaming existing fieldsBreakingWould require a new API version and an advance deprecation notice.
Altering HTTP response status codesBreakingWould require a new API version and an advance deprecation notice.
Changing a field's data type (e.g. string to array)BreakingWould require a new API version and an advance deprecation notice.

Planned deprecation headers

If a version is ever deprecated, we intend to send standard RFC 8594 HTTP headers so client code can detect it automatically, in the shape below. No version has ever reached this state, so no request today returns these headers.

Deprecation: @1785196800
Sunset: Mon, 01 Feb 2027 00:00:00 GMT
Link: <https://portal.orenyxengine.com/docs/versioning>; rel="deprecation"
Warning: 299 - "This API version is deprecated. See the migration guide before the sunset date."

Planned lifecycle stages

  • Active: the current supported version, receiving fixes and new features.
  • Deprecated: still works, but flagged for migration with a clear sunset date, intended to remain supported for a meaningful notice period before removal.
  • Sunset (retired): no longer responds to requests.

How we intend to notify you

  • Advance notice to workspace admins before any deprecation takes effect.
  • A warning visible in the Developer → API Keys page once a version enters deprecation.
  • The RFC 8594 headers above, once implemented.

Was this page helpful?