Messages changedapi/beta/messages
Recorded here
Lines+185added
Lines−185removed
From line
13
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits29to this page, all time
The whole hunk
from line 13, old and new numbered
/
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 13
1313
1414The Messages API can be used for either single queries or stateless multi-turn conversations.
1515
16Learn more about the Messages API in our [user guide](https://platform.claude.com/docs/en/get-started)
16Learn more about the Messages API in our [user guide](https://platform.claude.com/docs/en/get-started?sdk_languages=http)
1717
1818### Headers
1919
from line 21
2121
2222 The version of the Claude API you want to use.
2323
24 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
24 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
2525
2626- `"anthropic-beta": optional array of AnthropicBeta`
2727
from line 147
147147
148148 Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
149149
150 Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.
150 Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http#pre-warming-the-cache) without generating a response.
151151
152 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
152 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview?sdk_languages=http) for details.
153153
154154 minimum: 0
155155
from line 161
161161
162162 Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
163163
164 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors#prefill-not-supported).
164 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors?sdk_languages=http#prefill-not-supported).
165165
166166 Example with a single `user` message:
167167
from line 198
198198 {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
199199 ```
200200
201 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
201 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages?sdk_languages=http).
202202
203 Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
203 Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=http#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
204204
205205 There is a limit of 100,000 messages in a single request.
206206
from line 233
233233 - `5m`: 5 minutes
234234 - `1h`: 1 hour
235235
236 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
236 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.
237237
238238 - `"5m"`
239239
from line 3762
37623762
37633763- `fallbacks: optional BetaFallbacksParam or null`
37643764
3765 Opt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order: if the first entry also declines, the second is tried, and so on. Some models don't support fallbacks; on those models, a list of fallback models returns a 400 error. See [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). The string "default" requests the requested model's server-defined default fallback configuration. On a model that doesn't support fallbacks, the request runs on the requested model alone, so a declined request stays declined.
3765 Opt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order: if the first entry also declines, the second is tried, and so on. Some models don't support fallbacks; on those models, a list of fallback models returns a 400 error. See [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback?sdk_languages=http#server-side-fallback). The string "default" requests the requested model's server-defined default fallback configuration. On a model that doesn't support fallbacks, the request runs on the requested model alone, so a declined request stays declined.
37663766
37673767 - `array of BetaFallbackParam`
37683768
from line 3794
37943794
37953795 - `format: optional BetaJSONOutputFormat or null`
37963796
3797 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
3797 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=http)
37983798
37993799 - `type: "json_schema"`
38003800
from line 3842
38423842
38433843 Must be ≥1024 and less than `max_tokens`.
38443844
3845 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
3845 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
38463846
38473847 minimum: 1024
38483848
from line 3860
38603860
38613861 - `display: optional "summarized" or "omitted" or "updates" or null`
38623862
3863 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
3863 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=http#controlling-thinking-display).
38643864
38653865 - `"summarized"`
38663866
from line 3886
38863886
38873887 - `display: optional "summarized" or "omitted" or "updates" or null`
38883888
3889 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
3889 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=http#controlling-thinking-display).
38903890
38913891 - `"summarized"`
38923892
from line 3940
39403940
39413941 Determines whether to use priority capacity (if available) or standard capacity for this request.
39423942
3943 Anthropic offers different levels of service for your API requests. See [service-tiers](https://platform.claude.com/docs/en/api/service-tiers) for details.
3943 Anthropic offers different levels of service for your API requests. See [service-tiers](https://platform.claude.com/docs/en/api/service-tiers?sdk_languages=http) for details.
39443944
39453945 - `"auto"`
39463946
from line 3966
39663966
39673967 Whether to incrementally stream the response using server-sent events. When `true`, SDKs return a raw event stream.
39683968
3969 In the TypeScript, Python and Ruby SDKs, the recommended way to stream is `messages.stream()`. It sets `stream` for you and accumulates the events into the final message. See [Streaming with SDKs](https://platform.claude.com/docs/en/build-with-claude/streaming#streaming-with-sdks) for an example in each language.
3969 In the TypeScript, Python and Ruby SDKs, the recommended way to stream is `messages.stream()`. It sets `stream` for you and accumulates the events into the final message. See [Streaming with SDKs](https://platform.claude.com/docs/en/build-with-claude/streaming?sdk_languages=http#streaming-with-sdks) for an example in each language.
39703970
39713971- `system: optional string or array of BetaTextBlockParam`
39723972
39733973 System prompt.
39743974
3975 A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).
3975 A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=http#give-claude-a-role).
39763976
39773977 - `string`
39783978
from line 3996
39963996
39973997 With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit.
39983998
3999 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#configuring-thinking) for each model's behavior.
3999 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=http#configuring-thinking) for each model's behavior.
40004000
40014001 - `BetaThinkingConfigEnabled object`
40024002
from line 4062
40624062
40634063 If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks.
40644064
4065 There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)).
4065 There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools?sdk_languages=http), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool?sdk_languages=http)).
40664066
40674067 Each tool definition includes:
40684068
from line 4118
41184118
41194119 Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output.
41204120
4121 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
4121 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview?sdk_languages=http) for more details.
41224122
41234123 - `BetaTool object`
41244124
from line 4205
42054205
42064206 **Deprecated**
42074207
4208 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
4208 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=http)
42094209
42104210 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
42114211
from line 4486
44864486
44874487 This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact.
44884488
4489 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
4489 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
44904490
44914491 - `thinking: string`
44924492
from line 4504
45044504
45054505 Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation.
45064506
4507 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details.
4507 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http#redacted-thinking-blocks) for details.
45084508
45094509 - `BetaToolUseBlock object`
45104510
from line 5310
53105310 - `5m`: 5 minutes
53115311 - `1h`: 1 hour
53125312
5313 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
5313 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.
53145314
53155315 - `"5m"`
53165316
from line 7162
71627162
71637163 - `"code_execution_20250825"`
71647164
7165 - `"code_execution_20260120"`
7166
7167 - `"code_execution_20260521"`
7168
7169 - `cache_control: optional BetaCacheControlEphemeral or null`
7170
7171 Create a cache control breakpoint at this content block.
7172
7173 - `defer_loading: optional boolean`
7174
7175 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
7176
7177 - `strict
7165 - `"code_exe
No line in this hunk matches that.