[metadata]
apple-mobile-web-app-status-bar-style: default
description: 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…
mobile-web-app-capable: yes
og:description: 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…
og:image: https://platform.claude.com/web-api/og/api/en/messages/create?design-rev=2
og:image:alt: Create a Message - Claude API Reference
og:image:height: 630
og:image:type: image/png
og:image:width: 1200
og:locale: en
og:site_name: Claude API Reference
og:title: Create a Message - Claude API Reference
og:type: website
og:url: https://platform.claude.com/docs/en/api/messages/create
twitter:card: summary_large_image
twitter:description: 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…
twitter:image: https://platform.claude.com/web-api/og/api/en/messages/create?design-rev=2
twitter:title: Create a Message - Claude API Reference
viewport: width=device-width, initial-scale=1, viewport-fit=cover

[canonical-links]
https://platform.claude.com/docs/en/api/messages/create

[document-links]
AI agents: https://claude.com/solutions/agents
API reference: /docs/en/api/http
Admin: /docs/en/api/http/admin
Admin: /docs/en/manage-claude/admin-api
Anthropic: https://www.anthropic.com/company
Availability: https://www.anthropic.com/supported-countries
Best practices: /docs/en/about-claude/use-case-guides/overview
Beta headers: /docs/en/api/beta-headers
Blog: https://claude.com/blog
CLI, SDKs, and libraries: /docs/en/cli-sdks-libraries/overview
CacheControlEphemeral: /docs/en/api/http/messages#cache_control_ephemeral
Careers: https://www.anthropic.com/careers
Claude API skill: /docs/en/agents-and-tools/agent-skills/claude-api-skill
Claude Platform Docs: /docs/en/home
Claude on AWS: https://claude.com/partners/amazon-bedrock
Claude on Google Cloud: https://claude.com/partners/google-cloud-vertex-ai
Code modernization: https://claude.com/solutions/code-modernization
CodeExecutionToolResultBlockParamContent: /docs/en/api/http/messages#code_execution_tool_result_block_param_content
Coding: https://claude.com/solutions/coding
Completions: /docs/en/api/http/completions
Compliance API: /docs/en/api/http/compliance
Connectors: https://claude.com/partners/mcp
ContentBlockParam: /docs/en/api/http/messages#content_block_param
Courses: https://claude.com/resources/courses
Customer stories: https://claude.com/customers
Customer support: https://claude.com/solutions/customer-support
Discord: https://www.anthropic.com/discord
Economic Futures: https://www.anthropic.com/economic-futures
Engineering at Anthropic: https://www.anthropic.com/engineering
Errors: /docs/en/api/errors
Events: https://www.anthropic.com/events
Features overview: /docs/en/api/overview
Files: /docs/en/api/http/beta/files
Financial services: https://claude.com/solutions/financial-services
Government: https://claude.com/solutions/government
Higher education: https://claude.com/solutions/education
IAM actions (Claude Platform on AWS): /docs/en/api/claude-platform-on-aws-iam-actions
IP addresses: /docs/en/api/ip-addresses
JSON schema: https://json-schema.org/draft/2020-12
JSONOutputFormat: /docs/en/api/http/messages#json_output_format
K-12 teachers: https://claude.com/solutions/teachers
Learn more technical details here: https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277
Life sciences: https://claude.com/solutions/life-sciences
Log in: /login?returnTo=%2Fdocs%2Fen%2Fapi%2Fmessages%2Fcreate
Managed Agents: /docs/en/managed-agents/overview
MessageCreateParamsContainer: /docs/en/api/http/messages#message_create_params_container
MessageParam: /docs/en/api/http/messages#message_param
Messages: /docs/en/api/http/beta/messages
Messages: /docs/en/api/http/messages
Messages: /docs/en/intro
Metadata: /docs/en/api/http/messages#metadata
Model: /docs/en/api/http/messages#model
Models & pricing: /docs/en/models/overview
Models: /docs/en/api/http/beta/models
News: https://www.anthropic.com/news
Organization : /docs/en/api/http/beta/organization
OutputConfig: /docs/en/api/http/messages#output_config
Parse Unverified: /docs/en/api/http/beta/webhooks/parse_unverified
Powered by Claude: https://claude.com/partners/powered-by-claude
Privacy policy: https://www.anthropic.com/legal/privacy
Rate limits: /docs/en/api/rate-limits
RawMessageDeltaEvent: /docs/en/api/http/messages#raw_message_delta_event
RawMessageStartEvent: /docs/en/api/http/messages#raw_message_start_event
RawMessageStopEvent: /docs/en/api/http/messages#raw_message_stop_event
Release notes: /docs/en/release-notes/overview
Research: https://www.anthropic.com/research
Responsible Scaling Policy: https://www.anthropic.com/news/announcing-our-updated-responsible-scaling-policy
Responsible disclosure policy: https://www.anthropic.com/responsible-disclosure-policy
Security and compliance: https://trust.anthropic.com
Service partners: https://claude.com/partners/services
Service tiers: /docs/en/api/service-tiers
SkillParams: /docs/en/api/http/messages#skill_params
Skills: /docs/en/api/http/beta/skills
Startups program: https://claude.com/programs/startups
Status: https://status.claude.com/
Support: https://support.claude.com/
Supported regions: /docs/en/api/supported-regions
Terms of service: Commercial: https://www.anthropic.com/legal/commercial-terms
Terms of service: Consumer: https://www.anthropic.com/legal/consumer-terms
TextBlockParam: /docs/en/api/http/messages#text_block_param
TextCitationParam: /docs/en/api/http/messages#text_citation_param
ThinkingConfigParam: /docs/en/api/http/messages#thinking_config_param
ToolChoice: /docs/en/api/http/messages#tool_choice
ToolUnion: /docs/en/api/http/messages#tool_union
Transparency: https://www.anthropic.com/transparency
Trigger a routine: /docs/en/api/claude-code/routines-fire
Tunnels : /docs/en/api/http/beta/tunnels
Unwrap: /docs/en/api/http/beta/webhooks/unwrap
Usage policy: https://www.anthropic.com/legal/aup
Use cases: https://claude.com/resources/use-cases
User Profiles : /docs/en/api/http/beta/user_profiles
Versions: /docs/en/api/versioning
View the beta version: /docs/en/api/http/beta/messages/create
Webhooks : /docs/en/api/http/beta/webhooks
extended thinking: https://platform.claude.com/docs/en/build-with-claude/extended-thinking
guide to system prompts: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role
guide: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
https://instagram.com/claudeai
https://www.linkedin.com/showcase/claude
https://www.threads.com/@claudeai
https://www.youtube.com/@anthropic-ai
https://x.com/claudeai
input examples: https://platform.claude.com/docs/en/build-with-claude/working-with-messages
models: https://docs.anthropic.com/en/docs/models-overview
models: https://platform.claude.com/docs/en/about-claude/models/overview
prompt cache: https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache
prompt caching pricing: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
server tools: https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools
service-tiers: https://platform.claude.com/docs/en/api/service-tiers
streaming: https://platform.claude.com/docs/en/build-with-claude/streaming
structured outputs: https://platform.claude.com/docs/en/build-with-claude/structured-outputs
system prompt: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role
user guide: https://platform.claude.com/docs/en/get-started
web search tool: https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool
 Archive Tunnel: /docs/en/api/http/beta/tunnels/archive
 Count tokens in a Message: /docs/en/api/http/beta/messages/count_tokens
 Create Enrollment URL: /docs/en/api/http/beta/user_profiles/create_enrollment_url
 Create Skill: /docs/en/api/http/beta/skills/create
 Create Tunnel: /docs/en/api/http/beta/tunnels/create
 Create User Profile: /docs/en/api/http/beta/user_profiles/create
 Create a Message: /docs/en/api/http/beta/messages/create
 Create a Text Completion: /docs/en/api/http/completions/create
 Reveal Tunnel Token: /docs/en/api/http/beta/tunnels/reveal_token
 Rotate Tunnel Token: /docs/en/api/http/beta/tunnels/rotate_token
 Update User Profile: /docs/en/api/http/beta/user_profiles/update
 Upload File: /docs/en/api/http/beta/files/upload
 API reference: /docs/en/api/overview
 Console: /
 Delete File: /docs/en/api/http/beta/files/delete
 Delete Skill: /docs/en/api/http/beta/skills/delete
 Download File: /docs/en/api/http/beta/files/download
 Get Current Organization: /docs/en/api/http/beta/organization/retrieve
 Get File Metadata: /docs/en/api/http/beta/files/retrieve_metadata
 Get Skill: /docs/en/api/http/beta/skills/retrieve
 Get Tunnel: /docs/en/api/http/beta/tunnels/retrieve
 Get User Profile: /docs/en/api/http/beta/user_profiles/retrieve
 Get a Model: /docs/en/api/http/beta/models/retrieve
 List Files: /docs/en/api/http/beta/files/list
 List Models: /docs/en/api/http/beta/models/list
 List Skills: /docs/en/api/http/beta/skills/list
 List Tunnels: /docs/en/api/http/beta/tunnels/list
 List User Profiles: /docs/en/api/http/beta/user_profiles/list

