# How to Configure the `anthropic-version` Header in the Anthropic Python SDK

> Easily configure the anthropic-version header in the Anthropic Python SDK. Learn to override the default client-wide or per-request. Unlock flexible API version control today.

- Repository: [Anthropic/anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python)
- Tags: how-to-guide
- Published: 2026-02-23

---

**The Anthropic Python SDK automatically sets the `anthropic-version` header to `2023-06-01` for all requests, but you can override it client-wide or per-request using the `default_headers` parameter.**

The `anthropic-version` HTTP header tells the Anthropic API which version of the API contract your client expects. In the `anthropics/anthropic-sdk-python` repository, this header is hard-coded into the core client and sent with every request to ensure backwards compatibility as the API evolves.

## Understanding the Default `anthropic-version` Header

By default, the SDK pins the API version to `2023-06-01`. In [`src/anthropic/_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_client.py), the `default_headers` property constructs the header dictionary by merging the base client's defaults with SDK-specific values:

```python

# From src/anthropic/_client.py (lines 176-181)

@property
def default_headers(self) -> dict[str, str]:
    return {
        **super().default_headers,
        "anthropic-version": "2023-06-01",
        **self._custom_headers,
    }

```

This property is called during the request lifecycle to produce the final header map sent to `httpx`. The header allows Anthropic to introduce breaking changes in new API versions while maintaining backwards compatibility for clients that specify older versions.

## Overriding the Header at Client Initialization

You can specify a custom `anthropic-version` for all requests made by a client instance by passing a `default_headers` dictionary to the constructor. The `Anthropic.__init__` method stores these headers in `self._custom_headers`, which the `default_headers` property merges into the final header set:

```python
from anthropic import Anthropic

client = Anthropic(
    default_headers={"anthropic-version": "2024-01-01"}  # Custom version for all calls

)

# All subsequent requests will use the specified API version

response = client.messages.create(
    model="claude-3-opus-20240229",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

```

This approach modifies the client-wide configuration, ensuring consistency across your application without needing to specify the header for every individual API call.

## Overriding the Header Per-Request

For scenarios requiring different API versions for specific operations, pass `default_headers` directly to the method call. The SDK merges these request-level headers with the client's default headers at request time:

```python
from anthropic import Anthropic

client = Anthropic()

# Override the version for this specific request only

response = client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=512,
    messages=[{"role": "user", "content": "What is the weather?"}],
    default_headers={"anthropic-version": "2024-02-15"}
)

```

Because the header composition happens at request time, you can dynamically adjust the API version without reinstantiating the client.

## Architecture and Implementation Details

### Header Composition Flow

The `Anthropic` class builds the final header dictionary through a layered merge process defined in the `default_headers` property:

1. **Base defaults** – `super().default_headers` provides common SDK headers
2. **SDK-specific flags** – Headers like `X-Stainless-Async` are added
3. **Version pin** – The hard-coded `anthropic-version: 2023-06-01` is inserted
4. **User overrides** – `self._custom_headers` (set via constructor or request arguments) is merged last, allowing your values to take precedence

### Validation Behavior

The `_validate_headers` method in the base client ensures authentication headers (like `x-api-key`) are present, but it **does not** validate the `anthropic-version` value. The Anthropic API performs version validation when processing the request. If you specify an unsupported or incorrect version, the API will reject the request with an error rather than the SDK raising a local validation exception.

## Summary

- The SDK hard-codes `anthropic-version: 2023-06-01` in [`src/anthropic/_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_client.py) and sends it with every request
- Override the header globally by passing `default_headers` to `Anthropic()` during initialization
- Override the header for individual requests by passing `default_headers` to specific method calls like `messages.create()`
- The API validates the version string, not the SDK, so invalid versions will result in API-level errors
- Header composition occurs at request time, allowing dynamic changes without client reinstantiation

## Frequently Asked Questions

### What is the default value of the `anthropic-version` header?

The default value is `2023-06-01`. This is hard-coded in the `default_headers` property of the `Anthropic` client class in [`src/anthropic/_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_client.py).

### Can I override the API version for a single request only?

Yes. Pass a `default_headers` dictionary containing your desired `anthropic-version` to any SDK method call (such as `client.messages.create()`). This merges with the client's default headers for that specific request without affecting subsequent calls.

### What happens if I specify an unsupported API version?

The SDK does not validate the `anthropic-version` value locally. Instead, the Anthropic API validates the header when it receives the request. If you specify an unsupported version, the API will return an error response rather than processing the request.

### Where is the `anthropic-version` header defined in the source code?

The header is defined in [`src/anthropic/_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_client.py) within the `default_headers` property (around lines 176-181). This property constructs the final header dictionary by merging base client headers, SDK-specific headers, the hard-coded version string, and any user-provided custom headers.