---
title: "Create a new message conversation with Claude"
method: POST
path: "/v1/messages"
---

# Create a new message conversation with Claude

`POST /v1/messages`

Sends a message or a series of messages to Claude and retrieves a response, optionally including thinking traces.

## Request body

- MessageRequest
  - `model` string, required — The Claude model to use (e.g., claude-3-5-sonnet-20241022).
  - `messages` Message[], required — List of messages in the conversation, starting with a user message.
    - `role` 'user' | 'assistant', required — The role of the message sender.
    - `content` string, required — The content of the message.
  - `max_tokens` integer, required — Maximum number of tokens to generate in the response.
  - `temperature` number — Controls randomness of the response (0 to 1). Lower for analytical, higher for creative tasks.
  - `system` string — Optional system prompt to set context or instructions for Claude.
  - `top_p` number — Nucleus sampling parameter (0 to 1).
  - `top_k` integer — Only sample from the top K options for each token.
  - `thinking` object — Whether to include the thinking trace in the response (if supported by the model).
    - `type` 'enabled' | 'disabled'
    - `budget_tokens` integer — Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than max_tokens.

## Response `200`

Successful response with Claude's reply and optional thinking trace

- MessageResponse
  - `id` string — Unique identifier for the message response.
  - `type` string — Type of response, always "message" for this endpoint.
  - `role` string — Role of the responder, always "assistant".
  - `content` object[] — The generated content from Claude.
    - `type` string
    - `text` string

## Other responses

- `400` — Bad request - invalid parameters or malformed JSON
- `401` — Unauthorized - invalid or missing API key
- `429` — Too Many Requests - rate limit exceeded
- `500` — Internal Server Error

## Changes

- **2025-05-27** `d04c63884a9a` — 3 warning
  - removed the optional property `stop_reason` from the response with the `200` status
  - removed the optional property `thinking` from the response with the `200` status
  - removed the optional property `usage` from the response with the `200` status
- **2025-02-27** `36c4e3ff1d48` — 3 info
  - added the optional property `stop_reason` to the response with the `200` status
  - added the optional property `thinking` to the response with the `200` status
  - added the optional property `usage` to the response with the `200` status

[Change history](https://skmtc.dev/mmhk/apis/anthropic-claude-messages-api/changes/v1/messages/post.md)

---

[API](https://skmtc.dev/mmhk/apis/anthropic-claude-messages-api.md) · [All operations](https://skmtc.dev/mmhk/apis/anthropic-claude-messages-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mmhk/apis/anthropic-claude-messages-api/revisions/c8f805608547?raw)