[content]
Create a Message - Claude API Reference
Claude Platform Docs
Messages
Managed Agents
Admin
Resources

Best practices
Models & pricing
CLI, SDKs, and libraries
Claude API skill
Release notes

API reference

English


Console
Log in


Search
Ctrl
K

Include beta APIs
Using the API
Features overview
Beta headers
Errors
Messages

Create a Message

Count tokens in a Message
Batches

Managed Agents

Agents

Environments

Sessions

Deployments

Deployment Runs

Vaults

Memory Stores

Dreams

Files

Upload File

List Files

Download File

Get File Metadata

Delete File
Models

List Models

Get a Model
Skills

Create Skill

List Skills

Get Skill

Delete Skill
Versions

Organization


Get Current Organization
API Keys

External Keys

Federation

Invites

Service Accounts

Users

Workspaces

Rate Limits

Compliance Settings

Tunnels


Create Tunnel

Get Tunnel

List Tunnels

Archive Tunnel

Reveal Tunnel Token

Rotate Tunnel Token
Certificates

User Profiles


Create User Profile

List User Profiles

Get User Profile

Update User Profile

Create Enrollment URL
Webhooks

Unwrap
Parse Unverified
Admin
Organizations

Invites

Users

RBAC Groups

RBAC Roles

Workspaces

