Create a Message changedapi/beta/messages/create
Recorded here
Lines+27added
Lines−27removed
From line
11
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 11, 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 11
1111
1212The Messages API can be used for either single queries or stateless multi-turn conversations.
1313
14Learn more about the Messages API in our [user guide](https://platform.claude.com/docs/en/get-started)
14Learn more about the Messages API in our [user guide](https://platform.claude.com/docs/en/get-started?sdk_languages=http)
1515
1616## Headers
1717
from line 19
1919
2020 The version of the Claude API you want to use.
2121
22 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
22 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
2323
2424- `"anthropic-beta": optional array of AnthropicBeta`
2525
from line 145
145145
146146 Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
147147
148 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.
148 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.
149149
150 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
150 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.
151151
152152 minimum: 0
153153
from line 159
159159
160160 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.
161161
162 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).
162 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).
163163
164164 Example with a single `user` message:
165165
from line 196
196196 {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
197197 ```
198198
199 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
199 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages?sdk_languages=http).
200200
201 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.
201 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.
202202
203203 There is a limit of 100,000 messages in a single request.
204204
from line 231
231231 - `5m`: 5 minutes
232232 - `1h`: 1 hour
233233
234 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
234 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.
235235
236236 - `"5m"`
237237
from line 3760
37603760
37613761- `fallbacks: optional BetaFallbacksParam or null`
37623762
3763 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.
3763 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.
37643764
37653765 - `array of BetaFallbackParam`
37663766
from line 3792
37923792
37933793 - `format: optional BetaJSONOutputFormat or null`
37943794
3795 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
3795 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)
37963796
37973797 - `type: "json_schema"`
37983798
from line 3840
38403840
38413841 Must be ≥1024 and less than `max_tokens`.
38423842
3843 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
3843 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
38443844
38453845 minimum: 1024
38463846
from line 3858
38583858
38593859 - `display: optional "summarized" or "omitted" or "updates" or null`
38603860
3861 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).
3861 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).
38623862
38633863 - `"summarized"`
38643864
from line 3884
38843884
38853885 - `display: optional "summarized" or "omitted" or "updates" or null`
38863886
3887 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).
3887 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).
38883888
38893889 - `"summarized"`
38903890
from line 3938
39383938
39393939 Determines whether to use priority capacity (if available) or standard capacity for this request.
39403940
3941 Anthropic offers different levels of service for your API requests. See [service-tiers](https://platform.claude.com/docs/en/api/service-tiers) for details.
3941 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.
39423942
39433943 - `"auto"`
39443944
from line 3964
39643964
39653965 Whether to incrementally stream the response using server-sent events. When `true`, SDKs return a raw event stream.
39663966
3967 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.
3967 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.
39683968
39693969- `system: optional string or array of BetaTextBlockParam`
39703970
39713971 System prompt.
39723972
3973 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).
3973 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).
39743974
39753975 - `string`
39763976
from line 3994
39943994
39953995 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.
39963996
3997 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.
3997 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.
39983998
39993999 - `BetaThinkingConfigEnabled object`
40004000
from line 4060
40604060
40614061 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.
40624062
4063 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)).
4063 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)).
40644064
40654065 Each tool definition includes:
40664066
from line 4116
41164116
41174117 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.
41184118
4119 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
4119 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview?sdk_languages=http) for more details.
41204120
41214121 - `BetaTool object`
41224122
from line 4203
42034203
42044204 **Deprecated**
42054205
4206 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
4206 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=http)
42074207
42084208 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
42094209
from line 4484
44844484
44854485 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.
44864486
4487 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
4487 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
44884488
44894489 - `thinking: string`
44904490
from line 4502
45024502
45034503 Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation.
45044504
4505 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details.
4505 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http#redacted-thinking-blocks) for details.
45064506
45074507 - `BetaToolUseBlock object`
45084508
from line 5308
53085308 - `5m`: 5 minutes
53095309 - `1h`: 1 hour
53105310
5311 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
5311 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.
53125312
53135313 - `"5m"`
53145314
from line 7160
71607160
71617161 - `"code_execution_20250825"`
71627162
7163 - `"code_execution_20260120"`
7164
7165 - `"code_execution_20260521"`
7166
7167 - `cache_control: optional BetaCacheControlEphemeral or null`
7168
7169 Create a cache control breakpoint at this content block.
7170
7171 - `defer_loading: optional boolean`
7172
7173 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
7174
7175 - `strict:
7163 - `"code_exec
No line in this hunk matches that.