Messages schemas

The full schema and model definitions referenced by the Messages endpoints. Each endpoint page links here for the detailed shape of its request and response objects.

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; a 1h TTL is not supported.

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

Anthropic Citations Config Param

Document citation settings. Enabling citations is not supported.

Field	Type	Required	Description
`enabled`	`boolean`	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 Param

Document built from inline content blocks.

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

Anthropic Context Management Config

Anthropic beta context-management config. Known edit types are accepted for compatibility; no server-side context edits are applied.

Field	Type	Required	Description
`edits`	array of `AnthropicContextManagementEditParam`	No

Anthropic Context Management Edit Param

Context-management edit.

Field	Type	Required	Description
`type`	`enum ('clear_tool_uses_20250919', 'clear_thinking_20251015', 'compact_20260112')`	No

Anthropic Count Tokens Request

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

Anthropic Count Tokens Response

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

Anthropic Document Block Param

Document input.

Field	Type	Required
`type`	`enum ('document')`	No
`source`	`AnthropicDocumentSourceParam`	Yes
`title`	`string`	No
`context`	`string`	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
`messages`	array of `AnthropicInputMessage`	Yes	(minItems: 1)
`system`	`string` \| array of `AnthropicTextBlockParam`	No
`tools`	array of `AnthropicTool`	No
`tool_choice`	`AnthropicToolChoice`	No
`metadata`	`AnthropicMetadataParam`	No
`temperature`	`number`	No	(minimum: 0, maximum: 1)
`top_p`	`number`	No	(minimum: 0, maximum: 1)
`top_k`	`integer`	No
`thinking`	`AnthropicThinkingConfigParam`	No
`stop_sequences`	`array of string`	No
`service_tier`	`enum ('auto', 'standard_only')`	No
`cache_control`	`AnthropicCacheControlEphemeralParam`	No
`context_management`	`AnthropicContextManagementConfig` \| `null`	No
`container`	`object`	No
`inference_geo`	`string`	No
`output_config`	`AnthropicOutputConfig`	No
`max_tokens`	`integer`	Yes	(minimum: 0)
`stream`	`boolean`	No	(default: false)

Anthropic Message Request Base

Anthropic Messages request accepted at /v1/messages.

Field	Type	Required	Description
`model`	`string`	Yes
`messages`	array of `AnthropicInputMessage`	Yes	(minItems: 1)
`system`	`string` \| array of `AnthropicTextBlockParam`	No
`tools`	array of `AnthropicTool`	No
`tool_choice`	`AnthropicToolChoice`	No
`metadata`	`AnthropicMetadataParam`	No
`temperature`	`number`	No	(minimum: 0, maximum: 1)
`top_p`	`number`	No	(minimum: 0, maximum: 1)
`top_k`	`integer`	No
`thinking`	`AnthropicThinkingConfigParam`	No
`stop_sequences`	`array of string`	No
`service_tier`	`enum ('auto', 'standard_only')`	No
`cache_control`	`AnthropicCacheControlEphemeralParam`	No
`context_management`	`AnthropicContextManagementConfig` \| `null`	No
`container`	`object`	No
`inference_geo`	`string`	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
`type`	`enum ('text')`	No
`media_type`	`string`	No
`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.

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`	`string`	No
`title`	`string`	No
`content`		No	Text blocks with the result content.
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

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`	`string`	Yes
`input`	`object`	No
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

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

Anthropic Thinking Config Param

Extended reasoning settings.

Type: AnthropicThinkingConfigEnabledParam | AnthropicThinkingConfigAdaptiveParam | AnthropicThinkingConfigDisabledParam

Anthropic Tool

Anthropic tool definition. Custom (developer) tools are supported; supported hosted tools are accepted, and unsupported hosted tools return an invalid_request_error.

Field	Type	Required	Description
`type`	`string`	No	Tool type. Omitted or `custom` for a developer tool.
`name`	`string`	No
`description`	`string`	No
`input_schema`	`object`	No	JSON Schema for a custom tool's input.
`strict`	`boolean`	No
`defer_loading`	`boolean`	No
`user_location`	`AnthropicUserLocationParam`	No
`cache_control`	`AnthropicCacheControlEphemeralParam`	No

Anthropic Tool Choice

Field	Type	Required
`type`	`enum ('auto', 'any', 'none', 'tool')`	Yes
`name`	`string`	No
`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`		No	A string, or an array of content blocks (`text`, `image`, `document`, `search_result`, `tool_reference`).
`is_error`		No	`true` marks the result as an error.
`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`	No
`region`	`string`	No
`country`	`string`	No
`timezone`	`string`	No

Anthropic Video Block Param

Video input (Meta extension).

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