Home Docs Claude Developer Platform 12 Oct 2026

One change · api

Messages changedapi/messages

Recorded here 12 Oct 2026 06:37 UTC

Lines+138added

Lines−138removed

From line 13 where the diff opens

First seen 14 Aug 2026 this site's first read of the page

Recorded edits24to this page, all time

The whole hunk

from line 13, old and new numbered

lines

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-user-profile-id": optional string`

2727

from line 41

4141

4242 Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.

4343

44 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.

44 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.

4545

46 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.

46 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.

4747

4848 minimum: 0

4949

from line 55

5555

5656 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.

5757

58 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).

5959

6060 Example with a single `user` message:

6161

from line 92

9292 {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}

9393 ```

9494

95 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).

95 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages?sdk_languages=http).

9696

97 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.

97 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.

9898

9999 There is a limit of 100,000 messages in a single request.

100100

from line 127

127127 - `5m`: 5 minutes

128128 - `1h`: 1 hour

129129

130 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.

130 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.

131131

132132 - `"5m"`

133133

from line 1257

12571257

12581258 - `format: optional JSONOutputFormat or null`

12591259

1260 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

1260 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)

12611261

12621262 - `type: "json_schema"`

12631263

from line 1269

12691269

12701270 Determines whether to use priority capacity (if available) or standard capacity for this request.

12711271

1272 Anthropic offers different levels of service for your API requests. See [service-tiers](https://platform.claude.com/docs/en/api/service-tiers) for details.

1272 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.

12731273

12741274 - `"auto"`

12751275

from line 1287

12871287

12881288 Whether to incrementally stream the response using server-sent events. When `true`, SDKs return a raw event stream.

12891289

1290 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.

1290 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.

12911291

12921292- `system: optional string or array of TextBlockParam`

12931293

12941294 System prompt.

12951295

1296 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).

12971297

12981298 - `string`

12991299

from line 1317

13171317

13181318 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.

13191319

1320 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.

13211321

13221322 - `ThinkingConfigEnabled object`

13231323

from line 1329

13291329

13301330 Must be ≥1024 and less than `max_tokens`.

13311331

1332 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

1332 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.

13331333

13341334 minimum: 1024

13351335

13361336 - `display: optional "summarized" or "omitted" or null`

13371337

1338 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).

13391339

13401340 - `"summarized"`

13411341

from line 1355

13551355

13561356 - `display: optional "summarized" or "omitted" or null`

13571357

1358 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).

13591359

13601360 - `"summarized"`

13611361

from line 1417

14171417

14181418 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.

14191419

1420 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)).

1420 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)).

14211421

14221422 Each tool definition includes:

14231423

from line 1473

14731473

14741474 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.

14751475

1476 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.

1476 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview?sdk_languages=http) for more details.

14771477

14781478 - `Tool object`

14791479

from line 3328

33283328

33293329 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.

33303330

3331 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

3331 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.

33323332

33333333 - `thinking: string`

33343334

from line 3346

33463346

33473347 Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation.

33483348

3349 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details.

3349 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http#redacted-thinking-blocks) for details.

33503350

33513351 - `ToolUseBlock object`

33523352

from line 4048

40484048

40494049 - `"reasoning_extraction"`

40504050

4051 The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking).

40524052

40534053 - `"general_harms"`

40544054

from line 4522

45224522

45234523The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it.

45244524

4525Learn more about token counting in our [user guide](https://platform.claude.com/docs/en/build-with-claude/token-counting)

4525Learn more about token counting in our [user guide](https://platform.claude.com/docs/en/build-with-claude/token-counting?sdk_languages=http)

45264526

45274527### Headers

45284528

from line 4530

45304530

45314531 The version of the Claude API you want to use.

45324532

4533 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).

4533 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).

45344534

45354535- `"anthropic-user-profile-id": optional string`

45364536

from line 4552

45524552

45534553 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.

45544554

4555 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).

45564556

45574557 Example with a single `user` message:

45584558

from line 4589

45894589 {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}

45904590 ```

45914591

4592 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).

4592 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages?sdk_languages=http).

45934593

4594 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.

4594 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.

45954595

45964596 There is a limit of 100,000 messages in a single request.

45974597

from line 4624

46244624 - `5m`: 5 minutes

46254625 - `1h`: 1 hour

46264626

4627 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.

4627 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.

46284628

46294629 - `"5m"`

46304630

from line 5688

56885688

56895689 - `format: optional JSONOutputFormat or null`

56905690

5691 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

5691 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)

56925692

56935693 - `type: "json_schema"`

56945694

from line 5700

57005700

57015701 System prompt.

57025702

5703 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).

57045704

57055705 - `string`

57065706

from line 5724

57245724

57255725 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.

57265726

5727 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.

57285728

57295729 - `ThinkingConfigEnabled object`

57305730

from line 5736

57365736

57375737 Must be ≥1024 and less than `max_tokens`.

57385738

5739 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

5739 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.

57405740

57415741 minimum: 1024

57425742

57435743 - `display: optional "summarized" or "omitted" or null`

57445744

5745 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).

57465746

57475747 - `"summarized"`

57485748

from line 5762

57625762

57635763 - `display: optional "summarized" or "omitted" or null`

57645764

5765 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).

57665766

57675767 - `"summarized"`

57685768

from line 5824

58245824

58255825 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.

58265826

5827 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)).

5827 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)).

58285828

58295829 Each tool definition includes:

58305830

from line 5880

58805880

58815881 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.

58825882

5883 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.

5883 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview?sdk_languages=http) for more details.

58845884

58855885 - `Tool object`

58865886

from line 7719

77197719 - `5m`: 5 minutes

77207720 - `1h`: 1 hour

77217721

7722 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.

7722 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.

77237723

77247724 - `"5m"`

77257725

from line 8575

85758575

85768576 - `text: string`

85778577

8578 The key or chord to hold.

8579

8580 - `tab_id: optional string or null`

8581

8582 Tab to act on. Defaults to the active tab when omitted.

8583

8584 - `name: "hold_key"`

8585

8586 - `toolset_name: "browser"`

8587

8588### Browser Hover Config

8589

8590- `BrowserHoverConfig object`

8591

8592 `hover`'s config overrides.

8593

8594 - `defer_loading: optional boolean or null`

8595

8596 Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

8597

8598 - `enabled: optional boolean or null`

8599

8600 Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

8601

8602### Browser Hover Input

8603

8604- `BrowserHoverInput object`

8605

8606 Move the cursor to a coordinate or ele

8578 The key or chord to ho

This page’s history 24 edits

21 Oct 2026 +224 −0
21 Oct 2026 +3 −3
16 Oct 2026 +80 −1
12 Oct 2026 +4 −4
12 Oct 2026 +138 −138 · this one
9 Oct 2026 +28 −64

The page’s own history →

Where it came from

The captureapi
Upstream pageplatform.claude.com

Around it

Every changethe ledger
That day12 Oct 2026