Messages schemas

Common schema definitions referenced by the Messages endpoints. For operation-specific tool definitions, follow the schema links on each endpoint page.

Schemas

Anthropic Base64 Source Param

Inline base64-encoded media.

Field	Type	Required	Description
`type`	`enum ('base64')`	No
`media_type`	`string`	Yes	MIME type of the data, such as `image/png` or `application/pdf`.
`data`	`string`	Yes	Base64-encoded bytes.

Anthropic Cache Control Ephemeral Param

Prompt-cache breakpoint. Accepted to improve cache hit rates. Only the 5m TTL is supported.

Field	Type	Required	Description
`type`	`enum ('ephemeral')`	Yes
`ttl`	`enum ('5m')`	No

Anthropic Citations Config Param

Document citation settings. Enabling citations is not supported.

Field	Type	Required	Description
`enabled`	`enum ('false')`	No

Anthropic Messages content block. Supported block types are text, image, video (Meta extension), document, tool_use, tool_result, server_tool_use, thinking, and redacted_thinking. cache_control prompt-cache controls are accepted to improve cache hit rates. Unsupported block types return an invalid_request_error.

Field	Type	Required	Description
`type`	`string`	Yes	Content block discriminator, such as `text`, `image`, `video`, `document`, `tool_use`, or `tool_result`.

Anthropic Content Block Param

Input content block. A block type that a role does not support returns an invalid_request_error.

Anthropic Content Source Block Param

A block of an inline-content document.

Type: AnthropicContentSourceTextBlockParam | AnthropicContentSourceOtherBlockParam

Anthropic Content Source Other Block Param

Any other block of an inline-content document, passed as its JSON text.

Field	Type	Required	Description
`type`	`string`	Yes	Any block type except `text`.

Anthropic Content Source Param

Document built from inline content blocks.

Field	Type	Required	Description
`type`	`enum ('content')`	No
`content`	`string` \| array of `AnthropicContentSourceBlockParam`	Yes	A string, or an array of content blocks. Non-text blocks are passed as their JSON text.

Anthropic Content Source Text Block Param

A text block of an inline-content document.

Field	Type	Required	Description
`type`	`enum ('text')`	Yes
`text`	`string`	Yes

Anthropic Count Tokens Request

Field	Type	Required	Description
`model`	`string`	Yes	(minLength: 1)
`messages`	array of `AnthropicInputMessage`	Yes	(minItems: 1)
`system`	`string` \| array of `AnthropicSystemTextBlockParam`	No
`tools`	array of `AnthropicTool`	No
`tool_choice`	`AnthropicToolChoice`	No
`metadata`	`AnthropicMetadataParam`	No
`temperature`	`number` \| `null`	No	(minimum: 0, maximum: 1)
`top_p`	`number` \| `null`	No	(minimum: 0, maximum: 1)
`thinking`	`AnthropicThinkingConfigParam`	No
`service_tier`	`enum ('auto', 'standard_only')`	No
`cache_control`	`AnthropicCacheControlEphemeralParam`	No
`output_config`	`AnthropicOutputConfig`	No
`max_tokens`		No	Ignored.
`stream`		No	Ignored.

Anthropic Count Tokens Response

Field	Type	Required	Description
`input_tokens`	`integer`	Yes	Number of input tokens in the supplied Messages request.

Anthropic Custom Tool Param

A developer tool. type is omitted or custom.

Field	Type	Required	Description
`type`	`enum ('custom')`	No
`name`	`string`	Yes
`description`	`string` \| `null`	No
`input_schema`	`object` \| `null`	No	JSON Schema for the tool's input.
`parameters`		No	Parameter schema, read only for the client tool search tool named `ToolSearch`.
`strict`	`boolean` \| `null`	No
`defer_loading`	`boolean` \| `null`	No
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Direct Caller Param

The model invoked the tool directly.

Field	Type	Required	Description
`type`	`enum ('direct')`	Yes

Anthropic Document Block Param

Document input.

Field	Type	Required
`type`	`enum ('document')`	No
`source`	`AnthropicDocumentSourceParam`	Yes
`title`	`string` \| `null`	No
`context`	`string` \| `null`	No
`citations`	`AnthropicCitationsConfigParam`	No
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Document Source Param

Document source.

Type: AnthropicBase64SourceParam | AnthropicPlainTextSourceParam | AnthropicContentSourceParam | AnthropicUrlSourceParam | AnthropicFileSourceParam

Anthropic File Source Param

Media referenced by an uploaded file ID.

Field	Type	Required	Description
`type`	`enum ('file')`	No
`file_id`	`string`	Yes

Anthropic Image Block Param

Image input.

Field	Type	Required
`type`	`enum ('image')`	No
`source`	`AnthropicMediaSourceParam`	Yes
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Input Message

Anthropic Messages input message.

Field	Type	Required	Description
`role`	`enum ('user', 'assistant', 'system', 'developer')`	Yes
`content`	`string` \| array of `AnthropicContentBlockParam`	Yes