API Keys

External Keys

Usage Report

Cost Report

Analytics

Spend Limits

Rate Limits

Service Accounts

Federation Issuers

Federation Rules

MCP Tunnels


Compliance API
Activities

Organizations

Groups

Apps

Code

Completions

Create a Text Completion
Support & configuration
Rate limits
Service tiers
IAM actions (Claude Platform on AWS)
Versions
IP addresses
Supported regions
Claude Code
Trigger a routine

Console

Copy page

cURL


A beta version of this method exists and may have additional functionality.
View the beta version
.
API reference

Messages
Create a Message

POST
/v1/messages
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
Headers
"anthropic-user-profile-id"
:
optional
string

The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the
user-profiles
beta header.
Body

max_tokens
:
number

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.
minimum
0

messages
:
array of
MessageParam
{
content
,
role
}

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.
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:
[ {"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 no
"system"
role for input messages in the Messages API.
There is a limit of 100,000 messages in a single request.

content
:
string
or
array of
ContentBlockParam

One of the following:
string


array of
ContentBlockParam

One of the following:

TextBlockParam
object
{
text
,
type
,
cache_control
,
citations
}


ImageBlockParam
object
{
source
,
type
,
cache_control
,
transformations
}


DocumentBlockParam
object
{
source
,
type
,
cache_control
,
3
more
}


SearchResultBlockParam
object
{
content
,
source
,
title
,
3
more
}


ThinkingBlockParam
object
{
signature
,
thinking
,
type
}


signature
:
string

The
signature
value of this thinking block, exactly as returned by the API in a previous response. Used to verify that the block was generated by Claude.
Thinking blocks must be passed back unmodified and in their original order; a modified block results in a 400
invalid_request_error
.
thinking
:
string

The
thinking
text of this block as returned by the API.
type
:
"thinking"


RedactedThinkingBlockParam
object
{
data
,
type
}

data
:
string

The
data
value of this redacted thinking block, exactly as returned by the API in a previous response. Opaque and encrypted; pass it back unchanged.
type
:
"redacted_thinking"


ToolUseBlockParam
object
{
id
,
input
,
name
,
4
more
}


ToolResultBlockParam
object
{
tool_use_id
,
type
,
cache_control
,
3
more
}


ServerToolUseBlockParam
object
{
id
,
input
,
name
,
3
more
}


WebSearchToolResultBlockParam
object
{
content
,
tool_use_id
,
type
,
2
more
}


WebFetchToolResultBlockParam
object
{
content
,
tool_use_id
,
type
,
2
more
}


CodeExecutionToolResultBlockParam
object
{
content
,
tool_use_id
,
type
,
cache_control
}


content
:
CodeExecutionToolResultBlockParamContent

Code execution result with encrypted stdout for PFC + web_search results.
One of the following:

tool_use_id
:
string

pattern
^srvtoolu_[a-zA-Z0-9_]+$
type
:
"code_execution_tool_result"


cache_control
:
optional
CacheControlEphemeral
{
type
,
ttl
}
or
null

Create a cache control breakpoint at this content block.
type
:
"ephemeral"


ttl
:
optional
"5m"
or
"1h"

The time-to-live for the cache control breakpoint.
This may be one the following values:
5m
: 5 minutes
1h
: 1 hour
Defaults to
5m
. See
prompt caching pricing
for details.
One of the following:
"5m"

"1h"


BashCodeExecutionToolResultBlockParam
object
{
content
,
tool_use_id
,
type
,
cache_control
}


TextEditorCodeExecutionToolResultBlockParam
object
{
content
,
tool_use_id
,
type
,
cache_control
}


ToolSearchToolResultBlockParam
object
{
content
,
tool_use_id
,
type
,
cache_control
}


ContainerUploadBlockParam
object
{
file_id
,
type
,
cache_control
}

A content block that represents a file to be uploaded to the container Files uploaded via this block will be available in the container's input directory.
file_id
:
string

type
:
"container_upload"


cache_control
:
optional
CacheControlEphemeral
{
type
,
ttl
}
or
null

Create a cache control breakpoint at this content block.
type
:
"ephemeral"


ttl
:
optional
"5m"
or
"1h"

The time-to-live for the cache control breakpoint.
This may be one the following values:
5m
: 5 minutes
1h
: 1 hour
Defaults to
5m
. See
prompt caching pricing
for details.
One of the following:
"5m"

"1h"


role
:
"user"
or
"assistant"
or
"system"

One of the following:
"user"

"assistant"

"system"


model
:
Model

The model that will complete your prompt.
See
models
for additional details and options.
One of the following:

cache_control
:
optional
CacheControlEphemeral
{
type
,
ttl
}
or
null

Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.
type
:
"ephemeral"


ttl
:
optional
"5m"
or
"1h"

The time-to-live for the cache control breakpoint.
This may be one the following values:
5m
: 5 minutes
1h
: 1 hour
Defaults to
5m
. See
prompt caching pricing
for details.
One of the following:
"5m"

"1h"


container
:
optional
MessageCreateParamsContainer
or
null

Container identifier for reuse across requests.
One of the following:

ContainerParams
object
{
id
,
skills
}

Container parameters with skills to be loaded.
id
:
optional
string
or
null

Container id

skills
:
optional
array of
SkillParams
{
skill_id
,
type
,
version
}
or
null

List of skills to load in the container
maxItems
20

skill_id
:
string

Skill ID
maxLength
64
minLength
1

type
:
"anthropic"
or
"custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
One of the following:
"anthropic"

"custom"


version
:
optional
string

Skill version or 'latest' for most recent version
maxLength
64
minLength
1
string

inference_geo
:
optional
string
or
null

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.

user_id
:
optional
string
or
null

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.
maxLength
512

output_config
:
optional
OutputConfig
{
effort
,
format
}

Configuration options for the model's output, such as the output format.

effort
:
optional
"low"
or
"medium"
or
"high"
or
2
more
or
null

All possible effort levels.
One of the following:
"low"

"medium"

"high"

"xhigh"

"max"


format
:
optional
JSONOutputFormat
{
schema
,
type
}
or
null

A schema to specify Claude's output format in responses. See
structured outputs
schema
:
map
[
unknown
]

The JSON schema of the format
type
:
"json_schema"


service_tier
:
optional
"auto"
or
"standard_only"

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.
One of the following:
"auto"

"standard_only"


stop_sequences
:
optional
array of
string

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.

stream
:
optional
boolean

Whether to incrementally stream the response using server-sent events.
See
streaming
for details.

system
:
optional
string
or
array of
TextBlockParam
{
text
,
type
,
cache_control
,
citations
}

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
.
One of the following:
string


array of
TextBlockParam
{
text
,
type
,
cache_control
,
citations
}


text
:
string

minLength
1
type
:
"text"


cache_control
:
optional
CacheControlEphemeral
{
type
,
ttl
}
or
null

Create a cache control breakpoint at this content block.
type
:
"ephemeral"


ttl
:
optional
"5m"
or
"1h"

The time-to-live for the cache control breakpoint.
This may be one the following values:
5m
: 5 minutes
1h
: 1 hour
Defaults to
5m
. See
prompt caching pricing
for details.
One of the following:
"5m"

"1h"


citations
:
optional
array of
TextCitationParam
or
null

One of the following:

CitationCharLocationParam
object
{
cited_text
,
document_index
,
document_title
,
3
more
}

cited_text
:
string


document_index
:
number

minimum
0

document_title
:
string
or
null

maxLength
500
minLength
1
end_char_index
:
number


start_char_index
:
number

minimum
0
type
:
"char_location"


CitationPageLocationParam
object
{
cited_text
,
document_index
,
document_title
,
3
more
}

cited_text
:
string


document_index
:
number

minimum
0

document_title
:
string
or
null

maxLength
500
minLength
1
end_page_number
:
number


start_page_number
:
number

minimum
1
type
:
"page_location"


CitationContentBlockLocationParam
object
{
cited_text
,
document_index
,
document_title
,
3
more
}


cited_text
:
string

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

minimum
0

document_title
:
string
or
null

maxLength
500
minLength
1

end_block_index
:
number

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
:
number

0-based index of the first cited block in the source's
content
array.
minimum
0
type
:
"content_block_location"


CitationWebSearchResultLocationParam
object
{
cited_text
,
encrypted_index
,
title
,
2
more
}

cited_text
:
string

encrypted_index
:
string


title
:
string
or
null

maxLength
512
minLength
1
type
:
"web_search_result_location"


url
:
string

minLength
1

CitationSearchResultLocationParam
object
{
cited_text
,
end_block_index
,
search_result_index
,
4
more
}


cited_text
:
string

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
:
number

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
:
number

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.
minimum
0
source
:
string


start_block_index
:
number

0-based index of the first cited block in the source's
content
array.
minimum
0
title
:
string
or
null

type
:
"search_result_location"


thinking
:
optional
ThinkingConfigParam

Configuration for enabling Claude's extended thinking.
When enabled, responses include
thinking
content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your
max_tokens
limit.
See
extended thinking
for details.
One of the following:

tool_choice
:
optional
ToolChoice

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.
One of the following:

tools
:
optional
array of
ToolUnion

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 tool
input
shape that the model will produce in
tool_use
output 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.
One of the following:

Tool
object
{
input_schema
,
name
,
allowed_callers
,
7
more
}


ToolBash20250124
object
{
name
,
type
,
allowed_callers
,
4
more
}


CodeExecutionTool20250522
object
{
name
,
type
,
allowed_callers
,
3
more
}


CodeExecutionTool20250825
object
{
name
,
type
,
allowed_callers
,
3
more
}


CodeExecutionTool20260120
object
{
name
,
type
,
allowed_callers
,
3
more
}

Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).

CodeExecutionTool20260521
object
{
name
,
type
,
allowed_callers
,
3
more
}

Code execution tool with REPL state persistence.

BrowserToolset20260801
object
{
type
,
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.

MemoryTool20250818
object
{
name
,
type
,
allowed_callers
,
4
more
}


ComputerToolset20260801
object
{
type
,
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
.

ToolTextEditor20250124
object
{
name
,
type
,
allowed_callers
,
4
more
}


ToolTextEditor20250429
object
{
name
,
type
,
allowed_callers
,
4
more
}


ToolTextEditor20250728
object
{
name
,
type
,
allowed_callers
,
5
more
}


WebSearchTool20250305
object
{
name
,
type
,
allowed_callers
,
7
more
}


WebFetchTool20250910
object
{
name
,
type
,
allowed_callers
,
8
more
}


WebSearchTool20260209
object
{
name
,
type
,
allowed_callers
,
7
more
}


WebFetchTool20260209
object
{
name
,
type
,
allowed_callers
,
8
more
}


WebFetchTool20260309
object
{
name
,
type
,
allowed_callers
,
9
more
}

Web fetch tool with use_cache parameter for bypassing cached content.

WebSearchTool20260318
object
{
name
,
type
,
allowed_callers
,
8
more
}


WebFetchTool20260318
object
{
name
,
type
,
allowed_callers
,
10
more
}


ToolSearchToolBm25_20251119
object
{
name
,
type
,
allowed_callers
,
3
more
}


ToolSearchToolRegex20251119
object
{
name
,
type
,
allowed_callers
,
3
more
}


temperature
:
optional
number
⁠
Deprecated

Amount of randomness injected into the response.
Deprecated. Models released after Claude Opus 4.6 do not support setting temperature. A value of 1.0 of will be accepted for backwards compatibility, all other values will be rejected with a 400 error.
Defaults to
1.0
. Ranges from
0.0
to
1.0
. Use
temperature
closer to
0.0
for analytical / multiple choice, and closer to
1.0
for creative and generative tasks.
Note that even with
temperature
of
0.0
, the results will not be fully deterministic.
maximum
1
minimum
0

top_k
:
optional
number
⁠
Deprecated

Only sample from the top K options for each subsequent token.
Deprecated. Models released after Claude Opus 4.6 do not accept top_k; any value will be rejected with a 400 error.
Used to remove "long tail" low probability responses.
Learn more technical details here
.
Recommended for advanced use cases only.
minimum
0

top_p
:
optional
number
⁠
Deprecated

Use nucleus sampling.
Deprecated. Models released after Claude Opus 4.6 do not support setting top_p. A value >= 0.99 will be accepted for backwards compatibility, all other values will be rejected with a 400 error.
In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by
top_p
.
Recommended for advanced use cases only.
maximum
1
minimum
0
Returns

Message
object
{
id
,
container
,
content
,
7
more
}


RawMessageStreamEvent
=
RawMessageStartEvent
{
message
,
type
}
or
RawMessageDeltaEvent
{
delta
,
type
,
usage
}
or
RawMessageStopEvent
{
type
}
or
3
more

One of the following:

Create a Message
cURL


curl
https://api.anthropic.com/v1/messages
\
-H
'Content-Type: application/json'
\
-H
'anthropic-version: 2023-06-01'
\
-H
"X-Api-Key:
$ANTHROPIC_API_KEY
"
\
--max-time
600
\
-d
'{
"max_tokens": 1024,
"messages": [
{
"content": "Hello, world",
"role": "user"
}
],
"model": "claude-opus-5",
"stream": false,
"system": [
{
"text": "Today'
\'
's date is 2024-06-01.",
"type": "text"
}
],
"temperature": 1,
"thinking": {
"type": "adaptive"
},
"tools": [
{
"input_schema": {
"type": "object",
"properties": {
"location": "bar",
"unit": "bar"
},
"required": [
"location"
]
},
"name": "name"
}
],
"top_k": 5,
"top_p": 0.7
}'
Response 200

{
"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"
: [
{
"cited_text"
:
"The grass is green. The sky is blue."
,
"document_index"
:
0
,
"document_title"
:
"My Document"
,
"end_char_index"
:
0
,
"file_id"
:
"file_011CNha8iCJcU1wXNR6q4V8w"
,
"start_char_index"
:
0
,
"type"
:
"char_location"
}
],
"text"
:
"Hi! My name is Claude."
,
"type"
:
"text"
}
],
"model"
:
"claude-opus-5"
,
"role"
:
"assistant"
,
"stop_details"
: {
"category"
:
"cyber"
,
"explanation"
:
"This request was declined because it conflicts with Anthropic's Usage Policy."
,
"type"
:
"refusal"
},
"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"
}
}
Returns Examples
Response 200

