One read of Claude Developer Platformapi-20261104T020710Z
159 pages moved out of 847 read.
Pages moved
159
significant first
Pages read
847
in this capture
Captured
02:07 UTC
Corpus hash
61cf340e1136
corpus-hash
What this read moved
26-50 of 159, page 2 of 7This capture is too large to show at once. Changes 26-50 of 159 are below, significant first; the rest are on the following screens.
build-with-claude/claude-platform-on-aws Changed · +69 / -27 lines
### Connect through AWS PrivateLink
from line 39
3939
4040If you need AWS-operated Claude, see [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock). Claude Platform on AWS uses a separate capacity pool from both the first-party Claude API and Amazon Bedrock. You can run workloads on more than one platform and fail over between them.
4141
42[AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) is supported for connecting your VPC to the Claude Platform on AWS endpoint.
42[AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) is supported for connecting your VPC to the Claude Platform on AWS endpoint (see [Connect through AWS PrivateLink](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#connect-through-aws-privatelink)).
4343
4444**When to choose Bedrock:** Organizations in regulated industries that require FedRAMP High, IL4, IL5, or HIPAA-ready compliance, or that need AWS to be the sole data processor, should use [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock). Bedrock runs entirely on AWS-controlled infrastructure with AWS as the operating party.
4545
from line 130
130130* **“Not found” message during sign-in:** This message might appear briefly during redirect. You can dismiss it.
131131* **Usage page shows no data after your first API call:** Usage data can take a few minutes to appear in the Claude Console.
132132* **“Outbound web identity federation is disabled” on your first API call:** Enable federation once per account. See [Enable outbound web identity federation](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation).
133* **403 `permission_error` that names `sts:GetWebIdentityToken` or `sts:TagGetWebIdentityToken`:** Grant both actions to the IAM principal that the error message names. See [IAM policies](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#iam-policies).
133134
134135## Before making API calls
135136
from line 140
1391402. The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) installed and configured
1401413. **Outbound web identity federation enabled** on your AWS account, a one-time setup step (see [Enable outbound web identity federation](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation))
1411424. Your workspace ID (see [Obtain your workspace ID](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#obtain-your-workspace-id))
1425. IAM permission to call the API: the `aws-external-anthropic:CreateInference` action on your workspace, plus `aws-external-anthropic:CallWithBearerToken` if you authenticate with an API key (see [IAM policies](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#iam-policies))
1435. IAM permission to call the API: the `aws-external-anthropic:CreateInference` action on your workspace, plus the `sts:GetWebIdentityToken` and `sts:TagGetWebIdentityToken` actions (see [IAM policies](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#iam-policies))
1446. IAM permission for the `aws-external-anthropic:CallWithBearerToken` action if you authenticate with an API key (see [API key authentication](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#api-key-authentication))
143145
144146### Enable outbound web identity federation
145147
from line 199
197199
198200For simpler integration paths (local development and scripts), you can authenticate with an API key instead of SigV4. Set the `ANTHROPIC_AWS_API_KEY` environment variable or pass `api_key` (typescript, php: `apiKey`; go: `APIKey`; java: `.apiKey()`; csharp: `AwsClientOptions.ApiKey`) when you create the client.
199201
200Generate API keys in the **AWS Console** under **Claude Platform on AWS → API keys**. Click **Generate a key**, then copy the key value. Grant the `aws-external-anthropic:CallWithBearerToken` IAM action to the principals that should be allowed to use API key authentication.
202Generate API keys in the **AWS Console** under **Claude Platform on AWS → API keys**. Click **Generate a key**, then copy the key value. Principals that use API keys need the same IAM permissions as principals that sign requests with SigV4, including two STS actions (see [IAM policies](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#iam-policies)). Also grant the `aws-external-anthropic:CallWithBearerToken` IAM action to the principals that should be allowed to use API key authentication.
201203
202204<Note>
203205 API keys for Claude Platform on AWS are managed in the AWS Console, not the Claude Console. Keys created in the standard Claude Console at [platform.claude.com](https://platform.claude.com/) (for first-party API access) don’t work with the Claude Platform on AWS endpoint.
from line 259
257259
258260If you can generate the token locally, your process already has SigV4 credentials, and SigV4 authentication is usually the simpler choice. Use short-term keys when the process making API calls is separate from the process that holds AWS credentials.
259261
260The SDK does not refresh short-term keys automatically. When a token expires, generate a new one and construct a new client. The principal that uses the token still needs the `aws-external-anthropic:CallWithBearerToken` IAM action.
262The SDK does not refresh short-term keys automatically. When a token expires, generate a new one and construct a new client. The principal whose AWS credentials you use to generate the token needs the permissions described in [API key authentication](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#api-key-authentication).
261263
262264### Credential precedence
263265
from line 391
389391 -u "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
390392 -H "x-amz-security-token: $AWS_SESSION_TOKEN" \
391393 -H "content-type: application/json" \
392 -H "anthropic-version: 2023-06-01" \
394 -H "anthropic-version: 2026-10-21" \
393395 -H "anthropic-workspace-id: $ANTHROPIC_AWS_WORKSPACE_ID" \
394396 -d '{
395397 "model": "claude-sonnet-5-5",
from line 445
443445 ```csharp C#
444446 using Anthropic;
445447 using Anthropic.Aws;
448 using Anthropic.Models.Messages;
446449
447450 var client = new AnthropicAwsClient();
448451
from line 545
542545
543546Context-window sizes on Claude Platform on AWS are identical to the first-party Claude API. See [Context windows](https://platform.claude.com/docs/en/build-with-claude/context-windows) for per-model limits.
544547
548### Connect through AWS PrivateLink
549
550To connect your VPC to the Claude Platform on AWS endpoint through AWS PrivateLink, create an interface VPC endpoint in your workspace’s AWS region. For the procedure, see [Access an AWS service using an interface VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html) in the AWS documentation.
551
552The endpoint service name follows this format:
553
554```text wrap
555com.amazonaws.{region}.aws-external-anthropic
556```
557
558For example:
559
560```text wrap
561com.amazonaws.us-east-2.aws-external-anthropic
562```
563
564The endpoint service name is a different string from the hostname in the base URL, `aws-external-anthropic.{region}.api.aws`. That hostname is the service’s private DNS name. With private DNS enabled on the interface endpoint, it resolves to that endpoint inside your VPC. The SDK client and cURL requests keep the same base URL.
565
545566## Feature support
546567
547568Claude Platform on AWS uses Claude API endpoints directly, which means you get full feature parity with the first-party Claude API (except where noted in the [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported)):
from line 597
576597The following capabilities are not currently available on Claude Platform on AWS:
577598
578599* **HIPAA readiness:** Anthropic’s HIPAA-ready program is not available. See [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
600* **Admin API:** Workspace endpoints (create, get, list, update, and archive on `/v1/organizations/workspaces`), external key endpoints (register, get, list, update, and delete on `/v1/organizations/external_keys`, for [CMEK](https://platform.claude.com/docs/en/manage-claude/cmek); keys are validated when attached to a workspace rather than through a validate endpoint), the [telemetry destination endpoints](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#telemetry-destinations), and the [Usage and Cost Analytics API](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api) endpoints are available. Other Admin API endpoints (organization members, workspace members, invites, API keys, the legacy [Usage and Cost API](https://platform.claude.com/docs/en/manage-claude/usage-cost-api), and rate limit reports) are not available. AWS IAM manages organization membership.
601* **Workspace member management:** Adding or removing users from individual workspaces is not available. AWS IAM policies on workspace ARNs control access.
602* **Claude Code workspace and Claude Code Analytics API:** The Claude Code workspace with automatic rate limits is not available. Claude Code usage appears in the general usage view rather than a dedicated screen.
603* **OAuth authentication:** Not supported. Use SigV4 or API key authentication.
604* **Fast mode:** Not available on Claude Platform on AWS.
605* **OpenAI-compatible API endpoints:** Not available on Claude Platform on AWS.
606* **MCP tunnels:** Only MCP servers exposed over the public internet are supported.
579607
580- **Admin API:** Workspace endpoints (create, get, list, update, and archive on `/v1/organizations/workspaces`), external key endpoints (register, get, list, update, and delete on `/v1/organizations/external_keys`, for [CMEK](https://platform.claude.com/docs/en/manage-claude/cmek); keys are validated when attached to a workspace rather than through a validate endpoint), the [telemetry destination endpoints](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#telemetry-destinations), and the [Usage and Cost Analytics API](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api) endpoints are available. Other Admin API endpoints (organization members, workspace members, invites, API keys, the legacy [Usage and Cost API](https://platform.claude.com/docs/en/manage-claude/usage-cost-api), and rate limit reports) are not available. AWS IAM manages organization membership.
581- **Workspace member management:** Adding or removing users from individual workspaces is not available. AWS IAM policies on workspace ARNs control access.
582- **Claude Code workspace and Analytics API:** The Claude Code workspace with automatic rate limits is not available. Claude Code usage appears in the general usage view rather than a dedicated screen.
583- **OAuth authentication:** Not supported. Use SigV4 or API key authentication.
584- **Fast mode:** Not available on Claude Platform on AWS.
585- **OpenAI-compatible API endpoints:** Not available on Claude Platform on AWS.
586- **MCP tunnels:** Only MCP servers exposed over the public internet are supported.
587
588608## Data residency
589609
590610Claude Platform on AWS supports the following inference geographies:
from line 631
611631 -u "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
612632 -H "x-amz-security-token: $AWS_SESSION_TOKEN" \
613633 -H "content-type: application/json" \
614 -H "anthropic-version: 2023-06-01" \
634 -H "anthropic-version: 2026-10-21" \
615635 -H "anthropic-workspace-id: $ANTHROPIC_AWS_WORKSPACE_ID" \
616636 -d '{
617637 "model": "claude-sonnet-5-5",
from line 686
666686 ```csharp C#
667687 using Anthropic;
668688 using Anthropic.Aws;
689 using Anthropic.Models.Messages;
669690
670691 var client = new AnthropicAwsClient();
671692
from line 908
887908 -u "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
888909 -H "x-amz-security-token: $AWS_SESSION_TOKEN" \
889910 -H "content-type: application/json" \
890 -H "anthropic-version: 2023-06-01" \
911 -H "anthropic-version: 2026-10-21" \
891912 -H "anthropic-workspace-id: $ANTHROPIC_AWS_WORKSPACE_ID" \
892913 -d '{
893914 "model": "claude-sonnet-5-5",
from line 974
953974 ```csharp C#
954975 using Anthropic;
955976 using Anthropic.Aws;
977 using Anthropic.Models.Messages;
956978
957979 var client = new AnthropicAwsClient();
958980
959 var response = await client.WithRawResponse.Messages.Create(new()
981 using var response = await client.WithRawResponse.Messages.Create(new()
960982 {
961983 Model = Model.ClaudeSonnet5_5,
962984 MaxTokens = 1024,
from line 985
963985 Messages = [new UserMessageParam { Content = "Hello!" }]
964986 });
965987
966 Console.WriteLine(response.Headers.GetValues("x-amzn-requestid").First()); // AWS request ID
967 Console.WriteLine(response.Headers.GetValues("request-id").First()); // Anthropic request ID
968 Console.WriteLine(response.Value.Content);
988 Console.WriteLine(response.GetHeaderValues("x-amzn-requestid").First()); // AWS request ID
989 Console.WriteLine(response.RequestID); // Anthropic request ID
990 Console.WriteLine(await response.Deserialize());
969991 ```
970992
971993 ```go Go
from line 1050
10281050
10291051 $client = new Client();
10301052
1031 $response = $client->messages->raw->create(
1032 model: 'claude-sonnet-5-5',
1033 maxTokens: 1024,
1034 messages: [['role' => 'user', 'content' => 'Hello!']],
1035 );
1053 $response = $client->messages->raw->create([
1054 'model' => 'claude-sonnet-5-5',
1055 'maxTokens' => 1024,
1056 'messages' => [['role' => 'user', 'content' => 'Hello!']],
1057 ]);
10361058
10371059 echo $response->getHeaderLine('x-amzn-requestid') . "\n"; // AWS request ID
10381060 echo $response->getHeaderLine('request-id') . "\n"; // Anthropic request ID
1039 echo $response->parse()->content;
1061 echo $response->parse();
10401062 ```
10411063
10421064 ```ruby Ruby
from line 1157
11351157
11361158The SigV4 service name and IAM action namespace is `aws-external-anthropic`. Actions follow the pattern `aws-external-anthropic:<Action>` (for example, `aws-external-anthropic:CreateInference`).
11371159
1160Every principal that calls the API, with SigV4 or an API key, also needs permission for two AWS STS actions: `sts:GetWebIdentityToken` and `sts:TagGetWebIdentityToken`. The Claude Platform on AWS gateway calls STS as that principal to get a JWT it forwards to Anthropic (see [Enable outbound web identity federation](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation)). If either permission is missing, requests fail with a 403 `permission_error` whose message names the denied action, even when the `aws-external-anthropic` actions are granted.
1161
1162If the principal has the `AnthropicFullAccess`, `AnthropicLimitedAccess`, or `AnthropicReadOnlyAccess` AWS managed policy, or administrator access, it already has both actions. A custom policy must grant them, as the following example does. The example allows `sts:GetWebIdentityToken` only when the gateway makes the call and names one of Anthropic’s two audiences, as those managed policies do.
1163
11381164### Example: deny batch inference
11391165
11401166The following policy allows real-time inference while blocking batch processing:
from line 1182
11561182 },
11571183 {
11581184 "Effect": "Allow",
1159 "Action": "aws-external-anthropic:ListWorkspaces",
1185 "Action": ["aws-external-anthropic:ListWorkspaces", "sts:TagGetWebIdentityToken"],
11601186 "Resource": "*"
11611187 },
11621188 {
1189 "Effect": "Allow",
1190 "Action": "sts:GetWebIdentityToken",
1191 "Resource": "*",
1192 "Condition": {
1193 "ForAnyValue:StringEquals": {
1194 "sts:IdentityTokenAudience": [
1195 "https://api.anthropic.com",
1196 "https://platform.claude.com"
1197 ]
1198 },
1199 "StringEquals": {
1200 "aws:CalledViaLast": "aws-external-anthropic.amazonaws.com"
1201 }
1202 }
1203 },
1204 {
11631205 "Effect": "Deny",
11641206 "Action": [
11651207 "aws-external-anthropic:CreateBatchInference",
from line 1219
11771219<Note>
11781220 `ListWorkspaces` is account-scoped, so it appears in a separate Allow statement with `"Resource": "*"`. Specifying a workspace ARN on an account-scoped action has no effect (see [Provisioning automation](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#provisioning-automation)).
11791221
1180 This policy assumes AWS SigV4 authentication. If the principal authenticates with an API key, also add `aws-external-anthropic:CallWithBearerToken` to the `"Resource": "*"` Allow statement. `CallWithBearerToken` is a route-less authentication-layer action that does not bind to a workspace ARN. See [Per-customer workspace isolation](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#per-customer-workspace-isolation) for the two-statement pattern.
1222 This policy assumes AWS SigV4 authentication. If the principal authenticates with an API key, also add `aws-external-anthropic:CallWithBearerToken` to the `"Resource": "*"` Allow statement that holds `ListWorkspaces`. `CallWithBearerToken` is a route-less authentication-layer action that does not bind to a workspace ARN. See [Per-customer workspace isolation](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#per-customer-workspace-isolation) for a policy that grants it.
11811223</Note>
11821224
11831225### Managed policies
build-with-claude/compaction-threshold Changed · +158 / -106 lines
from line 73
7373 ```bash cURL
7474 curl https://api.anthropic.com/v1/messages \
7575 -H "x-api-key: $ANTHROPIC_API_KEY" \
76 -H "anthropic-version: 2023-06-01" \
76 -H "anthropic-version: 2026-10-21" \
7777 -H "anthropic-beta: compact-2026-01-12" \
7878 -H "content-type: application/json" \
7979 -d '{
from line 301
301301 ```bash cURL
302302 curl https://api.anthropic.com/v1/messages \
303303 -H "x-api-key: $ANTHROPIC_API_KEY" \
304 -H "anthropic-version: 2023-06-01" \
304 -H "anthropic-version: 2026-10-21" \
305305 -H "anthropic-beta: compact-2026-01-12" \
306306 -H "content-type: application/json" \
307307 -d '{
from line 522
522522 ```bash cURL
523523 curl https://api.anthropic.com/v1/messages \
524524 -H "x-api-key: $ANTHROPIC_API_KEY" \
525 -H "anthropic-version: 2023-06-01" \
525 -H "anthropic-version: 2026-10-21" \
526526 -H "anthropic-beta: compact-2026-01-12" \
527527 -H "content-type: application/json" \
528528 -d '{
from line 748
748748 # for the full pause-and-continue flow. Single paused request:
749749 curl https://api.anthropic.com/v1/messages \
750750 -H "x-api-key: $ANTHROPIC_API_KEY" \
751 -H "anthropic-version: 2023-06-01" \
751 -H "anthropic-version: 2026-10-21" \
752752 -H "anthropic-beta: compact-2026-01-12" \
753753 -H "content-type: application/json" \
754754 -d '{
from line 1074
10741074 ```
10751075</CodeGroup>
10761076
1077The API pauses even if no summary is generated. The `compaction` block’s `content` is then `null`, so keep the original messages when you continue. If safeguards block the summary, `content` is also `null` and the stop reason is `refusal` instead of `compaction`. [`stop_details`](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#refusal) gives the policy category, if there is one. Continue the same way in both cases: look for the `compaction` block instead of testing `stop_reason`, as the [example that preserves recent messages](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#examples) does.
1078
10771079#### Enforcing a total token budget
10781080
10791081When a model works on long tasks with many tool-use iterations, total token consumption can grow significantly. You can combine `pause_after_compaction` with a compaction counter to estimate cumulative usage and gracefully conclude the task once a budget is reached.
from line 1658
16561658* Keep the original messages in your list and let the API handle removing the compacted content
16571659* Manually drop the compacted messages and only include the compaction block onward
16581660
1661If no summary is generated, the block’s `content` is `null` and the API ignores the block. Nothing is compacted, so keep the original messages.
1662
16591663On Claude 5.1 and later models, thinking blocks from before a `compaction` block aren’t carried forward, so the summary is all the model has of that earlier work. If you write your own `instructions`, tell the model what the summary must retain; see [Tell the model what to preserve in compaction summaries](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#tell-the-model-what-to-preserve-in-compaction-summaries).
16601664
16611665### Streaming
from line 1670
16661670 ```bash cURL
16671671 curl https://api.anthropic.com/v1/messages \
16681672 -H "x-api-key: $ANTHROPIC_API_KEY" \
1669 -H "anthropic-version: 2023-06-01" \
1673 -H "anthropic-version: 2026-10-21" \
16701674 -H "anthropic-beta: compact-2026-01-12" \
16711675 -H "content-type: application/json" \
16721676 -d '{
from line 2034
20302034 ```bash cURL
20312035 curl https://api.anthropic.com/v1/messages \
20322036 -H "x-api-key: $ANTHROPIC_API_KEY" \
2033 -H "anthropic-version: 2023-06-01" \
2037 -H "anthropic-version: 2026-10-21" \
20342038 -H "anthropic-beta: compact-2026-01-12" \
20352039 -H "content-type: application/json" \
20362040 -d '{
from line 2309
23052309 ```bash cURL
23062310 curl https://api.anthropic.com/v1/messages/count_tokens \
23072311 -H "x-api-key: $ANTHROPIC_API_KEY" \
2308 -H "anthropic-version: 2023-06-01" \
2312 -H "anthropic-version: 2026-10-21" \
23092313 -H "anthropic-beta: compact-2026-01-12" \
23102314 -H "content-type: application/json" \
23112315 -d '{
from line 2521
25172521
25182522
25192523 # Run a long conversation
2520 print(chat("Help me build a Python web scraper"))
2521 print(chat("Add support for JavaScript-rendered pages"))
2522 print(chat("Now add rate limiting and error handling"))
2524 print(chat("Briefly, help me build a Python web scraper"))
2525 print(chat("Briefly, add support for JavaScript-rendered pages"))
2526 print(chat("Briefly, add rate limiting and error handling"))
25232527 # Continue calling chat() for as long as the conversation needs
25242528 ```
25252529
from line 2559
25552559 }
25562560
25572561 // Run a long conversation
2558 console.log(await chat("Help me build a Python web scraper"));
2559 console.log(await chat("Add support for JavaScript-rendered pages"));
2560 console.log(await chat("Now add rate limiting and error handling"));
2562 console.log(await chat("Briefly, help me build a Python web scraper"));
2563 console.log(await chat("Briefly, add support for JavaScript-rendered pages"));
2564 console.log(await chat("Briefly, add rate limiting and error handling"));
25612565 // Continue calling chat() for as long as the conversation needs
25622566 ```
25632567
from line 2569
25652569 AnthropicClient client = new();
25662570 List<BetaMessageParam> messages = new();
25672571
2568 Console.WriteLine(await Chat(client, messages, "Help me build a Python web scraper"));
2569 Console.WriteLine(await Chat(client, messages, "Add support for JavaScript-rendered pages"));
2570 Console.WriteLine(await Chat(client, messages, "Now add rate limiting and error handling"));
2572 Console.WriteLine(await Chat(client, messages, "Briefly, help me build a Python web scraper"));
2573 Console.WriteLine(await Chat(client, messages, "Briefly, add support for JavaScript-rendered pages"));
2574 Console.WriteLine(await Chat(client, messages, "Briefly, add rate limiting and error handling"));
25712575
25722576 static async Task<string> Chat(AnthropicClient client, List<BetaMessageParam> messages, string userMessage)
25732577 {
from line 2654
26502654 }
26512655
26522656 func main() {
2653 fmt.Println(chat("Help me build a Python web scraper"))
2654 fmt.Println(chat("Add support for JavaScript-rendered pages"))
2655 fmt.Println(chat("Now add rate limiting and error handling"))
2657 fmt.Println(chat("Briefly, help me build a Python web scraper"))
2658 fmt.Println(chat("Briefly, add support for JavaScript-rendered pages"))
2659 fmt.Println(chat("Briefly, add rate limiting and error handling"))
26562660 }
26572661 ```
26582662
from line 2669
26652669 private static final List<BetaMessageParam> messages = new ArrayList<>();
26662670
26672671 public static void main(String[] args) {
2668 System.out.println(chat("Help me build a Python web scraper"));
2669 System.out.println(chat("Add support for JavaScript-rendered pages"));
2670 System.out.println(chat("Now add rate limiting and error handling"));
2672 System.out.println(chat("Briefly, help me build a Python web scraper"));
2673 System.out.println(chat("Briefly, add support for JavaScript-rendered pages"));
2674 System.out.println(chat("Briefly, add rate limiting and error handling"));
26712675 }
26722676
26732677 private static String chat(String userMessage) {
from line 2737
27332737 return '';
27342738 }
27352739
2736 echo chat($client, $messages, 'Help me build a Python web scraper') . "\n";
2737 echo chat($client, $messages, 'Add support for JavaScript-rendered pages') . "\n";
2738 echo chat($client, $messages, 'Now add rate limiting and error handling') . "\n";
2740 echo chat($client, $messages, 'Briefly, help me build a Python web scraper') . "\n";
2741 echo chat($client, $messages, 'Briefly, add support for JavaScript-rendered pages') . "\n";
2742 echo chat($client, $messages, 'Briefly, add rate limiting and error handling') . "\n";
27392743 ```
27402744
27412745 ```ruby Ruby
from line 2769
27652769 response.content.find { |block| block.type == :text }&.text || ""
27662770 end
27672771
2768 puts chat(client, messages, "Help me build a Python web scraper")
2769 puts chat(client, messages, "Add support for JavaScript-rendered pages")
2770 puts chat(client, messages, "Now add rate limiting and error handling")
2772 puts chat(client, messages, "Briefly, help me build a Python web scraper")
2773 puts chat(client, messages, "Briefly, add support for JavaScript-rendered pages")
2774 puts chat(client, messages, "Briefly, add rate limiting and error handling")
27712775 ```
27722776</CodeGroup>
27732777
from line 2815
28112815 },
28122816 )
28132817
2814 # Check if compaction occurred and paused
2815 if response.stop_reason == "compaction":
2816 # Get the compaction block from the response
2817 compaction_block = response.content[0]
2818 # Look for the compaction block, not the stop reason:
2819 # stop_reason is "refusal", not "compaction", if the summary was blocked
2820 compaction_block = next(
2821 (block for block in response.content if block.type == "compaction"), None
2822 )
28182823
2824 # Replace the history only if a summary was generated
2825 if compaction_block is not None and compaction_block.content is not None:
28192826 # Preserve the prior exchange + current user message (3 messages)
28202827 # by including them after the compaction block, without thinking
28212828 # blocks; an assistant turn left with no content is dropped
from line 2847
28402847 {"role": "assistant", "content": new_assistant_content}
28412848 ] + preserved_messages
28422849
2843 # Continue the request with the compacted context + preserved messages
2850 # Update the message list to reflect the compaction
2851 messages.clear()
2852 messages.extend(messages_after_compaction)
2853
2854 if compaction_block is not None:
2855 # Continue the request, with the full history if there is no summary
28442856 response = client.beta.messages.create(
28452857 betas=["compact-2026-01-12"],
28462858 model="claude-opus-5-5",
28472859 max_tokens=4096,
2848 messages=messages_after_compaction,
2860 messages=messages,
28492861 context_management={"edits": [{"type": "compact_20260112"}]},
28502862 )
28512863
2852 # Update the message list to reflect the compaction
2853 messages.clear()
2854 messages.extend(messages_after_compaction)
2855
28562864 # Append the final response
28572865 messages.append({"role": "assistant", "content": response.content})
28582866
from line 2869
28612869
28622870
28632871 # Run a long conversation
2864 print(chat("Help me build a Python web scraper"))
2865 print(chat("Add support for JavaScript-rendered pages"))
2866 print(chat("Now add rate limiting and error handling"))
2872 print(chat("Briefly, help me build a Python web scraper"))
2873 print(chat("Briefly, add support for JavaScript-rendered pages"))
2874 print(chat("Briefly, add rate limiting and error handling"))
28672875 # Continue calling chat() for as long as the conversation needs
28682876 ```
28692877
from line 2899
28912899 }
28922900 });
28932901
2894 // Check if compaction occurred and paused
2895 if (response.stop_reason === "compaction") {
2896 // Get the compaction block from the response
2897 const compactionBlock = response.content[0];
2902 // Look for the compaction block, not the stop reason:
2903 // stop_reason is "refusal", not "compaction", if the summary was blocked
2904 const compactionBlock = response.content.find((block) => block.type === "compaction");
28982905
2906 // Replace the history only if a summary was generated
2907 if (compactionBlock && compactionBlock.content !== null) {
28992908 // Preserve the prior exchange + current user message (3 messages)
29002909 // by including them after the compaction block, without thinking
29012910 // blocks; an assistant turn left with no content is dropped
from line 2928
29192928 ...preservedMessages
29202929 ];
29212930
2922 // Continue the request with the compacted context + preserved messages
2931 // Update the message list to reflect the compaction
2932 messages = messagesAfterCompaction;
2933 }
2934
2935 if (compactionBlock) {
2936 // Continue the request, with the full history if there is no summary
29232937 response = await client.beta.messages.create({
29242938 betas: ["compact-2026-01-12"],
29252939 model: "claude-opus-5-5",
29262940 max_tokens: 4096,
2927 messages: messagesAfterCompaction,
2941 messages,
29282942 context_management: {
29292943 edits: [{ type: "compact_20260112" }]
29302944 }
29312945 });
2932
2933 // Update the message list to reflect the compaction
2934 messages = messagesAfterCompaction;
29352946 }
29362947
29372948 // Append the final response
from line 2954
29432954 }
29442955
29452956 // Run a long conversation
2946 console.log(await chat("Help me build a Python web scraper"));
2947 console.log(await chat("Add support for JavaScript-rendered pages"));
2948 console.log(await chat("Now add rate limiting and error handling"));
2957 console.log(await chat("Briefly, help me build a Python web scraper"));
2958 console.log(await chat("Briefly, add support for JavaScript-rendered pages"));
2959 console.log(await chat("Briefly, add rate limiting and error handling"));
29492960 // Continue calling chat() for as long as the conversation needs
29502961 ```
29512962
from line 2964
29532964 AnthropicClient client = new();
29542965 List<BetaMessageParam> messages = new();
29552966
2956 Console.WriteLine(await Chat("Help me build a Python web scraper"));
2957 Console.WriteLine(await Chat("Add support for JavaScript-rendered pages"));
2958 Console.WriteLine(await Chat("Now add rate limiting and error handling"));
2967 Console.WriteLine(await Chat("Briefly, help me build a Python web scraper"));
2968 Console.WriteLine(await Chat("Briefly, add support for JavaScript-rendered pages"));
2969 Console.WriteLine(await Chat("Briefly, add rate limiting and error handling"));
29592970
29602971 async Task<string> Chat(string userMessage)
29612972 {
from line 2988
29772988 }
29782989 });
29792990
2980 if (response.StopReason == BetaStopReason.Compaction)
2981 {
2982 if (!response.Content[0].TryPickCompaction(out _))
2983 throw new InvalidOperationException("Expected compaction block");
2991 // Look for the compaction block, not the stop reason:
2992 // StopReason is Refusal, not Compaction, if the summary was blocked
2993 var compactionBlock = response.Content.FirstOrDefault(block => block.Value is BetaCompactionBlock);
29842994
2995 // Replace the history only if a summary was generated
2996 if (compactionBlock?.Value is BetaCompactionBlock { Content: not null })
2997 {
29852998 // Preserve the prior exchange + current user message (3 messages),
29862999 // without thinking blocks; an assistant turn left empty is dropped
29873000 var preserved = new List<BetaMessageParam>();
from line 3020
30073020 {
30083021 new BetaAssistantMessageParam
30093022 {
3010 Content = new List<BetaContentBlockParam> { new BetaContentBlockParam(response.Content[0].Json) }
3023 Content = new List<BetaContentBlockParam> { new BetaContentBlockParam(compactionBlock.Json) }
30113024 }
30123025 };
30133026 messagesAfterCompaction.AddRange(preserved);
30143027
3028 messages = messagesAfterCompaction;
3029 }
3030
3031 if (compactionBlock is not null)
3032 {
3033 // Continue the request, with the full history if there is no summary
30153034 response = await client.Beta.Messages.Create(new()
30163035 {
30173036 Betas = ["compact-2026-01-12"],
30183037 Model = Model.ClaudeOpus5_5,
30193038 MaxTokens = 4096,
3020 Messages = messagesAfterCompaction,
3039 Messages = messages,
30213040 ContextManagement = new BetaContextManagementConfig
30223041 {
30233042 Edits = [new BetaCompact20260112Edit()]
30243043 }
30253044 });
3026
3027 messages = messagesAfterCompaction;
30283045 }
30293046
30303047 messages.Add(new BetaAssistantMessageParam
from line 3064
30473064 "context"
30483065 "fmt"
30493066 "log"
3067 "slices"
30503068
30513069 "github.com/anthropics/anthropic-sdk-go/v2"
30523070 )
from line 3097
30793097 log.Fatal(err)
30803098 }
30813099
3082 if response.StopReason == "compaction" {
3083 compactionParam := response.Content[0].ToParam()
3100 // Look for the compaction block, not the stop reason:
3101 // StopReason is "refusal", not "compaction", if the summary was blocked
3102 compactionIndex := slices.IndexFunc(response.Content, func(block anthropic.BetaContentBlockUnion) bool {
3103 return block.Type == "compaction"
3104 })
30843105
3106 // Replace the history only if a summary was generated (content is not null)
3107 if compactionIndex >= 0 && response.Content[compactionIndex].JSON.Content.Valid() {
3108 compactionParam := response.Content[compactionIndex].ToParam()
3109
30853110 // Preserve the prior exchange + current user message (3 messages),
30863111 // without thinking blocks; an assistant turn left empty is dropped
30873112 var preserved []anthropic.BetaMessageParam
from line 3132
31073132 }
31083133 messagesAfterCompaction = append(messagesAfterCompaction, preserved...)
31093134
3135 messages = messagesAfterCompaction
3136 }
3137
3138 if compactionIndex >= 0 {
3139 // Continue the request, with the full history if there is no summary
31103140 response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
31113141 Model: anthropic.ModelClaudeOpus5_5,
31123142 MaxTokens: 4096,
3113 Messages: messagesAfterCompaction,
3143 Messages: messages,
31143144 ContextManagement: anthropic.BetaContextManagementConfigParam{
31153145 Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
31163146 {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
from line 3151
31213151 if err != nil {
31223152 log.Fatal(err)
31233153 }
3124
3125 messages = messagesAfterCompaction
31263154 }
31273155
31283156 messages = append(messages, response.ToParam())
from line 3164
31363164 }
31373165
31383166 func main() {
3139 fmt.Println(chat("Help me build a Python web scraper"))
3140 fmt.Println(chat("Add support for JavaScript-rendered pages"))
3141 fmt.Println(chat("Now add rate limiting and error handling"))
3167 fmt.Println(chat("Briefly, help me build a Python web scraper"))
3168 fmt.Println(chat("Briefly, add support for JavaScript-rendered pages"))
3169 fmt.Println(chat("Briefly, add rate limiting and error handling"))
31423170 }
31433171 ```
31443172
from line 3174
31463174 import com.anthropic.models.beta.messages.BetaContextManagementConfig;
31473175 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
31483176 import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
3149 import com.anthropic.models.beta.messages.BetaStopReason;
31503177 // ...
31513178 private static final AnthropicClient client = AnthropicOkHttpClient.fromEnv();
31523179 private static final List<BetaMessageParam> messages = new ArrayList<>();
from line 3198
31713198
31723199 BetaMessage response = client.beta().messages().create(params);
31733200
3174 // Check if compaction occurred and paused
3175 if (response.stopReason().isPresent()
3176 && response.stopReason().get().equals(BetaStopReason.COMPACTION)) {
3201 // Look for the compaction block, not the stop reason:
3202 // stopReason() is REFUSAL, not COMPACTION, if the summary was blocked
3203 var compactionBlock = response.content().stream()
3204 .flatMap(block -> block.compaction().stream())
3205 .findFirst();
3206
3207 // Replace the history only if a summary was generated
3208 if (compactionBlock.flatMap(block -> block.content()).isPresent()) {
31773209 // Preserve the prior exchange + current user message (3 messages),
31783210 // without thinking blocks; an assistant turn left empty is dropped
31793211 List<BetaMessageParam> preservedMessages = new ArrayList<>();
from line 3227
31953227 messagesAfterCompaction.add(response.toParam());
31963228 messagesAfterCompaction.addAll(preservedMessages);
31973229
3198 // Continue the request with the compacted context + preserved messages
3230 // Update the message list to reflect the compaction
3231 messages.clear();
3232 messages.addAll(messagesAfterCompaction);
3233 }
3234
3235 if (compactionBlock.isPresent()) {
3236 // Continue the request, with the full history if there is no summary
31993237 MessageCreateParams continueParams = MessageCreateParams.builder()
32003238 .addBeta("compact-2026-01-12")
32013239 .model(Model.CLAUDE_OPUS_5_5)
32023240 .maxTokens(4096L)
3203 .messages(messagesAfterCompaction)
3241 .messages(messages)
32043242 .contextManagement(BetaContextManagementConfig.builder()
32053243 .addEdit(BetaCompact20260112Edit.builder().build())
32063244 .build())
from line 3245
32073245 .build();
32083246
32093247 response = client.beta().messages().create(continueParams);
3210
3211 // Update the message list to reflect the compaction
3212 messages.clear();
3213 messages.addAll(messagesAfterCompaction);
32143248 }
32153249
32163250 // Append the final response
from line 3258
32243258 }
32253259
32263260 public static void main(String[] args) {
3227 System.out.println(chat("Help me build a Python web scraper"));
3228 System.out.println(chat("Add support for JavaScript-rendered pages"));
3229 System.out.println(chat("Now add rate limiting and error handling"));
3261 System.out.println(chat("Briefly, help me build a Python web scraper"));
3262 System.out.println(chat("Briefly, add support for JavaScript-rendered pages"));
3263 System.out.println(chat("Briefly, add rate limiting and error handling"));
32303264 }
32313265 ```
32323266
from line 3288
32543288 ]
32553289 );
32563290
3257 if ($response->stopReason === 'compaction') {
3258 $compactionBlock = $response->content[0];
3291 // Look for the compaction block, not the stop reason:
3292 // stopReason is 'refusal', not 'compaction', if the summary was blocked
3293 $compactionBlock = null;
3294 foreach ($response->content as $block) {
3295 if ($block instanceof \Anthropic\Beta\Messages\BetaCompactionBlock) {
3296 $compactionBlock = $block;
3297 break;
3298 }
3299 }
32593300
3301 // Replace the history only if a summary was generated
3302 if ($compactionBlock?->content !== null) {
32603303 // Preserve the prior exchange + current user message (3 messages),
32613304 // without thinking blocks; an assistant turn left empty is dropped
32623305 $preserved = array_values(array_filter(array_map(
from line 3317
32743317 $preserved
32753318 );
32763319
3320 $messages = $messagesAfterCompaction;
3321 }
3322
3323 if ($compactionBlock !== null) {
3324 // Continue the request, with the full history if there is no summary
32773325 $response = $client->beta->messages->create(
32783326 maxTokens: 4096,
3279 messages: $messagesAfterCompaction,
3327 messages: $messages,
32803328 model: 'claude-opus-5-5',
32813329 betas: ['compact-2026-01-12'],
32823330 contextManagement: [
from line 3331
32833331 'edits' => [['type' => 'compact_20260112']]
32843332 ]
32853333 );
3286
3287 $messages = $messagesAfterCompaction;
32883334 }
32893335
32903336 $messages[] = ['role' => 'assistant', 'content' => $response->content];
from line 3343
32973343 return '';
32983344 }
32993345
3300 echo chat($client, $messages, 'Help me build a Python web scraper') . "\n";
3301 echo chat($client, $messages, 'Add support for JavaScript-rendered pages') . "\n";
3302 echo chat($client, $messages, 'Now add rate limiting and error handling') . "\n";
3346 echo chat($client, $messages, 'Briefly, help me build a Python web scraper') . "\n";
3347 echo chat($client, $messages, 'Briefly, add support for JavaScript-rendered pages') . "\n";
3348 echo chat($client, $messages, 'Briefly, add rate limiting and error handling') . "\n";
33033349 ```
33043350
33053351 ```ruby Ruby
from line 3371
33253371 }
33263372 )
33273373
3328 if response.stop_reason == :compaction
3329 compaction_block = response.content[0]
3374 # Look for the compaction block, not the stop reason:
3375 # stop_reason is :refusal, not :compaction, if the summary was blocked
3376 compaction_block = response.content.find { |block| block.type == :compaction }
33303377
3378 # Replace the history only if a summary was generated
3379 if compaction_block&.content
33313380 # Preserve the prior exchange + current user message (3 messages),
33323381 # without thinking blocks; an assistant turn left empty is dropped
33333382 preserved = messages.last(3).map do |message|
from line 3389
33403389 { role: "assistant", content: [compaction_block] }
33413390 ] + preserved
33423391
3392 messages.clear
3393 messages.concat(messages_after_compaction)
3394 end
3395
3396 if compaction_block
3397 # Continue the request, with the full history if there is no summary
33433398 response = client.beta.messages.create(
33443399 betas: ["compact-2026-01-12"],
33453400 model: Anthropic::Model::CLAUDE_OPUS_5_5,
33463401 max_tokens: 4096,
3347 messages: messages_after_compaction,
3402 messages: messages,
33483403 context_management: {
33493404 edits: [{ type: "compact_20260112" }]
33503405 }
33513406 )
3352
3353 messages.clear
3354 messages.concat(messages_after_compaction)
33553407 end
33563408
33573409 messages << { role: "assistant", content: response.content }
from line 3411
33593411 response.content.find { |block| block.type == :text }&.text || ""
33603412 end
33613413
3362 puts chat(client, messages, "Help me build a Python web scraper")
3363 puts chat(client, messages, "Add support for JavaScript-rendered pages")
3364 puts chat(client, messages, "Now add rate limiting and error handling")
3414 puts chat(client, messages, "Briefly, help me build a Python web scraper")
3415 puts chat(client, messages, "Briefly, add support for JavaScript-rendered pages")
3416 puts chat(client, messages, "Briefly, add rate limiting and error handling")
33653417 ```
33663418</CodeGroup>
33673419
build-with-claude/context-editing Changed · +8 / -8 lines
from line 111
111111 ```bash cURL
112112 curl https://api.anthropic.com/v1/messages \
113113 -H "x-api-key: $ANTHROPIC_API_KEY" \
114 -H "anthropic-version: 2023-06-01" \
114 -H "anthropic-version: 2026-10-21" \
115115 -H "content-type: application/json" \
116116 -H "anthropic-beta: context-management-2025-06-27" \
117117 -d '{
from line 324
324324 ```bash cURL
325325 curl https://api.anthropic.com/v1/messages \
326326 -H "x-api-key: $ANTHROPIC_API_KEY" \
327 -H "anthropic-version: 2023-06-01" \
327 -H "anthropic-version: 2026-10-21" \
328328 -H "content-type: application/json" \
329329 -H "anthropic-beta: context-management-2025-06-27" \
330330 -d '{
from line 727
727727 ```bash cURL
728728 curl https://api.anthropic.com/v1/messages \
729729 -H "x-api-key: $ANTHROPIC_API_KEY" \
730 -H "anthropic-version: 2023-06-01" \
730 -H "anthropic-version: 2026-10-21" \
731731 -H "content-type: application/json" \
732732 -H "anthropic-beta: context-management-2025-06-27" \
733733 -d '{
from line 956
956956 ```bash cURL
957957 curl https://api.anthropic.com/v1/messages \
958958 -H "x-api-key: $ANTHROPIC_API_KEY" \
959 -H "anthropic-version: 2023-06-01" \
959 -H "anthropic-version: 2026-10-21" \
960960 -H "content-type: application/json" \
961961 -H "anthropic-beta: context-management-2025-06-27" \
962962 -d '{
from line 1168
11681168 ```bash cURL
11691169 curl https://api.anthropic.com/v1/messages \
11701170 -H "x-api-key: $ANTHROPIC_API_KEY" \
1171 -H "anthropic-version: 2023-06-01" \
1171 -H "anthropic-version: 2026-10-21" \
11721172 -H "content-type: application/json" \
11731173 -H "anthropic-beta: context-management-2025-06-27" \
11741174 -d '{
from line 1368
13681368 ```bash cURL
13691369 curl https://api.anthropic.com/v1/messages \
13701370 -H "x-api-key: $ANTHROPIC_API_KEY" \
1371 -H "anthropic-version: 2023-06-01" \
1371 -H "anthropic-version: 2026-10-21" \
13721372 -H "content-type: application/json" \
13731373 -H "anthropic-beta: context-management-2025-06-27" \
13741374 -d '{
from line 1820
18201820 ```bash cURL
18211821 curl https://api.anthropic.com/v1/messages/count_tokens \
18221822 -H "x-api-key: $ANTHROPIC_API_KEY" \
1823 -H "anthropic-version: 2023-06-01" \
1823 -H "anthropic-version: 2026-10-21" \
18241824 -H "content-type: application/json" \
18251825 -H "anthropic-beta: context-management-2025-06-27" \
18261826 -d '{
from line 2125
21252125 ```bash cURL
21262126 curl https://api.anthropic.com/v1/messages \
21272127 -H "x-api-key: $ANTHROPIC_API_KEY" \
2128 -H "anthropic-version: 2023-06-01" \
2128 -H "anthropic-version: 2026-10-21" \
21292129 -H "content-type: application/json" \
21302130 -H "anthropic-beta: context-management-2025-06-27" \
21312131 -d '{
build-with-claude/fallback-credit Changed · +3 / -3 lines
from line 34
3434
3535<Steps>
3636 <Step title="Opt in with the beta header">
37 Send the request that may be refused with the `anthropic-beta: fallback-credit-2026-07-01` header. The `server-side-fallback-2026-07-01` header also grants the same fields, except on Amazon Bedrock and Claude Models on Google Cloud (Google managed), which return a 400 error for that header. The earlier `fallback-credit-2026-06-01` header remains accepted and grants the same fields.
37 Send the request that might be refused with the `anthropic-beta: fallback-credit-2026-07-01` header. The `server-side-fallback-2026-07-01` header also grants the same fields, except on Claude Models on Google Cloud (Google managed) and Amazon Bedrock, which return a 400 error for that header. The `fallback-credit-2026-06-01` header is accepted and grants the same fields.
3838 </Step>
3939
4040 <Step title="Read two fields from the refusal">
from line 606
606606</Accordion>
607607
608608<Accordion title="Token scope and lifetime">
609 The token redeems only from the organization and workspace that received the refusal, including on Microsoft Foundry. On Amazon Bedrock and Claude Models on Google Cloud (Google managed), which do not have workspaces, the token is bound to the platform’s caller identity instead.
609 The token redeems only from the organization and workspace that received the refusal, including on Microsoft Foundry. On Claude Models on Google Cloud (Google managed) and Amazon Bedrock, which do not have workspaces, the token is bound to the platform’s caller identity instead.
610610
611611 The token expires 5 minutes after the refusal. After that, send the retry without it. The token is also stateless: the server stores nothing about it, and there is no endpoint to inspect or revoke it.
612612</Accordion>
from line 637
637637 Every `stop_reason` value and how to handle it.
638638 </Card>
639639
640 <Card title="SDK middleware" icon="settings" href="https://platform.claude.com/docs/en/cli-sdks-libraries/middleware">
640 <Card title="SDK middleware" icon="settings" href="https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#client-side-fallback">
641641 The SDK helper that applies fallback credit automatically.
642642 </Card>
643643</CardGroup>
build-with-claude/files Changed · +8 / -8 lines
from line 68
6868 ```bash cURL
6969 curl -X POST https://api.anthropic.com/v1/files \
7070 -H "x-api-key: $ANTHROPIC_API_KEY" \
71 -H "anthropic-version: 2023-06-01" \
71 -H "anthropic-version: 2026-10-21" \
7272 -F "file=@/path/to/document.pdf"
7373 ```
7474
from line 194
194194 ```bash cURL
195195 curl -X POST https://api.anthropic.com/v1/messages \
196196 -H "x-api-key: $ANTHROPIC_API_KEY" \
197 -H "anthropic-version: 2023-06-01" \
197 -H "anthropic-version: 2026-10-21" \
198198 -H "content-type: application/json" \
199199 -d '{
200200 "model": "claude-opus-5-5",
from line 467
467467 curl https://api.anthropic.com/v1/messages \
468468 -H "content-type: application/json" \
469469 -H "x-api-key: $ANTHROPIC_API_KEY" \
470 -H "anthropic-version: 2023-06-01" \
470 -H "anthropic-version: 2026-10-21" \
471471 -d @- <<EOF
472472 {
473473 "model": "claude-opus-5-5",
from line 702
702702 ```bash cURL
703703 curl https://api.anthropic.com/v1/files \
704704 -H "x-api-key: $ANTHROPIC_API_KEY" \
705 -H "anthropic-version: 2023-06-01"
705 -H "anthropic-version: 2026-10-21"
706706 ```
707707
708708 ```bash CLI
from line 775
775775 ```bash cURL
776776 curl "https://api.anthropic.com/v1/files/$FILE_ID" \
777777 -H "x-api-key: $ANTHROPIC_API_KEY" \
778 -H "anthropic-version: 2023-06-01"
778 -H "anthropic-version: 2026-10-21"
779779 ```
780780
781781 ```bash CLI
from line 831
831831 ```bash cURL
832832 curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
833833 -H "x-api-key: $ANTHROPIC_API_KEY" \
834 -H "anthropic-version: 2023-06-01"
834 -H "anthropic-version: 2026-10-21"
835835 ```
836836
837837 ```bash CLI
from line 878
878878 ```bash cURL
879879 curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/content" \
880880 -H "x-api-key: $ANTHROPIC_API_KEY" \
881 -H "anthropic-version: 2023-06-01" \
881 -H "anthropic-version: 2026-10-21" \
882882 -o downloaded_file.txt
883883 ```
884884
from line 992
992992
993993## Migrate from `files-api-2025-04-14`
994994
995The Files API is out of beta and needs no beta header. Migrating off `files-api-2025-04-14` is optional: requests that still send it keep working and keep returning the beta response shapes, so an existing integration keeps working until you change it. Removing the header switches those requests to the shapes documented on this page:
995The Files API is out of beta and needs no beta header. Migrating off `files-api-2025-04-14` is optional: requests that send it keep working and keep returning the beta response shapes, so an existing integration keeps working until you change it. Removing the header switches those requests to the shapes documented on this page:
996996
997997| | With `files-api-2025-04-14` | Without the header |
998998| ---------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------- |
build-with-claude/handling-stop-reasons Changed · +10 / -10 lines
from line 55
5555 ```bash cURL
5656 curl https://api.anthropic.com/v1/messages \
5757 -H "x-api-key: $ANTHROPIC_API_KEY" \
58 -H "anthropic-version: 2023-06-01" \
58 -H "anthropic-version: 2026-10-21" \
5959 -H "content-type: application/json" \
6060 -d '{
6161 "model": "claude-opus-5-5",
from line 740
740740 ```bash cURL
741741 curl https://api.anthropic.com/v1/messages \
742742 -H "x-api-key: $ANTHROPIC_API_KEY" \
743 -H "anthropic-version: 2023-06-01" \
743 -H "anthropic-version: 2026-10-21" \
744744 -H "content-type: application/json" \
745745 -d '{
746746 "model": "claude-opus-5-5",
from line 1052
10521052 ```bash cURL
10531053 curl https://api.anthropic.com/v1/messages \
10541054 -H "x-api-key: $ANTHROPIC_API_KEY" \
1055 -H "anthropic-version: 2023-06-01" \
1055 -H "anthropic-version: 2026-10-21" \
10561056 -H "content-type: application/json" \
10571057 -d '{
10581058 "model": "claude-opus-5-5",
from line 1196
11961196 ```bash cURL
11971197 curl https://api.anthropic.com/v1/messages \
11981198 -H "x-api-key: $ANTHROPIC_API_KEY" \
1199 -H "anthropic-version: 2023-06-01" \
1199 -H "anthropic-version: 2026-10-21" \
12001200 -H "content-type: application/json" \
12011201 -d '{
12021202 "model": "claude-opus-5-5",
from line 1539
15391539 # on the response and re-POST with the assistant content appended.
15401540 curl https://api.anthropic.com/v1/messages \
15411541 -H "x-api-key: $ANTHROPIC_API_KEY" \
1542 -H "anthropic-version: 2023-06-01" \
1542 -H "anthropic-version: 2026-10-21" \
15431543 -H "content-type: application/json" \
15441544 -d '{
15451545 "model": "claude-opus-5-5",
from line 1757
17571757 ```bash cURL
17581758 curl https://api.anthropic.com/v1/messages \
17591759 -H "x-api-key: $ANTHROPIC_API_KEY" \
1760 -H "anthropic-version: 2023-06-01" \
1760 -H "anthropic-version: 2026-10-21" \
17611761 -H "content-type: application/json" \
17621762 -d '{
17631763 "model": "claude-opus-5-5",
from line 1894
18941894</CodeGroup>
18951895
18961896<Tip>
1897 If you encounter `refusal` stop reasons frequently while using Claude Sonnet 4.5 ([deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations)) or Claude Opus 4.1 (the latter [retired, except on Bedrock and Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations)), you can try updating your API calls to use Haiku 4.5 (`claude-haiku-4-5-20251001`), which has different usage restrictions. Learn more about [understanding Sonnet 4.5’s API safety filters](https://support.claude.com/en/articles/12449294-understanding-sonnet-4-5-s-api-safety-filters).
1897 If you encounter `refusal` stop reasons frequently while using Claude Sonnet 4.5 ([deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations)) or Claude Opus 4.1 (the latter [retired, except on Claude Models on Google Cloud (Google managed) and Amazon Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations)), you can try updating your API calls to use Claude Haiku 4.5 (`claude-haiku-4-5-20251001`), which has different usage restrictions. Learn more about [understanding Sonnet 4.5’s API safety filters](https://support.claude.com/en/articles/12449294-understanding-sonnet-4-5-s-api-safety-filters).
18981898</Tip>
18991899
19001900On a refusal, the [`stop_details`](https://platform.claude.com/docs/en/api/messages/create#message.stop_details) object identifies the policy category that triggered it. The categories and the full refusal response shape are covered in [What a refusal looks like](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response). `stop_details` is `null` for all stop reasons other than `refusal`.
from line 1913
19131913 ```bash cURL
19141914 curl https://api.anthropic.com/v1/messages \
19151915 -H "x-api-key: $ANTHROPIC_API_KEY" \
1916 -H "anthropic-version: 2023-06-01" \
1916 -H "anthropic-version: 2026-10-21" \
19171917 -H "content-type: application/json" \
19181918 -d '{
19191919 "model": "claude-opus-5-5",
from line 2703
27032703 # $? for errors and stop_reason for successful responses.
27042704 curl --fail-with-body https://api.anthropic.com/v1/messages \
27052705 -H "x-api-key: $ANTHROPIC_API_KEY" \
2706 -H "anthropic-version: 2023-06-01" \
2706 -H "anthropic-version: 2026-10-21" \
27072707 -H "content-type: application/json" \
27082708 -d '{
27092709 "model": "claude-opus-5-5",
from line 2917
29172917 # The message_delta event in the SSE stream carries stop_reason.
29182918 curl -N https://api.anthropic.com/v1/messages \
29192919 -H "x-api-key: $ANTHROPIC_API_KEY" \
2920 -H "anthropic-version: 2023-06-01" \
2920 -H "anthropic-version: 2026-10-21" \
29212921 -H "content-type: application/json" \
29222922 -d '{
29232923 "model": "claude-opus-5-5",
build-with-claude/mid-conversation-system-messages Changed · +5 / -5 lines
from line 58
5858 curl https://api.anthropic.com/v1/messages \
5959 -H "content-type: application/json" \
6060 -H "x-api-key: $ANTHROPIC_API_KEY" \
61 -H "anthropic-version: 2023-06-01" \
61 -H "anthropic-version: 2026-10-21" \
6262 -H "anthropic-beta: inline-tools-2026-09-15" \
6363 -d '{
6464 "model": "claude-opus-5-5",
from line 507
507507 curl https://api.anthropic.com/v1/messages \
508508 -H "content-type: application/json" \
509509 -H "x-api-key: $ANTHROPIC_API_KEY" \
510 -H "anthropic-version: 2023-06-01" \
510 -H "anthropic-version: 2026-10-21" \
511511 -H "anthropic-beta: inline-tools-2026-09-15" \
512512 -d '{
513513 "model": "claude-opus-5-5",
from line 1069
10691069 curl https://api.anthropic.com/v1/messages \
10701070 -H "content-type: application/json" \
10711071 -H "x-api-key: $ANTHROPIC_API_KEY" \
1072 -H "anthropic-version: 2023-06-01" \
1072 -H "anthropic-version: 2026-10-21" \
10731073 -H "anthropic-beta: inline-tools-2026-09-15,mcp-client-2026-09-15" \
10741074 -d '{
10751075 "model": "claude-opus-5-5",
from line 1665
16651665 curl https://api.anthropic.com/v1/messages \
16661666 -H "content-type: application/json" \
16671667 -H "x-api-key: $ANTHROPIC_API_KEY" \
1668 -H "anthropic-version: 2023-06-01" \
1668 -H "anthropic-version: 2026-10-21" \
16691669 -d '{
16701670 "model": "claude-opus-5-5",
16711671 "max_tokens": 1024,
from line 2123
21232123 ```bash cURL
21242124 curl https://api.anthropic.com/v1/messages \
21252125 -H "x-api-key: $ANTHROPIC_API_KEY" \
2126 -H "anthropic-version: 2023-06-01" \
2126 -H "anthropic-version: 2026-10-21" \
21272127 -H "anthropic-beta: mid-conversation-system-clear-at-2026-08-21" \
21282128 -H "content-type: application/json" \
21292129 -d '{
build-with-claude/multilingual-support Changed · +26 / -26 lines
from line 33
3333
3434## Overview
3535
36Claude demonstrates robust multilingual capabilities, with particularly strong performance in zero-shot tasks across languages. The model maintains consistent relative performance across both widely spoken and lower-resource languages, making it a reliable choice for multilingual applications.
36Claude demonstrates robust multilingual capabilities, with particularly strong performance in zero-shot tasks across languages.
3737
3838Claude is capable in many languages beyond those benchmarked in the following table. Test with any languages relevant to your specific use cases.
3939
4040## Performance data
4141
42The following table shows zero-shot chain-of-thought evaluation scores for Claude models across languages, expressed as a percentage relative to English performance (100%):
42The following table shows zero-shot scores for Claude models on [Global-MMLU](https://arxiv.org/abs/2412.03304), which extends the [MMLU (Massive Multitask Language Understanding)](https://en.wikipedia.org/wiki/MMLU) test set to 42 languages. Each score is a percentage of the same model’s English score:
4343
44| Language | Claude Sonnet 4.5 (deprecated)<sup>1</sup> | Claude Haiku 4.5<sup>1</sup> |
45| --------------------------------- | ------------------------------------------ | ---------------------------- |
46| English (baseline, fixed to 100%) | 100% | 100% |
47| Spanish | 98.2% | 96.4% |
48| Portuguese (Brazil) | 97.8% | 96.1% |
49| Italian | 97.9% | 96.0% |
50| French | 97.5% | 95.7% |
51| Indonesian | 97.3% | 94.2% |
52| German | 97.0% | 94.3% |
53| Arabic | 97.2% | 92.5% |
54| Chinese (Simplified) | 96.9% | 94.2% |
55| Korean | 96.7% | 93.3% |
56| Japanese | 96.8% | 93.5% |
57| Hindi | 96.7% | 92.4% |
58| Bengali | 95.4% | 90.4% |
59| Swahili | 91.1% | 78.3% |
60| Yoruba | 79.7% | 52.7% |
44| Language | Claude Fable 5.1 | Claude Opus 5.5 | Claude Sonnet 5.5 | Claude Haiku 5.5 |
45| -------------------- | ---------------- | --------------- | ----------------- | ---------------- |
46| English | 100% | 100% | 100% | 100% |
47| Spanish | 99.4% | 99.3% | 99.0% | 98.1% |
48| Portuguese (Brazil) | 99.0% | 99.2% | 98.7% | 98.1% |
49| Italian | 99.0% | 99.2% | 98.4% | 97.7% |
50| French | 99.0% | 99.3% | 98.7% | 97.7% |
51| Indonesian | 98.9% | 99.1% | 98.6% | 97.1% |
52| German | 99.1% | 99.1% | 98.5% | 97.4% |
53| Arabic | 98.7% | 99.3% | 98.3% | 96.6% |
54| Chinese (Simplified) | 98.8% | 99.3% | 98.5% | 97.7% |
55| Korean | 98.8% | 99.1% | 98.3% | 97.0% |
56| Japanese | 98.7% | 99.2% | 98.4% | 97.4% |
57| Hindi | 98.9% | 99.2% | 98.5% | 96.6% |
58| Bengali | 98.3% | 98.6% | 97.2% | 95.4% |
59| Swahili | 97.7% | 98.3% | 96.9% | 94.0% |
60| Yoruba | 95.1% | 96.3% | 93.6% | 87.0% |
6161
62<sup>1</sup> With [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking).
62All scores use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) at the `max` [effort level](https://platform.claude.com/docs/en/build-with-claude/effort). Scores exclude questions that safety classifiers blocked or that went unanswered. For each score in the table, at most 1.7 percent of the questions are excluded.
6363
6464<Note>
65 These metrics are based on [MMLU (Massive Multitask Language Understanding)](https://en.wikipedia.org/wiki/MMLU) English test sets that were translated into 14 additional languages by professional human translators, as documented in [OpenAI’s simple-evals repository](https://github.com/openai/simple-evals/blob/main/multilingual_mmlu_benchmark_results.md). The use of human translators for this evaluation ensures high-quality translations, particularly important for languages with fewer digital resources.
65 Use the table to compare languages within a model, not to rank models. Differences of less than about 1 percentage point are within measurement noise.
6666</Note>
6767
6868***
from line 76
7676 curl https://api.anthropic.com/v1/messages \
7777 -H "content-type: application/json" \
7878 -H "x-api-key: $ANTHROPIC_API_KEY" \
79 -H "anthropic-version: 2023-06-01" \
79 -H "anthropic-version: 2026-10-21" \
8080 -d '{
8181 "model": "claude-opus-5-5",
8282 "max_tokens": 1024,
from line 230
230230 </Card>
231231
232232 <Card title="Customer support agent" icon="headset" href="https://platform.claude.com/docs/en/about-claude/use-case-guides/customer-support-chat">
233 Build a localized support chatbot using a language-constrained system prompt.
233 Build a customer support chatbot. One chatbot can serve customers in many languages.
234234 </Card>
235235
236236 <Card title="Models overview" icon="table" href="https://platform.claude.com/docs/en/models/overview">
from line 238
238238 </Card>
239239
240240 <Card title="Define success criteria and build evaluations" icon="scales" href="https://platform.claude.com/docs/en/test-and-evaluate/develop-tests">
241 Evaluate translation and localization quality before you ship.
241 Apply general evaluation methods to measure output quality in each language you support.
242242 </Card>
243243</CardGroup>
244244
build-with-claude/pdf-support Changed · +7 / -7 lines
from line 89
89893. By a `file_id` from the [Files API](https://platform.claude.com/docs/en/build-with-claude/files)
9090
9191<Note>
92 On Amazon Bedrock and Claude Models on Google Cloud (Google managed), only base64-encoded sources are currently available. On Microsoft Foundry, the Files API is not supported for deployments hosted on Azure.
92 On Claude Models on Google Cloud (Google managed) and Amazon Bedrock, only base64-encoded sources are available. On Microsoft Foundry, the Files API is not supported for deployments hosted on Azure.
9393</Note>
9494
9595#### Option 1: URL-based PDF document
from line 101
101101 curl https://api.anthropic.com/v1/messages \
102102 -H "content-type: application/json" \
103103 -H "x-api-key: $ANTHROPIC_API_KEY" \
104 -H "anthropic-version: 2023-06-01" \
104 -H "anthropic-version: 2026-10-21" \
105105 -d '{
106106 "model": "claude-opus-5-5",
107107 "max_tokens": 1024,
from line 396
396396 curl https://api.anthropic.com/v1/messages \
397397 -H "content-type: application/json" \
398398 -H "x-api-key: $ANTHROPIC_API_KEY" \
399 -H "anthropic-version: 2023-06-01" \
399 -H "anthropic-version: 2026-10-21" \
400400 -d @request.json
401401 ```
402402
from line 709
709709 # First, upload your PDF to the Files API
710710 curl -sS -X POST https://api.anthropic.com/v1/files \
711711 -H "x-api-key: $ANTHROPIC_API_KEY" \
712 -H "anthropic-version: 2023-06-01" \
712 -H "anthropic-version: 2026-10-21" \
714714
715715 # Then use the file_id from the upload response in your message
from line 716
716716 curl https://api.anthropic.com/v1/messages \
717717 -H "content-type: application/json" \
718718 -H "x-api-key: $ANTHROPIC_API_KEY" \
719 -H "anthropic-version: 2023-06-01" \
719 -H "anthropic-version: 2026-10-21" \
720720 -d '{
721721 "model": "claude-opus-5-5",
722722 "max_tokens": 1024,
from line 1080
10801080 curl https://api.anthropic.com/v1/messages \
10811081 -H "content-type: application/json" \
10821082 -H "x-api-key: $ANTHROPIC_API_KEY" \
1083 -H "anthropic-version: 2023-06-01" \
1083 -H "anthropic-version: 2026-10-21" \
10841084 -d @-
10851085 ```
10861086
from line 1437
14371437 curl https://api.anthropic.com/v1/messages/batches \
14381438 -H "content-type: application/json" \
14391439 -H "x-api-key: $ANTHROPIC_API_KEY" \
1440 -H "anthropic-version: 2023-06-01" \
1440 -H "anthropic-version: 2026-10-21" \
14411441 -d @request.json
14421442 ```
14431443
build-with-claude/preserved-thinking Changed · +14 / -14 lines
from line 184
184184 ```bash cURL
185185 curl https://api.anthropic.com/v1/messages \
186186 -H "x-api-key: $ANTHROPIC_API_KEY" \
187 -H "anthropic-version: 2023-06-01" \
187 -H "anthropic-version: 2026-10-21" \
188188 -H "anthropic-beta: thinking-binding-controls-2026-08-01" \
189189 -H "content-type: application/json" \
190190 -d '{
from line 1070
10701070
10711071Each common prefix edit has a replacement that gives the model the same information and leaves earlier bytes unchanged, so later thinking stays valid. Find the edit your code makes today in the first column:
10721072
1073| Instead of | Use | Beta header |
1074| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1075| Rebuilding the top-level `system` prompt | A [mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#new-instructions) | None |
1076| Re-rendering the context in your first user message (environment, date, memory, project instructions) on each request | Render it once and resend it unchanged. When something changes, [put the new version in the newest turn](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#changing-context) | None |
1077| Clearing or shortening old `tool_result` content, or re-encoding old images, in place | Shorten a tool result or downscale an image before the first time you send it, not after. To clear old results later, [trim context on the server](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#server-side-trimming) with `clear_tool_uses_20250919` | `context-management-2025-06-27` |
1078| Injecting a reminder and deleting it on the next request | A [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#per-turn-reminders) (`clear_at: "next_user_message"`) | `mid-conversation-system-clear-at-2026-08-21` |
1079| Adding or removing entries in `tools` | [`tool_addition` and `tool_removal` blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#tool-changes) | `inline-tools-2026-09-15` (add `mcp-client-2026-09-15` when the tool comes from an MCP server connected through the MCP connector), or the older `mid-conversation-tool-changes-2026-07-01`, which works on the Claude API, Amazon Bedrock, Claude Platform on AWS, and Claude Models on Google Cloud (Google managed) |
1080| Changing top-level `output_config.effort` (restarts the cache, doesn’t affect thinking) | A [per-message `output_config`](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#effort-changes) | `mid-conversation-output-config-2026-07-01` |
1081| Dropping or summarizing old turns on the client | [On-demand compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand) to keep the recent turns with their thinking, other server-side [compaction or context editing](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#server-side-trimming), or [client-side compaction](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#custom-compaction-on-the-client) that keeps no stale thinking | `compact-2026-09-04` |
1082| An image or document URL whose bytes change between requests | A [`file_id` from the Files API](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#files-by-id), or base64 | None |
1073| Instead of | Use | Beta header |
1074| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1075| Rebuilding the top-level `system` prompt | A [mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#new-instructions) | None |
1076| Re-rendering the context in your first user message (environment, date, memory, project instructions) on each request | Render it once and resend it unchanged. When something changes, [put the new version in the newest turn](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#changing-context) | None |
1077| Clearing or shortening old `tool_result` content, or re-encoding old images, in place | Shorten a tool result or downscale an image before the first time you send it, not after. To clear old results later, [trim context on the server](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#server-side-trimming) with `clear_tool_uses_20250919` | `context-management-2025-06-27` |
1078| Injecting a reminder and deleting it on the next request | A [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#per-turn-reminders) (`clear_at: "next_user_message"`) | `mid-conversation-system-clear-at-2026-08-21` |
1079| Adding or removing entries in `tools` | [`tool_addition` and `tool_removal` blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#tool-changes) | `inline-tools-2026-09-15` (add `mcp-client-2026-09-15` when the tool comes from an MCP server connected through the MCP connector), or `mid-conversation-tool-changes-2026-07-01`, which works on the Claude API, Amazon Bedrock, Claude Platform on AWS, and Claude Models on Google Cloud (Google managed) |
1080| Changing top-level `output_config.effort` (restarts the cache, doesn’t affect thinking) | A [per-message `output_config`](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#effort-changes) | `mid-conversation-output-config-2026-07-01` |
1081| Dropping or summarizing old turns on the client | [On-demand compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand) to keep the recent turns with their thinking, other server-side [compaction or context editing](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#server-side-trimming), or [client-side compaction](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#custom-compaction-on-the-client) that keeps no stale thinking | `compact-2026-09-04` |
1082| An image or document URL whose bytes change between requests | A [`file_id` from the Files API](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#files-by-id), or base64 | None |
10831083
10841084All of these assume you [send assistant turns back exactly as returned](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#append-assistant-turns-exactly-as-returned). Mid-conversation system messages, turn-scoped system messages, and tool changes aren’t available on every model: [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) lists the models that accept them. If your code serves several models, keep editing the top-level `system` prompt for the models that don’t accept them.
10851085
from line 1185
11851185
11861186### Add or remove tools with `tool_addition` and `tool_removal`
11871187
1188Editing the `tools` array mid-session invalidates preserved thinking blocks. Leave the array as you first sent it, and change which tools the model can use by appending a `role: "system"` message that carries `tool_addition` or `tool_removal` blocks. These are [mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) and need the beta header `inline-tools-2026-09-15`, which is available on the Claude API and Claude Platform on AWS. The older `mid-conversation-tool-changes-2026-07-01` header still works for changes that name a tool by reference, on the Claude API, Amazon Bedrock, Claude Platform on AWS, and Claude Models on Google Cloud (Google managed).
1188Editing the `tools` array mid-session invalidates preserved thinking blocks. Leave the array as you first sent it, and change which tools the model can use by appending a `role: "system"` message that carries `tool_addition` or `tool_removal` blocks. These are [mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) and need the beta header `inline-tools-2026-09-15`, which is available on the Claude API and Claude Platform on AWS. The `mid-conversation-tool-changes-2026-07-01` header works for changes that name a tool by reference, on the Claude API, Amazon Bedrock, Claude Platform on AWS, and Claude Models on Google Cloud (Google managed).
11891189
11901190You have two ways to use these blocks:
11911191
from line 1247
12471247
12481248If the API connects to the MCP server for you through the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector), also send `mcp-client-2026-09-15`. It covers everything `mcp-client-2025-11-20` does, so send it instead of that one. The block’s `definition` can then be an `mcp_toolset` for a server listed in `mcp_servers`. When the API has to fetch a server’s tool list, the response starts with an `mcp_tool_listing` block for that server. Send it back unchanged with the rest of the assistant turn, and keep sending `mcp-client-2026-09-15` on every later request that carries it. The block pins the toolset to that list, so the API doesn’t contact the server again for it. These MCP connector features are available on the Claude API.
12491249
1250With only the older header, you can still append a tool you learn about mid-session to `tools` with `defer_loading: true`, then offer it with a `tool_addition` block. That’s safe because the prefix check ignores a deferred tool until a `tool_addition` block references it. Adding a tool without `defer_loading: true` changes the prefix and invalidates earlier thinking.
1250With only the `mid-conversation-tool-changes-2026-07-01` header, you can append a tool you learn about mid-session to `tools` with `defer_loading: true`, then offer it with a `tool_addition` block. That’s safe because the prefix check ignores a deferred tool until a `tool_addition` block references it. Adding a tool without `defer_loading: true` changes the prefix and invalidates earlier thinking.
12511251
12521252The `role: "system"` messages that carry these blocks join the prefix for later thinking. Leave them in place on later requests.
12531253
from line 1313
13131313 curl https://api.anthropic.com/v1/messages \
13141314 -H "content-type: application/json" \
13151315 -H "x-api-key: $ANTHROPIC_API_KEY" \
1316 -H "anthropic-version: 2023-06-01" \
1316 -H "anthropic-version: 2026-10-21" \
13171317 -H "anthropic-beta: thinking-binding-controls-2026-08-01" \
13181318 -d '{
13191319 "model": "claude-fable-5-1",
build-with-claude/prompt-caching Changed · +14 / -14 lines
from line 53
5353 curl https://api.anthropic.com/v1/messages \
5454 -H "content-type: application/json" \
5555 -H "x-api-key: $ANTHROPIC_API_KEY" \
56 -H "anthropic-version: 2023-06-01" \
56 -H "anthropic-version: 2026-10-21" \
5757 -d '{
5858 "model": "claude-opus-5-5",
5959 "max_tokens": 1024,
from line 271
271271| Claude Opus 4.7 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
272272| Claude Opus 4.6 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
273273| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
274| Claude Opus 4.1 ([retired, except on Bedrock and Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
274| Claude Opus 4.1 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
275275| Claude Opus 4 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
276276| Claude Sonnet 5.5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.10 / MTok<sup>2</sup> | $10 / MTok |
277277| Claude Sonnet 5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.20 / MTok | $10 / MTok |
278278| Claude Sonnet 4.6 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
279279| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
280| Claude Sonnet 4 ([retired, except on Bedrock and Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
280| Claude Sonnet 4 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
281281| Claude Haiku 5.5 (for prompts up to 100,000 tokens) | $0.10 / MTok | $0.125 / MTok | $0.20 / MTok | $0.01 / MTok | $0.50 / MTok |
282282| Claude Haiku 5.5 (for prompts over 100,000 tokens) | $0.50 / MTok | $0.625 / MTok | $1 / MTok | $0.05 / MTok | $2.50 / MTok |
283283| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
from line 316
316316 curl https://api.anthropic.com/v1/messages \
317317 -H "content-type: application/json" \
318318 -H "x-api-key: $ANTHROPIC_API_KEY" \
319 -H "anthropic-version: 2023-06-01" \
319 -H "anthropic-version: 2026-10-21" \
320320 -d '{
321321 "model": "claude-opus-5-5",
322322 "max_tokens": 1024,
from line 628
628628* 512 tokens for Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), and Claude Haiku 5.5
629629* 2,048 tokens for [Claude Mythos Preview](https://anthropic.com/glasswing) and Claude Opus 4.7
630630* 4,096 tokens for Claude Opus 4.6 and Claude Opus 4.5
631* 1,024 tokens for Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 ([deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations)), Claude Opus 4.1 ([retired, except on Bedrock and Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations)), Claude Opus 4 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations)), and Claude Sonnet 4 ([retired, except on Bedrock and Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations))
631* 1,024 tokens for Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 ([deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations)), Claude Opus 4.1 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations)), Claude Opus 4 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations)), and Claude Sonnet 4 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations))
632632* 4,096 tokens for Claude Haiku 4.5
633633* 2,048 tokens for Claude Haiku 3.5 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations))
634634
from line 779
779779### Cache storage and sharing
780780
781781<Warning>
782 Prompt caching uses [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces)-level isolation. Caches are isolated by workspace, ensuring data separation between workspaces within the same organization. This applies to the Claude API, Claude Platform on AWS, and Microsoft Foundry; Bedrock and Claude Models on Google Cloud (Google managed) maintain organization-level cache isolation. If you use multiple workspaces, review your caching strategy to account for this difference.
782 Prompt caching uses [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces)-level isolation. Caches are isolated by workspace, ensuring data separation between workspaces within the same organization. This applies to the Claude API, Claude Platform on AWS, and Microsoft Foundry; Claude Models on Google Cloud (Google managed) and Bedrock maintain organization-level cache isolation. If you use multiple workspaces, review your caching strategy to account for this difference.
783783</Warning>
784784
785* **Organization and workspace isolation:** Caches are isolated between organizations. Different organizations never share caches, even if they use identical prompts. Caches are also isolated by workspace within an organization on the Claude API, Claude Platform on AWS, and Microsoft Foundry; Bedrock and Claude Models on Google Cloud (Google managed) use organization-level isolation only.
785* **Organization and workspace isolation:** Caches are isolated between organizations. Different organizations never share caches, even if they use identical prompts. Caches are also isolated by workspace within an organization on the Claude API, Claude Platform on AWS, and Microsoft Foundry; Claude Models on Google Cloud (Google managed) and Bedrock use organization-level isolation only.
786786
787787* **Exact matching:** Cache hits require 100 percent identical prompt segments, including all text and images up to and including the block marked with cache control.
788788
from line 933
933933 curl https://api.anthropic.com/v1/messages \
934934 -H "content-type: application/json" \
935935 -H "x-api-key: $ANTHROPIC_API_KEY" \
936 -H "anthropic-version: 2023-06-01" \
936 -H "anthropic-version: 2026-10-21" \
937937 -d '{
938938 "model": "claude-opus-5-5",
939939 "max_tokens": 0,
from line 1168
11681168 curl https://api.anthropic.com/v1/messages \
11691169 -H "content-type: application/json" \
11701170 -H "x-api-key: $ANTHROPIC_API_KEY" \
1171 -H "anthropic-version: 2023-06-01" \
1171 -H "anthropic-version: 2026-10-21" \
11721172 -d '{
11731173 "model": "claude-opus-5-5",
11741174 "max_tokens": 0,
from line 1186
11861186 curl https://api.anthropic.com/v1/messages \
11871187 -H "content-type: application/json" \
11881188 -H "x-api-key: $ANTHROPIC_API_KEY" \
1189 -H "anthropic-version: 2023-06-01" \
1189 -H "anthropic-version: 2026-10-21" \
11901190 -d '{
11911191 "model": "claude-opus-5-5",
11921192 "max_tokens": 1024,
from line 1573
15731573 ```bash cURL
15741574 curl https://api.anthropic.com/v1/messages \
15751575 -H "x-api-key: $ANTHROPIC_API_KEY" \
1576 -H "anthropic-version: 2023-06-01" \
1576 -H "anthropic-version: 2026-10-21" \
15771577 -H "content-type: application/json" \
15781578 -d '{
15791579 "model": "claude-opus-5-5",
from line 1877
18771877 ```bash cURL
18781878 curl https://api.anthropic.com/v1/messages \
18791879 -H "x-api-key: $ANTHROPIC_API_KEY" \
1880 -H "anthropic-version: 2023-06-01" \
1880 -H "anthropic-version: 2026-10-21" \
18811881 -H "content-type: application/json" \
18821882 -d '{
18831883 "model": "claude-opus-5-5",
from line 2279
22792279 ```bash cURL
22802280 curl https://api.anthropic.com/v1/messages \
22812281 -H "x-api-key: $ANTHROPIC_API_KEY" \
2282 -H "anthropic-version: 2023-06-01" \
2282 -H "anthropic-version: 2026-10-21" \
22832283 -H "content-type: application/json" \
22842284 -d '{
22852285 "model": "claude-opus-5-5",
from line 3302
33023302
33033303 1. Cache keys are generated using a cryptographic hash of the prompts up to the cache control point. This means only requests with identical prompts can access a specific cache.
33043304
3305 2. On the Claude API, Claude Platform on AWS, and Microsoft Foundry, caches are isolated by workspace within an organization. On Bedrock and Claude Models on Google Cloud (Google managed), caches are isolated by organization. In every case, caches are never shared across organizations, even for identical prompts. See [Cache storage and sharing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing) for details.
3305 2. On the Claude API, Claude Platform on AWS, and Microsoft Foundry, caches are isolated by workspace within an organization. On Claude Models on Google Cloud (Google managed) and Bedrock, caches are isolated by organization. In every case, caches are never shared across organizations, even for identical prompts. See [Cache storage and sharing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing) for details.
33063306
33073307 3. The caching mechanism is designed to maintain the integrity and privacy of each unique conversation or context.
33083308
build-with-claude/prompt-engineering/claude-prompting-best-practices Changed · +3 / -3 lines
from line 110
110110 curl https://api.anthropic.com/v1/messages \
111111 -H "content-type: application/json" \
112112 -H "x-api-key: $ANTHROPIC_API_KEY" \
113 -H "anthropic-version: 2023-06-01" \
113 -H "anthropic-version: 2026-10-21" \
114114 -d '{
115115 "model": "claude-opus-5-5",
116116 "max_tokens": 1024,
from line 570
570570 curl https://api.anthropic.com/v1/messages \
571571 -H "content-type: application/json" \
572572 -H "x-api-key: $ANTHROPIC_API_KEY" \
573 -H "anthropic-version: 2023-06-01" \
573 -H "anthropic-version: 2026-10-21" \
574574 -d '{
575575 "model": "claude-sonnet-4-5-20250929",
576576 "max_tokens": 16000,
from line 584
584584 curl https://api.anthropic.com/v1/messages \
585585 -H "content-type: application/json" \
586586 -H "x-api-key: $ANTHROPIC_API_KEY" \
587 -H "anthropic-version: 2023-06-01" \
587 -H "anthropic-version: 2026-10-21" \
588588 -d '{
589589 "model": "claude-opus-5-5",
590590 "max_tokens": 16000,
build-with-claude/refusals-and-fallback Changed · +3 / -3 lines
from line 37
3737 ```bash cURL
3838 curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
3939 -H "x-api-key: $ANTHROPIC_API_KEY" \
40 -H "anthropic-version: 2023-06-01" \
40 -H "anthropic-version: 2026-10-21" \
4141 -H "anthropic-beta: server-side-fallback-2026-07-01" \
4242 -H "content-type: application/json" \
4343 -d '{
from line 261
261261 ```bash cURL
262262 curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
263263 -H "x-api-key: $ANTHROPIC_API_KEY" \
264 -H "anthropic-version: 2023-06-01" \
264 -H "anthropic-version: 2026-10-21" \
265265 -H "anthropic-beta: server-side-fallback-2026-07-01" \
266266 -H "content-type: application/json" \
267267 -d '{
from line 508
508508 ```bash cURL
509509 curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
510510 -H "x-api-key: $ANTHROPIC_API_KEY" \
511 -H "anthropic-version: 2023-06-01" \
511 -H "anthropic-version: 2026-10-21" \
512512 -H "anthropic-beta: server-side-fallback-2026-07-01" \
513513 -H "content-type: application/json" \
514514 -d '{
build-with-claude/search-results Changed · +34 / -12 lines
from line 175
175175 model="claude-opus-5",
176176 max_tokens=1024,
177177 tools=[knowledge_base_tool],
178 tool_choice={"type": "tool", "name": "search_knowledge_base"},
178 tool_choice={
179 "type": "tool",
180 "name": "search_knowledge_base",
181 "disable_parallel_tool_use": True,
182 },
179183 messages=messages,
180184 )
181185
from line 274
270274 model: "claude-opus-5",
271275 max_tokens: 1024,
272276 tools: [knowledgeBaseTool],
273 tool_choice: { type: "tool", name: "search_knowledge_base" },
277 tool_choice: {
278 type: "tool",
279 name: "search_knowledge_base",
280 disable_parallel_tool_use: true
281 },
274282 messages
275283 });
276284
from line 365
357365 Model = Model.ClaudeOpus5,
358366 MaxTokens = 1024,
359367 Tools = tools,
360 ToolChoice = new ToolChoiceTool { Name = "search_knowledge_base" },
368 ToolChoice = new ToolChoiceTool
369 {
370 Name = "search_knowledge_base",
371 DisableParallelToolUse = true,
372 },
361373 Messages = messages,
362374 });
363375
from line 429
417429 }
418430
419431 response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
420 Model: anthropic.ModelClaudeOpus5,
421 MaxTokens: 1024,
422 Tools: []anthropic.ToolUnionParam{knowledgeBaseTool},
423 ToolChoice: anthropic.ToolChoiceUnionParam{OfTool: &anthropic.ToolChoiceToolParam{Name: "search_knowledge_base"}},
424 Messages: messages,
432 Model: anthropic.ModelClaudeOpus5,
433 MaxTokens: 1024,
434 Tools: []anthropic.ToolUnionParam{knowledgeBaseTool},
435 ToolChoice: anthropic.ToolChoiceUnionParam{
436 OfTool: &anthropic.ToolChoiceToolParam{
437 Name: "search_knowledge_base",
438 DisableParallelToolUse: anthropic.Bool(true),
439 },
440 },
441 Messages: messages,
425442 })
426443 if err != nil {
427444 log.Fatal(err)
from line 547
530547 .addTool(knowledgeBaseTool)
531548 .toolChoice(ToolChoice.ofTool(ToolChoiceTool.builder()
532549 .name("search_knowledge_base")
550 .disableParallelToolUse(true)
533551 .build()))
534552 .messages(messages)
535553 .build();
from line 681
663681 maxTokens: 1024,
664682 messages: $messages,
665683 model: 'claude-opus-5',
666 toolChoice: ['type' => 'tool', 'name' => 'search_knowledge_base'],
684 toolChoice: [
685 'type' => 'tool',
686 'name' => 'search_knowledge_base',
687 'disableParallelToolUse' => true,
688 ],
667689 tools: [$knowledgeBaseTool],
668690 );
669691
from line 778
756778 model: "claude-opus-5",
757779 max_tokens: 1024,
758780 tools: [knowledge_base_tool],
759 tool_choice: { type: "tool", name: "search_knowledge_base" },
781 tool_choice: { type: "tool", name: "search_knowledge_base", disable_parallel_tool_use: true },
760782 messages: messages
761783 )
762784
from line 827
805827 ```bash cURL
806828 curl https://api.anthropic.com/v1/messages \
807829 -H "x-api-key: $ANTHROPIC_API_KEY" \
808 -H "anthropic-version: 2023-06-01" \
830 -H "anthropic-version: 2026-10-21" \
809831 -H "content-type: application/json" \
810832 -d '{
811833 "model": "claude-opus-5-5",
from line 1343
13211343 ```bash cURL
13221344 curl https://api.anthropic.com/v1/messages \
13231345 -H "x-api-key: $ANTHROPIC_API_KEY" \
1324 -H "anthropic-version: 2023-06-01" \
1346 -H "anthropic-version: 2026-10-21" \
13251347 -H "content-type: application/json" \
13261348 -d '{
13271349 "model": "claude-opus-5-5",
build-with-claude/skills-guide Changed · +22 / -22 lines
from line 76
7676 ```bash cURL
7777 curl https://api.anthropic.com/v1/messages \
7878 -H "x-api-key: $ANTHROPIC_API_KEY" \
79 -H "anthropic-version: 2023-06-01" \
79 -H "anthropic-version: 2026-10-21" \
8080 -H "content-type: application/json" \
8181 -d '{
8282 "model": "claude-opus-5-5",
from line 698
698698 # Get file metadata
699699 curl "https://api.anthropic.com/v1/files/$FILE_ID" \
700700 -H "x-api-key: $ANTHROPIC_API_KEY" \
701 -H "anthropic-version: 2023-06-01"
701 -H "anthropic-version: 2026-10-21"
702702
703703 # List all files
704704 curl "https://api.anthropic.com/v1/files" \
705705 -H "x-api-key: $ANTHROPIC_API_KEY" \
706 -H "anthropic-version: 2023-06-01"
706 -H "anthropic-version: 2026-10-21"
707707
708708 # Delete a file
709709 curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
710710 -H "x-api-key: $ANTHROPIC_API_KEY" \
711 -H "anthropic-version: 2023-06-01"
711 -H "anthropic-version: 2026-10-21"
712712 ```
713713
714714 ```bash CLI
from line 1620
16201620</CodeGroup>
16211621
16221622<Note>
1623 The response might include a `pause_turn` stop reason, which indicates that the API paused a long-running Skill operation. You can provide the response back as-is in a subsequent request to let Claude continue its turn, or modify the content if you want to interrupt the conversation and provide additional guidance.
1623 The response might include a `pause_turn` stop reason, which indicates that the API paused a long-running Skill operation. You can provide the response back as-is in a subsequent request to let Claude continue its turn, or modify the content if you want to interrupt the conversation and provide additional guidance. Send the response’s container ID back with that request, in the same `container` object as your Skills, as the example does. Without it, the request runs in a new container, and files from earlier in the turn are lost.
16241624</Note>
16251625
16261626### Using multiple Skills
from line 1631
16311631 ```bash cURL
16321632 curl https://api.anthropic.com/v1/messages \
16331633 -H "x-api-key: $ANTHROPIC_API_KEY" \
1634 -H "anthropic-version: 2023-06-01" \
1634 -H "anthropic-version: 2026-10-21" \
16351635 -H "content-type: application/json" \
16361636 -d '{
16371637 "model": "claude-opus-5-5",
from line 1956
19561956
19571957### Creating a Skill
19581958
1959A Skill bundle is a directory containing a `SKILL.md` file at the top level with `name` and `description` YAML frontmatter, plus any supporting scripts or resources. See [Get started with Agent Skills in the API](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart) to author one, and the **Requirements** list following the examples for the full constraints.
1959A Skill bundle is a directory containing a `SKILL.md` file at the top level with `name` and `description` YAML frontmatter, plus any supporting scripts or resources. See [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) to author one, and the **Requirements** list following the examples for the full constraints.
19601960
19611961Upload your custom Skill to make it available in your workspace. You can upload a zip archive or individual file objects. The Python SDK also provides a `files_from_dir` helper that accepts a directory path, and the CLI’s `ant apply` uploads the directory itself.
19621962
from line 1966
19661966 ```bash cURL
19671967 curl -X POST "https://api.anthropic.com/v1/skills" \
19681968 -H "x-api-key: $ANTHROPIC_API_KEY" \
1969 -H "anthropic-version: 2023-06-01" \
1969 -H "anthropic-version: 2026-10-21" \
19701970 -F "files[]=@financial_skill/SKILL.md;filename=financial_skill/SKILL.md" \
19711971 -F "files[]=@financial_skill/analyze.py;filename=financial_skill/analyze.py"
19721972 ```
from line 2271
22712271 # List all Skills
22722272 curl "https://api.anthropic.com/v1/skills" \
22732273 -H "x-api-key: $ANTHROPIC_API_KEY" \
2274 -H "anthropic-version: 2023-06-01"
2274 -H "anthropic-version: 2026-10-21"
22752275
22762276 # List only custom Skills
22772277 curl "https://api.anthropic.com/v1/skills?source=custom" \
22782278 -H "x-api-key: $ANTHROPIC_API_KEY" \
2279 -H "anthropic-version: 2023-06-01"
2279 -H "anthropic-version: 2026-10-21"
22802280 ```
22812281
22822282 ```bash CLI
from line 2416
24162416 ```bash cURL
24172417 curl "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
24182418 -H "x-api-key: $ANTHROPIC_API_KEY" \
2419 -H "anthropic-version: 2023-06-01"
2419 -H "anthropic-version: 2026-10-21"
24202420 ```
24212421
24222422 ```bash CLI
from line 2513
25132513 ```bash cURL
25142514 curl -X DELETE "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
25152515 -H "x-api-key: $ANTHROPIC_API_KEY" \
2516 -H "anthropic-version: 2023-06-01"
2516 -H "anthropic-version: 2026-10-21"
25172517 ```
25182518
25192519 ```bash CLI
from line 2595
25952595 # Create a new version
25962596 curl -X POST "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv/versions" \
25972597 -H "x-api-key: $ANTHROPIC_API_KEY" \
2598 -H "anthropic-version: 2023-06-01" \
2598 -H "anthropic-version: 2026-10-21" \
25992599 -F "files[]=@financial_skill/SKILL.md;filename=financial_skill/SKILL.md" \
26002600 -F "files[]=@financial_skill/analyze.py;filename=financial_skill/analyze.py"
26012601
from line 2602
26022602 # Use a specific version: the ID from the create response
26032603 curl https://api.anthropic.com/v1/messages \
26042604 -H "x-api-key: $ANTHROPIC_API_KEY" \
2605 -H "anthropic-version: 2023-06-01" \
2605 -H "anthropic-version: 2026-10-21" \
26062606 -H "content-type: application/json" \
26072607 -d '{
26082608 "model": "claude-opus-5-5",
from line 2621
26212621 # Use latest version
26222622 curl https://api.anthropic.com/v1/messages \
26232623 -H "x-api-key: $ANTHROPIC_API_KEY" \
2624 -H "anthropic-version: 2023-06-01" \
2624 -H "anthropic-version: 2026-10-21" \
26252625 -H "content-type: application/json" \
26262626 -d '{
26272627 "model": "claude-opus-5-5",
from line 3134
31343134 ```bash cURL
31353135 curl -X POST "https://api.anthropic.com/v1/skills" \
31363136 -H "x-api-key: $ANTHROPIC_API_KEY" \
3137 -H "anthropic-version: 2023-06-01" \
3137 -H "anthropic-version: 2026-10-21" \
31383138 -F "files[]=@dcf_skill/SKILL.md;filename=dcf_skill/SKILL.md"
31393139 ```
31403140
from line 3264
32643264 ```bash cURL
32653265 curl https://api.anthropic.com/v1/messages \
32663266 -H "x-api-key: $ANTHROPIC_API_KEY" \
3267 -H "anthropic-version: 2023-06-01" \
3267 -H "anthropic-version: 2026-10-21" \
32683268 -H "content-type: application/json" \
32693269 -d '{
32703270 "model": "claude-opus-5-5",
from line 3588
35883588 # Pin to specific versions for stability
35893589 curl https://api.anthropic.com/v1/messages \
35903590 -H "x-api-key: $ANTHROPIC_API_KEY" \
3591 -H "anthropic-version: 2023-06-01" \
3591 -H "anthropic-version: 2026-10-21" \
35923592 -H "content-type: application/json" \
35933593 -d '{
35943594 "model": "claude-opus-5-5",
from line 3729
37293729 # Use latest for active development
37303730 curl https://api.anthropic.com/v1/messages \
37313731 -H "x-api-key: $ANTHROPIC_API_KEY" \
3732 -H "anthropic-version: 2023-06-01" \
3732 -H "anthropic-version: 2026-10-21" \
37333733 -H "content-type: application/json" \
37343734 -d '{
37353735 "model": "claude-opus-5-5",
from line 3872
38723872 # Skills render into the system prompt in a fixed, cache-friendly order
38733873 curl https://api.anthropic.com/v1/messages \
38743874 -H "x-api-key: $ANTHROPIC_API_KEY" \
3875 -H "anthropic-version: 2023-06-01" \
3875 -H "anthropic-version: 2026-10-21" \
38763876 -H "content-type: application/json" \
38773877 -d '{
38783878 "model": "claude-opus-5-5",
from line 3889
38893889 # Changing the Skills list ([xlsx] versus [xlsx, pptx]) changes the prefix: a cache miss, whereas an identical list is a cache hit
38903890 curl https://api.anthropic.com/v1/messages \
38913891 -H "x-api-key: $ANTHROPIC_API_KEY" \
3892 -H "anthropic-version: 2023-06-01" \
3892 -H "anthropic-version: 2026-10-21" \
38933893 -H "content-type: application/json" \
38943894 -d '{
38953895 "model": "claude-opus-5-5",
from line 4501
45014501
45024502## Migrate from `skills-2025-10-02`
45034503
4504The Skills API is out of beta and needs no beta header. Migrating off `skills-2025-10-02` is optional: requests that still send it keep working and keep returning the beta response shapes, so an existing integration keeps working until you change it. Removing the header switches those requests to the shapes documented on this page:
4504The Skills API is out of beta and needs no beta header. Migrating off `skills-2025-10-02` is optional: requests that send it keep working and keep returning the beta response shapes, so an existing integration keeps working until you change it. Removing the header switches those requests to the shapes documented on this page:
45054505
45064506| | With `skills-2025-10-02` | Without the header |
45074507| ------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
build-with-claude/streaming Changed · +4 / -4 lines
from line 424
424424<CodeGroup>
425425 ```bash cURL
426426 curl https://api.anthropic.com/v1/messages \
427 -H "anthropic-version: 2023-06-01" \
427 -H "anthropic-version: 2026-10-21" \
428428 -H "content-type: application/json" \
429429 -H "x-api-key: $ANTHROPIC_API_KEY" \
430430 -d '{
from line 601
601601 curl https://api.anthropic.com/v1/messages \
602602 -H "content-type: application/json" \
603603 -H "x-api-key: $ANTHROPIC_API_KEY" \
604 -H "anthropic-version: 2023-06-01" \
604 -H "anthropic-version: 2026-10-21" \
605605 -d '{
606606 "model": "claude-opus-5",
607607 "max_tokens": 1024,
from line 994
994994 ```bash cURL
995995 curl https://api.anthropic.com/v1/messages \
996996 -H "x-api-key: $ANTHROPIC_API_KEY" \
997 -H "anthropic-version: 2023-06-01" \
997 -H "anthropic-version: 2026-10-21" \
998998 -H "content-type: application/json" \
999999 -d '{
10001000 "model": "claude-opus-5-5",
from line 1245
12451245 ```bash cURL
12461246 curl https://api.anthropic.com/v1/messages \
12471247 -H "x-api-key: $ANTHROPIC_API_KEY" \
1248 -H "anthropic-version: 2023-06-01" \
1248 -H "anthropic-version: 2026-10-21" \
12491249 -H "content-type: application/json" \
12501250 -d '{
12511251 "model": "claude-opus-5-5",
build-with-claude/structured-outputs Changed · +6 / -6 lines
from line 81
8181 curl https://api.anthropic.com/v1/messages \
8282 -H "content-type: application/json" \
8383 -H "x-api-key: $ANTHROPIC_API_KEY" \
84 -H "anthropic-version: 2023-06-01" \
84 -H "anthropic-version: 2026-10-21" \
8585 -d '{
8686 "model": "claude-opus-5-5",
8787 "max_tokens": 1024,
from line 762
762762 curl https://api.anthropic.com/v1/messages \
763763 -H "content-type: application/json" \
764764 -H "x-api-key: $ANTHROPIC_API_KEY" \
765 -H "anthropic-version: 2023-06-01" \
765 -H "anthropic-version: 2026-10-21" \
766766 -d '{
767767 "model": "claude-opus-5-5",
768768 "max_tokens": 1024,
from line 1213
12131213 curl https://api.anthropic.com/v1/messages \
12141214 -H "content-type: application/json" \
12151215 -H "x-api-key: $ANTHROPIC_API_KEY" \
1216 -H "anthropic-version: 2023-06-01" \
1216 -H "anthropic-version: 2026-10-21" \
12171217 -d '{
12181218 "model": "claude-opus-5-5",
12191219 "max_tokens": 4096,
from line 1545
15451545 curl https://api.anthropic.com/v1/messages \
15461546 -H "content-type: application/json" \
15471547 -H "x-api-key: $ANTHROPIC_API_KEY" \
1548 -H "anthropic-version: 2023-06-01" \
1548 -H "anthropic-version: 2026-10-21" \
15491549 -d '{
15501550 "model": "claude-opus-5-5",
15511551 "max_tokens": 1024,
from line 1830
18301830 curl https://api.anthropic.com/v1/messages \
18311831 -H "content-type: application/json" \
18321832 -H "x-api-key: $ANTHROPIC_API_KEY" \
1833 -H "anthropic-version: 2023-06-01" \
1833 -H "anthropic-version: 2026-10-21" \
18341834 -d '{
18351835 "model": "claude-opus-5-5",
18361836 "max_tokens": 1024,
from line 2180
21802180 curl https://api.anthropic.com/v1/messages \
21812181 -H "content-type: application/json" \
21822182 -H "x-api-key: $ANTHROPIC_API_KEY" \
2183 -H "anthropic-version: 2023-06-01" \
2183 -H "anthropic-version: 2026-10-21" \
21842184 -d '{
21852185 "model": "claude-opus-5-5",
21862186 "max_tokens": 1024,
build-with-claude/thinking Changed · +4 / -4 lines
from line 110
110110 ```bash cURL
111111 curl https://api.anthropic.com/v1/messages \
112112 -H "x-api-key: $ANTHROPIC_API_KEY" \
113 -H "anthropic-version: 2023-06-01" \
113 -H "anthropic-version: 2026-10-21" \
114114 -H "content-type: application/json" \
115115 -d '{
116116 "model": "claude-opus-5-5",
from line 361
361361 ```bash cURL
362362 curl https://api.anthropic.com/v1/messages \
363363 -H "x-api-key: $ANTHROPIC_API_KEY" \
364 -H "anthropic-version: 2023-06-01" \
364 -H "anthropic-version: 2026-10-21" \
365365 -H "content-type: application/json" \
366366 -d '{
367367 "model": "claude-sonnet-5",
from line 574
574574 ```bash cURL
575575 curl https://api.anthropic.com/v1/messages \
576576 -H "x-api-key: $ANTHROPIC_API_KEY" \
577 -H "anthropic-version: 2023-06-01" \
577 -H "anthropic-version: 2026-10-21" \
578578 -H "content-type: application/json" \
579579 -d '{
580580 "model": "claude-opus-5-5",
from line 1251
12511251| Claude Haiku 5.5 | 128K | 300K |
12521252| Claude Haiku 4.5 | 64K | Not available |
12531253
1254See the [models overview](https://platform.claude.com/docs/en/models/overview) for limits on legacy models.
1254To read a model’s limits programmatically, see [Using the Models API](https://platform.claude.com/docs/en/models/overview#using-the-models-api).
12551255
12561256### Long requests
12571257
build-with-claude/token-counting Changed · +10 / -9 lines
from line 24
2424 - claude-opus-4-6
2525 - claude-sonnet-4-6
2626 - claude-opus-4-5-20251101
27 - claude-sonnet-4-5-20250929
2728 supportedPlatforms:
2829 Claude API: stable
2930 Claude Platform on AWS: stable
from line 78
7778 curl https://api.anthropic.com/v1/messages/count_tokens \
7879 -H "x-api-key: $ANTHROPIC_API_KEY" \
7980 -H "content-type: application/json" \
80 -H "anthropic-version: 2023-06-01" \
81 -H "anthropic-version: 2026-10-21" \
8182 -d '{
8283 "model": "claude-opus-5-5",
8384 "system": "You are a scientist",
from line 229
228229 curl https://api.anthropic.com/v1/messages/count_tokens \
229230 -H "x-api-key: $ANTHROPIC_API_KEY" \
230231 -H "content-type: application/json" \
231 -H "anthropic-version: 2023-06-01" \
232 -H "anthropic-version: 2026-10-21" \
232233 -d '{
233234 "model": "claude-opus-5-5",
234235 "tools": [
from line 511
510511
511512 curl https://api.anthropic.com/v1/messages/count_tokens \
512513 -H "x-api-key: $ANTHROPIC_API_KEY" \
513 -H "anthropic-version: 2023-06-01" \
514 -H "anthropic-version: 2026-10-21" \
514515 -H "content-type: application/json" \
515516 -d @- <<EOF
516517 {
from line 826
825826 curl https://api.anthropic.com/v1/messages/count_tokens \
826827 -H "x-api-key: $ANTHROPIC_API_KEY" \
827828 -H "content-type: application/json" \
828 -H "anthropic-version: 2023-06-01" \
829 -H "anthropic-version: 2026-10-21" \
829830 -d '{
830831 "model": "claude-opus-5-5",
831832 "thinking": {
from line 1146
11451146 curl https://api.anthropic.com/v1/messages/count_tokens \
11461147 -H "x-api-key: $ANTHROPIC_API_KEY" \
11471148 -H "content-type: application/json" \
1148 -H "anthropic-version: 2023-06-01" \
1149 -H "anthropic-version: 2026-10-21" \
11491150 -d @- <<EOF
11501151 {
11511152 "model": "claude-opus-5-5",
from line 1481
14801481
14811482## Availability
14821483
1483Token counting is available on select models and eligible for zero data retention and HIPAA readiness.
1484Token counting is available on every model and eligible for zero data retention and HIPAA readiness.
14841485
14851486### API support
14861487
from line 1489
14881489
14891490* Availability: Available
14901491
1491| Status | Models |
1492| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1493| Available | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Haiku 4.5](https://platform.claude.com/docs/en/models/haiku-4-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/en/models/sonnet-4-6/overview), [Claude Opus 4.5](https://platform.claude.com/docs/en/models/opus-4-5/overview) |
1492| Status | Models |
1493| --------- | ----------------------------------------------------------------- |
1494| Available | [All models](https://platform.claude.com/docs/en/models/overview) |
14941495
14951496#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)
14961497
build-with-claude/vision Changed · +7 / -7 lines
from line 57
57573. A `file_id` returned by the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) (upload once, reference many times)
5858
5959<Note>
60 On Amazon Bedrock and Claude Models on Google Cloud (Google managed), only base64-encoded sources are currently available.
60 On Claude Models on Google Cloud (Google managed) and Amazon Bedrock, only base64-encoded sources are available.
6161</Note>
6262
6363<Tip>
from line 70
7070 ```bash cURL
7171 curl https://api.anthropic.com/v1/messages \
7272 -H "x-api-key: $ANTHROPIC_API_KEY" \
73 -H "anthropic-version: 2023-06-01" \
73 -H "anthropic-version: 2026-10-21" \
7474 -H "content-type: application/json" \
7575 -d @- <<EOF
7676 {
from line 332
332332 ```bash cURL
333333 curl https://api.anthropic.com/v1/messages \
334334 -H "x-api-key: $ANTHROPIC_API_KEY" \
335 -H "anthropic-version: 2023-06-01" \
335 -H "anthropic-version: 2026-10-21" \
336336 -H "content-type: application/json" \
337337 -d '{
338338 "model": "claude-opus-5-5",
from line 576
576576 # First, upload your image to the Files API
577577 curl -sS -X POST https://api.anthropic.com/v1/files \
578578 -H "x-api-key: $ANTHROPIC_API_KEY" \
579 -H "anthropic-version: 2023-06-01" \
579 -H "anthropic-version: 2026-10-21" \
581581
582582 # Then use the file_id from the upload response in your message
583583 curl https://api.anthropic.com/v1/messages \
584584 -H "x-api-key: $ANTHROPIC_API_KEY" \
585 -H "anthropic-version: 2023-06-01" \
585 -H "anthropic-version: 2026-10-21" \
586586 -H "content-type: application/json" \
587587 -d '{
588588 "model": "claude-opus-5-5",
from line 900
900900 ```bash cURL
901901 curl https://api.anthropic.com/v1/messages \
902902 -H "x-api-key: $ANTHROPIC_API_KEY" \
903 -H "anthropic-version: 2023-06-01" \
903 -H "anthropic-version: 2026-10-21" \
904904 -H "content-type: application/json" \
905905 -d '{
906906 "model": "claude-opus-5-5",
from line 1275
12751275
12761276The maximum dimensions for each image are 8000x8000 px.
12771277
1278If a single API request contains more than 20 images, a stricter per-image dimension limit applies to every image in that request. All `image` blocks in the request count toward this threshold, including images from earlier conversation turns that you resend and images nested inside `tool_result` content (for example, screenshots returned to the computer use tool). On Amazon Bedrock and Claude Models on Google Cloud (Google managed), document blocks such as PDFs also count toward this threshold. Images exceeding the stricter limit are rejected with an `invalid_request_error` whose message references “many-image requests” and states the current limit in pixels. To stay under the limit on all platforms, either resize each image so that neither dimension exceeds 3,000 px, or keep the request to 20 or fewer image and document blocks.
1278If a single API request contains more than 20 images, a stricter per-image dimension limit applies to every image in that request. All `image` blocks in the request count toward this threshold, including images from earlier conversation turns that you resend and images nested inside `tool_result` content (for example, screenshots returned to the computer use tool). On Claude Models on Google Cloud (Google managed) and Amazon Bedrock, document blocks such as PDFs also count toward this threshold. Images exceeding the stricter limit are rejected with an `invalid_request_error` whose message references “many-image requests” and states the current limit in pixels. To stay under the limit on all platforms, either resize each image so that neither dimension exceeds 3,000 px, or keep the request to 20 or fewer image and document blocks.
12791279
12801280The maximum size per image is:
12811281
build-with-claude/working-with-messages Changed · +5 / -5 lines
from line 55
5555 #!/bin/sh
5656 curl https://api.anthropic.com/v1/messages \
5757 -H "x-api-key: $ANTHROPIC_API_KEY" \
58 -H "anthropic-version: 2023-06-01" \
58 -H "anthropic-version: 2026-10-21" \
5959 -H "content-type: application/json" \
6060 -d '{
6161 "model": "claude-opus-5-5",
from line 194
194194 #!/bin/sh
195195 curl https://api.anthropic.com/v1/messages \
196196 -H "x-api-key: $ANTHROPIC_API_KEY" \
197 -H "anthropic-version: 2023-06-01" \
197 -H "anthropic-version: 2026-10-21" \
198198 -H "content-type: application/json" \
199199 -d '{
200200 "model": "claude-opus-5-5",
from line 371
371371 #!/bin/sh
372372 curl https://api.anthropic.com/v1/messages \
373373 -H "x-api-key: $ANTHROPIC_API_KEY" \
374 -H "anthropic-version: 2023-06-01" \
374 -H "anthropic-version: 2026-10-21" \
375375 -H "content-type: application/json" \
376376 -d '{
377377 "model": "claude-sonnet-4-5",
from line 541
541541
542542 curl https://api.anthropic.com/v1/messages \
543543 -H "x-api-key: $ANTHROPIC_API_KEY" \
544 -H "anthropic-version: 2023-06-01" \
544 -H "anthropic-version: 2026-10-21" \
545545 -H "content-type: application/json" \
546546 -d @- <<EOF
547547 {
from line 563
563563 # Option 2: URL-referenced image
564564 curl https://api.anthropic.com/v1/messages \
565565 -H "x-api-key: $ANTHROPIC_API_KEY" \
566 -H "anthropic-version: 2023-06-01" \
566 -H "anthropic-version: 2026-10-21" \
567567 -H "content-type: application/json" \
568568 -d '{
569569 "model": "claude-opus-5-5",
cli-sdks-libraries/sdks/typescript Changed · +14 / -7 lines
from line 178
178178To report an error from a tool back to the model, throw a `ToolError` from the `run` function. Unlike a plain `Error`, `ToolError` accepts content blocks, allowing you to include images or other structured content in the error response:
179179
180180```typescript
181import { ToolError } from "@anthropic-ai/sdk/lib/tools/BetaRunnableTool";
181import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
182import { ToolError } from "@anthropic-ai/sdk/resources/beta/messages";
183import { z } from "zod";
182184
183185const screenshotTool = betaZodTool({
184186 name: "take_screenshot",
185187 inputSchema: z.object({ url: z.string() }),
188 description: "Take a screenshot of a webpage",
186189 run: async (input) => {
187190 if (!isValidUrl(input.url)) {
188191 throw new ToolError(`Invalid URL: ${input.url}`);
from line 201
198201 }
199202 ]);
200203 }
201 return {
202 type: "image",
203 source: { type: "base64", data: result.screenshot, media_type: "image/png" }
204 };
204 return [
205 {
206 type: "image",
207 source: { type: "base64", data: result.screenshot, media_type: "image/png" }
208 }
209 ];
205210 }
206211});
207212```
from line 766
761766
762767 * **Internal tools:** If the application is used solely within a controlled internal environment where the users are trusted, the risk of credential exposure can be mitigated.
763768 * **Development or debugging purpose:** Enabling this feature temporarily might be acceptable, provided the credentials are short-lived, aren’t also used in production environments, or are frequently rotated.
769
770 Even in these cases, browser support works only if your organization can call the Claude API directly from a browser. Organizations with zero data retention (ZDR) or the Compliance API enabled cannot, and their browser requests fail with a 401 error. See [Browser-based applications](https://platform.claude.com/docs/en/manage-claude/authentication#browser-based-applications).
764771</Accordion>
765772
766773## Platform integrations
from line 797
790797
791798## Semantic versioning
792799
793Each major version of this SDK sends one API version in the `anthropic-version` header by default, and a new major version comes with each new API version. The first major version that sends `2026-10-21` is 1.0.0; see [Migrating to API version 2026-10-21](https://platform.claude.com/docs/en/api/migration-2026-10-21#upgrade).
794
795800This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backward-incompatible changes may be released as minor versions:
796801
7978021. Changes that only affect static types, without breaking runtime behavior.
from line 804
7998043. Changes that aren’t expected to impact the vast majority of users in practice.
800805
801806Backward compatibility is taken seriously to ensure you can rely on a smooth upgrade experience.
807
808Every request to the Claude API uses an API version. With this SDK, your requests use the API version that was current when your SDK’s major version was released, so you move to a new API version by upgrading to a new major version. Version 1.0.0 is the first to use `2026-10-21`. See [Migrating to API version 2026-10-21](https://platform.claude.com/docs/en/api/migration-2026-10-21#upgrade) for how to upgrade.
802809
803810## Frequently asked questions
804811
manage-claude/access-transparency Changed · +3 / -3 lines
from line 36
3636* **Your own organization’s activity:** Your API calls, admin actions, and Compliance API reads are covered by standard [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed) event types.
3737* **Claude for Enterprise and Claude Apps:** claude.ai Enterprise seats, Claude for Work, Cowork, and Claude in Chrome are not covered.
3838* **Claude consumer products:** Claude Free, Pro, Max, or Ultra plans.
39* **Partner-operated platforms:** Amazon Bedrock and Claude Models on Google Cloud (Google managed). Refer to those platforms’ transparency controls.
39* **Partner-operated platforms:** Claude Models on Google Cloud (Google managed) and Amazon Bedrock. Refer to those platforms’ transparency controls.
4040* **Anything ZDR does not cover:** Products that are not covered by ZDR (for example, the Files API, Anthropic-hosted stateful applications, and the Batch API) are not covered by Access Transparency. See [Zero data retention (ZDR)](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#zero-data-retention-zdr-scope) for additional details.
4141
4242## Getting started
from line 69
6969 --data-urlencode "activity_types[]=anthropic_access" \
7070 --data-urlencode "limit=50" \
7171 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
72 -H "anthropic-version: 2023-06-01"
72 -H "anthropic-version: 2026-10-21"
7373```
7474
7575Pagination, date-range filtering (`created_at.gte` / `.lt`), and the response envelope (`has_more`, `first_id`, `last_id`) are shared with the rest of the Activity Feed. See [Query the Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed).
from line 130
130130 --data-urlencode "activity_types[]=cmek_preserve" \
131131 --data-urlencode "limit=50" \
132132 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
133 -H "anthropic-version: 2023-06-01"
133 -H "anthropic-version: 2026-10-21"
134134```
135135
136136Example JSON message:
manage-claude/access-transparency-log Changed · +4 / -4 lines
from line 121
121121curl --fail-with-body -sS \
122122 "https://api.anthropic.com/v1/compliance/transparency_log/checkpoint" \
123123 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
124 -H "anthropic-version: 2023-06-01"
124 -H "anthropic-version: 2026-10-21"
125125```
126126
127127The response is `text/plain`: a C2SP [signed note](https://c2sp.org/signed-note). The body lines are the origin, the tree size in decimal, and the base64 root hash. A blank line follows, then the signature line, which starts with an em dash (U+2014), names the origin, and ends with a base64 value. Values here are illustrative:
from line 147
147147curl --fail-with-body -sS \
148148 "https://api.anthropic.com/v1/compliance/transparency_log/keys" \
149149 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
150 -H "anthropic-version: 2023-06-01"
150 -H "anthropic-version: 2026-10-21"
151151```
152152
153153```json
from line 211
211211 "https://api.anthropic.com/v1/compliance/transparency_log/inclusion" \
212212 --data-urlencode "leaf_index=41" \
213213 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
214 -H "anthropic-version: 2023-06-01"
214 -H "anthropic-version: 2026-10-21"
215215```
216216
217217```json
from line 257
257257 "https://api.anthropic.com/v1/compliance/transparency_log/consistency" \
258258 --data-urlencode "from=1180" \
259259 -H "x-api-key: $ANTHROPIC_COMPLIANCE_ACCESS_KEY" \
260 -H "anthropic-version: 2023-06-01"
260 -H "anthropic-version: 2026-10-21"
261261```
262262
263263```json
manage-claude/admin-api Changed · +15 / -15 lines
from line 52
5252 ```bash cURL
5353 curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/me" \
5454 -H "authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
55 -H "anthropic-version: 2023-06-01"
55 -H "anthropic-version: 2026-10-21"
5656 ```
5757
5858 ```bash CLI
from line 138
138138 ```bash cURL
139139 curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/me" \
140140 -H "x-api-key: $ANTHROPIC_API_KEY" \
141 -H "anthropic-version: 2023-06-01"
141 -H "anthropic-version: 2026-10-21"
142142 ```
143143
144144 ```bash CLI
from line 250
250250 ```bash cURL
251251 curl "https://api.anthropic.com/v1/organizations/users?limit=10" \
252252 -H "x-api-key: $ANTHROPIC_API_KEY" \
253 -H "anthropic-version: 2023-06-01"
253 -H "anthropic-version: 2026-10-21"
254254 ```
255255
256256 ```bash CLI
from line 348
348348 ```bash cURL
349349 curl "https://api.anthropic.com/v1/organizations/users/user_01WxYzAbCdEfGhJkMnPqRsTu" \
350350 -H "x-api-key: $ANTHROPIC_API_KEY" \
351 -H "anthropic-version: 2023-06-01" \
351 -H "anthropic-version: 2026-10-21" \
352352 -H "content-type: application/json" \
353353 -d '{"role": "developer"}'
354354 ```
from line 463
463463 ```bash cURL
464464 curl -X DELETE "https://api.anthropic.com/v1/organizations/users/user_01WxYzAbCdEfGhJkMnPqRsTu" \
465465 -H "x-api-key: $ANTHROPIC_API_KEY" \
466 -H "anthropic-version: 2023-06-01"
466 -H "anthropic-version: 2026-10-21"
467467 ```
468468
469469 ```bash CLI
from line 544
544544 ```bash cURL
545545 curl "https://api.anthropic.com/v1/organizations/invites" \
546546 -H "x-api-key: $ANTHROPIC_API_KEY" \
547 -H "anthropic-version: 2023-06-01" \
547 -H "anthropic-version: 2026-10-21" \
548548 -H "content-type: application/json" \
549549 -d '{
from line 670
670670 ```bash cURL
671671 curl "https://api.anthropic.com/v1/organizations/invites?limit=10" \
672672 -H "x-api-key: $ANTHROPIC_API_KEY" \
673 -H "anthropic-version: 2023-06-01"
673 -H "anthropic-version: 2026-10-21"
674674 ```
675675
676676 ```bash CLI
from line 768
768768 ```bash cURL
769769 curl -X DELETE "https://api.anthropic.com/v1/organizations/invites/invite_015gWxHNr6h6TdRPZTmuCGnn" \
770770 -H "x-api-key: $ANTHROPIC_API_KEY" \
771 -H "anthropic-version: 2023-06-01"
771 -H "anthropic-version: 2026-10-21"
772772 ```
773773
774774 ```bash CLI
from line 857
857857 ```bash cURL
858858 curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members" \
859859 -H "x-api-key: $ANTHROPIC_API_KEY" \
860 -H "anthropic-version: 2023-06-01" \
860 -H "anthropic-version: 2026-10-21" \
861861 -H "content-type: application/json" \
862862 -d '{
863863 "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu",
from line 993
993993 ```bash cURL
994994 curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members?limit=10" \
995995 -H "x-api-key: $ANTHROPIC_API_KEY" \
996 -H "anthropic-version: 2023-06-01"
996 -H "anthropic-version: 2026-10-21"
997997 ```
998998
999999 ```bash CLI
from line 1110
11101110 ```bash cURL
11111111 curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members/user_01WxYzAbCdEfGhJkMnPqRsTu" \
11121112 -H "x-api-key: $ANTHROPIC_API_KEY" \
1113 -H "anthropic-version: 2023-06-01" \
1113 -H "anthropic-version: 2026-10-21" \
11141114 -H "content-type: application/json" \
11151115 -d '{"workspace_role": "workspace_admin"}'
11161116 ```
from line 1243
12431243 ```bash cURL
12441244 curl -X DELETE "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members/user_01WxYzAbCdEfGhJkMnPqRsTu" \
12451245 -H "x-api-key: $ANTHROPIC_API_KEY" \
1246 -H "anthropic-version: 2023-06-01"
1246 -H "anthropic-version: 2026-10-21"
12471247 ```
12481248
12491249 ```bash CLI
from line 1351
13511351 ```bash cURL
13521352 curl "https://api.anthropic.com/v1/organizations/api_keys?limit=10&status=active&workspace_id=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" \
13531353 -H "x-api-key: $ANTHROPIC_API_KEY" \
1354 -H "anthropic-version: 2023-06-01"
1354 -H "anthropic-version: 2026-10-21"
13551355 ```
13561356
13571357 ```bash CLI
from line 1480
14801480 ```bash cURL
14811481 curl "https://api.anthropic.com/v1/organizations/api_keys/apikey_01Rj2N8SVvo6BePZj99NhmiT" \
14821482 -H "x-api-key: $ANTHROPIC_API_KEY" \
1483 -H "anthropic-version: 2023-06-01" \
1483 -H "anthropic-version: 2026-10-21" \
14841484 -H "content-type: application/json" \
14851485 -d '{
14861486 "status": "inactive",
from line 1631
16311631 ```bash cURL
16321632 curl "https://api.anthropic.com/v1/organizations/me" \
16331633 -H "x-api-key: $ANTHROPIC_API_KEY" \
1634 -H "anthropic-version: 2023-06-01"
1634 -H "anthropic-version: 2026-10-21"
16351635 ```
16361636
16371637 ```bash CLI