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 per-request by setting the header; override per-SDK-client by configuring apiVersion on the constructor.

import { RevKeen } from "@revkeen/sdk";

const client = new RevKeen({
  apiKey: process.env.REVKEEN_API_KEY!,
  apiVersion: "2026-05-01",
});

import revkeen "github.com/RevKeen/sdk-go"

client := revkeen.NewClient(revkeen.Config{
    APIKey:     os.Getenv("REVKEEN_API_KEY"),
    APIVersion: "2026-05-01",
})

use RevKeen\RevKeenClient;

$client = new RevKeenClient([
    'api_key'     => getenv('REVKEEN_API_KEY'),
    'api_version' => '2026-05-01',
]);

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 apiVersion on one SDK client rather than flipping 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 minor versions correspond one-to-one with API versions. Upgrading an SDK patch version (for example 1.14.3 → 1.14.4) never changes the API version it targets — only bug fixes and non-breaking additions.

Version numbers are updated on SDK release. Check the repositories for current tags.

See also