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, the request uses the current version (2026-05-01). Pin a version explicitly so a future release cannot change the responses you receive.
• If you cannot set headers, pass the version as a query parameter: ?version=2026-05-01. The header takes precedence when both are sent.
• The effective version is echoed back on every response as RevKeen-Version.
• 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.

Supported versions

2026-05-01 introduced normalised list responses (object: "list", data, has_more, url) and returns structured errors (error.type, error.code, error.message, error.param).

How an unlisted version is resolved

• A version that is not in the table resolves to the nearest older supported version. For example, 2026-03-01 resolves to 2026-01-15.
• A version newer than the current version resolves to the current version.
• A version older than every supported version, or a value that is not a YYYY-MM-DD date, is rejected with a 400 invalid_request_error whose param is RevKeen-Version. Nothing is silently upgraded.

Check the RevKeen-Version response header to confirm which version served your request.

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

• When a version is superseded, it is deprecated and given a sunset date. 2026-01-15 has a six-month deprecation window, ending on 15 November 2026.
• Responses served under a deprecated version carry Sunset and Deprecation headers, both set to the sunset date:

  RevKeen-Version: 2026-01-15
  Sunset: Sat, 15 Nov 2026 00:00:00 GMT
  Deprecation: Sat, 15 Nov 2026 00:00:00 GMT

• Treat these headers as your signal to upgrade. Monitor for them in your integration logs.

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 first — this limits blast radius.
4. Update the header in every service once your tests pass, then confirm the RevKeen-Version response header shows the new version.

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

Owner: david · Reviewed 30 Sep 2026 · Next review 30 Oct 2026