Anthropic Json Output Format

Anthropic JSON structured-output format.

Field	Type	Required	Description
`type`	`enum ('json_schema')`	Yes
`schema`	`object`	Yes

Anthropic Media Source Param

Image or video source.

Type: AnthropicBase64SourceParam | AnthropicUrlSourceParam | AnthropicFileSourceParam

Anthropic Message

Anthropic-compatible assistant message response.

Field	Type	Required
`id`	`string`	Yes
`type`	`enum ('message')`	Yes
`role`	`enum ('assistant')`	Yes
`content`	array of `AnthropicContentBlock`	Yes
`model`	`string`	Yes
`stop_reason`	`enum ('end_turn', 'max_tokens', 'stop_sequence', 'tool_use', 'pause_turn', 'refusal')`	Yes
`stop_sequence`	`string` \| `null`	Yes
`usage`	`AnthropicUsage`	Yes

Anthropic Message Request

Field	Type	Required	Description
`model`	`string`	Yes	(minLength: 1)
`messages`	array of `AnthropicInputMessage`	Yes	(minItems: 1)
`system`	`string` \| array of `AnthropicSystemTextBlockParam`	No
`tools`	array of `AnthropicTool`	No
`tool_choice`	`AnthropicToolChoice`	No
`metadata`	`AnthropicMetadataParam`	No
`temperature`	`number` \| `null`	No	(minimum: 0, maximum: 1)
`top_p`	`number` \| `null`	No	(minimum: 0, maximum: 1)
`thinking`	`AnthropicThinkingConfigParam`	No
`service_tier`	`enum ('auto', 'standard_only')`	No
`cache_control`	`AnthropicCacheControlEphemeralParam`	No
`output_config`	`AnthropicOutputConfig`	No
`max_tokens`	`integer`	Yes	(minimum: 1)
`stream`	`boolean`	No	(default: false)

Anthropic Message Request Base

Anthropic Messages request accepted at /v1/messages. top_k, stop_sequences and inference_geo are not supported, so a request that sets them is rejected.

Field	Type	Required	Description
`model`	`string`	Yes	(minLength: 1)
`messages`	array of `AnthropicInputMessage`	Yes	(minItems: 1)
`system`	`string` \| array of `AnthropicSystemTextBlockParam`	No
`tools`	array of `AnthropicTool`	No
`tool_choice`	`AnthropicToolChoice`	No
`metadata`	`AnthropicMetadataParam`	No
`temperature`	`number` \| `null`	No	(minimum: 0, maximum: 1)
`top_p`	`number` \| `null`	No	(minimum: 0, maximum: 1)
`thinking`	`AnthropicThinkingConfigParam`	No
`service_tier`	`enum ('auto', 'standard_only')`	No
`cache_control`	`AnthropicCacheControlEphemeralParam`	No
`output_config`	`AnthropicOutputConfig`	No

Anthropic Metadata Param

Request metadata. user_id identifies the end user; other string values are passed through.

Field	Type	Required	Description
`user_id`	`string`	No

Anthropic Output Config

Anthropic output controls. effort sets the reasoning effort; max selects the strongest available effort.

Field	Type	Required	Description
`effort`	`enum ('low', 'medium', 'high', 'xhigh', 'max')`	No
`format`	`AnthropicJsonOutputFormat`	No

Anthropic Plain Text Source Param

Plain-text document.

Field	Type	Required	Description
`type`	`enum ('text')`	No
`media_type`		No	Ignored. Plain text is always `text/plain`.
`data`	`string`	Yes

Anthropic Redacted Thinking Block Param

Encrypted reasoning returned by an earlier response, replayed as is.

Field	Type	Required	Description
`type`	`enum ('redacted_thinking')`	No
`data`		No	The encrypted reasoning, as returned.
`redacted_thinking`		No	Older name for `data`, read when `data` is absent.

Anthropic Search Result Block Param

Search result passed to the model as its JSON text.

Field	Type	Required	Description
`type`	`enum ('search_result')`	No
`source`		No	Where the result came from.
`title`		No	Result title.
`content`		No	Text blocks with the result content.
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Server Tool Caller Param

What invoked the tool. Accepted and ignored.

Type: AnthropicDirectCallerParam

Anthropic Server Tool Use Block Param

Earlier server tool call, replayed. Supported names are web_search and tool_search.

Field	Type	Required
`type`	`enum ('server_tool_use')`	No
`id`	`string`	Yes
`name`	`enum ('web_search', 'tool_search')`	Yes
`input`	`AnthropicServerToolUseInputParam`	Yes
`cache_control`	`AnthropicCacheControlEphemeralParam`	No
`caller`	`AnthropicServerToolCallerParam`	No

Anthropic Server Tool Use Input Param

The call input, as returned.

Field	Type	Required	Description
`query`		No	The search query.

Anthropic Stream Event

