One read of Claude Developer Platformapi-20261009T153709Z
536 pages moved out of 760 read.
Pages moved
536
significant first
Pages read
760
in this capture
Captured
15:37 UTC
Corpus hash
9680386eb15e
corpus-hash
What this read moved
401-425 of 536, page 17 of 22This capture is too large to show at once. Changes 401-425 of 536 are below, significant first; the rest are on the following screens.
build-with-claude/thinking-troubleshooting Changed · +5 / -1 lines
from line 122
122122
123123The message says thinking is disabled because `between_tools` has no up-front thinking. With `between_tools`, effort can't change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. `messages.N` is the position of the message that set the new level.
124124
125Claude Haiku 5.5 returns the same message for a per-message effort change while `thinking: {type: "disabled"}` is set.
126
125127Remove that per-message effort, or set it to the level in effect. To vary effort per turn, use adaptive thinking, which is what the message means by "enable thinking".
126128
127129Claude Haiku 5.5 returns the same message when a request with `thinking: {type: "disabled"}` sets a per-message effort that differs from the level in effect. Remove that per-message effort, or set `thinking` to `{"type": "adaptive"}` to vary effort per turn.
from line 168
166168
167169On Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, the API accepts a replayed thinking block only while the `system` prompt, `tools`, and messages that preceded it are unchanged. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check). The error means something earlier in the conversation changed between requests: an edited, reordered, or removed turn, a per-turn reminder that was injected and later removed, a rebuilt `system` prompt or `tools` array, or client-side compaction that kept recent turns and their thinking verbatim. The check is enforced for new accounts created on or after August 31, 2026, and for any request that sets `thinking.block_binding.prefix_mismatch_behavior`. Server-side [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) and [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) never trigger it.
168170
169To fix it, keep the history append-only: pass earlier turns back exactly as sent and received, add instructions with a [mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) instead of editing `system` or `tools`, and let server-side [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) or [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) do any trimming. Retrying the same request body doesn't clear the error. To continue this request without the invalidated reasoning, send the `thinking-binding-controls-2026-08-01` beta header and set `thinking.block_binding.prefix_mismatch_behavior` to `"drop_block"`. Alternatively, strip every `thinking` and `redacted_thinking` block from the history (at minimum the named block and every one after it, in that turn and all later turns), leave each turn's other blocks in place, and retry once. On Claude Sonnet 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With `between_tools`, keep the history append-only, or strip the thinking blocks from the edited turn on.
171To fix it, keep the history append-only: pass earlier turns back exactly as sent and received, add instructions with a [mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) instead of editing `system` or `tools`, and let server-side [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) or [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) do any trimming. Retrying the same request body doesn't clear the error. To continue this request without the invalidated reasoning, send the `thinking-binding-controls-2026-08-01` beta header and set `thinking.block_binding.prefix_mismatch_behavior` to `"drop_block"`. Alternatively, strip every `thinking` and `redacted_thinking` block from the history (at minimum the named block and every one after it, in that turn and all later turns), leave each turn's other blocks in place, and retry once. On Claude Sonnet 5.5 and Claude Haiku 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With `between_tools` on Claude Sonnet 5.5, or `thinking: {"type": "disabled"}` on Claude Haiku 5.5, keep the history append-only, or strip the thinking blocks from the edited turn on.
170172
171173A block from a model the target model can't read never produces this error: the API drops it and, under the beta header, reports it in `input_transformations`.
172174
from line 189
187189This is normal in adaptive mode: Claude skips thinking on requests it judges simple enough to answer directly.
188190
189191If you want thinking more often or more deeply, raise `effort` or steer with prompting; see [Steering how often Claude thinks](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior).
192
193A forced `tool_choice` (`{"type": "any"}` or a named tool) also returns no `thinking` block: the response starts with the tool call. To let the model think before it calls a tool, use `tool_choice: {"type": "auto"}` and say in the prompt when to use the tool.
190194
191195## Tool calls or XML tags appear in the text output
192196
claude_api_primer Changed · +3 / -3 lines
from line 239
239239
240240## Thinking
241241
242Thinking can sometimes help Claude with very hard tasks. The current mechanism is [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) (`thinking: {"type": "adaptive"}`): Claude determines when and how much to think, and you steer thinking depth with the [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) parameter rather than a token budget. Adaptive thinking is supported on Claude 4.6 and later models and Claude Mythos Preview. On Claude 5 models and Claude Mythos Preview, thinking is on by default when the `thinking` parameter is omitted.
242Thinking can sometimes help Claude with very hard tasks. The current mechanism is [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) (`thinking: {"type": "adaptive"}`): Claude determines when and how much to think, and you steer thinking depth with the [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) parameter rather than a token budget. Adaptive thinking is supported on Claude 4.6 and later models and Claude Mythos Preview. On Claude 5 and later models and Claude Mythos Preview, thinking is on by default when the `thinking` parameter is omitted.
243243
244244Temperature must be set to 1 (or left unset) whenever thinking is enabled, on all models. On Claude 4.7 and later models and Claude Mythos Preview, `temperature` is deprecated and only its default value is accepted, even when thinking is off.
245245
from line 246
246246Thinking is supported in the following models:
247247
248248* Claude Opus 5.5 (`claude-opus-5-5`, adaptive thinking only, always on)
249* Claude Sonnet 5.5 (`claude-sonnet-5-5`, adaptive thinking only, on by default)
249* Claude Sonnet 5.5 (`claude-sonnet-5-5`, adaptive thinking only, on by default; `thinking: {"type": "disabled"}` returns a 400 error, so send `thinking: {"type": "between_tools"}` to turn off up-front thinking)
250250* Claude Haiku 5.5 (`claude-haiku-5-5`, adaptive thinking only, on by default)
251251* Claude Opus 5 (claude-opus-5, adaptive thinking only, on by default)
252252* Claude Sonnet 5 (`claude-sonnet-5`, adaptive thinking only, on by default)
from line 315
315315
316316Important limitations:
317317
3181. **Tool choice limitation:** Only supports `tool_choice: {"type": "auto"}` (default) or `tool_choice: {"type": "none"}`.
3181. **Tool choice limitation:** With manual extended thinking (`thinking: {"type": "enabled"}`), only `tool_choice: {"type": "auto"}` (default) or `tool_choice: {"type": "none"}` is supported. Adaptive thinking accepts forced tool use, except on the models listed under [Forcing tool use](https://platform.claude.com/docs/en/claude_api_primer#forcing-tool-use). Where it's accepted, a forced tool call skips thinking: the response starts with the tool call and has no `thinking` block.
3193192. **Preserving thinking blocks:** During tool use, you must pass `thinking` blocks back to the API for the last assistant message.
320320
321321### Preserving thinking blocks
cli-sdks-libraries/libraries/openai-sdk Changed · +42 / -42 lines
from line 189
189189* The `strict` parameter for function calling is ignored, which means the tool use JSON is not guaranteed to follow the supplied schema. For guaranteed schema conformance, use the native [Claude API with Structured Outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs).
190190* Audio input is not supported; it will be ignored and stripped from input
191191* Prompt caching is not supported, but it is supported in the [Anthropic SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview)
192* System/developer messages are hoisted and concatenated to the beginning of the conversation, as Anthropic only supports a single initial system message.
192* System/developer messages are hoisted and concatenated into the top-level `system` field, wherever they appear in the conversation. To add system instructions partway through a conversation, use [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) in the native Claude API.
193193
194194Most unsupported fields are silently ignored rather than producing errors. These are all documented in the following sections.
195195
from line 199
199199
200200### System / developer message hoisting
201201
202Most of the inputs to the OpenAI SDK clearly map directly to Anthropic’s API parameters, but one distinct difference is the handling of system / developer prompts. These two prompts can be put throughout a chat conversation via OpenAI. Since Anthropic only supports an initial system message, the API takes all system/developer messages and concatenates them together with a single newline (`\n`) in between them. This full string is then supplied as a single system message at the start of the messages.
202Most of the inputs to the OpenAI SDK clearly map directly to Anthropic’s API parameters, but one distinct difference is the handling of system / developer prompts. These two prompts can be put throughout a chat conversation via OpenAI. The compatibility layer takes all system/developer messages and concatenates them together with a single newline (`\n`) in between them. This full string is then supplied as the top-level `system` field, ahead of every message.
203203
204204### Thinking support
205205
from line 289
289289
290290#### Simple fields
291291
292| Field | Support status |
293| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
294| `model` | Use Claude model names |
295| `max_tokens` | Fully supported |
296| `max_completion_tokens` | Fully supported |
297| `stream` | Fully supported |
298| `stream_options` | Fully supported |
299| `top_p` | Fully supported |
300| `parallel_tool_calls` | Fully supported |
301| `stop` | All non-whitespace stop sequences work |
302| `temperature` | Between 0 and 1 (inclusive). Values greater than 1 are capped at 1. |
303| `n` | Must be exactly 1 |
304| `logprobs` | Ignored |
305| `metadata` | Ignored |
306| `response_format` | Ignored. For JSON output, use [Structured Outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) with the native Claude API |
307| `prediction` | Ignored |
308| `presence_penalty` | Ignored |
309| `frequency_penalty` | Ignored |
310| `seed` | Ignored |
311| `service_tier` | Ignored |
312| `audio` | Ignored |
313| `logit_bias` | Ignored |
314| `store` | Ignored |
315| `user` | Ignored |
316| `modalities` | Ignored |
317| `top_logprobs` | Ignored |
318| `reasoning_effort` | Ignored |
292| Field | Support status |
293| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
294| `model` | Use Claude model names |
295| `max_tokens` | Fully supported |
296| `max_completion_tokens` | Fully supported |
297| `stream` | Fully supported |
298| `stream_options` | Fully supported |
299| `top_p` | Passed through to the model. Claude 4.7 and later models and Claude Mythos Preview return a 400 error for any value other than `0.99`, the default, so omit it. A request that sets both `temperature` and `top_p` also returns a 400 error. See [Working with messages](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). |
300| `parallel_tool_calls` | Fully supported |
301| `stop` | All non-whitespace stop sequences work |
302| `temperature` | Between 0 and 1 (inclusive). Values greater than 1 are capped at 1. On Claude 4.7 and later models and Claude Mythos Preview, any value below 1 returns a 400 error, so omit it. See [Working with messages](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). |
303| `n` | Must be exactly 1 |
304| `logprobs` | Ignored |
305| `metadata` | Ignored |
306| `response_format` | Ignored. For JSON output, use [Structured Outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) with the native Claude API |
307| `prediction` | Ignored |
308| `presence_penalty` | Ignored |
309| `frequency_penalty` | Ignored |
310| `seed` | Ignored |
311| `service_tier` | Ignored |
312| `audio` | Ignored |
313| `logit_bias` | Ignored |
314| `store` | Ignored |
315| `user` | Ignored |
316| `modalities` | Ignored |
317| `top_logprobs` | Ignored |
318| `reasoning_effort` | Ignored |
319319
320320#### `tools` / `functions` fields
321321
from line 410
410410 <Tab title="Tool role">
411411 Fields for `messages[n].role == "tool"`
412412
413 | Field | Variant | Support status |
414 | -------------- | ------------------------- | --------------- |
415 | `content` | `string` | Fully supported |
416 | | `array`, `type == "text"` | Fully supported |
417 | `tool_call_id` | | Fully supported |
418 | `tool_choice` | | Fully supported |
419 | `name` | | Ignored |
413 | Field | Variant | Support status |
414 | -------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
415 | `content` | `string` | Fully supported |
416 | | `array`, `type == "text"` | Fully supported |
417 | `tool_call_id` | | Fully supported |
418 | `tool_choice` | | Supported. `"required"` and named-function values force a tool call; Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1 don't support forced tool use and return an error, so use `"auto"` on those models. See [Forcing tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#forcing-tool-use). |
419 | `name` | | Ignored |
420420 </Tab>
421421
422422 <Tab title="Function role">
423423 Fields for `messages[n].role == "function"`
424424
425 | Field | Variant | Support status |
426 | ------------- | ------------------------- | --------------- |
427 | `content` | `string` | Fully supported |
428 | | `array`, `type == "text"` | Fully supported |
429 | `tool_choice` | | Fully supported |
430 | `name` | | Ignored |
425 | Field | Variant | Support status |
426 | ------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
427 | `content` | `string` | Fully supported |
428 | | `array`, `type == "text"` | Fully supported |
429 | `tool_choice` | | Supported. `"required"` and named-function values force a tool call; Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1 don't support forced tool use and return an error, so use `"auto"` on those models. See [Forcing tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#forcing-tool-use). |
430 | `name` | | Ignored |
431431 </Tab>
432432 </Tabs>
433433</Accordion>
manage-claude/rate-limits-api Changed · +278 / -12 lines
### Include inherited values
from line 157
157157* **`group_type`:** Deprecated in favor of the `type` inside `group`. It's still returned, always equals that value, and has no removal date. The `group_type` query parameter isn't deprecated. See [Filtering by group type](https://platform.claude.com/docs/en/manage-claude/rate-limits-api#filtering-by-group-type) for the list of values.
158158* **`models` list:** For `model_group` entries, the `models` field lists every model ID and alias that counts against that group's limits. Use this list to look up which group any model string falls under. For other group types, `models` is `null`.
159159* **`limits` list:** Each group carries a list of `{type, value}` pairs. The `type` field identifies the limiter (such as `requests_per_minute`, `input_tokens_per_minute`, or `output_tokens_per_minute`) and `value` is the configured limit. See [Rate limits](https://platform.claude.com/docs/en/api/rate-limits) for how each limiter is measured and enforced.
160* **`source` on workspace limits:** On the workspace endpoint, every limit value also carries `source`, which says where `value` comes from: `{"type": "workspace"}` for an override stored on the workspace, or `{"type": "organization"}` for a value inherited from the organization. By default, the workspace endpoint returns overrides only, so `source.type` is always `workspace` there; inherited values appear when you pass `include_inherited=true`. See [Workspace rate limits](https://platform.claude.com/docs/en/manage-claude/rate-limits-api#workspace-rate-limits).
160161
161162For complete parameter details and response schemas, see the [Organization Rate Limits API reference](https://platform.claude.com/docs/en/api/organization/rate_limits/list).
162163
from line 282
281282 ```
282283</CodeGroup>
283284
284```json
285```text wrap
285286{
286287 "data": [
287288 {
from line 477
476477
477478## Workspace rate limits
478479
479The `/v1/organizations/workspaces/{workspace_id}/rate_limits` endpoint returns the rate limit overrides configured for a single workspace.
480The `/v1/organizations/workspaces/{workspace_id}/rate_limits` endpoint returns the rate limit overrides configured for a single workspace. To also see the values the workspace inherits, pass `include_inherited=true` (see [Include inherited values](https://platform.claude.com/docs/en/manage-claude/rate-limits-api#include-inherited-values)).
480481
481The response only includes overrides, so anything missing from it is inherited from the organization:
482By default, the response only includes overrides, so anything missing from it is inherited from the organization:
482483
483484* A group that is absent from `data` has no workspace override at all. The workspace inherits the organization-level limits for that group (it is not unlimited).
484485* Within a group that is present, a limiter type that is absent from `limits[]` has no workspace override for that limiter. The workspace inherits the organization value for it.
485* For each limiter that is present, `org_limit` is the organization-level value for the same limiter, or `null` if the organization has no configured limit for that limiter type.
486* For each limiter that is present, `org_limit` is the organization-level value for the same limiter, or `null` if the organization has no configured limit for that limiter type, and `source` is `{"type": "workspace"}`.
486487
487488For complete parameter details and response schemas, see the [Workspace Rate Limits API reference](https://platform.claude.com/docs/en/api/organization/workspaces/rate_limits/list).
488489
489490<Tip>
490 To retrieve your organization's workspace IDs, use the [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) endpoint, or find them in the [Claude Console](https://platform.claude.com/settings/workspaces). The default workspace cannot have rate limit overrides, so it has no entry on this endpoint; use the organization endpoint to read its limits.
491 To retrieve your organization's workspace IDs, use the [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) endpoint, or find them in the [Claude Console](https://platform.claude.com/settings/workspaces). The default workspace cannot have rate limit overrides, and this endpoint returns a 404 error for it, with or without `include_inherited`; use the organization endpoint to read its limits.
491492</Tip>
492493
493494<CodeGroup>
from line 625
624625 ```
625626</CodeGroup>
626627
627```json
628```text wrap
628629{
629630 "data": [
630631 {
from line 638
637638 },
638639 "models": ["claude-opus-5-5"],
639640 "limits": [
640 { "type": "requests_per_minute", "value": 1000, "org_limit": 4000 },
641 { "type": "input_tokens_per_minute", "value": 500000, "org_limit": 10000000 }
641 {
642 "type": "requests_per_minute",
643 "value": 1000,
644 "org_limit": 4000,
645 "source": { "type": "workspace" }
646 },
647 {
648 "type": "input_tokens_per_minute",
649 "value": 500000,
650 "org_limit": 10000000,
651 "source": { "type": "workspace" }
652 }
642653 ]
643654 },
644655 {
from line 668
657668 "claude-opus-4-8"
658669 ],
659670 "limits": [
660 { "type": "requests_per_minute", "value": 1000, "org_limit": 4000 },
661 { "type": "input_tokens_per_minute", "value": 500000, "org_limit": 10000000 }
671 {
672 "type": "requests_per_minute",
673 "value": 1000,
674 "org_limit": 4000,
675 "source": { "type": "workspace" }
676 },
677 {
678 "type": "input_tokens_per_minute",
679 "value": 500000,
680 "org_limit": 10000000,
681 "source": { "type": "workspace" }
682 }
662683 ]
663684 }
664685 ],
from line 687
666687}
667688```
668689
690### Include inherited values
691
692To read a workspace's applicable limits in one request, add the optional `include_inherited` query parameter. It defaults to `false`; a value that isn't a Boolean returns a 400 error. With `include_inherited=true`:
693
694* `data` has one entry for each group that applies to the workspace and has an organization-level value, even if the workspace overrides none of it. A model group applies when the workspace can access at least one of its models.
695* Each entry's `limits[]` lists every limiter type the organization has a value for on that group, plus any type the workspace overrides. Each type appears once, with the workspace's override where one is stored and the organization's value otherwise, so one entry can mix the two.
696* Each value's `source` tells them apart: `{"type": "workspace"}` is a stored override, and `{"type": "organization"}` is an inherited value, where `value` equals `org_limit`.
697
698<CodeGroup>
699 ```bash cURL
700 curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/rate_limits?include_inherited=true" \
701 -H "x-api-key: $ANTHROPIC_API_KEY" \
702 -H "anthropic-version: 2023-06-01"
703 ```
704
705 ```bash CLI
706 ant organization:workspaces:rate-limits list \
707 --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ \
708 --include-inherited
709 ```
710
711 ```python Python
712 client = anthropic.Anthropic()
713
714 rate_limits = client.organization.workspaces.rate_limits.list(
715 "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
716 include_inherited=True,
717 )
718
719 for entry in rate_limits:
720 models = f" ({', '.join(entry.models)})" if entry.models else ""
721 print(f"{entry.group.type}{models}")
722 for limit in entry.limits:
723 print(f" {limit.type}: {limit.value} ({limit.source.type})")
724 ```
725
726 ```typescript TypeScript
727 const client = new Anthropic();
728
729 const rateLimits = await client.organization.workspaces.rateLimits.list(
730 "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
731 { include_inherited: true }
732 );
733
734 for await (const entry of rateLimits) {
735 const models = entry.models ? ` (${entry.models.join(", ")})` : "";
736 console.log(`${entry.group.type}${models}`);
737 for (const limit of entry.limits) {
738 console.log(` ${limit.type}: ${limit.value} (${limit.source.type})`);
739 }
740 }
741 ```
742
743 ```csharp C#
744 AnthropicClient client = new();
745
746 var rateLimits = await client.Organization.Workspaces.RateLimits.List(
747 "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
748 new() { IncludeInherited = true }
749 );
750
751 await foreach (var entry in rateLimits.Paginate())
752 {
753 var models = entry.Models is null ? "" : $" ({string.Join(", ", entry.Models)})";
754 Console.WriteLine($"{entry.Group.Type.GetString()}{models}");
755 foreach (var limit in entry.Limits)
756 {
757 Console.WriteLine($" {limit.Type}: {limit.Value} ({limit.Source.Type.GetString()})");
758 }
759 }
760 ```
761
762 ```go Go
763 client := anthropic.NewClient()
764
765 rateLimits := client.Organization.Workspaces.RateLimits.ListAutoPaging(
766 context.Background(),
767 "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
768 anthropic.OrganizationWorkspaceRateLimitListParams{
769 IncludeInherited: anthropic.Bool(true),
770 },
771 )
772
773 for rateLimits.Next() {
774 entry := rateLimits.Current()
775 models := ""
776 if len(entry.Models) > 0 {
777 models = fmt.Sprintf(" (%s)", strings.Join(entry.Models, ", "))
778 }
779 fmt.Printf("%s%s\n", entry.Group.Type, models)
780 for _, limit := range entry.Limits {
781 fmt.Printf(" %s: %d (%s)\n", limit.Type, limit.Value, limit.Source.Type)
782 }
783 }
784 if err := rateLimits.Err(); err != nil {
785 log.Fatal(err)
786 }
787 ```
788
789 ```java Java
790 import com.anthropic.models.organization.workspaces.ratelimits.RateLimitListParams;
791
792 void main() {
793 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
794
795 var params = RateLimitListParams.builder()
796 .includeInherited(true)
797 .build();
798 var rateLimits = client.organization().workspaces().rateLimits()
799 .list("wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", params);
800
801 for (var entry : rateLimits.autoPager()) {
802 var models = entry.models()
803 .map(modelIds -> " (" + String.join(", ", modelIds) + ")")
804 .orElse("");
805 IO.println(entry.group().type().asString() + models);
806 for (var limit : entry.limits()) {
807 IO.println(" " + limit.type() + ": " + limit.value()
808 + " (" + limit.source().type().asString() + ")");
809 }
810 }
811 }
812 ```
813
814 ```php PHP
815 $client = new Client();
816
817 $rateLimits = $client->organization->workspaces->rateLimits->list(
818 workspaceID: 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ',
819 includeInherited: true,
820 );
821
822 foreach ($rateLimits->data as $entry) {
823 $models = $entry->models ? ' (' . implode(', ', $entry->models) . ')' : '';
824 echo "{$entry->group->type}{$models}\n";
825 foreach ($entry->limits as $limit) {
826 echo " {$limit->type}: {$limit->value} ({$limit->source->type})\n";
827 }
828 }
829 ```
830
831 ```ruby Ruby
832 client = Anthropic::Client.new
833
834 workspace_id = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
835 rate_limits = client.organization.workspaces.rate_limits.list(workspace_id, include_inherited: true)
836
837 rate_limits.data.each do |entry|
838 models = entry.models ? " (#{entry.models.join(", ")})" : ""
839 puts "#{entry.group.type}#{models}"
840 entry.limits.each do |limit|
841 puts " #{limit.type}: #{limit.value} (#{limit.source.type})"
842 end
843 end
844 ```
845</CodeGroup>
846
847```text wrap
848{
849 "data": [
850 {
851 "type": "workspace_rate_limit",
852 "group_type": "model_group",
853 "group": {
854 "type": "model_group",
855 "id": "rlg_01Hq7YkP3mZ9dTwRx4cVbN2s",
856 "display_name": "Claude Opus 5.5"
857 },
858 "models": ["claude-opus-5-5"],
859 "limits": [
860 {
861 "type": "requests_per_minute",
862 "value": 1000,
863 "org_limit": 4000,
864 "source": { "type": "workspace" }
865 },
866 {
867 "type": "input_tokens_per_minute",
868 "value": 500000,
869 "org_limit": 10000000,
870 "source": { "type": "workspace" }
871 },
872 {
873 "type": "output_tokens_per_minute",
874 "value": 800000,
875 "org_limit": 800000,
876 "source": { "type": "organization" }
877 }
878 ]
879 },
880 {
881 "type": "workspace_rate_limit",
882 "group_type": "model_group",
883 "group": {
884 "type": "model_group",
885 "id": "rlg_01Kd5wMv8nSq2LcXy6tRfJ4b",
886 "display_name": "Claude Opus 4.x"
887 },
888 "models": [
889 "claude-opus-4-5",
890 "claude-opus-4-5-20251101",
891 "claude-opus-4-6",
892 "claude-opus-4-7",
893 "claude-opus-4-8"
894 ],
895 "limits": [
896 {
897 "type": "requests_per_minute",
898 "value": 1000,
899 "org_limit": 4000,
900 "source": { "type": "workspace" }
901 },
902 {
903 "type": "input_tokens_per_minute",
904 "value": 500000,
905 "org_limit": 10000000,
906 "source": { "type": "workspace" }
907 },
908 {
909 "type": "output_tokens_per_minute",
910 "value": 800000,
911 "org_limit": 800000,
912 "source": { "type": "organization" }
913 }
914 ]
915 },
916 {
917 "type": "workspace_rate_limit",
918 "group_type": "batch",
919 "group": { "type": "batch", "id": "rlg_01Wn3pBz6kCg9vHtQ7mLxD5a" },
920 "models": null,
921 "limits": [
922 {
923 "type": "enqueued_batch_requests",
924 "value": 500000,
925 "org_limit": 500000,
926 "source": { "type": "organization" }
927 }
928 ]
929 }
930 ],
931 "next_page": null
932}
933```
934
669935## Filtering by group type
670936
671937Both endpoints accept an optional `group_type` query parameter that restricts the response to a single category:
from line 1088
8221088
8231089### What does it mean if a group is missing from the workspace response?
8241090
825The workspace has no override for that group and inherits the organization-level limit. Query the organization endpoint to see the inherited values.
1091By default, the workspace response lists only overrides, so a missing group has no workspace override and inherits the organization-level limit. Pass `include_inherited=true` to see inherited values on the workspace endpoint, or query the organization endpoint. With `include_inherited=true`, a group is missing only when it doesn't apply to the workspace or the organization has no limit set for it.
8261092
8271093### Can I update rate limits with this API?
8281094
managed-agents/events-and-streaming Changed · +177 / -189 lines
from line 748
748748
7497491. The session emits the tool call as an `agent.custom_tool_use`, `agent.tool_use`, or `agent.mcp_tool_use` event.
7507502. The session pauses with a `session.status_idle` event whose `stop_reason.type` is `requires_action`. The blocking event IDs are in the `stop_reason.event_ids` array.
7513. For each blocking event ID, send a [`user.custom_tool_result`](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#return-a-custom-tool-result) or a [`user.tool_confirmation`](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#confirm-a-tool-call) event.
7513. For each blocking event ID, send a [`user.custom_tool_result`](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#return-a-custom-tool-result) or a [`user.tool_confirmation`](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#confirm-a-tool-call) event. A custom tool result doesn't have to wait for step 2.
7527524. Once all blocking events are resolved, the session transitions back to `running`.
753753
754754In a multiagent session, a subagent's blocking events are cross-posted to the primary thread. See [Tool permissions and custom tools](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#tool-permissions-and-custom-tools).
from line 757
757757
758758The `agent.custom_tool_use` event contains the tool name and input. Execute the tool in your system. Then send a `user.custom_tool_result` event, passing the event ID in the `custom_tool_use_id` parameter along with the result content.
759759
760You can send the result as soon as the `agent.custom_tool_use` event arrives, without waiting for `session.status_idle`. The session still emits `session.status_idle` with a `requires_action` stop reason for the call, and your client can ignore it. A second result for the same call is accepted and has no effect.
761
762When you [reconnect](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#reconnect-without-missing-events) to a paused session, `stop_reason.event_ids` on the latest `session.status_idle` event lists the calls to answer.
763
764The following example answers each call as it arrives:
765
760766<CodeGroup>
761767 ```bash cURL
762768 exec {stream_fd}< <(curl --fail-with-body -sS -N \
from line 776
770776 while IFS= read -r -u "$stream_fd" line; do
771777 [[ $line == data:* ]] || continue
772778 event_json="${line#data: }"
773 stop_reason=$(jq -r 'select(.type == "session.status_idle") | .stop_reason.type // empty' <<<"$event_json")
774 case "$stop_reason" in
775 requires_action)
776 while IFS= read -r event_id; do
777 # Execute the tool and send the result back
778 result=$(call_tool "$event_id")
779 jq -n --arg id "$event_id" --arg result "$result" \
780 '{events: [{type: "user.custom_tool_result", custom_tool_use_id: $id, content: [{type: "text", text: $result}]}]}' |
781 curl --fail-with-body -sS \
782 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
783 -H "x-api-key: $ANTHROPIC_API_KEY" \
784 -H "anthropic-version: 2023-06-01" \
785 -H "anthropic-beta: managed-agents-2026-04-01" \
786 -H "content-type: application/json" \
787 -d @-
788 done < <(jq -r '.stop_reason.event_ids[]' <<<"$event_json")
779 case $(jq -r '.type' <<<"$event_json") in
780 agent.custom_tool_use)
781 # Execute the tool and send the result back
782 result=$(call_tool "$(jq -r '.name' <<<"$event_json")" "$(jq -c '.input' <<<"$event_json")")
783 jq --arg result "$result" \
784 '{events: [{type: "user.custom_tool_result", custom_tool_use_id: .id, content: [{type: "text", text: $result}]}]}' <<<"$event_json" |
785 curl --fail-with-body -sS \
786 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
787 -H "x-api-key: $ANTHROPIC_API_KEY" \
788 -H "anthropic-version: 2023-06-01" \
789 -H "anthropic-beta: managed-agents-2026-04-01" \
790 -H "content-type: application/json" \
791 -d @-
789792 ;;
790 end_turn)
791 break
793 session.status_idle)
794 if [[ $(jq -r '.stop_reason.type' <<<"$event_json") == end_turn ]]; then
795 break
796 fi
792797 ;;
793798 esac
794799 done
from line 808
803808 ```python Python
804809 with client.beta.sessions.events.stream(session.id) as stream:
805810 for event in stream:
806 if event.type == "session.status_idle" and (stop_reason := event.stop_reason):
807 match stop_reason.type:
808 case "requires_action":
809 for event_id in stop_reason.event_ids:
810 # Look up the custom tool use event and execute it
811 tool_event = events_by_id[event_id]
812 result = call_tool(tool_event.name, tool_event.input)
811 match event.type:
812 case "agent.custom_tool_use":
813 # Execute the tool
814 result = call_tool(event.name, event.input)
813815
814 # Send the result back
815 client.beta.sessions.events.send(
816 session.id,
817 events=[
818 {
819 "type": "user.custom_tool_result",
820 "custom_tool_use_id": event_id,
821 "content": [{"type": "text", "text": result}],
822 },
823 ],
824 )
825 case "end_turn":
816 # Send the result back
817 client.beta.sessions.events.send(
818 session.id,
819 events=[
820 {
821 "type": "user.custom_tool_result",
822 "custom_tool_use_id": event.id,
823 "content": [{"type": "text", "text": result}],
824 },
825 ],
826 )
827 case "session.status_idle":
828 if event.stop_reason and event.stop_reason.type == "end_turn":
826829 break
827830 ```
828831
from line 832
829832 ```typescript TypeScript
830833 const stream = await client.beta.sessions.events.stream(session.id);
831834
832 for await (const event of stream) {
833 if (event.type !== "session.status_idle") continue;
834 if (event.stop_reason.type === "end_turn") break;
835 if (event.stop_reason.type !== "requires_action") continue;
835 loop: for await (const event of stream) {
836 switch (event.type) {
837 case "agent.custom_tool_use": {
838 // Execute the tool
839 const result = await callTool(event.name, event.input);
836840
837 for (const eventId of event.stop_reason.event_ids) {
838 // Look up the custom tool use event and execute it
839 const toolEvent = eventsById.get(eventId);
840 if (!toolEvent) continue;
841 const result = await callTool(toolEvent.name, toolEvent.input);
842
843 // Send the result back
844 await client.beta.sessions.events.send(session.id, {
845 events: [
846 {
847 type: "user.custom_tool_result",
848 custom_tool_use_id: eventId,
849 content: [{ type: "text", text: result }],
850 },
851 ],
852 });
841 // Send the result back
842 await client.beta.sessions.events.send(session.id, {
843 events: [
844 {
845 type: "user.custom_tool_result",
846 custom_tool_use_id: event.id,
847 content: [{ type: "text", text: result }],
848 },
849 ],
850 });
851 break;
852 }
853 case "session.status_idle":
854 if (event.stop_reason.type === "end_turn") break loop;
855 break;
853856 }
854857 }
855858 ```
from line 860
857860 ```csharp C#
858861 await foreach (var streamEvent in client.Beta.Sessions.Events.StreamStreaming(session.ID))
859862 {
860 if (streamEvent.Value is not BetaManagedAgentsSessionStatusIdleEvent idle) continue;
861
862 if (idle.StopReason?.Value is BetaManagedAgentsSessionRequiresAction requiresAction)
863 if (streamEvent.Value is BetaManagedAgentsAgentCustomToolUseEvent toolUse)
863864 {
864 foreach (var eventId in requiresAction.EventIds)
865 {
866 // Look up the custom tool use event and execute it
867 var toolEvent = eventsById[eventId];
868 var result = await CallTool(toolEvent.Name, toolEvent.Input);
865 // Execute the tool
866 var result = await CallTool(toolUse.Name, toolUse.Input);
869867
870 // Send the result back
871 await client.Beta.Sessions.Events.Send(session.ID, new()
872 {
873 Events =
874 [
875 new BetaManagedAgentsUserCustomToolResultEventParams
876 {
877 Type = BetaManagedAgentsUserCustomToolResultEventParamsType.UserCustomToolResult,
878 CustomToolUseID = eventId,
879 Content =
880 [
881 new BetaManagedAgentsTextBlock
882 {
883 Type = BetaManagedAgentsTextBlockType.Text,
884 Text = result,
885 },
886 ],
887 },
888 ],
889 });
890 }
868 // Send the result back
869 await client.Beta.Sessions.Events.Send(session.ID, new()
870 {
871 Events =
872 [
873 new BetaManagedAgentsUserCustomToolResultEventParams
874 {
875 Type = BetaManagedAgentsUserCustomToolResultEventParamsType.UserCustomToolResult,
876 CustomToolUseID = toolUse.ID,
877 Content =
878 [
879 new BetaManagedAgentsTextBlock
880 {
881 Type = BetaManagedAgentsTextBlockType.Text,
882 Text = result,
883 },
884 ],
885 },
886 ],
887 });
891888 }
892 else if (idle.StopReason?.Value is BetaManagedAgentsSessionEndTurn)
889 else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent idle
890 && idle.StopReason?.Value is BetaManagedAgentsSessionEndTurn)
893891 {
894892 break;
895893 }
from line 900
902900
903901 loop:
904902 for stream.Next() {
905 event, ok := stream.Current().AsAny().(anthropic.BetaManagedAgentsSessionStatusIdleEvent)
906 if !ok {
907 continue
908 }
909 switch stopReason := event.StopReason.AsAny().(type) {
910 case anthropic.BetaManagedAgentsSessionRequiresAction:
911 for _, eventID := range stopReason.EventIDs {
912 // Look up the custom tool use event and execute it
913 toolEvent := eventsByID[eventID]
914 result := callTool(toolEvent.Name, toolEvent.Input)
915 // Send the result back
916 if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
917 Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
918 OfUserCustomToolResult: &anthropic.BetaManagedAgentsUserCustomToolResultEventParams{
919 Type: anthropic.BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult,
920 CustomToolUseID: eventID,
921 Content: []anthropic.BetaManagedAgentsUserCustomToolResultEventParamsContentUnion{{
922 OfText: &anthropic.BetaManagedAgentsTextBlockParam{
923 Type: anthropic.BetaManagedAgentsTextBlockTypeText,
924 Text: result,
925 },
926 }},
927 },
928 }},
929 }); err != nil {
930 panic(err)
931 }
903 switch event := stream.Current().AsAny().(type) {
904 case anthropic.BetaManagedAgentsAgentCustomToolUseEvent:
905 // Execute the tool
906 result := callTool(event.Name, event.Input)
907 // Send the result back
908 if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
909 Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
910 OfUserCustomToolResult: &anthropic.BetaManagedAgentsUserCustomToolResultEventParams{
911 Type: anthropic.BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult,
912 CustomToolUseID: event.ID,
913 Content: []anthropic.BetaManagedAgentsUserCustomToolResultEventParamsContentUnion{{
914 OfText: &anthropic.BetaManagedAgentsTextBlockParam{
915 Type: anthropic.BetaManagedAgentsTextBlockTypeText,
916 Text: result,
917 },
918 }},
919 },
920 }},
921 }); err != nil {
922 panic(err)
932923 }
933 case anthropic.BetaManagedAgentsSessionEndTurn:
934 break loop
924 case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
925 if _, ok := event.StopReason.AsAny().(anthropic.BetaManagedAgentsSessionEndTurn); ok {
926 break loop
927 }
935928 }
936929 }
937930 if err := stream.Err(); err != nil {
from line 934
941934
942935 ```java Java
943936 try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
944 stream.stream()
945 .filter(BetaManagedAgentsStreamSessionEvents::isSessionStatusIdle)
946 .map(idleEvent -> idleEvent.asSessionStatusIdle().stopReason())
947 .takeWhile(stopReason -> !stopReason.isEndTurn())
948 .filter(stopReason -> stopReason.isRequiresAction())
949 .flatMap(stopReason -> stopReason.asRequiresAction().eventIds().stream())
950 .forEach(eventId -> {
951 // Look up the custom tool use event and execute it
952 var toolEvent = eventsById.get(eventId);
953 var result = callTool(toolEvent.name(), toolEvent.input());
937 loop:
938 for (var event : (Iterable<BetaManagedAgentsStreamSessionEvents>) stream.stream()::iterator) {
939 switch (event.type().value()) {
940 case AGENT_CUSTOM_TOOL_USE -> {
941 // Execute the tool
942 var toolUse = event.asAgentCustomToolUse();
943 var result = callTool(toolUse.name(), toolUse.input());
954944
955 // Send the result back
956 client.beta().sessions().events().send(
957 session.id(),
958 EventSendParams.builder()
959 .addEvent(BetaManagedAgentsUserCustomToolResultEventParams.builder()
960 .type(BetaManagedAgentsUserCustomToolResultEventParams.Type.USER_CUSTOM_TOOL_RESULT)
961 .customToolUseId(eventId)
962 .addTextContent(result)
963 .build())
964 .build());
965 });
945 // Send the result back
946 client.beta().sessions().events().send(
947 session.id(),
948 EventSendParams.builder()
949 .addEvent(BetaManagedAgentsUserCustomToolResultEventParams.builder()
950 .type(BetaManagedAgentsUserCustomToolResultEventParams.Type.USER_CUSTOM_TOOL_RESULT)
951 .customToolUseId(toolUse.id())
952 .addTextContent(result)
953 .build())
954 .build());
955 }
956 case SESSION_STATUS_IDLE -> {
957 if (event.asSessionStatusIdle().stopReason().isEndTurn()) {
958 break loop;
959 }
960 }
961 }
962 }
966963 }
967964 ```
968965
from line 967
970967 $stream = $client->beta->sessions->events->streamStream($session->id);
971968
972969 foreach ($stream as $event) {
973 if ($event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusIdleEvent && $event->stopReason) {
974 switch (true) {
975 case $event->stopReason instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionRequiresAction:
976 foreach ($event->stopReason->eventIDs as $eventId) {
977 // Look up the custom tool use event and execute it
978 $toolEvent = $eventsById[$eventId];
979 $result = callTool($toolEvent->name, $toolEvent->input);
970 switch (true) {
971 case $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsAgentCustomToolUseEvent:
972 // Execute the tool
973 $result = callTool($event->name, $event->input);
980974
981 // Send the result back
982 $client->beta->sessions->events->send(
983 $session->id,
984 events: [
985 [
986 'type' => 'user.custom_tool_result',
987 'custom_tool_use_id' => $eventId,
988 'content' => [['type' => 'text', 'text' => $result]],
989 ],
990 ],
991 );
992 }
993 break;
994 case $event->stopReason instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionEndTurn:
975 // Send the result back
976 $client->beta->sessions->events->send(
977 $session->id,
978 events: [
979 [
980 'type' => 'user.custom_tool_result',
981 'custom_tool_use_id' => $event->id,
982 'content' => [['type' => 'text', 'text' => $result]],
983 ],
984 ],
985 );
986 break;
987 case $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusIdleEvent:
988 if ($event->stopReason instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionEndTurn) {
995989 break 2;
996 }
990 }
991 break;
997992 }
998993 }
999994 ```
from line 996
1001996 ```ruby Ruby
1002997 client.beta.sessions.events.stream_events(session.id).each do |event|
1003998 case event
999 when Anthropic::Beta::Sessions::BetaManagedAgentsAgentCustomToolUseEvent
1000 # Execute the tool
1001 result = call_tool.call(event.name, event.input)
1002 # Send the result back
1003 client.beta.sessions.events.send_(
1004 session.id,
1005 events: [
1006 {
1007 type: "user.custom_tool_result",
1008 custom_tool_use_id: event.id,
1009 content: [{type: "text", text: result}]
1010 }
1011 ]
1012 )
10041013 when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusIdleEvent
1005 stop_reason = event.stop_reason
1006 case stop_reason
1007 when Anthropic::Beta::Sessions::BetaManagedAgentsSessionRequiresAction
1008 stop_reason.event_ids.each do |event_id|
1009 # Look up the custom tool use event and execute it
1010 tool_event = events_by_id[event_id]
1011 result = call_tool.call(tool_event.name, tool_event.input)
1012 # Send the result back
1013 client.beta.sessions.events.send_(
1014 session.id,
1015 events: [
1016 {
1017 type: "user.custom_tool_result",
1018 custom_tool_use_id: event_id,
1019 content: [{type: "text", text: result}]
1020 }
1021 ]
1022 )
1023 end
1024 when Anthropic::Beta::Sessions::BetaManagedAgentsSessionEndTurn
1025 break
1026 end
1014 break if event.stop_reason.is_a?(Anthropic::Beta::Sessions::BetaManagedAgentsSessionEndTurn)
10271015 end
10281016 end
10291017 ```
managed-agents/multiagent-orchestration Changed · +35 / -22 lines
from line 92
9292 ```markdown
9393 ---
9494 name: reviewer
95 model: claude-haiku-4-5
95 model: claude-haiku-5-5
9696 ---
9797
9898 You are a code reviewer.
from line 103
103103 ```markdown
104104 ---
105105 name: test-writer
106 model: claude-haiku-4-5
106 model: claude-haiku-5-5
107107 ---
108108
109109 You write unit tests.
from line 426
426426 research_agent_id=$(curl --fail-with-body -sS "$BASE/v1/agents" "${H[@]}" --data @- <<'EOF' | jq -er '.id'
427427 {
428428 "name": "researcher",
429 "model": "claude-haiku-4-5",
429 "model": "claude-haiku-5-5",
430430 "mcp_servers": [{"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"}],
431431 "tools": [{"type": "mcp_toolset", "mcp_server_name": "github"}]
432432 }
from line 471
471471 ```markdown
472472 ---
473473 name: researcher
474 model: claude-haiku-4-5
474 model: claude-haiku-5-5
475475 mcp_servers:
476476 - type: url
477477 name: github
from line 487
487487 ```python Python
488488 research_agent = client.beta.agents.create(
489489 name="researcher",
490 model="claude-haiku-4-5",
490 model="claude-haiku-5-5",
491491 mcp_servers=[
492492 {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
493493 ],
from line 508
508508 ```typescript TypeScript
509509 const researchAgent = await client.beta.agents.create({
510510 name: "researcher",
511 model: "claude-haiku-4-5",
511 model: "claude-haiku-5-5",
512512 mcp_servers: [
513513 { type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/" },
514514 ],
from line 530
530530 var researchAgent = await client.Beta.Agents.Create(new()
531531 {
532532 Name = "researcher",
533 Model = BetaManagedAgentsModel.ClaudeHaiku4_5,
533 Model = BetaManagedAgentsModel.ClaudeHaiku5_5,
534534 McpServers =
535535 [
536536 new()
from line 579
579579 ```go Go
580580 researcher, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
581581 Name: "researcher",
582 Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeHaiku4_5},
582 Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeHaiku5_5},
583583 MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{
584584 Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
585585 Name: "github",
from line 623
623623 var researcher = client.beta().agents().create(
624624 AgentCreateParams.builder()
625625 .name("researcher")
626 .model(BetaManagedAgentsModel.CLAUDE_HAIKU_4_5)
626 .model(BetaManagedAgentsModel.CLAUDE_HAIKU_5_5)
627627 .addMcpServer(BetaManagedAgentsUrlMcpServerParams.builder()
628628 .name("github")
629629 .type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
from line 657
657657 ```php PHP
658658 $researchAgent = $client->beta->agents->create(
659659 name: 'researcher',
660 model: 'claude-haiku-4-5',
660 model: 'claude-haiku-5-5',
661661 mcpServers: [
662662 ['type' => 'url', 'name' => 'github', 'url' => 'https://api.githubcopilot.com/mcp/'],
663663 ],
from line 684
684684 ```ruby Ruby
685685 research_agent = client.beta.agents.create(
686686 name: "researcher",
687 model: "claude-haiku-4-5",
687 model: "claude-haiku-5-5",
688688 mcp_servers: [
689689 {type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/"}
690690 ],
from line 832
832832 curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads" \
833833 -H "x-api-key: $ANTHROPIC_API_KEY" \
834834 -H "anthropic-version: 2023-06-01" \
835 -H "anthropic-beta: managed-agents-2026-04-01" \
836 | jq -r '.data[] | "[\(.agent.name)] \(.status)"'
835 -H "anthropic-beta: managed-agents-2026-04-01"
837836 ```
838837
839838 ```bash CLI
from line 841
842841
843842 ```python Python
844843 for thread in client.beta.sessions.threads.list(session.id):
845 print(f"[{thread.agent.name}] {thread.status}")
844 agent = thread.agent
845 label = agent.type if agent.type == "advisor" else agent.name
846 print(f"[{label}] {thread.status}")
846847 ```
847848
848849 ```typescript TypeScript
849850 for await (const thread of client.beta.sessions.threads.list(session.id)) {
850 const name = thread.agent.type === "agent" ? thread.agent.name : "advisor";
851 console.log(`[${name}] ${thread.status}`);
851 const label = thread.agent.type === "advisor" ? thread.agent.type : thread.agent.name;
852 console.log(`[${label}] ${thread.status}`);
852853 }
853854 ```
854855
from line 856
855856 ```csharp C#
856857 await foreach (var thread in (await client.Beta.Sessions.Threads.List(session.ID)).Paginate())
857858 {
858 Console.WriteLine($"[{thread.Agent.Name}] {thread.Status}");
859 var label = thread.Agent.TryPickBetaManagedAgentsSessionThread(out var agent)
860 ? agent.Name
861 : thread.Agent.Json.GetProperty("type").GetString();
862 Console.WriteLine($"[{label}] {thread.Status.Raw()}");
859863 }
860864 ```
861865
from line 867
863867 threads := client.Beta.Sessions.Threads.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionThreadListParams{})
864868 for threads.Next() {
865869 thread := threads.Current()
866 fmt.Printf("[%s] %s\n", thread.Agent.Name, thread.Status)
870 label := cmp.Or(thread.Agent.Name, thread.Agent.Type)
871 fmt.Printf("[%s] %s\n", label, thread.Status)
867872 }
868873 if err := threads.Err(); err != nil {
869874 panic(err)
from line 877
872877
873878 ```java Java
874879 for (var thread : client.beta().sessions().threads().list(session.id()).autoPager()) {
875 var name = thread.agent().isAgent() ? thread.agent().asAgent().name() : "advisor";
876 IO.println("[" + name + "] " + thread.status());
880 var agent = thread.agent();
881 var label = agent.isAgent() ? agent.asAgent().name() : agent.type().asString();
882 IO.println("[" + label + "] " + thread.status());
877883 }
878884 ```
879885
880886 ```php PHP
881887 foreach ($client->beta->sessions->threads->list($session->id)->pagingEachItem() as $thread) {
882 echo "[{$thread->agent->name}] {$thread->status}\n";
888 $label = $thread->agent instanceof \Anthropic\Beta\Agents\BetaManagedAgentsAdvisor
889 ? $thread->agent->type
890 : $thread->agent->name;
891 echo "[{$label}] {$thread->status}\n";
883892 }
884893 ```
885894
886895 ```ruby Ruby
887896 client.beta.sessions.threads.list(session.id).auto_paging_each do |thread|
888 puts "[#{thread.agent.name}] #{thread.status}"
897 agent = thread.agent
898 label = agent.type == :advisor ? agent.type : agent.name
899 puts "[#{label}] #{thread.status}"
889900 end
890901 ```
891902 </CodeGroup>
from line 1476
14651476```
14661477
14671478Post `user.tool_confirmation` (with `tool_use_id`) or `user.custom_tool_result` (with `custom_tool_use_id`); the server routes the response to the correct thread automatically.
1479
1480The session goes `idle` only when no thread is `running`, so `session.status_idle` can arrive long after a subagent's call. You don't have to wait for it: send the `user.custom_tool_result` as soon as the cross-posted `agent.custom_tool_use` event arrives.
14681481
14691482Under `auto`, your `user.message` events can lead the server to allow a call it would otherwise deny. Nothing in a subagent's thread counts as your intent: your client posts no messages there, and the coordinator's messages to the subagent do not count. When the server denies a call under `auto`, nothing is cross-posted: the event and the error tool result appear only on the subagent's own [thread stream](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#session-thread-events), and the subagent keeps running.
14701483
managed-agents/sessions Changed · +9 / -9 lines
from line 490
490490 "agent": {
491491 "type": "agent_with_overrides",
492492 "id": "$AGENT_ID",
493 "model": {"id": "claude-sonnet-5"},
493 "model": {"id": "claude-sonnet-5-5"},
494494 "system": null
495495 },
496496 "environment_id": "$ENVIRONMENT_ID"
from line 506
506506 type: agent_with_overrides
507507 id: $AGENT_ID
508508 model:
509 id: claude-sonnet-5
509 id: claude-sonnet-5-5
510510 system: null
511511 environment_id: $ENVIRONMENT_ID
512512 YAML
from line 517
517517 agent={
518518 "type": "agent_with_overrides",
519519 "id": agent.id,
520 "model": {"id": "claude-sonnet-5"},
520 "model": {"id": "claude-sonnet-5-5"},
521521 "system": None, # clear the agent's system prompt for this session
522522 },
523523 environment_id=environment.id,
from line 532
532532 agent: {
533533 type: "agent_with_overrides",
534534 id: agent.id,
535 model: { id: "claude-sonnet-5" },
535 model: { id: "claude-sonnet-5-5" },
536536 system: null // clear the agent's system prompt for this session
537537 },
538538 environment_id: environment.id
from line 551
551551 ID = agent.ID,
552552 Model = new BetaManagedAgentsModelConfigParams
553553 {
554 ID = BetaManagedAgentsModel.ClaudeSonnet5,
554 ID = BetaManagedAgentsModel.ClaudeSonnet5_5,
555555 },
556556 System = null, // clear the agent's system prompt for this session
557557 },
from line 569
569569 Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
570570 ID: agent.ID,
571571 Model: anthropic.BetaManagedAgentsModelConfigParams{
572 ID: anthropic.BetaManagedAgentsModelClaudeSonnet5,
572 ID: anthropic.BetaManagedAgentsModelClaudeSonnet5_5,
573573 },
574574 // Clear the agent's system prompt for this session.
575575 System: param.Null[string](),
from line 591
591591 .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
592592 .id(agent.id())
593593 .model(BetaManagedAgentsModelConfigParams.builder()
594 .id(BetaManagedAgentsModel.CLAUDE_SONNET_5)
594 .id(BetaManagedAgentsModel.CLAUDE_SONNET_5_5)
595595 .build())
596596 .system((String) null) // clear the agent's system prompt for this session
597597 .build())
from line 606
606606 $overrides = BetaManagedAgentsAgentWithOverridesParams::with(
607607 id: $agent->id,
608608 type: 'agent_with_overrides',
609 model: ['id' => 'claude-sonnet-5'],
609 model: ['id' => 'claude-sonnet-5-5'],
610610 );
611611 // Clear the system prompt for this session. Array access is load-bearing here:
612612 // create() strips nulls from raw arrays and ::with() treats null args as omitted.
from line 628
628628 agent: Anthropic::Beta::BetaManagedAgentsAgentWithOverridesParams.new(
629629 type: :agent_with_overrides,
630630 id: agent.id,
631 model: {id: "claude-sonnet-5"},
631 model: {id: "claude-sonnet-5-5"},
632632 system_: nil
633633 ),
634634 environment_id: environment.id
models/fable-5-1/migration-guide Changed · +7 / -7 lines
from line 37
3737
3838## Migrating to Claude Fable 5.1 from Claude Fable 5
3939
40Migration is mostly drop-in. The API surface, limits, per-token pricing, tokenizer, always-on adaptive thinking, refusal handling, and `stop_details` categories all match Claude Fable 5. What changes: forced tool choice returns a 400 error, thinking blocks are preserved only for the model that produced them or a newer one and only in the conversation that produced them, cache reads cost less, and agent-loop behavior differs in three ways. The same changes apply to [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/fable-5-1/migration-guide#migrating-from-claude-mythos-5-to-claude-mythos-5-1), except the conversation check on thinking blocks, which Claude Mythos 5.1 doesn't run.
40Migration is mostly drop-in. The API surface, limits, per-token pricing, tokenizer, always-on adaptive thinking, refusal handling, and `stop_details` categories all match Claude Fable 5. What changes: forced tool choice returns a 400 error; only Claude Fable 5.1 and Claude Mythos 5.1 read Claude Fable 5.1's thinking blocks, and only in the conversation that produced them; cache reads cost less; and agent-loop behavior differs in three ways. The same changes apply to [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/fable-5-1/migration-guide#migrating-from-claude-mythos-5-to-claude-mythos-5-1), except the conversation check on thinking blocks, which Claude Mythos 5.1 doesn't run.
4141
4242### Update your model name
4343
from line 925
925925
926926 Keep the `role: "system"` message in the history on later requests, as with any other turn. Mid-conversation system messages need no beta header. `tool_choice: {"type": "none"}` still works for a turn that must not call tools.
927927
9282. **Thinking blocks are preserved only for the model that produced them, or a newer one:** Every `thinking` block records which model produced it. Claude Fable 5.1 reads its own blocks and those from Claude Mythos 5.1, Claude Opus 5, Claude Fable 5, Claude Mythos 5, and earlier Claude models. A conversation moving onto `claude-fable-5-1` from any of those keeps its earlier reasoning. The condition is one-way: apart from Claude Mythos 5.1, none of those models can read Claude Fable 5.1's blocks.
9282. **Only Claude Fable 5.1 and Claude Mythos 5.1 read Claude Fable 5.1's thinking blocks:** Every `thinking` block records which model produced it. Claude Fable 5.1 reads its own blocks and those from Claude Mythos 5.1, Claude Opus 5, Claude Fable 5, Claude Mythos 5, and earlier Claude models. A conversation moving onto `claude-fable-5-1` from any of those keeps its earlier reasoning. The condition is one-way: apart from Claude Mythos 5.1, none of those models can read Claude Fable 5.1's blocks.
929929
930 A conversation that ran on Claude Fable 5.1 can land on an older model through a router switch, a client-side retry, or a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback), including a [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). The API removes the blocks that model can't read before it sees them, the request succeeds, and you aren't billed for the dropped input tokens. The target model re-plans without that reasoning, which can raise cost and latency on the first turn after the switch. To see what was dropped, send the `thinking-binding-controls-2026-08-01` [beta header](https://platform.claude.com/docs/en/api/beta-headers): responses then carry an `input_transformations` array naming each dropped block with `reason: "model_binding_mismatch"`. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
930 A conversation that ran on Claude Fable 5.1 can land on another model, older or newer, through a router switch, a client-side retry, or a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback), including a [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). The API removes the blocks that model can't read before it sees them, the request succeeds, and you aren't billed for the dropped input tokens. The target model re-plans without that reasoning, which can raise cost and latency on the first turn after the switch. To see what was dropped, send the `thinking-binding-controls-2026-08-01` [beta header](https://platform.claude.com/docs/en/api/beta-headers): responses then carry an `input_transformations` array naming each dropped block with `reason: "model_binding_mismatch"`. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
931931
9329323. **Editing earlier turns invalidates thinking blocks:** Each `thinking` block from Claude Fable 5.1 is valid only against the `system` prompt, `tools`, and conversation history that preceded it. If Claude Code, claude.ai, [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), or the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) manages your conversation history, it already keeps that prefix intact. If your code builds the `messages` array itself, this item applies to you, and [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) is the full integration guide. Where the check is enforced, a request that sends the block back after any of those changed is rejected with a 400 error:
933933
from line 1502
15021502 ```
15031503 </CodeGroup>
15041504
1505 The value applies to the following user turn and every later turn until another `role: "system"` message changes it. Only the named levels are accepted (`low`, `medium`, `high`, `xhigh`, `max`), and the `mid-conversation-output-config-2026-07-01` beta header is required. See [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta).
1505 Placed between an `assistant` turn and the next `user` turn, as here, the message takes effect from that `user` turn. Placed directly after a `user` turn with new input, it sets the level for Claude's reply to that turn. A `user` turn that holds only tool results doesn't count as new input: the change waits for the next `user` turn with new input. The level then holds until another `role: "system"` message changes it. Only the named levels are accepted (`low`, `medium`, `high`, `xhigh`, `max`), and the `mid-conversation-output-config-2026-07-01` beta header is required. See [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta).
15061506
150715072. **Change instructions and tools with mid-conversation system messages:** To change instructions or tools partway through a session, append a [`role: "system"` message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages), with `tool_addition` and `tool_removal` blocks for tool changes (beta header `inline-tools-2026-09-15` on the Claude API). A `tool_addition` block can name a tool declared in `tools` at session start or [carry the tool's full definition](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta), so a tool that is unknown at session start doesn't need to be in `tools`. This preserves prompt cache hits on earlier turns and keeps the conversation history append-only. 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, and Google Cloud. The same message replaces forced `tool_choice` when a specific tool must run on the current turn (see [Breaking changes](https://platform.claude.com/docs/en/models/fable-5-1/migration-guide#fable-5-1-breaking-changes)). For a reminder that applies to one turn only, send it as a separate text-only `role: "system"` message with `clear_at: "next_user_message"` ([turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages), beta header `mid-conversation-system-clear-at-2026-08-21`) and leave it in the history: it stops rendering after the next user message and costs no tokens once cleared. A message that carries `tool_addition` or `tool_removal` blocks can't be turn-scoped.
15081508
from line 1522
15221522
15231523* Update the model name from `claude-fable-5` to `claude-fable-5-1` (or `claude-mythos-5` to `claude-mythos-5-1`).
15241524* Replace forced `tool_choice` (`{type: "any"}` or `{type: "tool", ...}`). It returns a 400 error. Use `{type: "auto"}` plus an explicit instruction and `strict: true` tools, or JSON outputs. Put the instruction in the `user` turn, or in a mid-conversation `role: "system"` message when your application requires the call.
1525* Keep passing `thinking` blocks back unchanged on every turn, including empty ones. Claude Fable 5.1 reads blocks from Claude Opus 5, Claude Fable 5, Claude Mythos 5, and earlier models. Moving a conversation from Claude Fable 5.1 to an earlier model drops its blocks (Claude Mythos 5.1 reads them).
1525* Keep passing `thinking` blocks back unchanged on every turn, including empty ones. Claude Fable 5.1 reads blocks from Claude Opus 5, Claude Fable 5, Claude Mythos 5, and earlier models. Moving a conversation from Claude Fable 5.1 to any model other than Claude Mythos 5.1 drops its blocks.
15261526* If your code builds the `messages` array itself, check whether it [edits earlier turns](https://platform.claude.com/docs/en/models/fable-5-1/migration-guide#fable-5-1-preserved-thinking): run a session with the `thinking-binding-controls-2026-08-01` beta header and `prefix_mismatch_behavior: "drop_block"`, log `input_transformations`, and fix every `prefix_binding_mismatch`. `model_binding_mismatch` entries after a model switch are expected.
15271527* Keep conversation history append-only: freeze `system` and `tools` at session start and move mid-session changes to `role: "system"` messages and `tool_addition` / `tool_removal` blocks, send per-turn reminders as turn-scoped system messages you never remove, trim context server-side or strip thinking blocks from any turns you carry across a client-side summary, and reference cross-turn files by `file_id`.
15281528* Pick a production `prefix_mismatch_behavior` (`"error"` by default, or `"drop_block"`) and monitor it. If you maintain a tool that others run with their own API key, test with the field set: new accounts are enforced by default even if yours isn't.
from line 1602
16021602
16031603[Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview) is the counterpart to Claude Fable 5.1 for organizations verified through Anthropic's verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842). Confirm that your organization has access to Claude Mythos 5.1 before you switch model IDs.
16041604
1605The API-level delta matches [Migrating to Claude Fable 5.1 from Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5-1/migration-guide#migrating-from-claude-fable-5-to-claude-fable-5-1): forced tool choice returns a 400 error, and thinking blocks are preserved only for the model that produced them or a newer one (Claude Mythos 5.1 reads Claude Mythos 5's blocks, not the reverse). Unlike Claude Fable 5.1, Claude Mythos 5.1 doesn't run the conversation check, so editing earlier turns doesn't [invalidate thinking blocks](https://platform.claude.com/docs/en/models/fable-5-1/migration-guide#fable-5-1-preserved-thinking), though it still restarts the prompt cache.
1605The API-level delta matches [Migrating to Claude Fable 5.1 from Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5-1/migration-guide#migrating-from-claude-fable-5-to-claude-fable-5-1): forced tool choice returns a 400 error, and only Claude Mythos 5.1 and Claude Fable 5.1 read Claude Mythos 5.1's thinking blocks (Claude Mythos 5.1 reads Claude Mythos 5's blocks, not the reverse). Unlike Claude Fable 5.1, Claude Mythos 5.1 doesn't run the conversation check, so editing earlier turns doesn't [invalidate thinking blocks](https://platform.claude.com/docs/en/models/fable-5-1/migration-guide#fable-5-1-preserved-thinking), though it still restarts the prompt cache.
16061606
16071607### Update your model name
16081608
models/fable-5-1/whats-new-fable-5-1 Changed · +5 / -5 lines
### Only Claude Fable 5.1 and Claude Mythos 5.1 read Claude Fable 5.1 thinking blocks ### Earlier models can't read Claude Fable 5.1 thinking blocks
from line 6
66
77Claude Fable 5.1 extends Claude Fable 5 at the same input and output prices, with cache reads at a quarter of the cost, and brings stronger long-running agentic coding, multistep research, and document, spreadsheet, and slide work. For most workloads, start with Claude Opus 5.5 (see [Choosing a model](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model)). Use Claude Fable 5.1 for demanding reasoning and long-horizon agentic work, or when your evals on Claude Opus 5.5 at higher effort still fall short. Claude Mythos 5.1 offers the same capabilities only to organizations verified through Anthropic's verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842).
88
9If you already call Claude Fable 5, three changes are breaking: [forced tool use returns an error](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#forced-tool-use-is-not-supported), [earlier models can't read its thinking blocks](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#thinking-blocks-are-tied-to-the-model-that-produced-them), and [editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#editing-earlier-turns-invalidates-thinking-blocks). Five are additive: [per-message effort](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#change-effort-mid-conversation-beta) (beta), [turn-scoped system messages](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#turn-scoped-system-messages-beta) (beta), [readable progress updates between tool calls](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#progress-updates-between-tool-calls-beta) (`display: "updates"`, beta), a [lower cache read price](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#pricing), and [content provenance](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#content-provenance).
9If you already call Claude Fable 5, three changes are breaking: [forced tool use returns an error](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#forced-tool-use-is-not-supported), [only Claude Fable 5.1 and Claude Mythos 5.1 can read Claude Fable 5.1's thinking blocks](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#thinking-blocks-are-tied-to-the-model-that-produced-them), and [editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#editing-earlier-turns-invalidates-thinking-blocks). Five are additive: [per-message effort](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#change-effort-mid-conversation-beta) (beta), [turn-scoped system messages](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#turn-scoped-system-messages-beta) (beta), [readable progress updates between tool calls](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#progress-updates-between-tool-calls-beta) (`display: "updates"`, beta), a [lower cache read price](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#pricing), and [content provenance](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#content-provenance).
1010
1111## Models
1212
from line 38
3838
3939Thinking is always on for these models, and a forced tool call would skip it. The model would write its working-out into the tool arguments instead, which lowers argument quality. For schema-valid JSON, keep `tool_choice: {"type": "auto"}` and set `strict: true` with [strict tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use), or move the schema to [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs). To make the model call a tool rather than reply in text, state in the prompt when the tool applies (for example, "Use the `get_weather` tool to answer"). Claude Fable 5.1 follows explicit tool instructions reliably.
4040
41### Earlier models can't read Claude Fable 5.1 thinking blocks
41### Only Claude Fable 5.1 and Claude Mythos 5.1 read Claude Fable 5.1 thinking blocks
4242
43Every thinking block records which model produced it, and it's preserved in one direction only: Claude Fable 5.1 reads earlier models' thinking blocks, and no earlier model reads Claude Fable 5.1's. A conversation that moves onto Claude Fable 5.1 (from Claude Opus 5, Claude Fable 5, or any earlier Claude model) keeps its reasoning. A conversation that moves from Claude Fable 5.1 to any of those models loses it for the turns that run there.
43Every thinking block records which model produced it. Claude Fable 5.1 reads earlier models' thinking blocks, but only Claude Fable 5.1 and Claude Mythos 5.1 read Claude Fable 5.1's. A conversation that moves onto Claude Fable 5.1 (from Claude Opus 5, Claude Fable 5, or any earlier Claude model) keeps its reasoning. A conversation that moves from Claude Fable 5.1 to any other model loses it for the turns that run there.
4444
4545When a request carries a block the target model can't read (a router or fallback that switches models mid-conversation, for example), the API drops the block before the model sees it. Dropped blocks don't count toward `input_tokens` and aren't billed. With the `thinking-binding-controls-2026-08-01` beta header, the drop is reported in a top-level `input_transformations` array. Without it, the drop is silent. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
4646
from line 413
413413| ---------- | --------------- | --------------- | ------------ | ---------- |
414414| $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok | $50 / MTok |
415415
416Cache reads (hits and refreshes) cost 0.025 times the base input price on these models, compared with 0.1 on other Claude models. Long agentic sessions that re-read a cached prefix pay a quarter of the Claude Fable 5 rate. Cache writes and the [512-token minimum cacheable prompt length](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations) are unchanged.
416Cache reads (hits and refreshes) cost 0.025 times the base input price on these models, compared with 0.05 on Claude Opus 5.5 and Claude Sonnet 5.5, and 0.1 on other Claude models. Long agentic sessions that re-read a cached prefix pay a quarter of the Claude Fable 5 rate. Cache writes and the [512-token minimum cacheable prompt length](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations) are unchanged.
417417
418418[Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) is $5 USD per million input tokens and $25 USD per million output tokens. See [Pricing](https://platform.claude.com/docs/en/about-claude/pricing) for data residency and tool pricing.
419419
models/haiku-4-5/overview Changed · +0 / -8 lines
from line 99
9999 <Card title="Extended thinking" icon="brain" href="https://platform.claude.com/docs/en/build-with-claude/extended-thinking">
100100 Claude Haiku 4.5 supports manual extended thinking with `budget_tokens`.
101101 </Card>
102
103 <Card title="Choosing a model" icon="scales" href="https://platform.claude.com/docs/en/about-claude/models/choosing-a-model">
104 When to start efficiency-first with Haiku and when to reach for a larger model.
105 </Card>
106
107 <Card title="Reduce latency" icon="gauge" href="https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency">
108 Techniques that pair well with a fast, low-cost model.
109 </Card>
110102</CardGroup>
111103
112104## Reference
models/haiku-5-5/migration-guide Changed · +15 / -8 lines
from line 1
11---
22title: Claude Haiku 5.5 migration guide
33url: https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide
4description: Switch to Claude Haiku 5.5 from earlier Haiku models with this migration guide. The guidance to enable Claude Haiku 5.5 includes the new model ID, each breaking change with the request before and after, and a checklist for each starting model.
4description: Switch to Claude Haiku 5.5 from earlier Haiku models with this migration guide. The guidance to enable Claude Haiku 5.5 includes the new model ID, settings that return errors, thinking changes, and a checklist for each starting model.
55---
66
77<Note>
from line 27
2727### Every starting model
2828
29291. Replace the model ID with the Claude Haiku 5.5 ID for your platform. See [Use the Claude Haiku 5.5 model ID](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#use-the-claude-haiku-5-5-model-id).
302. Recount your prompts, and revisit `max_tokens` limits and cost estimates, because the same text counts as more tokens. See [Recount tokens](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#recount-tokens).
302. Recount your prompts, and revisit `max_tokens` limits and cost estimates, because the same text counts as more tokens and large images count as more visual tokens. See [Recount tokens](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#recount-tokens).
31313. If your requests send `thinking: {"type": "enabled", "budget_tokens": N}`, change `thinking` to `{"type": "adaptive"}`. See [Configure thinking](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#configure-thinking).
32324. If your code reads the first content block as the answer, select blocks by `type` instead. See [Configure thinking](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#configure-thinking).
33335. Remove `temperature`, `top_p`, and `top_k` from your requests. See [Remove sampling parameters](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#remove-sampling-parameters).
34346. If your requests end `messages` with an assistant turn for the model to continue, end them with a user turn instead. See [Replace assistant prefill](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#replace-assistant-prefill).
357. If you use computer use on the Claude API or Google Cloud, move from `computer_20250124` to the `computer_toolset_20260801` toolset. See [Move computer use to the toolset](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#computer-use-toolset).
357. If you use computer use, replace `computer_20250124`: on the Claude API and Google Cloud, with the `computer_toolset_20260801` toolset; on Amazon Bedrock, with `computer_20251124` and the `computer-use-2025-11-24` beta header. See [Move computer use to the toolset](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#computer-use-toolset).
36368. If you replay stored conversations through a different account, replay each one through the account that produced it. See [Replay thinking blocks through the account that produced them](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#replay-thinking-blocks-through-the-producing-account).
37379. If your code changes `system`, `tools`, or earlier `messages` between requests in a conversation and sends thinking blocks back, keep the conversation append-only. See [Keep earlier turns unchanged](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#keep-earlier-turns-unchanged).
383810. Handle `stop_reason: "refusal"`. Claude Haiku 5.5 runs safety classifiers that can decline a request, and it has no server-side fallback. See [Safeguard refusals](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#safeguard-refusals).
3911. If you use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) (`output_config.format` or `strict: true` tools) on Amazon Bedrock, describe the format in the prompt or use a tool without `strict`, and validate the output in your code. Structured outputs aren't available for Claude Haiku 5.5 on Amazon Bedrock.
3940
4041If your organization has a [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models) commitment on Claude Haiku 4.5, plan capacity separately: Priority Tier is not supported on Claude Haiku 5.5.
4142
from line 70
6970* `usage` fields and [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) results are higher for the same text.
7071* A given number of tokens holds less text.
7172* A `max_tokens` limit tuned for Claude Haiku 4.5 may cut off equivalent output.
72* Cost estimates made from Claude Haiku 4.5's token counts need recomputing with Claude Haiku 5.5's counts and [prices](https://platform.claude.com/docs/en/about-claude/pricing).
73* Cost estimates made from Claude Haiku 4.5's token counts need recomputing with Claude Haiku 5.5's counts and [prices](https://platform.claude.com/docs/en/about-claude/pricing), including its higher prices for long prompts. See [Long context pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing).
7374
75Large images can also cost more tokens. Claude Haiku 5.5 uses the high-resolution image tier, which downscales images above 2,576 pixels on the long edge or 4,784 visual tokens. Claude Haiku 4.5 and earlier Haiku models use the standard tier, which downscales images above 1,568 pixels on the long edge or 1,568 visual tokens. An image of 2,000 by 1,500 pixels costs about 2.5 times as many visual tokens on Claude Haiku 5.5 as on Claude Haiku 4.5. See [Resolution and token cost](https://platform.claude.com/docs/en/build-with-claude/vision#evaluate-image-size).
76
7477Count your prompts with `model` set to `claude-haiku-5-5` rather than reusing counts measured on Claude Haiku 4.5.
7578
7679## Configure thinking
from line 107
104107
105108Thinking tokens count toward `max_tokens`, so a request with a small `max_tokens` can stop with `stop_reason: "max_tokens"` after a `thinking` block and before any text. If you set a small `max_tokens` for Claude Haiku 4.5, raise it to leave room for thinking, or choose a lower [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level.
106109
110Thinking blocks from earlier assistant turns stay in context and count as input tokens, where Claude Haiku 4.5 kept only the latest turn's. Multi-turn conversations therefore carry more input tokens than the tokenizer change alone explains. To remove older blocks, use [thinking block clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing). See [Thinking block preservation by model](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model).
111
107112By default, Claude Haiku 5.5 returns each `thinking` block with an empty `thinking` field and only a `signature`, where Claude Haiku 4.5 returned summarized thinking. To receive summarized thinking, set `thinking: {"type": "adaptive", "display": "summarized"}`.
108113
109114Claude Haiku 5.5 accepts a forced `tool_choice` (`any` or a named tool), but the response starts with the tool call and has no `thinking` block. To let the model think before it calls a tool, use `tool_choice: {"type": "auto"}` and say in the prompt when to use the tool.
110115
116Claude Haiku 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, so a conversation you switch from Claude Haiku 4.5 onto Claude Haiku 5.5 keeps its reasoning. It doesn't read blocks from Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, or any Claude Fable or Claude Mythos model; the API drops those without an error. On the Claude API and Google Cloud, Claude Opus 5.5 and Claude Sonnet 5.5 read Claude Haiku 5.5's blocks. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
117
111118## Remove sampling parameters
112119
113120Claude Haiku 4.5 accepts `temperature`, `top_p`, and `top_k`. On Claude Haiku 5.5, omit all three and use prompting to guide the model's behavior instead. If a request includes `temperature`, it must be `1`. If it includes `top_p`, it must be `0.99`, its default. Any other `temperature` or `top_p` value returns a 400 error, including a `top_p` of `1`. So does any `top_k` value, and so does a request that includes both `temperature` and `top_p`.
from line 123
116123
117124A prefill is a final assistant turn in `messages` that the model continues. Claude Haiku 4.5 accepts one when thinking is off. Claude Haiku 5.5 rejects it with a 400 error, even with thinking turned off. End `messages` with a user turn, and replace each prefill according to what it was for:
118125
119* **Output format:** use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs), or tools with enum fields for classification. On Claude in Amazon Bedrock, which doesn't support structured outputs, use tools.
126* **Output format:** use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs), or tools with enum fields for classification. On Amazon Bedrock, structured outputs aren't available for Claude Haiku 5.5. There, describe the format in the prompt or use a tool without `strict`, and validate the output in your code.
120127* **Preambles:** ask in the system prompt for a direct answer.
121128* **Continuations:** move them to the user message, for example "Your previous response was interrupted and ended with `[previous_response]`. Continue from where you left off."
122129* **Context reminders:** put them in the user turn.
from line 130
123130
124131## Move computer use to the toolset
125132
126Claude Haiku 4.5 supports [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) through the `computer_20250124` tool, with the `computer-use-2025-01-24` beta header. On the Claude API and Google Cloud, Claude Haiku 5.5 supports computer use only through the `computer_toolset_20260801` toolset, and a request that declares `computer_20250124` returns a 400 error.
133Claude Haiku 4.5 supports [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) through the `computer_20250124` tool, with the `computer-use-2025-01-24` beta header. On the Claude API and Google Cloud, Claude Haiku 5.5 supports computer use only through the `computer_toolset_20260801` toolset, and a request that declares `computer_20250124` returns a 400 error. On Amazon Bedrock, Claude Haiku 5.5 doesn't accept `computer_20250124` either; use the `computer_20251124` tool version with the `computer-use-2025-11-24` beta header.
127134
128To move an integration, drop the `computer-use-2025-01-24` beta header and replace the `tools` entry with `{"type": "computer_toolset_20260801"}`. Then make the other request and agent-loop changes in [Migrate from `computer_20251124`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124): dispatch on each member `tool_use` block's `name` and `toolset_name` rather than on `input.action`, handle every such block in a turn, and echo `toolset_name` on results. Zoom is on by default in the toolset; if your environment doesn't implement it, add `"configs": {"zoom": {"enabled": false}}`. If you send the `fine-grained-tool-streaming-2025-05-14` beta header, remove it. Alongside a toolset entry, it returns a 400 error. For other platforms, see the computer use tool's [Compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#compatibility) section.
135To move an integration to the toolset, drop the `computer-use-2025-01-24` beta header and replace the `tools` entry with `{"type": "computer_toolset_20260801"}`. Then make the other request and agent-loop changes in [Migrate from `computer_20251124`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124): dispatch on each member `tool_use` block's `name` and `toolset_name` rather than on `input.action`, handle every such block in a turn, and echo `toolset_name` on results. Zoom is on by default in the toolset; if your environment doesn't implement it, add `"configs": {"zoom": {"enabled": false}}`. If you send the `fine-grained-tool-streaming-2025-05-14` beta header, remove it. Alongside a toolset entry, it returns a 400 error. For other platforms, see the computer use tool's [Compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#compatibility) section.
129136
130137On the Claude API and Google Cloud, Claude Haiku 5.5 also supports the [browser use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) (`browser_toolset_20260801`) for tasks inside webpages. Claude Haiku 4.5 doesn't support it.
131138
from line 146
139146
140147## Migrating to Claude Haiku 5.5 from Claude Haiku 3.5 and earlier Haiku models
141148
142Claude Haiku 3.5 is retired on the Claude API and Amazon Bedrock, and Claude Haiku 3 is retired on the Claude API. Requests to a retired model fail. Google Cloud lists Claude Haiku 3.5 as deprecated and available only to existing customers. See [Model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations).
149Claude Haiku 3.5 is retired on the Claude API and Amazon Bedrock, and Claude Haiku 3 is retired on the Claude API and Google Cloud. Requests to a retired model fail. Google Cloud lists Claude Haiku 3.5 as deprecated and available only to existing customers. See [Model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations).
143150
144151From either model, first apply every preceding section, then these changes:
145152
models/haiku-5-5/overview Changed · +3 / -2 lines
from line 90
9090## Good to know
9191
9292* Adaptive thinking is on by default. Control thinking depth with the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort).
93* Omit `temperature`, `top_p`, and `top_k`, since a non-default value for any of them returns a 400 error.
93* Omit `temperature`, `top_p`, and `top_k`. See [Remove sampling parameters](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#remove-sampling-parameters) for the values that return a 400 error.
9494* On the [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing#extended-output-beta), Claude Haiku 5.5 supports up to 300k output tokens with the `output-300k-2026-03-24` beta header.
95* The minimum cacheable prompt length is 512 tokens. See [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations).
9596* Query limits and capabilities programmatically with the [Models API](https://platform.claude.com/docs/en/api/models/list).
9697
9798## Resources
from line 111
110111 </Card>
111112
112113 <Card title="Context windows" icon="stack" href="https://platform.claude.com/docs/en/build-with-claude/context-windows">
113 1M tokens. How the window is counted and managed.
114 How the context window is counted and managed.
114115 </Card>
115116</CardGroup>
116117
models/haiku-5-5/whats-new-haiku-5-5 Changed · +24 / -16 lines
### Earlier thinking blocks stay in context
from line 12
1212
1313Each row names one change, whether it is new, changed, or breaking, and what your code has to do.
1414
15| Change | Type | Action needed |
16| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
17| [Adaptive thinking and effort](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#adaptive-thinking-and-effort) | New | Optional: set `effort` to trade response quality against speed and cost. |
18| [Larger context window and output](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#larger-context-window-and-output) | New | None. Existing `max_tokens` values stay valid, but thinking tokens count toward them. |
19| [Browser use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) | New | None. Available on the Claude API and Google Cloud. |
20| [Safety classifiers can decline a request](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response) | New | Handle `stop_reason: "refusal"` in your client. Server-side fallback isn't available. |
21| [Manual extended thinking returns an error](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#configure-thinking) | Breaking | Replace `budget_tokens` with adaptive thinking. |
22| [Non-default sampling parameters return an error](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#remove-sampling-parameters) | Breaking | Omit `temperature`, `top_p`, and `top_k`. |
23| [Assistant message prefill returns an error](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#replace-assistant-prefill) | Breaking | End `messages` with a user turn. |
24| [Computer use needs the toolset on the Claude API and Google Cloud](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#computer-use-toolset) | Breaking | Replace `computer_20250124` with `computer_toolset_20260801`. |
25| [Changing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#keep-earlier-turns-unchanged) | Breaking | Keep conversations append-only if you send thinking blocks back. |
26| [Responses can begin with thinking blocks](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#responses-can-begin-with-thinking-blocks) | Changed | Select content blocks by `type`, not by position. |
27| [Thinking text is omitted by default](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#configure-thinking) | Changed | To receive summarized thinking, set `thinking.display` to `"summarized"`. |
28| [Same text counts as more tokens](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#same-text-counts-as-more-tokens) | Changed | Recount prompts and revisit `max_tokens` and cost estimates. |
29| [Replaying thinking blocks across accounts](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#replaying-thinking-blocks-across-accounts) | Changed | If you replay stored conversations through a different account, replay each through the account that produced it. |
15| Change | Type | Action needed |
16| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
17| [Adaptive thinking and effort](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#adaptive-thinking-and-effort) | New | Optional: set `effort` to trade response quality against speed and cost. |
18| [Larger context window and output](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#larger-context-window-and-output) | New | None. Existing `max_tokens` values stay valid, but thinking tokens count toward them. Long prompts are billed at higher prices; see [Long context pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing). |
19| [Browser use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) | New | None. Available on the Claude API and Google Cloud. |
20| [Safety classifiers can decline a request](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response) | New | Handle `stop_reason: "refusal"` in your client. Server-side fallback isn't available. |
21| [Manual extended thinking returns an error](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#configure-thinking) | Breaking | Replace `budget_tokens` with adaptive thinking. |
22| [Sampling parameters can return an error](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#remove-sampling-parameters) | Breaking | Omit `temperature`, `top_p`, and `top_k`. |
23| [Assistant message prefill returns an error](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#replace-assistant-prefill) | Breaking | End `messages` with a user turn. |
24| [`computer_20250124` returns an error on the Claude API, Google Cloud, and Amazon Bedrock](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#computer-use-toolset) | Breaking | Replace it with `computer_toolset_20260801` on the Claude API and Google Cloud, or with `computer_20251124` on Amazon Bedrock. |
25| [Structured outputs aren't available on Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | Breaking | On Amazon Bedrock, describe the format in the prompt or use a tool without `strict`, and validate the output in your code. |
26| [Changing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#keep-earlier-turns-unchanged) | Breaking | Keep conversations append-only if you send thinking blocks back. |
27| [Responses can begin with thinking blocks](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#responses-can-begin-with-thinking-blocks) | Changed | Select content blocks by `type`, not by position. |
28| [Thinking text is omitted by default](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#configure-thinking) | Changed | To receive summarized thinking, set `thinking.display` to `"summarized"`. |
29| [Same text counts as more tokens](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#same-text-counts-as-more-tokens) | Changed | Recount prompts and revisit `max_tokens` and cost estimates. |
30| [Replaying thinking blocks across accounts](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#replaying-thinking-blocks-across-accounts) | Changed | If you replay stored conversations through a different account, replay each through the account that produced it. |
31| [Earlier thinking blocks stay in context](https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5#earlier-thinking-blocks-stay-in-context) | Changed | Expect more input tokens in multi-turn conversations. To remove older blocks, use [thinking block clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing). |
32| [Shorter prompts can be cached](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations) | Changed | None. The minimum cacheable prompt length is 512 tokens, down from 4,096 on Claude Haiku 4.5, so a prompt in between that sets `cache_control` is cached on Claude Haiku 5.5. |
33| [Context awareness tags aren't injected](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-awareness) | Changed | To give the model an explicit budget for an agentic loop, use [task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets) (beta). |
3034
3135## New capabilities
3236
from line 40
3640
3741### Larger context window and output
3842
39Claude Haiku 5.5 has a 1M token [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) and returns up to 128k output tokens, up from 200k and 64k on Claude Haiku 4.5. Existing `max_tokens` values stay valid, but thinking tokens count toward `max_tokens`, so a small limit can stop after a `thinking` block and before any text. See [Configure thinking](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#configure-thinking).
43Claude Haiku 5.5 has a 1M token [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) and returns up to 128k output tokens, up from 200k and 64k on Claude Haiku 4.5. Existing `max_tokens` values stay valid, but thinking tokens count toward `max_tokens`, so a small limit can stop after a `thinking` block and before any text. See [Configure thinking](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#configure-thinking). Long prompts are billed at higher prices; see [Long context pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing).
4044
4145## Behavior changes
4246
from line 47
4347### Responses can begin with thinking blocks
4448
4549Adaptive thinking is on by default, so a response can begin with one or more `thinking` blocks even when the request doesn't mention thinking. Code that reads the first content block as the answer needs to select blocks by their `type` field. See [Configure thinking](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide#configure-thinking) in the migration guide.
50
51### Earlier thinking blocks stay in context
52
53Claude Haiku 5.5 keeps thinking blocks from all earlier assistant turns in context, and they count as input tokens. Claude Haiku 4.5 kept only the latest turn's blocks. Multi-turn conversations therefore carry more input tokens than the tokenizer change alone explains. To remove older blocks, use [thinking block clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing). See [Thinking block preservation by model](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model).
4654
4755### Same text counts as more tokens
4856
models/sonnet-5-5/whats-new-sonnet-5-5 Changed · +4 / -4 lines
from line 10
1010* [Forced tool use returns an error](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#forced-tool-use-is-not-supported).
1111* [Thinking blocks are tied to the model and the conversation](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#thinking-blocks-are-tied-to-the-model-that-produced-them).
1212* [On the Claude API and Google Cloud, the earlier `computer_20251124` computer use tool is not accepted](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#computer-20251124-is-not-supported).
13* [The advisor tool rejects Claude Opus 4.8, Claude Opus 4.7, and Claude Sonnet 5 as advisors](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#advisor-tool-pairings).
13* [The advisor tool rejects Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, and Claude Haiku 5.5 as advisors](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#advisor-tool-pairings).
1414
1515One more change alters the response shape without failing any request: [text between tool calls comes back in `thinking` blocks](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#text-between-tool-calls). An application that streams that text to its users goes quiet between tool calls until it sets a `display` value that returns the text, or turns off up-front thinking with `between_tools`.
1616
from line 48
4848
4949### Thinking blocks are tied to the model and the conversation
5050
51Every thinking block records which model produced it. Each model reads its own blocks and only some other models' blocks. Claude Sonnet 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, but not from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. On the Claude API and Google Cloud, Claude Opus 5.5 reads Claude Sonnet 5.5 thinking blocks; no other model does.
51Every thinking block records which model produced it. Each model reads its own blocks and only some other models' blocks. Claude Sonnet 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, and, on the Claude API and Google Cloud, from Claude Haiku 5.5, but not from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. On the Claude API and Google Cloud, Claude Opus 5.5 reads Claude Sonnet 5.5 thinking blocks; no other model does.
5252
5353So a conversation that moves from Claude Sonnet 5 onto Claude Sonnet 5.5, or from Claude Sonnet 5.5 up to Claude Opus 5.5 on the Claude API and Google Cloud, keeps its reasoning, and any other move away from Claude Sonnet 5.5 runs the turns after the switch without it. When a request carries a block the target model can't read, the API drops it before the model sees it: the request succeeds, and dropped blocks aren't billed. With the `thinking-binding-controls-2026-08-01` beta header, the drop is reported in a top-level `input_transformations` array. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
5454
from line 70
7070
7171### Some advisor tool pairings are not supported
7272
73With the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) (beta), a Claude Sonnet 5.5 executor needs Claude Mythos 5.1, Claude Fable 5.1, Claude Mythos 5, Claude Fable 5, Claude Opus 5.5, or Claude Opus 5 as its advisor, or Claude Sonnet 5.5 itself. Claude Opus 4.8, Claude Opus 4.7, and Claude Sonnet 5 advisors work with a Claude Sonnet 5 executor, but with a Claude Sonnet 5.5 executor they return a 400 `invalid_request_error`. Every advisor that Claude Sonnet 5.5 accepts returns its advice encrypted, as an `advisor_redacted_result` block, so your client can't read the advice text. See the advisor tool's [Model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) and [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants).
73With the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) (beta), a Claude Sonnet 5.5 executor needs Claude Mythos 5.1, Claude Fable 5.1, Claude Mythos 5, Claude Fable 5, Claude Opus 5.5, or Claude Opus 5 as its advisor, or Claude Sonnet 5.5 itself. Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, and Claude Haiku 5.5 advisors work with a Claude Sonnet 5 executor, but with a Claude Sonnet 5.5 executor they return a 400 `invalid_request_error`. Every advisor that Claude Sonnet 5.5 accepts returns its advice encrypted, as an `advisor_redacted_result` block, so your client can't read the advice text. See the advisor tool's [Model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) and [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants).
7474
7575## Feature support
7676
from line 160
1601602. Replace `tool_choice` types `any` and `tool` with `auto` plus [strict tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use).
1611613. Keep conversations append-only. A request that replays a Claude Sonnet 5.5 thinking block after an edit to earlier history can return a 400 error. See [Thinking blocks are tied to the model and the conversation](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#thinking-blocks-are-tied-to-the-model-that-produced-them).
1621624. If you use computer use through `computer_20251124` on the Claude API or Google Cloud, [move to the toolset](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124).
1635. If you use the advisor tool with a Claude Opus 4.8, Claude Opus 4.7, or Claude Sonnet 5 advisor, [switch to an advisor that Claude Sonnet 5.5 accepts](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#advisor-tool-pairings).
1635. If you use the advisor tool with a Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, or Claude Haiku 5.5 advisor, [switch to an advisor that Claude Sonnet 5.5 accepts](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#advisor-tool-pairings).
1641646. If your interface shows the text between tool calls, set `thinking.display` when you use adaptive thinking. With `between_tools`, the text comes back without it. See [Text between tool calls is returned in thinking blocks](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#text-between-tool-calls).
165165
166166The [migration guide](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide) has step-by-step instructions from Claude Sonnet 5 and earlier models, and the full checklist.
test-and-evaluate/strengthen-guardrails/handle-streaming-refusals Changed · +3 / -3 lines
from line 327
327327
328328* **Monitor for refusals:** Include **`stop_reason`: `refusal`** checks in your error handling
329329* **Reset automatically:** Implement automatic context reset when refusals are detected
330* **Fall back to another model:** Configure [server-side fallback or the SDK middleware](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) so refused requests are retried on another Claude model instead of surfacing a refusal to the user
331* **Redeem fallback credit on manual retries:** If you build the retry yourself, pass the refusal's [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) token so the retry doesn't pay the prompt-cache cost twice
330* **Fall back to another model:** Configure [server-side fallback or the SDK middleware](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) so refused requests are retried on another Claude model instead of surfacing a refusal to the user. Claude Haiku 5.5 has no server-side fallback, so set up its retry in your client
331* **Redeem fallback credit on manual retries:** If you build the retry yourself, pass the refusal's [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) token so the retry doesn't pay the prompt-cache cost twice. Claude Haiku 5.5 refusals carry no fallback credit
332332* **Provide custom messaging:** Create user-friendly messages for better UX when refusals occur
333333* **Track refusal patterns:** Monitor refusal frequency to identify potential issues with your prompts
334334
from line 338
338338
339339* **Refusals are responses, not errors.** A refusal arrives as a successful HTTP 200 response with `stop_reason`: `"refusal"`, so monitoring built only on error rates won't surface it. Track refusals as their own signal.
340340* **Refusals include structured detail.** On every model, a refusal also includes a `stop_details` object that identifies the policy category behind the decline. See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response) for the full response shape.
341* **Retry on a different model.** Re-sending a refused request to the same model usually results in another refusal. Instead of only resetting context, retry on a fallback model with [server-side fallback, the SDK middleware, or a manual retry](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback), and redeem [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) when you build the retry yourself.
341* **Retry on a different model.** Re-sending a refused request to the same model usually results in another refusal. Instead of only resetting context, retry on a fallback model with [server-side fallback, the SDK middleware, or a manual retry](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback), and redeem [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) when you build the retry yourself. Claude Haiku 5.5 has no server-side fallback, and its refusals carry no fallback credit, so set up its retry in your client.
342342* **Check batch results for refusals.** A refused request in a [Message Batch](https://platform.claude.com/docs/en/build-with-claude/batch-processing) is returned as a succeeded result with `stop_reason`: `"refusal"`, not as an errored result.
343343* **Centralize handling on `stop_reason`.** The API continues to consolidate refusal handling around `stop_reason`: `"refusal"`, so branch on the stop reason rather than on model-specific behavior.
344344
about-claude/glossary Changed · +1 / -1 lines
from line 62
6262
6363## Tokens
6464
65Tokens are the smallest individual units of a language model, and can correspond to words, subwords, characters, or even bytes (in the case of Unicode). For Claude, a token approximately represents 3.5 English characters, though the exact number can vary depending on the language used. Tokens are typically hidden when interacting with language models at the "text" level but become relevant when examining the exact inputs and outputs of a language model. When Claude is provided with text to evaluate, the text (consisting of a series of characters) is encoded into a series of tokens for the model to process. Larger tokens enable data efficiency during inference and pretraining (and are used when possible), while smaller tokens allow a model to handle uncommon or never-before-seen words. The choice of tokenization method can impact the model's performance, vocabulary size, and ability to handle out-of-vocabulary words.
65Tokens are the smallest individual units of a language model, and can correspond to words, subwords, characters, or even bytes (in the case of Unicode). For Claude, the number of characters a token represents depends on the model and the language. Claude 4.7 and later models and Claude Mythos Preview use a newer tokenizer that produces approximately 30 percent more tokens for the same text than earlier models, on which a token represents approximately 3.5 English characters. To get exact counts, use [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) with the model you plan to use. Tokens are typically hidden when interacting with language models at the "text" level but become relevant when examining the exact inputs and outputs of a language model. When Claude is provided with text to evaluate, the text (consisting of a series of characters) is encoded into a series of tokens for the model to process. Larger tokens enable data efficiency during inference and pretraining (and are used when possible), while smaller tokens allow a model to handle uncommon or never-before-seen words. The choice of tokenization method can impact the model's performance, vocabulary size, and ability to handle out-of-vocabulary words.
6666
agents-and-tools/mcp-connector Changed · +0 / -2 lines
from line 9
99 supportedPlatforms:
1010 Claude API: beta
1111 Claude Platform on AWS: beta
12 Amazon Bedrock: not available
13 Google Cloud: not available
1412 Microsoft Foundry: beta
1513---
1614
agents-and-tools/tool-use/code-execution-tool Changed · +0 / -2 lines
from line 25
2525 supportedPlatforms:
2626 Claude API: ga
2727 Claude Platform on AWS: ga
28 Amazon Bedrock: not available
29 Google Cloud: not available
3028 Microsoft Foundry:
3129 availability: ga
3230 note: On [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), code execution requires a [Hosted on Anthropic deployment](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
agents-and-tools/tool-use/programmatic-tool-calling Changed · +0 / -2 lines
from line 24
2424 supportedPlatforms:
2525 Claude API: ga
2626 Claude Platform on AWS: ga
27 Amazon Bedrock: not available
28 Google Cloud: not available
2927 Microsoft Foundry:
3028 availability: ga
3129 note: On [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), programmatic tool calling requires a [Hosted on Anthropic deployment](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
agents-and-tools/tool-use/tool-search-tool Changed · +1 / -0 lines
from line 48
4848| Claude Opus 5.5 (claude-opus-5-5) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
4949| Claude Opus 5 (claude-opus-5) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
5050| Claude Sonnet 5.5 (claude-sonnet-5-5) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
51| Claude Sonnet 5 (claude-sonnet-5) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
5152| Claude Haiku 5.5 (claude-haiku-5-5) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
5253| Claude Opus 4.8 (claude-opus-4-8) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
5354| Claude Opus 4.7 (claude-opus-4-7) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
api/beta/agents/archive Changed · +2 / -0 lines
from line 17
1717
1818## Headers
1919
20- `"anthropic-version": optional string`
21
2022- `"anthropic-beta": optional array of AnthropicBeta`
2123
2224 Optional header to specify the beta version(s) you want to use.
api/beta/agents/create Changed · +2 / -0 lines
from line 11
1111
1212## Headers
1313
14- `"anthropic-version": optional string`
15
1416- `"anthropic-beta": optional array of AnthropicBeta`
1517
1618 Optional header to specify the beta version(s) you want to use.
api/beta/agents/list Changed · +2 / -0 lines
from line 39
3939
4040## Headers
4141
42- `"anthropic-version": optional string`
43
4244- `"anthropic-beta": optional array of AnthropicBeta`
4345
4446 Optional header to specify the beta version(s) you want to use.
api/beta/agents/retrieve Changed · +2 / -0 lines
from line 25
2525
2626## Headers
2727
28- `"anthropic-version": optional string`
29
2830- `"anthropic-beta": optional array of AnthropicBeta`
2931
3032 Optional header to specify the beta version(s) you want to use.
api/beta/agents/update Changed · +2 / -0 lines
from line 17
1717
1818## Headers
1919
20- `"anthropic-version": optional string`
21
2022- `"anthropic-beta": optional array of AnthropicBeta`
2123
2224 Optional header to specify the beta version(s) you want to use.