Repository Public
1---2title: Beta headers3url: https://platform.claude.com/docs/en/api/beta-headers4description: Access experimental features before they become part of the standard API with the `anthropic-beta` header or the SDKs' `betas` parameter.5---67Beta headers allow you to access experimental features and new model capabilities before they become part of the standard API.89<Info>10 Each [client SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) exposes a `beta` namespace for calling the API with beta features enabled.11</Info>1213## How to use beta headers1415To access beta features, include the `anthropic-beta` header in your API requests:1617```http18POST /v1/messages19x-api-key: YOUR_API_KEY20anthropic-version: 2023-06-0121anthropic-beta: BETA_FEATURE_NAME22content-type: application/json23```2425Each feature's documentation states the exact beta name to send. The [API overview](https://platform.claude.com/docs/en/api/overview) lists the APIs currently in beta.2627The following examples show the same request with cURL, the `ant` CLI, and the SDKs, using the [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) beta as the example. The SDKs take beta names in the `betas` parameter and send the `anthropic-beta` header for you:2829<CodeGroup>30 ```bash cURL31 curl https://api.anthropic.com/v1/messages \32 -H "x-api-key: $ANTHROPIC_API_KEY" \33 -H "anthropic-version: 2023-06-01" \34 -H "anthropic-beta: context-management-2025-06-27" \35 -H "content-type: application/json" \36 -d '{37 "model": "claude-opus-5",38 "max_tokens": 1024,39 "messages": [40 {"role": "user", "content": "Hello, Claude"}41 ]42 }'43 ```4445 ```bash CLI46 ant beta:messages create \47 --beta context-management-2025-06-27 \48 --model claude-opus-5 \49 --max-tokens 1024 \50 --message '{role: user, content: "Hello, Claude"}'51 ```5253 ```python Python54 client = Anthropic()5556 response = client.beta.messages.create(57 model="claude-opus-5",58 max_tokens=1024,59 messages=[{"role": "user", "content": "Hello, Claude"}],60 betas=["context-management-2025-06-27"],61 )6263 print(response.content)64 ```6566 ```typescript TypeScript67 const client = new Anthropic();6869 const msg = await client.beta.messages.create({70 model: "claude-opus-5",71 max_tokens: 1024,72 messages: [{ role: "user", content: "Hello, Claude" }],73 betas: ["context-management-2025-06-27"]74 });7576 console.log(msg.content);77 ```7879 ```csharp C#80 var client = new AnthropicClient();8182 var message = await client.Beta.Messages.Create(83 new MessageCreateParams84 {85 Model = "claude-opus-5",86 MaxTokens = 1024,87 Messages = [new() { Role = Role.User, Content = "Hello, Claude" }],88 Betas = ["context-management-2025-06-27"],89 }90 );9192 Console.WriteLine(string.Join("\n", message.Content));93 ```9495 ```go Go96 client := anthropic.NewClient()9798 message, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{99 Model: anthropic.ModelClaudeOpus5,100 MaxTokens: 1024,101 Messages: []anthropic.BetaMessageParam{102 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),103 },104 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},105 })106 if err != nil {107 panic(err)108 }109110 fmt.Printf("%+v\n", message.Content)111 ```112113 ```java Java114 AnthropicClient client = AnthropicOkHttpClient.fromEnv();115116 MessageCreateParams params = MessageCreateParams.builder()117 .model(Model.CLAUDE_OPUS_5)118 .maxTokens(1024)119 .addUserMessage("Hello, Claude")120 .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)121 .build();122123 BetaMessage message = client.beta().messages().create(params);124 System.out.println(message.content());125 ```126127 ```php PHP128 $client = new Client();129130 $message = $client->beta->messages->create(131 maxTokens: 1024,132 messages: [['role' => 'user', 'content' => 'Hello, Claude']],133 model: 'claude-opus-5',134 betas: ['context-management-2025-06-27'],135 );136137 echo $message;138 ```139140 ```ruby Ruby141 client = Anthropic::Client.new142143 message = client.beta.messages.create(144 model: "claude-opus-5",145 max_tokens: 1024,146 messages: [{role: "user", content: "Hello, Claude"}],147 betas: ["context-management-2025-06-27"]148 )149150 puts(message.content)151 ```152</CodeGroup>153154<Warning>155 Beta features are experimental and may:156157 * Have breaking changes with notice158 * Be deprecated or removed159 * Have different rate limits or pricing160 * Not be available in all regions161</Warning>162163### Multiple beta features164165To use multiple beta features in a single request, include all feature names in the header separated by commas:166167```http168anthropic-beta: feature1,feature2,feature3169```170171You 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:172173```http174anthropic-beta: feature1175anthropic-beta: feature2176anthropic-beta: feature3177```178179When using an SDK, list each feature in the `betas` parameter (for example, `betas=["feature1", "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`).180181### Endpoint-specific headers182183Some beta APIs are scoped to specific endpoints and require a feature-specific beta header on every request:184185| Endpoints | Beta header |186| ------------------------------------------------ | --------------------------- |187| `/v1/agents`, `/v1/sessions`, `/v1/environments` | `managed-agents-2026-04-01` |188| `/v1/tunnels` | `mcp-tunnels-2026-06-22` |189| `/v1/memory_stores` and sub-resources | `agent-memory-2026-07-22` |190191The SDKs' `beta` namespaces add these headers automatically. Add them yourself only when making raw HTTP requests. See the [Managed Agents overview](https://platform.claude.com/docs/en/managed-agents/overview), [Using agent memory](https://platform.claude.com/docs/en/managed-agents/memory), and the [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#tunnels-api) for details.192193Endpoint-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 client SDKs send the correct header for each endpoint automatically.194195### Version naming conventions196197Beta 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.198199## Error handling200201If you use an invalid beta name, or a beta your organization doesn't have access to, you'll receive a `400` error response:202203```json Output204{205 "type": "error",206 "error": {207 "type": "invalid_request_error",208 "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."209 },210 "request_id": "req_011CcnGfC9fELffo2EALu4Wd"211}212```213214## Getting help215216For updates to beta features, see the [release notes](https://platform.claude.com/docs/en/release-notes/overview). For help with production issues, contact [support](https://support.claude.com/).217218## Next steps219220<CardGroup cols={2}>221 <Card title="Errors" icon="info" href="https://platform.claude.com/docs/en/api/errors">222 Understand the HTTP status codes, error response shape, and request IDs the Claude API returns, and handle errors with the SDKs' typed exceptions.223 </Card>224225 <Card title="API overview" icon="compass" href="https://platform.claude.com/docs/en/api/overview">226 Explore the Claude API's features, including the APIs currently in beta.227 </Card>228</CardGroup>229