SPB Git

Repository Public

beta-headers.md 7.9 KB 229 lines markdown

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
Files main
Menu

Theme