Versioning

How Humanos API versions works, 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-07-06",
  },
});

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	Automatically set to the latest version available at your first request

On your first API request, the latest available version is pinned to your organization. All subsequent requests use that pinned version unless you explicitly send an API-Version header. To upgrade, send the desired version in the header.

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 your pinned version falls 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

Webhooks are versioned independently from the API. Each organization has its own webhook version, which you can manage in the Humanos Dashboard.

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

{
  "eventType": "credential",
  "api_version": "2026-07-06",
  "requestId": "68c42ec3e47c9a7f9241e0ba",
  ...
}

Pin your webhook version 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. Your organization is automatically pinned to the version available at your first request, 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.