Anthropic Messages server-sent event. Stream event names include message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop, and error.

Type: object

Anthropic System Text Block Param

A system prompt text block.

Field	Type	Required	Description
`type`	`enum ('text')`	Yes
`text`	`string`	Yes
`citations`		No	Accepted and ignored.
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Text Block Param

Text content.

Field	Type	Required	Description
`type`	`enum ('text')`	No
`text`	`string`	Yes
`citations`		No	Accepted and ignored.
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Thinking Block Param

Earlier reasoning summary, replayed.

Field	Type	Required	Description
`type`	`enum ('thinking')`	No
`thinking`	`string`	Yes
`signature`		No	Accepted and ignored.

Anthropic Thinking Config Adaptive Param

The model decides how much to reason.

Field	Type	Required	Description
`type`	`enum ('adaptive')`	No
`display`	`enum ('summarized', 'omitted')`	No

Anthropic Thinking Config Disabled Param

Reasoning off, where the model supports it.

Field	Type	Required	Description
`type`	`enum ('disabled')`	No

Anthropic Thinking Config Enabled Param

Reasoning with a token budget.

Field	Type	Required	Description
`type`	`enum ('enabled')`	No
`budget_tokens`	`integer (int64)`	Yes	Reasoning token budget. Must be less than `max_tokens`. (minimum: 1024)
`display`	`enum ('summarized', 'omitted')`	No

Field	Type	Required	Description
`type`	`enum ('auto', 'any', 'none')`	Yes
`name`		No	Ignored.
`disable_parallel_tool_use`	`boolean`	No

Anthropic Tool Result Block Param

Result of an earlier tool call.

Field	Type	Required	Description
`type`	`enum ('tool_result')`	No
`tool_use_id`	`string`	Yes
`content`	`string` \| array of `AnthropicToolResultContentBlockParam`	No	A string, or an array of content blocks. Any other value is passed as its JSON text.
`is_error`		No	`true` marks the result as an error.
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Tool Result Content Block Param

A block of a tool result. Blocks other than text, image and document are passed as their JSON text.

Type: AnthropicContentSourceTextBlockParam | AnthropicToolResultImageBlockParam | AnthropicToolResultDocumentBlockParam | AnthropicToolResultOtherBlockParam

Anthropic Tool Result Document Block Param

A document in a tool result.

Field	Type	Required
`type`	`enum ('document')`	Yes
`source`	`AnthropicDocumentSourceParam`	Yes
`title`	`string` \| `null`	No
`context`	`string` \| `null`	No
`citations`	`AnthropicCitationsConfigParam`	No

Anthropic Tool Result Image Block Param

An image in a tool result.

Field	Type	Required	Description
`type`	`enum ('image')`	Yes
`source`	`AnthropicMediaSourceParam`	Yes

Anthropic Tool Result Other Block Param

Any other block of a tool result, passed as its JSON text.

Field	Type	Required	Description
`type`	`string`	No	Any block type except `text`, `image` and `document`.

Anthropic Tool Search Tool Param

The hosted tool search tool.

Field	Type	Required	Description
`type`	`enum ('tool_search', 'tool_search_20250305')`	Yes
`execution`	`enum ('server', 'client')` \| `null`	No
`description`	`string` \| `null`	No
`parameters`	`object` \| `null`	No	Parameter schema for a client-executed tool search tool.
`input_schema`		No	Used as `parameters` when `parameters` is omitted.
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Tool Use Block Param

Earlier tool call, replayed.

Field	Type	Required	Description
`type`	`enum ('tool_use')`	No
`id`	`string`	Yes
`name`	`string`	Yes
`input`		No	Tool arguments, as an object.
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Url Source Param

Media fetched from a URL.

Field	Type	Required	Description
`type`	`enum ('url')`	No
`url`	`string`	Yes

Anthropic Usage

Field	Type	Required
`input_tokens`	`integer`	Yes
`output_tokens`	`integer`	Yes
`cache_creation_input_tokens`	`integer`	No
`cache_read_input_tokens`	`integer`	No
`output_tokens_details`	`object`	No
`output_tokens_details.thinking_tokens`	`integer`	No

Anthropic User Location Param

Approximate user location for web search.

Field	Type	Required
`type`	`enum ('approximate')`	No
`city`	`string` \| `null`	No
`region`	`string` \| `null`	No
`country`	`string` \| `null`	No
`timezone`	`string` \| `null`	No

Anthropic Video Block Param

Video input (Meta extension).

Field	Type	Required	Description
`type`	`enum ('video')`	No
`source`	`AnthropicMediaSourceParam`	Yes
`fps`	`number` \| `null`	No	Frames per second to sample.
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Web Search Tool Param

The hosted web search tool.

Field	Type	Required
`type`	`enum ('web_search', 'web_search_20250305', 'web_search_20250305_15')`	Yes
`user_location`	`AnthropicUserLocationParam`	No
`cache_control`	`AnthropicCacheControlEphemeralParam`	No