Claude Platform Docs

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-version": optional string

The version of the Claude API you want to use.

Read more about versioning and our version history here.

"anthropic-beta": optional array of AnthropicBeta

Optional header to specify the beta version(s) you want to use.

One of the following:
string
"computer-use-2024-10-22"
"computer-use-2025-01-24"
"output-128k-2025-02-19"
"mcp-client-2025-04-04"
"mcp-client-2025-11-20"
"dev-full-thinking-2025-05-14"
"interleaved-thinking-2025-05-14"
"code-execution-2025-05-22"
"context-1m-2025-08-07"
"context-management-2025-06-27"
"model-context-window-exceeded-2025-08-26"
"fast-mode-2026-02-01"
"output-300k-2026-03-24"
"user-profiles-2026-03-24"
"user-profiles-2026-08-18"
"user-profiles-2026-09-04"
"advisor-tool-2026-03-01"
"managed-agents-2026-04-01"
"dreaming-2026-04-21"
"thinking-token-count-2026-05-13"
"server-side-fallback-2026-06-01"
"server-side-fallback-2026-07-01"
"fallback-credit-2026-06-01"
"fallback-credit-2026-07-01"
"agent-memory-2026-07-22"
"mid-conversation-tool-changes-2026-07-01"
"compact-2026-01-12"
"computer-use-2025-11-24"
"mcp-tunnels-2026-06-22"
"structured-outputs-2025-11-13"
"task-budgets-2026-03-13"
"thinking-display-updates-2026-08-18"
"mid-conversation-output-config-2026-07-01"
"thinking-binding-controls-2026-08-01"
"mid-conversation-system-clear-at-2026-08-21"
"compact-2026-09-04"
"inline-tools-2026-09-15"
"mcp-client-2026-09-15"
"ce-plugins-2026-09-01"
"spend-limit-reads-2026-09-26"
"telemetry-destinations-2026-08-11"
"webhooks-2026-10-07"
"admin-user-sign-out-2026-10-08"
"message-threads-2026-08-12"
"analytics-usage-cost-2026-08-24"
"experimental-claude-tag-2026-10-21"
"user-profiles-billing-2026-10-01"
"message-batches-2024-09-24"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"prompt-caching-2024-07-31"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"pdfs-2024-09-25"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"token-counting-2024-11-01"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"token-efficient-tools-2025-02-19"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"files-api-2025-04-14"⁠Deprecated
Sending this value selects the beta response shapes. Removing it moves you to the current shapes, so follow the migration steps: https://platform.claude.com/docs/en/build-with-claude/files#migrate-from-files-api-2025-04-14
"extended-cache-ttl-2025-04-11"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"skills-2025-10-02"⁠Deprecated
Sending this value selects the beta response shapes. Removing it moves you to the current shapes, so follow the migration steps: https://platform.claude.com/docs/en/build-with-claude/skills-guide#migrate-from-skills-2025-10-02
"cache-diagnosis-2026-04-07"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"ce-user-management-2026-07-13"⁠Deprecated
This value is no longer needed. Remove it from your requests.
"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.

"anthropic-workspace-id": optional string

Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).

Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

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.

minimum0
messages: array of BetaMessageParam

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. This is called prefill. On models that don't support prefill, creating a message that ends with a partial assistant response returns a 400 error. See Prefill not supported.

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, for models that support prefill:

