Versioning

The RevKeen API is versioned by release date. Pin your integration to a specific version with the RevKeen-Version header so schema changes and new enum values never arrive silently.

Setting the version

GET /v2/customers HTTP/1.1
Host: api.revkeen.com
x-api-key: rk_live_...
RevKeen-Version: 2026-05-01

• If you omit the header, requests use the default version pinned to your API key at the time it was issued.
• The effective version is echoed back on every response as RevKeen-Version.
• Override it by setting the RevKeen-Version header explicitly. Keep one version value per deployed integration and exercise upgrades in sandbox first.

The generated transports expose request headers through their normal configuration or request-options surface. The SDKs do not silently change the version and do not infer a version from their package number.

What counts as a breaking change

Any of the following ship only in a new version. They never change under an existing version header.

• Removing or renaming a field
• Changing a field's type, format, or nullability
• Adding a required field to a request body
• Removing an endpoint or HTTP method
• Changing an HTTP status code for an existing response
• Tightening a validation rule so previously-accepted inputs become invalid

The following are non-breaking and can appear at any time under any version:

• Adding new endpoints or HTTP methods
• Adding optional request parameters
• Adding new response fields
• Adding new enum values (handle unknown values defensively)
• Adding new webhook event types
• Adding new error code values under an existing error.type

Deprecation policy

• Minimum supported window: 12 months from the date a version is superseded.
• Deprecation notices are sent via email to account admins 180 days before a version is retired.
• Sunset headers are set on every response in the final 30 days:

  Sunset: Wed, 01 Jul 2026 00:00:00 GMT
  Deprecation: version="2025-09-01"
  Link: <https://docs.revkeen.com/developers/versioning>; rel="deprecation"

• After sunset, requests using the retired version receive 400 Bad Request with error.code = "api_version_retired".

Upgrading between versions

1. Read the Changelog for the new version. Breaking changes are flagged explicitly.
2. Set the version header on a single request in a staging environment and run your integration tests.
3. Roll out by setting RevKeen-Version for one sandbox integration before changing the account default — this limits blast radius.
4. Promote the account default via the dashboard once all services have shipped with the new header.

SDK compatibility

SDK package versions and API versions are independent. A reviewed SDK release records the contract it was generated from; the RevKeen-Version request header remains the integration's explicit compatibility control.

Version numbers are added only after the supported release channel is independently verified.

See also