POST
Send a Message

Overview

The /v1/messages endpoint is the core of the Claude API. Every interaction — basic messages, multi-turn conversations, streaming responses, and tool use — goes through this single endpoint.

Required Headers

Every request requires these three headers:
The anthropic-version header pins your integration to a specific API contract. 2023-06-01 is the current stable version. Always include it — requests without it return a 400 error.

Stop Reasons

Always check stop_reason before processing Claude’s output — a 200 OK does not guarantee a complete response:
Setting max_tokens too low causes silent truncation. A request with a very low max_tokens value returns a 200 OK with an empty content array and stop_reason: "max_tokens" — no error is thrown. Always check stop_reason to confirm a response is complete.

Error Reference

All errors follow the same structure:
Every error response includes a request_id field. If you contact Anthropic support about a failed request, this ID is what their team needs to investigate.

Further Reading

Messages

Understand the messages array and multi-turn context

Tokens

How tokens are counted and how they affect cost

System Prompts

Shape Claude’s behavior with system-level instructions

Tool Use

Connect Claude to real-time data and external services

Authorizations

x-api-key
string
header
required

Headers

anthropic-version
string
required
Example:

"2023-06-01"

Body

application/json
model
enum<string>
required

The Claude model to use.

Available options:
claude-sonnet-4-6,
claude-opus-4-6,
claude-haiku-4-5
Example:

"claude-sonnet-4-6"

max_tokens
integer
required

Maximum number of output tokens to generate.

Required range: x >= 1
Example:

1024

messages
object[]
required

Response

Successful response

id
string
Example:

"msg_01XFDUDYJgAACzvnptvVoYEL"

type
string
Example:

"message"

role
string
Example:

"assistant"

content
object[]
model
string
Example:

"claude-sonnet-4-6"

stop_reason
enum<string>
Available options:
end_turn,
max_tokens,
stop_sequence,
tool_use
Example:

"end_turn"

stop_details
object | null
usage
object