Create a Message

POST /v1/messages?beta=true

Copy endpoint

https://api.anthropic.com

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

header Header Parameters

Name	Type
`anthropic-beta` Optional header to specify the beta version(s) you want to use. To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.	string
`anthropic-version` The version of the Claude API you want to use. Read more about versioning and our version history here.	string

Request Body

application/json required

interface BetaCreateMessageParams {
model:

Model

The model that will complete your prompt.\n\nSee models for additional details and options.

;
messages:

BetaInputMessage

interface BetaInputMessage {
content: BetaInputContentBlock[] | string;
role: "user" | "assistant";
}

[];
container?:

BetaContainerParams

Container parameters with skills to be loaded.

interface BetaContainerParams {
id?: string | null;
skills?: BetaSkillParams[] | null;
}

| string | null;
context_management?:

BetaContextManagementConfig

interface BetaContextManagementConfig {
edits?: (BetaClearToolUses20250919 | BetaClearThinking20251015)[];
}

| null;
max_tokens: number;
mcp_servers?:

BetaRequestMCPServerURLDefinition

interface BetaRequestMCPServerURLDefinition {
authorization_token?: string | null;
name: string;
tool_configuration?: BetaRequestMCPServerToolConfiguration | null;
type: "url";
url: string;
}

[];
metadata?:

BetaMetadata

interface BetaMetadata {
user_id?: string | null;
}

;
output_config?:

BetaOutputConfig

interface BetaOutputConfig {
effort?: BetaEffortLevel | null;
}

;
output_format?:

BetaJsonOutputFormat

interface BetaJsonOutputFormat {
schema: { };
type: "json_schema";
}

| null;
service_tier?: "auto" | "standard_only";
stop_sequences?: string[];
stream?: boolean;
system?:

BetaRequestTextBlock

interface BetaRequestTextBlock {
cache_control?: BetaCacheControlEphemeral | null;
citations?: (BetaRequestCharLocationCitation | BetaRequestPageLocationCitation | BetaRequestContentBlockLocationCitation | BetaRequestWebSearchResultLocationCitation | BetaRequestSearchResultLocationCitation)[] | null;
text: string;
type: "text";
}

[] | string;
temperature?: number;
thinking?:

BetaThinkingConfigParam

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.

type BetaThinkingConfigParam = BetaThinkingConfigEnabled | BetaThinkingConfigDisabled

;
tool_choice?:

BetaToolChoice

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.

type BetaToolChoice = BetaToolChoiceAuto | BetaToolChoiceAny | BetaToolChoiceTool | BetaToolChoiceNone

;
tools?: (

BetaTool

interface BetaTool {
type?: "custom" | null;
description?: string;
name: string;
input_schema: BetaInputSchema;
cache_control?: BetaCacheControlEphemeral | null;
strict?: boolean;
allowed_callers?: ("direct" | "code_execution_20250825")[];
defer_loading?: boolean;
input_examples?: { }[];
}

BetaBashTool20241022

interface BetaBashTool20241022 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
input_examples?: { }[];
name: "bash";
strict?: boolean;
type: "bash_20241022";
}

BetaBashTool20250124

interface BetaBashTool20250124 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
input_examples?: { }[];
name: "bash";
strict?: boolean;
type: "bash_20250124";
}

BetaCodeExecutionTool20250522

interface BetaCodeExecutionTool20250522 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
name: "code_execution";
strict?: boolean;
type: "code_execution_20250522";
}

BetaCodeExecutionTool20250825

interface BetaCodeExecutionTool20250825 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
name: "code_execution";
strict?: boolean;
type: "code_execution_20250825";
}

BetaComputerUseTool20241022

interface BetaComputerUseTool20241022 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
display_height_px: number;
display_number?: number | null;
display_width_px: number;
input_examples?: { }[];
name: "computer";
strict?: boolean;
type: "computer_20241022";
}

BetaMemoryTool20250818

interface BetaMemoryTool20250818 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
input_examples?: { }[];
name: "memory";
strict?: boolean;
type: "memory_20250818";
}

BetaComputerUseTool20250124

interface BetaComputerUseTool20250124 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
display_height_px: number;
display_number?: number | null;
display_width_px: number;
input_examples?: { }[];
name: "computer";
strict?: boolean;
type: "computer_20250124";
}

BetaTextEditor20241022

interface BetaTextEditor20241022 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
input_examples?: { }[];
name: "str_replace_editor";
strict?: boolean;
type: "text_editor_20241022";
}

BetaComputerUseTool20251124

interface BetaComputerUseTool20251124 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
display_height_px: number;
display_number?: number | null;
display_width_px: number;
enable_zoom?: boolean;
input_examples?: { }[];
name: "computer";
strict?: boolean;
type: "computer_20251124";
}

