> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanos.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```javascript theme={"dark"}
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.

<Warning>
  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.
</Warning>

<div className="hm-tip">
  When your pinned version falls below the supported floor, responses include a
  **`Deprecation`** header, defined in [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745).
  Watch for it and upgrade before the version leaves the supported range.
</div>

## Webhook versioning

Webhooks are versioned independently from the API. Each organization has its own webhook version, which you can manage in the [Humanos Dashboard](https://app.humanos.tech/webhooks).

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

```json theme={"dark"}
{
  "eventType": "credential",
  "api_version": "2026-07-06",
  "requestId": "68c42ec3e47c9a7f9241e0ba",
  ...
}
```

<div className="hm-tip">
  Pin your webhook version to avoid unexpected payload changes. Update it on your own schedule after reviewing the changelog.
</div>

## 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.