Versioning

How Humanos API versions work, how to pin a version, and what happens when you don’t

The Humanos API uses date-based versioning in YYYY-MM-DD format. A new version is created whenever the API changes: this includes breaking changes, new endpoints, new optional fields, and new response fields. Any modification to the API specification triggers a new dated version.

The API-Version header

Include the API-Version header in your requests to pin your integration to a specific version:

const response = await fetch("https://api.humanos.tech/request", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "X-Timestamp": timestamp.toString(),
    "X-Signature": signature,
    "API-Version": "2026-09-01",
  },
});

Version resolution

The API resolves the version for each request using the following priority:

Priority	Source	Description
1	API-Version header	Explicitly set per request
2	Pinned version	Set on your API key when the key is created (the latest version at that time)

Each API key is pinned to the latest available version when it is created. Requests made with that key use its pinned version unless you send an API-Version header. To upgrade, send the desired version in the header, or change the key’s pinned version in the dashboard under API Keys.

Requests are served only for versions in the supported range, from your organization’s floor version up to today. An API-Version in the future, or older than the floor and no longer supported, returns a 400 Bad Request whose message states the current supported range.

When the version a request resolves to (header or key pin) is below the supported floor, responses include a Deprecation header, defined in RFC 9745. Watch for it and upgrade before the version leaves the supported range.

Webhook versioning

By default, each webhook event uses the API version of the request that triggered it. You can instead pin a version per webhook endpoint in the Humanos Dashboard.

Every webhook payload includes an api_version field indicating which version format it uses:

{
  "eventType": "credential",
  "api_version": "2026-09-01",
  "requestId": "68c42ec3e47c9a7f9241e0ba",
  ...
}

Pin a version on your webhook endpoint to avoid unexpected payload changes. Update it on your own schedule after reviewing the changelog.

Best practices

• Pin a version via the API-Version header when you go to production. Each API key is automatically pinned to the latest version when it is created, but explicitly setting it in the header gives you full control.
• Test version upgrades before switching. Use the API-Version header to test against a newer version without affecting your default pinned version.
• Keep webhook and API versions in sync unless you have a specific reason not to. This avoids confusion when correlating API responses with webhook payloads.