Files
Agent-Workbench/tests/fixtures/model-request-contract/sources/anthropic-beta.md
T
2026-11-07 14:53:51 +08:00

9.8 KiB
Raw Blame History

title, url, description
title url description
Beta headers https://platform.claude.com/docs/en/api/beta-headers Access experimental features before they become part of the standard API with the `anthropic-beta` header or the SDK's `betas` parameter.

Beta headers allow you to access experimental features and new model capabilities before they become part of the standard API.

The [client SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) exposes a `client.beta` (csharp, go: `client.Beta`; java: `client.beta()`; php: `$client->beta`) namespace for calling the API with beta features enabled.

How to use beta headers

To access beta features, include the anthropic-beta header in your API requests:

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2026-10-21
anthropic-beta: BETA_FEATURE_NAME
content-type: application/json

Each feature’s documentation states the exact beta name to send. The API overview lists the APIs in beta.

The following example sends a request with the context editing beta. The SDK takes beta names through betas (csharp, go: Betas; java: .addBeta()) and sends the anthropic-beta header for you:

```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2026-10-21" \ -H "anthropic-beta: context-management-2025-06-27" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 1024, "messages": [ {"role": "user", "content": "Hello, Claude"} ] }' ```
ant beta:messages create \
  --beta context-management-2025-06-27 \
  --model claude-opus-5-5 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'
client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    betas=["context-management-2025-06-27"],
)

print(response.content)
const client = new Anthropic();

const msg = await client.beta.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  betas: ["context-management-2025-06-27"]
});

console.log(msg.content);
var client = new AnthropicClient();

var message = await client.Beta.Messages.Create(
    new MessageCreateParams
    {
        Model = Model.ClaudeOpus5_5,
        MaxTokens = 1024,
        Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
        Betas = ["context-management-2025-06-27"],
    }
);

Console.WriteLine(string.Join("\n", message.Content));
client := anthropic.NewClient()

message, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
	Model:     anthropic.ModelClaudeOpus5_5,
	MaxTokens: 1024,
	Messages: []anthropic.BetaMessageParam{
		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),
	},
	Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},
})
if err != nil {
	panic(err)
}

fmt.Printf("%+v\n", message.Content)
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_5_5)
    .maxTokens(1024)
    .addUserMessage("Hello, Claude")
    .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
    .build();

BetaMessage message = client.beta().messages().create(params);
System.out.println(message.content());
$client = new Client();

$message = $client->beta->messages->create(
    maxTokens: 1024,
    messages: [['role' => 'user', 'content' => 'Hello, Claude']],
    model: Model::CLAUDE_OPUS_5_5,
    betas: ['context-management-2025-06-27'],
);

echo $message;
client = Anthropic::Client.new

message = client.beta.messages.create(
  model: Anthropic::Model::CLAUDE_OPUS_5_5,
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  betas: ["context-management-2025-06-27"]
)

puts(message.content)
Beta features are experimental and may:
  • Have breaking changes with notice
  • Be deprecated or removed
  • Have different rate limits or pricing
  • Not be available in all regions

Multiple beta features

To use multiple beta features in a single request, include all feature names in the header separated by commas:

anthropic-beta: feature1,feature2,feature3

You can also send the anthropic-beta header more than once in the same request. The Claude API reads every anthropic-beta header, so the following is equivalent to the previous example:

anthropic-beta: feature1
anthropic-beta: feature2
anthropic-beta: feature3

With the SDK, list each feature (for example, betas=["feature1", "feature2"] (typescript, ruby: betas: ["feature1", "feature2"]; php: betas: ['feature1', 'feature2']; csharp: Betas = ["feature1", "feature2"]; go: Betas: []anthropic.AnthropicBeta{"feature1", "feature2"}; java: .addBeta("feature1").addBeta("feature2"))). With the CLI, pass a single --beta flag with the feature names separated by commas (for example, --beta feature1,feature2). You can also repeat the flag (for example, --beta feature1 --beta feature2).

Beta features on other platforms

Beta names are the same on every platform that accepts them, but not every platform accepts every beta. Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Microsoft Foundry, and Claude Models on Google Cloud (Google managed) take beta names in the anthropic-beta header, as the Claude API does. To send several betas, put their names in one header, separated by commas: Claude Models on Google Cloud (Google managed) reads only one anthropic-beta header and ignores the rest, so betas in the others don’t take effect.

On Amazon Bedrock, where beta names go depends on the API you call:

  • Claude in Amazon Bedrock (bedrock-mantle endpoints) takes them in the anthropic-beta header.
  • The InvokeModel API reads them from the request body, not from a header. List them in the body’s anthropic_beta array, one name for each element, for example "anthropic_beta": ["feature1", "feature2"].

Endpoint-specific headers

Some beta APIs are scoped to specific endpoints and require a feature-specific beta header on every request:

Endpoints Beta header
/v1/agents, /v1/sessions, /v1/environments managed-agents-2026-04-01
/v1/tunnels mcp-tunnels-2026-06-22
/v1/memory_stores and sub-resources agent-memory-2026-07-22

The SDK’s client.beta (csharp, go: client.Beta; java: client.beta(); php: $client->beta) namespace adds these headers automatically. Add them yourself only when making raw HTTP requests. See the Managed Agents overview, Using agent memory, and the MCP tunnels reference for details.

Endpoint-specific headers that apply to the same endpoint aren’t always combinable. On memory store endpoints, agent-memory-2026-07-22 replaces managed-agents-2026-04-01: sending both on the same request returns a 400 error. The SDK sends the correct header for each endpoint automatically.

Version naming conventions

Beta feature names typically follow the pattern feature-name-YYYY-MM-DD, where the date indicates when the beta was released. Always use the exact beta feature name as documented.

Error handling

If you use an invalid beta name, or a beta your organization doesn’t have access to, you’ll receive a 400 error response:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Unexpected value(s) `invalid-beta-name` for the `anthropic-beta` header. Please consult our documentation at platform.claude.com/docs or try again without the header."
  },
  "request_id": "req_011CcnGfC9fELffo2EALu4Wd"
}

Getting help

For updates to beta features, see the release notes. For help with production issues, contact support.

Next steps

Understand the HTTP status codes, error response shape, and request IDs the Claude API returns, and handle errors with the SDK’s typed exceptions. Explore the Claude API’s features, including the APIs in beta.