API Versioning & Deprecation Policy
Where the API stands today, and how we intend to handle versioning once a second version ever exists.
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
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 Type | Impact Level | Intended Handling |
|---|---|---|
| Adding new optional request fields | Non-breaking | Released without a new version. |
| Adding new response fields / JSON keys | Non-breaking | Released without a new version. Clients should ignore fields they don't recognize. |
| Removing or renaming existing fields | Breaking | Would require a new API version and an advance deprecation notice. |
| Altering HTTP response status codes | Breaking | Would require a new API version and an advance deprecation notice. |
| Changing a field's data type (e.g. string to array) | Breaking | Would 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?