---
title: "MessagesRequest"
---

Request schema for Anthropic Messages API endpoint


## Fields

| Field                                                                                                                                                                                                                                                                                                                                                                                                                | Type                                                                                                                                                                                                                                                                                                                                                                                                                 | Required                                                                                                                                                                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                          | Example                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cache_control`                                                                                                                                                                                                                                                                                                                                                                                                      | [Optional[components.AnthropicCacheControlDirective]](../components/anthropiccachecontroldirective.mdx)                                                                                                                                                                                                                                                                                                               | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. Currently supported for Anthropic Claude models.                                                                                                                                                                                                          | \{<br/>"type": "ephemeral"<br/>}                                                                                                                                                                                                                                                                                                                                                                                      |
| `context_management`                                                                                                                                                                                                                                                                                                                                                                                                 | [OptionalNullable[components.ContextManagement]](../components/contextmanagement.mdx)                                                                                                                                                                                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `fallbacks`                                                                                                                                                                                                                                                                                                                                                                                                          | List[[components.MessagesFallbackParam](../components/messagesfallbackparam.mdx)]                                                                                                                                                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Fallback models to try if the primary model fails or refuses, in order. Handled by OpenRouter multi-model routing rather than Anthropic server-side fallbacks; cannot be combined with `models`. Each entry accepts only `model`. Maximum of 3 entries.                                                                                                                                                              | [<br/>\{<br/>"model": "claude-opus-4-8"<br/>}<br/>]                                                                                                                                                                                                                                                                                                                                                                   |
| `max_tokens`                                                                                                                                                                                                                                                                                                                                                                                                         | *Optional[int]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `messages`                                                                                                                                                                                                                                                                                                                                                                                                           | List[[components.MessagesMessageParam](../components/messagesmessageparam.mdx)]                                                                                                                                                                                                                                                                                                                                       | :heavy_check_mark:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `metadata`                                                                                                                                                                                                                                                                                                                                                                                                           | [Optional[components.MessagesRequestMetadata]](../components/messagesrequestmetadata.mdx)                                                                                                                                                                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `model`                                                                                                                                                                                                                                                                                                                                                                                                              | *str*                                                                                                                                                                                                                                                                                                                                                                                                                | :heavy_check_mark:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `models`                                                                                                                                                                                                                                                                                                                                                                                                             | List[*str*]                                                                                                                                                                                                                                                                                                                                                                                                          | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `output_config`                                                                                                                                                                                                                                                                                                                                                                                                      | [Optional[components.MessagesOutputConfig]](../components/messagesoutputconfig.mdx)                                                                                                                                                                                                                                                                                                                                   | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Configuration for controlling output behavior. Supports the effort parameter and structured output format.                                                                                                                                                                                                                                                                                                           | \{<br/>"effort": "medium"<br/>}                                                                                                                                                                                                                                                                                                                                                                                       |
| `plugins`                                                                                                                                                                                                                                                                                                                                                                                                            | List[[components.MessagesRequestPlugin](../components/messagesrequestplugin.mdx)]                                                                                                                                                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Plugins you want to enable for this request, including their settings.                                                                                                                                                                                                                                                                                                                                               |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `provider`                                                                                                                                                                                                                                                                                                                                                                                                           | [OptionalNullable[components.ProviderPreferences]](../components/providerpreferences.mdx)                                                                                                                                                                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | When multiple model providers are available, optionally indicate your routing preference.                                                                                                                                                                                                                                                                                                                            | \{<br/>"allow_fallbacks": true<br/>}                                                                                                                                                                                                                                                                                                                                                                                  |
| `service_tier`                                                                                                                                                                                                                                                                                                                                                                                                       | *Optional[str]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `session_id`                                                                                                                                                                                                                                                                                                                                                                                                         | *Optional[str]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `speed`                                                                                                                                                                                                                                                                                                                                                                                                              | [OptionalNullable[components.Speed]](../components/speed.mdx)                                                                                                                                                                                                                                                                                                                                                         | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  | fast                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `stop_sequences`                                                                                                                                                                                                                                                                                                                                                                                                     | List[*str*]                                                                                                                                                                                                                                                                                                                                                                                                          | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `stop_server_tools_when`                                                                                                                                                                                                                                                                                                                                                                                             | List[[components.StopServerToolsWhenCondition](../components/stopservertoolswhencondition.mdx)]                                                                                                                                                                                                                                                                                                                       | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`.                                                                                                                                                                                                                                                                           | [<br/>\{<br/>"step_count": 5,<br/>"type": "step_count_is"<br/>},<br/>\{<br/>"max_cost_in_dollars": 0.5,<br/>"type": "max_cost"<br/>}<br/>]                                                                                                                                                                                                                                                                             |
| `stream`                                                                                                                                                                                                                                                                                                                                                                                                             | *Optional[bool]*                                                                                                                                                                                                                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `system`                                                                                                                                                                                                                                                                                                                                                                                                             | [Optional[components.System]](../components/system.mdx)                                                                                                                                                                                                                                                                                                                                                               | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `temperature`                                                                                                                                                                                                                                                                                                                                                                                                        | *Optional[float]*                                                                                                                                                                                                                                                                                                                                                                                                    | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `thinking`                                                                                                                                                                                                                                                                                                                                                                                                           | [Optional[components.Thinking]](../components/thinking.mdx)                                                                                                                                                                                                                                                                                                                                                           | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `tool_choice`                                                                                                                                                                                                                                                                                                                                                                                                        | [Optional[components.ToolChoice]](../components/toolchoice.mdx)                                                                                                                                                                                                                                                                                                                                                       | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `tools`                                                                                                                                                                                                                                                                                                                                                                                                              | List[[components.MessagesRequestToolUnion](../components/messagesrequesttoolunion.mdx)]                                                                                                                                                                                                                                                                                                                               | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `top_k`                                                                                                                                                                                                                                                                                                                                                                                                              | *Optional[int]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `top_p`                                                                                                                                                                                                                                                                                                                                                                                                              | *Optional[float]*                                                                                                                                                                                                                                                                                                                                                                                                    | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `trace`                                                                                                                                                                                                                                                                                                                                                                                                              | [Optional[components.TraceConfig]](../components/traceconfig.mdx)                                                                                                                                                                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.                                                                                                                                                                             | \{<br/>"trace_id": "trace-abc123",<br/>"trace_name": "my-app-trace"<br/>}                                                                                                                                                                                                                                                                                                                                             |
| `user`                                                                                                                                                                                                                                                                                                                                                                                                               | *Optional[str]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | A unique identifier representing your end-user, which helps distinguish between different users of your app. This allows your app to identify specific users in case of abuse reports, preventing your entire app from being affected by the actions of individual users. Maximum of 256 characters.                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                      |