{
"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"
: [
{
"cited_text"
:
"The grass is green. The sky is blue."
,
"document_index"
:
0
,
"document_title"
:
"My Document"
,
"end_char_index"
:
0
,
"file_id"
:
"file_011CNha8iCJcU1wXNR6q4V8w"
,
"start_char_index"
:
0
,
"type"
:
"char_location"
}
],
"text"
:
"Hi! My name is Claude."
,
"type"
:
"text"
}
],
"model"
:
"claude-opus-5"
,
"role"
:
"assistant"
,
"stop_details"
: {
"category"
:
"cyber"
,
"explanation"
:
"This request was declined because it conflicts with Anthropic's Usage Policy."
,
"type"
:
"refusal"
},
"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"
}
}
Claude Platform Docs


Solutions
AI agents
Code modernization
Coding
Customer support
Financial services
Government
Higher education
K-12 teachers
Life sciences
Partners
Claude on AWS
Claude on Google Cloud
Learn
Blog
Courses
Use cases
Connectors
Customer stories
Engineering at Anthropic
Events
Powered by Claude
Service partners
Startups program
Company
Anthropic
Careers
Economic Futures
Research
News
Responsible Scaling Policy
Security and compliance
Transparency
Learn
Blog
Courses
Use cases
Connectors
Customer stories
Engineering at Anthropic
Events
Powered by Claude
Service partners
Startups program
Help and security
Availability
Status
Support
Discord
Terms and policies
Privacy policy
Responsible disclosure policy
Terms of service: Commercial
Terms of service: Consumer
Usage policy
Ask Docs

