Create a Message
Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.
The Messages API can be used for either single queries or stateless multi-turn conversations.
Learn more about the Messages API in our user guide
Parameters
--max-tokens: numberThe maximum number of tokens to generate before stopping.
The maximum number of tokens to generate before stopping.
Note that our models may stop before reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
Set to 0 to populate the prompt cache without generating a response.
Different models have different maximum values for this parameter. See models for details.
--message: array of MessageParamInput messages.
Input messages.
Our models are trained to operate on alternating user and assistant conversational turns. When creating a new Message, you specify the prior conversational turns with the messages parameter, and the model then generates the next Message in the conversation. Consecutive user or assistant turns in your request will be combined into a single turn.
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.
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.
Example with a single user message:
[{"role": "user", "content": "Hello, Claude"}]Example with multiple conversational turns:
[
{"role": "user", "content": "Hello there."},
{"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
{"role": "user", "content": "Can you explain LLMs in plain English?"},
]Example with a partially-filled response from Claude, for models that support prefill:
[
{"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "The best answer is ("},
]Each input message content may be either a single string or an array of content blocks, where each block has a specific type. Using a string for content is shorthand for an array of one content block of type "text". The following input messages are equivalent:
{"role": "user", "content": "Hello, Claude"}{"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}See input examples.
Note that if you want to include a system prompt, you can use the top-level system parameter.
There is a limit of 100,000 messages in a single request.
user_message_param: object{ content, role }
content: array of ContentBlockParam
assistant_message_param: object{ content, role }
content: array of ContentBlockParam
system_message_param: object{ content, role }
--model: ModelThe model that will complete your prompt.
The model that will complete your prompt.
See models for additional details and options.
Built for the most ambitious work in coding, enterprise workflows, and the sciences
Built for the most demanding cybersecurity and life sciences research, available through verification programs
Fastest model for high-volume, real-time tasks
Efficient model for coding and agents
Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
Powerful intelligence for coding, knowledge work, and long-running agents
Our most capable model for cybersecurity and biology research, available through trusted access programs
Efficient model for coding and agents
Next generation of intelligence for the hardest knowledge work and coding problems
Most capable model for cybersecurity and biology research
Powerful intelligence for long-running agents and coding
Powerful intelligence for long-running agents and coding
Powerful intelligence for long-running agents and coding
Powerful intelligence for long-running agents and coding
Best combination of speed and intelligence
Powerful intelligence for long-running agents and coding
Powerful intelligence for long-running agents and coding
"claude-mythos-preview"DeprecatedNew class of intelligence, strongest in coding and cybersecurity
New class of intelligence, strongest in coding and cybersecurity
"claude-sonnet-4-5"DeprecatedHigh-performance model for agents and coding
High-performance model for agents and coding
"claude-sonnet-4-5-20250929"DeprecatedHigh-performance model for agents and coding
High-performance model for agents and coding
--cache-control: optional CacheControlEphemeral { type: "ephemeral", ttl }Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.
Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.
ttl: optional "5m" or "1h"The time-to-live for the cache control breakpoint.
The time-to-live for the cache control breakpoint.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
--container: optional MessageCreateParamsContainerContainer identifier for reuse across requests.
Container identifier for reuse across requests.
container_params: object{ id, skills }Container parameters with skills to be loaded.
Container parameters with skills to be loaded.
Container id
skills: optional array of SkillParams { type, skill_id, version }List of skills to load in the container
List of skills to load in the container
type: "anthropic" or "custom"Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
skill_id: stringSkill ID
Skill ID
version: optional stringSkill version or 'latest' for most recent version
Skill version or 'latest' for most recent version
--diagnostics: optional DiagnosticsParam { previous_message_id }Request-level diagnostics. Supply previous_message_id to have the response include diagnostics.cache_miss_reason explaining any prompt-cache divergence from that prior request.
Request-level diagnostics. Supply previous_message_id to have the response include diagnostics.cache_miss_reason explaining any prompt-cache divergence from that prior request.
previous_message_id: optional stringThe id (msg_...) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns diagnostics.cache_miss_reason when the prompt-cache prefix could not be reused. Pass null on the first turn to opt in without a prior message to compare.
The id (msg_...) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns diagnostics.cache_miss_reason when the prompt-cache prefix could not be reused. Pass null on the first turn to opt in without a prior message to compare.
Specifies the geographic region for inference processing. If not specified, the workspace's default_inference_geo is used.
--metadata: optional Metadata { user_id }An object describing metadata about the request.
An object describing metadata about the request.
user_id: optional stringAn external identifier for the user who is associated with the request.
An external identifier for the user who is associated with the request.
This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.
--output-config: optional OutputConfig { effort, format }Configuration options for the model's output, such as the output format.
Configuration options for the model's output, such as the output format.
effort: optional "low" or "medium" or "high" or 2 moreHow much effort the model should put into its response. Higher effort levels may result in more thorough analysis but take longer.
How much effort the model should put into its response. Higher effort levels may result in more thorough analysis but take longer.
Valid values are low, medium, high, xhigh, or max.
format: optional object{ type: "json_schema", schema }A schema to specify Claude's output format in responses. See structured outputs
A schema to specify Claude's output format in responses. See structured outputs
The JSON schema of the format
--service-tier: optional "auto" or "standard_only"Determines whether to use priority capacity (if available) or standard capacity for this request.
Determines whether to use priority capacity (if available) or standard capacity for this request.
Anthropic offers different levels of service for your API requests. See service-tiers for details.
--speed: optional "standard" or "fast"The inference speed mode for this request. "fast" enables high output-tokens-per-second inference.
The inference speed mode for this request. "fast" enables high output-tokens-per-second inference.
Some models require the fast-mode-2026-02-01 beta header for any speed value. See fast mode for which models.
--stop-sequence: optional array of stringCustom text sequences that will cause the model to stop generating.
Custom text sequences that will cause the model to stop generating.
Our models will normally stop when they have naturally completed their turn, which will result in a response stop_reason of "end_turn".
If you want the model to stop generating when it encounters custom strings of text, you can use the stop_sequences parameter. If the model encounters one of the custom sequences, the response stop_reason value will be "stop_sequence" and the response stop_sequence value will contain the matched stop sequence.
--system: optional string or array of TextBlockParamSystem prompt.
System prompt.
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.
union_member_1: array of TextBlockParam { type: "text", text, cache_control, citations }
text: string
cache_control: optional object{ type: "ephemeral", ttl }Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
ttl: optional "5m" or "1h"The time-to-live for the cache control breakpoint.
The time-to-live for the cache control breakpoint.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
citations: optional array of TextCitationParam
citation_char_location_param: object{ type: "char_location", cited_text, document_index, 3 more }
document_index: number
document_title: string
start_char_index: number
citation_page_location_param: object{ type: "page_location", cited_text, document_index, 3 more }
document_index: number
document_title: string
start_page_number: number
citation_content_block_location_param: object{ type: "content_block_location", cited_text, document_index, 3 more }
cited_text: stringThe full text of the cited block range, concatenated.
The full text of the cited block range, concatenated.
Always equals the contents of content[start_block_index:end_block_index] joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
document_index: number
document_title: string
end_block_index: numberExclusive 0-based end index of the cited block range in the source's content array.
Exclusive 0-based end index of the cited block range in the source's content array.
Always greater than start_block_index; a single-block citation has end_block_index = start_block_index + 1.
start_block_index: number0-based index of the first cited block in the source's content array.
0-based index of the first cited block in the source's content array.
citation_web_search_result_location_param: object{ type: "web_search_result_location", cited_text, encrypted_index, 2 more }
title: string
url: string
citation_search_result_location_param: object{ type: "search_result_location", cited_text, end_block_index, 4 more }
cited_text: stringThe full text of the cited block range, concatenated.
The full text of the cited block range, concatenated.
Always equals the contents of content[start_block_index:end_block_index] joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
end_block_index: numberExclusive 0-based end index of the cited block range in the source's content array.
Exclusive 0-based end index of the cited block range in the source's content array.
Always greater than start_block_index; a single-block citation has end_block_index = start_block_index + 1.
search_result_index: number0-based index of the cited search result among all search_result content blocks in the request, in the order they appear across messages and tool results.
0-based index of the cited search result among all search_result content blocks in the request, in the order they appear across messages and tool results.
Counted separately from document_index; server-side web search results are not included in this count.
start_block_index: number0-based index of the first cited block in the source's content array.
0-based index of the first cited block in the source's content array.
--thinking: optional ThinkingConfigParamConfiguration for Claude's thinking.
Configuration for Claude's thinking.
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.
Which type values are accepted, and what happens when you omit thinking, depend on the model. See thinking for each model's behavior.
--tool-choice: optional ToolChoiceHow the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
--tool: optional array of ToolUnionDefinitions of tools that the model may use.
Definitions of tools that the model may use.
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.
There are two types of tools: client tools and server tools. The behavior described below applies to client tools. For server tools, see their individual documentation as each has its own behavior (e.g., the web search tool).
Each tool definition includes:
name: Name of the tool.description: Optional, but strongly-recommended description of the tool.input_schema: JSON schema for the toolinputshape that the model will produce intool_useoutput content blocks.
For example, if you defined tools as:
[
{
"name": "get_stock_price",
"description": "Get the current stock price for a given ticker symbol.",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
"description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
}
},
"required": ["ticker"]
}
}
]And then asked the model "What's the S&P 500 at today?", the model might produce tool_use content blocks in the response like this:
[
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "get_stock_price",
"input": { "ticker": "^GSPC" }
}
]You might then run your get_stock_price tool with {"ticker": "^GSPC"} as an input, and return the following back to the model in a subsequent user message:
[
{
"type": "tool_result",
"tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"content": "259.75 USD"
}
]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.
See our guide for more details.
tool: object{ type: "custom", input_schema, name, 7 more }
tool_bash_20250124: object{ type: "bash_20250124", name, allowed_callers, 4 more }
code_execution_tool_20250522: object{ type: "code_execution_20250522", name, allowed_callers, 3 more }
code_execution_tool_20250825: object{ type: "code_execution_20250825", name, allowed_callers, 3 more }
code_execution_tool_20260120: object{ type: "code_execution_20260120", name, allowed_callers, 3 more }A tools entry for the code execution tool, version code_execution_20260120. It adds REPL state persistence to version code_execution_20250825.
A tools entry for the code execution tool, version code_execution_20260120. It adds REPL state persistence to version code_execution_20250825.
REPL state persistence applies with programmatic tool calling. With it, the Python interpreter state, such as variable bindings, persists across requests that reuse the container.
See the code execution tool guide to learn what each tool version adds.
code_execution_tool_20260521: object{ type: "code_execution_20260521", name, allowed_callers, 3 more }Code execution tool with REPL state persistence.
Code execution tool with REPL state persistence.
browser_toolset_20260801: object{ type: "browser_toolset_20260801", cache_control, configs }The browser toolset: a single tools[] entry (carrying no
name) that declares the browser tool family. The model is served
the family's tool with any members disabled via configs removed
from its schema.
The browser toolset: a single tools[] entry (carrying no
name) that declares the browser tool family. The model is served
the family's tool with any members disabled via configs removed
from its schema.
memory_tool_20250818: object{ type: "memory_20250818", name, allowed_callers, 4 more }
computer_toolset_20260801: object{ type: "computer_toolset_20260801", cache_control, configs }The computer toolset: a single tools[] entry (carrying no
name) that declares the computer tool family. The model is
served the family's tool with any members disabled via configs
removed from its schema. Every member is enabled by default, zoom
included. The single-tool options display_number and
enable_zoom are not fields of a toolset entry — it carries only
type, configs, and cache_control; zoom is controlled
via configs.zoom.enabled.
The computer toolset: a single tools[] entry (carrying no
name) that declares the computer tool family. The model is
served the family's tool with any members disabled via configs
removed from its schema. Every member is enabled by default, zoom
included. The single-tool options display_number and
enable_zoom are not fields of a toolset entry — it carries only
type, configs, and cache_control; zoom is controlled
via configs.zoom.enabled.
tool_text_editor_20250124: object{ type: "text_editor_20250124", name, allowed_callers, 4 more }
tool_text_editor_20250429: object{ type: "text_editor_20250429", name, allowed_callers, 4 more }
tool_text_editor_20250728: object{ type: "text_editor_20250728", name, allowed_callers, 5 more }
web_search_tool_20250305: object{ type: "web_search_20250305", name, allowed_callers, 7 more }
web_fetch_tool_20250910: object{ type: "web_fetch_20250910", name, allowed_callers, 9 more }
web_search_tool_20260209: object{ type: "web_search_20260209", name, allowed_callers, 7 more }
web_fetch_tool_20260209: object{ type: "web_fetch_20260209", name, allowed_callers, 9 more }
web_fetch_tool_20260309: object{ type: "web_fetch_20260309", name, allowed_callers, 10 more }Web fetch tool with use_cache parameter for bypassing cached content.
Web fetch tool with use_cache parameter for bypassing cached content.
web_search_tool_20260318: object{ type: "web_search_20260318", name, allowed_callers, 8 more }
web_fetch_tool_20260318: object{ type: "web_fetch_20260318", name, allowed_callers, 11 more }
tool_search_tool_bm25_20251119: object{ type, name, allowed_callers, 3 more }
tool_search_tool_regex_20251119: object{ type, name, allowed_callers, 3 more }
The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization.
--workspace-id: optional stringHeader parameterOptional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).
Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
Returns
message: object{ type: "message", id, container, 8 more }
raw_message_stream_event: RawMessageStartEvent or RawMessageDeltaEvent or RawMessageStopEvent or 3 more
Errors
Any method can also return the general HTTP errors.
Each code below is the value of error.details.error_code in the response body.
On a streaming call, the errors listed below apply when the API rejects the request before the stream starts. Once the stream has started, the response status is already 200, so a later error comes through the stream, with no status of its own. To identify it, use error.details.error_code if the error has one, and error.type if not.
The tools available after a message exceed a limit on their number or their size.
The API key belongs to the Claude Code workspace, and the user who created it is no longer a member of the organization or of that workspace.
The request comes from a Claude Code version older than the minimum that the requested model or the organization requires. Update Claude Code, then retry.
The workspace's customer-managed encryption key is disabled or revoked. Re-enable the key, then retry.
The key management service's network access controls blocked the request to the workspace's customer-managed encryption key. The key itself may be healthy.
messages holds more than one compaction block with content. Send only the block the conversation returned last.
The compaction block is not the first block of the conversation, or is in a system message.
The compaction block's content differs from the text its signature recorded.
The compaction request ends on an assistant turn that is not finished.
messages holds no user or assistant content to summarize or adopt.
The compaction block's signature does not verify.
The conversation references more distinct tools than a compaction block can record.
The compaction block's tool_changes differs from what was returned with the block.
Anthropic has disabled the organization for trust and safety reasons. An organization disabled for any other reason, such as billing, does not get this code. appeal_url, when present, is where the organization can appeal.
The request body is not valid for its Content-Encoding.
The request's Content-Encoding is not supported.
The response that previous_message_id names has already been continued, and each response can be continued only once. Continue from the Thread's most recent response id.
Another request is still continuing from the same previous_message_id. Wait for it to complete and continue from its response id, or replay the full conversation with thread: {"type": "create"}.
A field that must stay the same across a Thread's turns differs from the value stored with the Thread; the message names each such field. Send the stored values, or replay the full conversation with thread: {"type": "create"} to change them.
The request combines thread with a request field or an organization setting that Threads do not support; unsupported, when present, names it. Send the full conversation without thread, or change that field.
A tool made available in messages takes a name that an available tool of another kind, or of another MCP server, already holds.
A tool change or MCP tool listing references a tool or MCP server that is not defined at that position in the conversation.
No usable Thread state was found for previous_message_id. Replay the full conversation with thread: {"type": "create"} to start a new Thread.
A custom skill the request names is stored under an encryption key state the workspace cannot currently decrypt.
The compressed request body exceeds the request size limit once decoded.
The organization has crossed the monthly API usage threshold of its API tier.
The request would exceed a ramp limit, which caps how fast usage can grow. Retry after the time in the retry-after header.
The workspace's customer-managed encryption key could not be reached. Retry the request; if this continues, check that the key is available in your key management service, or contact Anthropic support.
The compaction could not be completed for a transient server reason. Retry the request.
ant messages create \
--max-tokens 1024 \
--message '{content: [{text: x, type: text}], role: user}' \
--model claude-opus-5-5{
"id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
"container": {
"id": "container_011CpZohnwH4vuy7gazohgSP",
"expires_at": "2019-12-27T18:11:19.117Z",
"skills": [
{
"skill_id": "pdf",
"type": "anthropic",
"version": "latest"
}
]
},
"content": [
{
"citations": null,
"text": "Hi! My name is Claude.",
"type": "text"
}
],
"diagnostics": null,
"model": "claude-opus-5-5",
"role": "assistant",
"stop_details": null,
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 0
},
"cache_creation_input_tokens": 2051,
"cache_read_input_tokens": 2051,
"inference_geo": "global",
"input_tokens": 2095,
"output_tokens": 503,
"output_tokens_details": {
"thinking_tokens": 0
},
"server_tool_use": {
"web_fetch_requests": 2,
"web_search_requests": 0
},
"service_tier": "standard",
"speed": "standard"
}
}Returns Examples
{
"id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
"container": {
"id": "container_011CpZohnwH4vuy7gazohgSP",
"expires_at": "2019-12-27T18:11:19.117Z",
"skills": [
{
"skill_id": "pdf",
"type": "anthropic",
"version": "latest"
}
]
},
"content": [
{
"citations": null,
"text": "Hi! My name is Claude.",
"type": "text"
}
],
"diagnostics": null,
"model": "claude-opus-5-5",
"role": "assistant",
"stop_details": null,
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 0
},
"cache_creation_input_tokens": 2051,
"cache_read_input_tokens": 2051,
"inference_geo": "global",
"input_tokens": 2095,
"output_tokens": 503,
"output_tokens_details": {
"thinking_tokens": 0
},
"server_tool_use": {
"web_fetch_requests": 2,
"web_search_requests": 0
},
"service_tier": "standard",
"speed": "standard"
}
}