Create a Message

POST /v1/messages

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-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 CreateMessageParams {
model:

Model

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

;
messages:

InputMessage

interface InputMessage {
content: InputContentBlock[] | string;
role: "user" | "assistant";
}

[];
max_tokens: number;
metadata?:

Metadata

interface Metadata {
user_id?: string | null;
}

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

RequestTextBlock

interface RequestTextBlock {
cache_control?: CacheControlEphemeral | null;
citations?: (RequestCharLocationCitation | RequestPageLocationCitation | RequestContentBlockLocationCitation | RequestWebSearchResultLocationCitation | RequestSearchResultLocationCitation)[] | null;
text: string;
type: "text";
}

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

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.

type ThinkingConfigParam = ThinkingConfigEnabled | ThinkingConfigDisabled

;
tool_choice?:

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.

type ToolChoice = ToolChoiceAuto | ToolChoiceAny | ToolChoiceTool | ToolChoiceNone

;
tools?: (

Tool

interface Tool {
type?: "custom" | null;
description?: string;
name: string;
input_schema: InputSchema;
cache_control?: CacheControlEphemeral | null;
}

BashTool20250124

interface BashTool20250124 {
cache_control?: CacheControlEphemeral | null;
name: "bash";
type: "bash_20250124";
}

TextEditor20250124

interface TextEditor20250124 {
cache_control?: CacheControlEphemeral | null;
name: "str_replace_editor";
type: "text_editor_20250124";
}

TextEditor20250429

interface TextEditor20250429 {
cache_control?: CacheControlEphemeral | null;
name: "str_replace_based_edit_tool";
type: "text_editor_20250429";
}

TextEditor20250728

interface TextEditor20250728 {
cache_control?: CacheControlEphemeral | null;
max_characters?: number | null;
name: "str_replace_based_edit_tool";
type: "text_editor_20250728";
}

WebSearchTool20250305

interface WebSearchTool20250305 {
allowed_domains?: string[] | null;
blocked_domains?: string[] | null;
cache_control?: CacheControlEphemeral | null;
max_uses?: number | null;
name: "web_search";
type: "web_search_20250305";
user_location?: UserLocation | null;
}

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

Responses

200 application/json

Message object.

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

ContentBlock

[];
model:

Model

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

;
stop_reason:

StopReason

| null;
stop_sequence: string | null;
usage:

Usage

interface Usage {
cache_creation: CacheCreation | null;
cache_creation_input_tokens: number | null;
cache_read_input_tokens: number | null;
input_tokens: number;
output_tokens: number;
server_tool_use: ServerToolUsage | null;
service_tier: "standard" | "priority" | "batch" | null;
}

;
}

Client Errors

4XX application/json

Error response.

See our errors documentation for more details.

interface ErrorResponse {
error:

InvalidRequestError

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

AuthenticationError

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

BillingError

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

PermissionError

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

NotFoundError

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

RateLimitError

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

GatewayTimeoutError

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

APIError

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

OverloadedError

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

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