BetaTextEditor20250124

interface BetaTextEditor20250124 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
input_examples?: { }[];
name: "str_replace_editor";
strict?: boolean;
type: "text_editor_20250124";
}

BetaTextEditor20250429

interface BetaTextEditor20250429 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
input_examples?: { }[];
name: "str_replace_based_edit_tool";
strict?: boolean;
type: "text_editor_20250429";
}

BetaTextEditor20250728

interface BetaTextEditor20250728 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
input_examples?: { }[];
max_characters?: number | null;
name: "str_replace_based_edit_tool";
strict?: boolean;
type: "text_editor_20250728";
}

BetaWebSearchTool20250305

interface BetaWebSearchTool20250305 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
allowed_domains?: string[] | null;
blocked_domains?: string[] | null;
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
max_uses?: number | null;
name: "web_search";
strict?: boolean;
type: "web_search_20250305";
user_location?: BetaUserLocation | null;
}

BetaWebFetchTool20250910

interface BetaWebFetchTool20250910 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
allowed_domains?: string[] | null;
blocked_domains?: string[] | null;
cache_control?: BetaCacheControlEphemeral | null;
citations?: BetaRequestCitationsConfig | null;
defer_loading?: boolean;
max_content_tokens?: number | null;
max_uses?: number | null;
name: "web_fetch";
strict?: boolean;
type: "web_fetch_20250910";
}

BetaToolSearchToolBM2520251119

interface BetaToolSearchToolBM2520251119 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
name: "tool_search_tool_bm25";
strict?: boolean;
type: "tool_search_tool_bm25_20251119" | "tool_search_tool_bm25";
}

BetaToolSearchToolRegex20251119

interface BetaToolSearchToolRegex20251119 {
allowed_callers?: ("direct" | "code_execution_20250825")[];
cache_control?: BetaCacheControlEphemeral | null;
defer_loading?: boolean;
name: "tool_search_tool_regex";
strict?: boolean;
type: "tool_search_tool_regex_20251119" | "tool_search_tool_regex";
}

BetaMCPToolset

Configuration for a group of tools from an MCP server.

Allows configuring enabled status and defer_loading for all tools from an MCP server, with optional per-tool overrides.

interface BetaMCPToolset {
cache_control?: BetaCacheControlEphemeral | null;
configs?: { } | null;
default_config?: BetaMCPToolDefaultConfig;
mcp_server_name: string;
type: "mcp_toolset";
}

)[];
top_k?: number;
top_p?: number;
}

Responses

200 application/json

Message object.

interface BetaMessage {
id: string;
type: "message";
role: "assistant";
content:

BetaContentBlock

[];
model:

Model

The model that will complete your prompt.\n\nSee models for additional details and options.

;
stop_reason:

BetaStopReason

| null;
stop_sequence: string | null;
usage:

BetaUsage

interface BetaUsage {
cache_creation: BetaCacheCreation | null;
cache_creation_input_tokens: number | null;
cache_read_input_tokens: number | null;
input_tokens: number;
output_tokens: number;
server_tool_use: BetaServerToolUsage | null;
service_tier: "standard" | "priority" | "batch" | null;
}

;
context_management:

BetaResponseContextManagement

interface BetaResponseContextManagement {
applied_edits: (BetaResponseClearToolUses20250919Edit | BetaResponseClearThinking20251015Edit)[];
}

| null;
container:

BetaContainer

Information about the container used in the request (for the code execution tool)

interface BetaContainer {
expires_at: string;
id: string;
skills: BetaSkill[] | null;
}

| null;
}

Client Errors

4XX application/json

Error response.

See our errors documentation for more details.

interface BetaErrorResponse {
error:

BetaInvalidRequestError

interface BetaInvalidRequestError {
message: string;
type: "invalid_request_error";
}

BetaAuthenticationError

interface BetaAuthenticationError {
message: string;
type: "authentication_error";
}

BetaBillingError

interface BetaBillingError {
message: string;
type: "billing_error";
}

BetaPermissionError

interface BetaPermissionError {
message: string;
type: "permission_error";
}

BetaNotFoundError

interface BetaNotFoundError {
message: string;
type: "not_found_error";
}

BetaRateLimitError

interface BetaRateLimitError {
message: string;
type: "rate_limit_error";
}

BetaGatewayTimeoutError

interface BetaGatewayTimeoutError {
message: string;
type: "timeout_error";
}

BetaAPIError

interface BetaAPIError {
message: string;
type: "api_error";
}

BetaOverloadedError

interface BetaOverloadedError {
message: string;
type: "overloaded_error";
}

;
request_id: string | null;
type: "error";
}