[
  {"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 a limit of 100,000 messages in a single request.

One of the following:
BetaUserMessageParam object{ content, role }
One of the following:
role: "user"
BetaAssistantMessageParam object{ content, role }
One of the following:
role: "assistant"
BetaSystemMessageParam object{ role, clear_at, content, output_config }
model: Model

The model that will complete your prompt.

See models for additional details and options.

One of the following:
billing_policy: optional BetaBillingPolicy { type: "billing_policy", bill_to } or null⁠

Declares which organization is billed for this request. {"type": "billing_policy", "bill_to": "user_profile"} bills the customer behind the user profile named in the anthropic-user-profile-id header, instead of your organization. If that customer has not linked an Anthropic organization to the profile, or has not allowed your organization to bill it, the request is rejected rather than billed to you. Omit the field, or send "bill_to": "self" (the default), to be billed as usual.

type: "billing_policy"
bill_to: optional BetaBillTo

Who is billed. self, the default, bills your organization, as if billing_policy were omitted. user_profile bills the customer behind the user profile the request names; if that customer has not linked an Anthropic organization to the profile, or has not allowed your organization to bill it, the request is rejected rather than billed to you.

One of the following:
"self"
"user_profile"
cache_control: optional BetaCacheControlEphemeral { type: "ephemeral", 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"
compaction: optional BetaCompactionConfig { type: "summarize", instructions } or null⁠

Compaction configuration.

When set on POST /v1/messages, the request is a compaction request: the conversation in messages is summarized and the response holds only the resulting compaction block (stop_reason "compaction"), which later requests send first in messages in place of the messages it summarizes. POST /v1/messages/count_tokens accepts this parameter and ignores it: the count it returns is for the conversation in messages as sent. Cannot be combined with context_management.

type: "summarize"
instructions: optional string or null

Replaces the server's default summarization prompt for this request. An empty or whitespace-only value counts as absent.

maxLength16384
container: optional BetaContainerParams or string or null

Container identifier for reuse across requests.

One of the following:
BetaContainerParams object{ id, skills }

Container parameters with skills to be loaded.

id: optional string or null

Container id

skills: optional array of BetaSkillParams { type, skill_id, version } or null

List of skills to load in the container

maxItems20
type: "anthropic" or "custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

One of the following:
"anthropic"
"custom"
skill_id: string

Skill ID

minLength1
maxLength64
version: optional string

Skill version or 'latest' for most recent version

minLength1
maxLength64
string
context_management: optional BetaContextManagementConfig { edits } or null⁠

Context management configuration.

This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not.

diagnostics: optional BetaDiagnosticsParam { previous_message_id } or null

Request-level diagnostics. Supply previous_message_id to have the response include diagnostics.cache_miss_reason explaining any prompt-cache divergence from that prior request.

previous_message_id: optional string or null

The id (msg_...) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns diagnostics.cache_miss_reason when the prompt-cache prefix could not be reused. Pass null on the first turn to opt in without a prior message to compare.

maxLength256
fallback_credit_token: optional string or BetaFallbackCreditTokenParam or null⁠

The fallback_credit_token from a prior refusal's stop_details.

When a preceding request was refused and returned a fallback_credit_token, pass that code here on the retry to have the retry's cache-creation tokens for the prefix that was warm on the refused model billed at the cache-read rate. Must be redeemed by the same organization and workspace, with the same request body (optionally extended by one appended assistant message whose content is the partial text — with any trailing whitespace stripped from the final text block — and paired server-tool blocks streamed before the refusal; the appended-assistant form is not available for requests with output_format set or forced tool_choice), on an eligible fallback model, on the same platform, and within 5 minutes of the refusal; a mismatch is a 400. A token minted mid-server-tool-loop whose partial content was continuable may only be redeemed with the appended-assistant form — if an exact-body retry is rejected with a 400 saying the token must be redeemed by continuing the partial response, retry with the appended-assistant form instead.

When the appended-assistant form is used on a model that otherwise disallows assistant-turn prefill, this token also authorizes that one prefill.

One of the following:
string
BetaFallbackCreditTokenParam object{ token, mode }

Object form of fallback_credit_token: the token plus a redemption mode.

Requires anthropic-beta: fallback-credit-2026-07-01; without that header the field accepts the bare string only. The bare string and the mode-less object are equivalent (both select strict), so wrapping an existing token changes nothing by itself.

token: string

The opaque fallback_credit_token from a prior refusal's stop_details — the same string the bare-string form carries.

minLength1
maxLength2048
mode: optional "strict" or "best_effort"

How a failing token affects the retry. strict (the default, and the bare-string behavior): a failing redemption is a 400 and the retry is not served. best_effort: the retry is served either way — a token-layer failure no longer rejects the request; the retry proceeds at normal price and the outcome is reported on the response's usage.fallback_credit. Two failures stay hard in both modes: a malformed token, and combining fallback_credit_token with fallbacks.

One of the following:
"strict"
"best_effort"
fallbacks: optional BetaFallbacksParam or null⁠

Opt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order: if the first entry also declines, the second is tried, and so on. Some models don't support fallbacks; on those models, a list of fallback models returns a 400 error. See Server-side fallback. The string "default" requests the requested model's server-defined default fallback configuration. On a model that doesn't support fallbacks, the request runs on the requested model alone, so a declined request stays declined.

One of the following:
inference_geo: optional string or null

Specifies the geographic region for inference processing. If not specified, the workspace's default_inference_geo is used.

mcp_servers: optional array of BetaRequestMCPServerURLDefinition { type: "url", name, url, 2 more }⁠

MCP servers to be utilized in this request

maxItems20
type: "url"
name: string
url: string
authorization_token: optional string or null
tool_configuration: optional BetaRequestMCPServerToolConfiguration { allowed_tools, enabled } or null
allowed_tools: optional array of string or null
enabled: optional boolean or null
metadata: optional BetaMetadata { 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.

maxLength512
output_config: optional BetaOutputConfig { effort, format, task_budget }

Configuration options for the model's output, such as the output format.

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"
speed: optional "standard" or "fast" or null

The inference speed mode for this request. "fast" enables high output-tokens-per-second inference.

Some models require the fast-mode-2026-02-01 beta header for any speed value. See fast mode for which models.

One of the following:
"standard"
"fast"
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. When true, SDKs return a raw event stream.

In the TypeScript, Python and Ruby SDKs, the recommended way to stream is messages.stream(). It sets stream for you and accumulates the events into the final message. See Streaming with SDKs for an example in each language.

system: optional string or array of BetaTextBlockParam

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 BetaTextBlockParam { type: "text", text, cache_control, citations }
type: "text"
text: string
minLength1
cache_control: optional BetaCacheControlEphemeral { type: "ephemeral", 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 BetaTextCitationParam or null
One of the following:
BetaCitationCharLocationParam object{ type: "char_location", cited_text, document_index, 3 more }
type: "char_location"
cited_text: string
document_index: number
minimum0
document_title: string or null
minLength1
maxLength500
end_char_index: number
start_char_index: number
minimum0
BetaCitationPageLocationParam object{ type: "page_location", cited_text, document_index, 3 more }
type: "page_location"
cited_text: string
document_index: number
minimum0
document_title: string or null
minLength1
maxLength500
end_page_number: number
start_page_number: number
minimum1
BetaCitationContentBlockLocationParam object{ type: "content_block_location", cited_text, document_index, 3 more }
type: "content_block_location"
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
minimum0
document_title: string or null
minLength1
maxLength500
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.

minimum0
BetaCitationWebSearchResultLocationParam object{ type: "web_search_result_location", cited_text, encrypted_index, 2 more }
type: "web_search_result_location"
cited_text: string
encrypted_index: string
title: string or null
minLength1
maxLength512
url: string
minLength1
BetaCitationSearchResultLocationParam object{ type: "search_result_location", cited_text, end_block_index, 4 more }
type: "search_result_location"
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.

minimum0
source: string
start_block_index: number

0-based index of the first cited block in the source's content array.

minimum0
title: string or null
thinking: optional BetaThinkingConfigParam

Configuration for Claude's thinking.

With {"type": "adaptive"}, Claude decides when and how much to think. With {"type": "enabled"} (manual extended thinking), you set a budget_tokens of at least 1,024. Thinking tokens count toward your max_tokens limit.

Which type values are accepted, and what happens when you omit thinking, depend on the model. See thinking for each model's behavior.

One of the following:
thread: optional BetaMessageThreadParam or null⁠

Server-held conversation state (a Thread). {"type": "create"} asks the server to hold this conversation's state under the response's id; {"type": "continue", "previous_message_id": ...} resumes from a previous response so only the new turn's messages are sent. The response shape is unchanged.

One of the following:
BetaThreadCreateParams object{ type: "create" }

Start holding conversation state under this response's id.

type: "create"
BetaThreadContinueParams object{ type: "continue", previous_message_id }

Resume from the response named by previous_message_id.

type: "continue"
previous_message_id: string

The id of the previous response in this Thread.

tool_choice: optional 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.

One of the following:
tools: optional array of BetaToolUnion

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:
BetaTool object{ type, input_schema, name, 7 more }
BetaToolBash20241022 object{ type: "bash_20241022", name, allowed_callers, 4 more }⁠
BetaToolBash20250124 object{ type: "bash_20250124", name, allowed_callers, 4 more }
BetaCodeExecutionTool20250522 object{ type: "code_execution_20250522", name, allowed_callers, 3 more }
BetaCodeExecutionTool20250825 object{ type: "code_execution_20250825", name, allowed_callers, 3 more }
BetaCodeExecutionTool20260120 object{ type: "code_execution_20260120", name, allowed_callers, 3 more }

A tools entry for the code execution tool, version code_execution_20260120. It adds REPL state persistence to version code_execution_20250825.

REPL state persistence applies with programmatic tool calling. With it, the Python interpreter state, such as variable bindings, persists across requests that reuse the container.

See the code execution tool guide to learn what each tool version adds.

BetaCodeExecutionTool20260521 object{ type: "code_execution_20260521", name, allowed_callers, 3 more }

Code execution tool with REPL state persistence.

BetaBrowserToolset20260801 object{ type: "browser_toolset_20260801", 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.

BetaToolComputerUse20241022 object{ type: "computer_20241022", display_height_px, display_width_px, 7 more }⁠
BetaMemoryTool20250818 object{ type: "memory_20250818", name, allowed_callers, 4 more }
BetaToolComputerUse20250124 object{ type: "computer_20250124", display_height_px, display_width_px, 7 more }⁠
BetaToolTextEditor20241022 object{ type: "text_editor_20241022", name, allowed_callers, 4 more }⁠
BetaToolComputerUse20251124 object{ type: "computer_20251124", display_height_px, display_width_px, 8 more }⁠
BetaComputerToolset20260801 object{ type: "computer_toolset_20260801", 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.

BetaToolTextEditor20250124 object{ type: "text_editor_20250124", name, allowed_callers, 4 more }
BetaToolTextEditor20250429 object{ type: "text_editor_20250429", name, allowed_callers, 4 more }
BetaToolTextEditor20250728 object{ type: "text_editor_20250728", name, allowed_callers, 5 more }
BetaWebSearchTool20250305 object{ type: "web_search_20250305", name, allowed_callers, 7 more }
BetaWebFetchTool20250910 object{ type: "web_fetch_20250910", name, allowed_callers, 9 more }
BetaWebSearchTool20260209 object{ type: "web_search_20260209", name, allowed_callers, 7 more }
BetaWebFetchTool20260209 object{ type: "web_fetch_20260209", name, allowed_callers, 9 more }
BetaWebFetchTool20260309 object{ type: "web_fetch_20260309", name, allowed_callers, 10 more }

Web fetch tool with use_cache parameter for bypassing cached content.

BetaWebSearchTool20260318 object{ type: "web_search_20260318", name, allowed_callers, 8 more }
BetaWebFetchTool20260318 object{ type: "web_fetch_20260318", name, allowed_callers, 11 more }
BetaAdvisorTool20260301 object{ type: "advisor_20260301", model, name, 7 more }⁠
BetaToolSearchToolBm25_20251119 object{ type, name, allowed_callers, 3 more }
BetaToolSearchToolRegex20251119 object{ type, name, allowed_callers, 3 more }
BetaMCPToolset object{ type: "mcp_toolset", mcp_server_name, cache_control, 3 more }⁠

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.

output_format: optional BetaJSONOutputFormat { type: "json_schema", schema } or null⁠Deprecated

Deprecated: Use output_config.format instead. See structured outputs

A schema to specify Claude's output format in responses. This parameter will be removed in a future release.

type: "json_schema"
schema: map[unknown]

The JSON schema of the format

Returns
BetaMessage object{ type: "message", id, container, 10 more }
One of the following:
Errors

Any method can also return the general HTTP errors.

Each code below is the value of error.details.error_code in the response body.

On a streaming call, the errors listed below apply when the API rejects the request before the stream starts. Once the stream has started, the response status is already 200, so a later error comes through the stream, with no status of its own. To identify it, use error.details.error_code if the error has one, and error.type if not.

error code available_tools_limit_exceededHTTP status 400

The tools available after a message exceed a limit on their number or their size.

error code claude_code_key_creator_not_memberHTTP status 400

The API key belongs to the Claude Code workspace, and the user who created it is no longer a member of the organization or of that workspace.

error code claude_code_version_too_oldHTTP status 400

The request comes from a Claude Code version older than the minimum that the requested model or the organization requires. Update Claude Code, then retry.

error code cmek_key_disabledHTTP status 400

The workspace's customer-managed encryption key is disabled or revoked. Re-enable the key, then retry.

error code cmek_key_network_blockedHTTP status 400

The key management service's network access controls blocked the request to the workspace's customer-managed encryption key. The key itself may be healthy.

error code compaction_block_ambiguousHTTP status 400

messages holds more than one compaction block with content. Send only the block the conversation returned last.

error code compaction_block_misplacedHTTP status 400

The compaction block is not the first block of the conversation, or is in a system message.

error code compaction_content_mismatchHTTP status 400

The compaction block's content differs from the text its signature recorded.

error code compaction_incomplete_turnHTTP status 400

The compaction request ends on an assistant turn that is not finished.

error code compaction_nothing_to_summarizeHTTP status 400

messages holds no user or assistant content to summarize or adopt.

error code compaction_signature_invalidHTTP status 400

The compaction block's signature does not verify.

error code compaction_too_many_tool_referencesHTTP status 400

The conversation references more distinct tools than a compaction block can record.

error code compaction_tool_changes_mismatchHTTP status 400

The compaction block's tool_changes differs from what was returned with the block.

error code organization_on_holdHTTP status 400

Anthropic has disabled the organization for trust and safety reasons. An organization disabled for any other reason, such as billing, does not get this code. appeal_url, when present, is where the organization can appeal.

error code request_body_encoding_invalidHTTP status 400

The request body is not valid for its Content-Encoding.

error code request_body_encoding_unsupportedHTTP status 400

The request's Content-Encoding is not supported.

error code thread_already_continuedHTTP status 400

The response that previous_message_id names has already been continued, and each response can be continued only once. Continue from the Thread's most recent response id.

error code thread_continue_in_flightHTTP status 400

Another request is still continuing from the same previous_message_id. Wait for it to complete and continue from its response id, or replay the full conversation with thread: {"type": "create"}.

error code thread_fingerprint_mismatchHTTP status 400

A field that must stay the same across a Thread's turns differs from the value stored with the Thread; the message names each such field. Send the stored values, or replay the full conversation with thread: {"type": "create"} to change them.

error code thread_unsupported_requestHTTP status 400

The request combines thread with a request field or an organization setting that Threads do not support; unsupported, when present, names it. Send the full conversation without thread, or change that field.

error code tool_name_conflictHTTP status 400

A tool made available in messages takes a name that an available tool of another kind, or of another MCP server, already holds.

error code tool_reference_unresolvedHTTP status 400

A tool change or MCP tool listing references a tool or MCP server that is not defined at that position in the conversation.

error code thread_not_foundHTTP status 404

No usable Thread state was found for previous_message_id. Replay the full conversation with thread: {"type": "create"} to start a new Thread.

error code skill_read_blocked_undecryptableHTTP status 409

A custom skill the request names is stored under an encryption key state the workspace cannot currently decrypt.

error code request_body_too_large_after_decodingHTTP status 413

The compressed request body exceeds the request size limit once decoded.

error code enforced_spend_limit_reachedHTTP status 429

The organization has crossed the monthly API usage threshold of its API tier.

error code ramp_limit_exceededHTTP status 429

The request would exceed a ramp limit, which caps how fast usage can grow. Retry after the time in the retry-after header.

error code cmek_key_unreachableHTTP status 503

The workspace's customer-managed encryption key could not be reached. Retry the request; if this continues, check that the key is available in your key management service, or contact Anthropic support.

error code compaction_unavailableHTTP status 529

The compaction could not be completed for a transient server reason. Retry the request.

Create a Message
curl https://api.anthropic.com/v1/messages \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2026-10-21' \
    -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
    --max-time 600 \
    -d '{
          "max_tokens": 1024,
          "messages": [
            {
              "content": "Hello, world",
              "role": "user"
            }
          ],
          "model": "claude-opus-5-5",
          "stream": false,
          "system": [
            {
              "text": "Today'\''s date is 2024-06-01.",
              "type": "text"
            }
          ],
          "thinking": {
            "type": "adaptive"
          },
          "tools": [
            {
              "input_schema": {
                "type": "object",
                "properties": {
                  "location": "bar",
                  "unit": "bar"
                },
                "required": [
                  "location"
                ]
              },
              "name": "name"
            }
          ]
        }'
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": null,
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "context_management": {
    "applied_edits": [
      {
        "cleared_input_tokens": 0,
        "cleared_tool_uses": 0,
        "type": "clear_tool_uses_20250919"
      }
    ]
  },
  "diagnostics": null,
  "model": "claude-opus-5-5",
  "role": "assistant",
  "stop_details": null,
  "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,
    "fallback_credit": {
      "status": {
        "type": "redeemed"
      }
    },
    "inference_geo": "global",
    "input_tokens": 2095,
    "iterations": [
      {
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 0
        },
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "input_tokens": 0,
        "model": "claude-fable-5-2",
        "output_tokens": 0,
        "type": "message"
      }
    ],
    "output_tokens": 503,
    "output_tokens_details": {
      "thinking_tokens": 0
    },
    "server_tool_use": {
      "web_fetch_requests": 2,
      "web_search_requests": 0
    },
    "service_tier": "standard",
    "speed": "standard"
  },
  "input_transformations": [
    {
      "path": "path",
      "reason": "model_binding_mismatch",
      "type": "thinking_dropped"
    }
  ]
}