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

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, the default_headers property constructs the header dictionary by merging the base client's defaults with SDK-specific values:

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

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:

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

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}