Skip to main content
POST
Use POST /v1/messages to send Claude requests in the Anthropic Messages format. The examples configure the official Anthropic SDK with the CometAPI base URL and read your API key from $COMETAPI_KEY.
For field definitions and model-specific options, see the official Messages API reference. For OpenAI-compatible requests, see Chat Completions.
Authenticate with x-api-key or Authorization: Bearer. The Anthropic SDK uses x-api-key. The HTTP examples include anthropic-version: 2023-06-01.

Quick start

The following examples request three search queries. Set $COMETAPI_KEY before running them. Install anthropic for Python or @anthropic-ai/sdk for JavaScript:
The response contains a content array. Read blocks whose type is text; thinking and tool blocks can appear before the text.

Control adaptive thinking

Set thinking.type to adaptive and choose an output_config.effort value. The following example uses xhigh and reads the completed message from a stream:
Thinking contributes to the max_tokens output limit. Leave room for the final answer as well as thinking. A response can contain text without a visible thinking block. Preserve any returned thinking blocks unchanged in conversation history. For the model-specific thinking configuration, see Thinking. The examples omit temperature, top_p, and top_k; consult the selected model’s parameter documentation before adding sampling controls.

Cache prompts

Place a cache breakpoint on reference material that you reuse between requests. Save your reference material in a UTF-8 reference.txt file before running this example. Use a prefix that meets the selected model’s minimum cacheable length:
Run the request again with the same model, reference text, and thinking settings. Inspect the usage counters to determine whether the request reused a prefix:
  • cache_creation_input_tokens counts tokens written to the cache.
  • cache_read_input_tokens counts tokens read from the cache.
  • input_tokens counts input processed outside those cache counters.
On repeated requests, cache_read_input_tokens reports how many input tokens were read from the cache. The OpenAPI Prompt Cache example contains a complete fictional reference that you can save as reference.txt to try the sample.

Stream responses

Set stream: true for Server-Sent Events. The SDK exposes text fragments as they arrive:
A message stream contains message_start, content block events, message_delta, and message_stop. Content blocks can contain text, thinking, or tool activity. For a text block, content_block_delta contains a text_delta. Read final usage and the stop reason from message_delta.

Control effort

Set output_config.effort to guide the amount of reasoning. This example uses low for a short explanation and waits for the completed streamed message:
Use the official effort reference to choose an effort level. Set max_tokens separately to limit output length.

Use server tools

Server tools execute during the API request and return result blocks alongside Claude’s answer.
Fetch a paper and ask Claude to use the retrieved document in its answer. This example streams the response and inspects both the final text and the web_fetch_tool_result block:
The response pairs a server_tool_use block with a web_fetch_tool_result containing the fetched document or a tool error.

Return client tool results

For a client tool, Claude returns a tool_use block. Run your application function and send its result in a tool_result block with the matching tool_use_id. Preserve the complete assistant content between the two requests. This example supplies a fictional order result and asks Claude to use that result:

Response example

A non-streaming request returns a message object. The following example shows its text and usage fields with an illustrative message identifier:
The stop reason describes the next action. end_turn completes the answer, max_tokens means output reached the limit, and tool_use requests a client tool result. For a server-tool turn that returns pause_turn, continue with the returned assistant content unchanged.

Authorizations

x-api-key
string
header
required

Your CometAPI key passed via the x-api-key header. Authorization: Bearer $COMETAPI_KEY is also supported.

Headers

anthropic-version
string
default:2023-06-01

The Anthropic API version to use. Defaults to 2023-06-01.

Example:

"2023-06-01"

anthropic-beta
string

Comma-separated feature identifiers required by a specific beta API feature. Omit this header for the examples on this page.

Body

application/json
model
string
default:claude-opus-5
required

The Claude model to use. See the Models page for available Claude model IDs.

Example:

"claude-opus-5"

messages
object[]
required

Conversation history. Use user and assistant messages with text strings or content-block arrays. Return complete assistant content blocks when continuing a tool call.

max_tokens
integer
required

The maximum number of tokens to generate. The model may stop before reaching this limit. When using thinking, the thinking tokens count towards this limit.

Required range: x >= 1
Example:

1024

system

System prompt providing context and instructions to Claude. Can be a plain string or an array of content blocks (useful for prompt caching).

temperature
number

Sampling temperature. The examples omit sampling overrides.

Required range: 0 <= x <= 1
top_p
number

Nucleus sampling threshold. The examples omit sampling overrides.

Required range: 0 <= x <= 1
top_k
integer

Limits sampling to the k most likely tokens. The examples omit sampling overrides.

Required range: x >= 0
stream
boolean
default:false

If true, stream the response incrementally using Server-Sent Events (SSE). Events include message_start, content_block_start, content_block_delta, content_block_stop, message_delta, and message_stop.

stop_sequences
string[]

Custom strings that cause the model to stop generating when encountered. The stop sequence is not included in the response.

thinking
object

Thinking configuration. The adaptive example uses type adaptive and sets output_config.effort separately.

tools
object[]

Client tools define a name and input_schema. Server tools use a versioned type and name, such as the web_fetch and web_search examples on this page.

tool_choice
object

Controls how the model uses tools.

metadata
object

Request metadata for tracking and analytics.

output_config
object

Configuration for reasoning effort and structured output.

service_tier
enum<string>

The service tier to use. auto tries priority capacity first, standard_only uses only standard capacity.

Available options:
auto,
standard_only

Response

Successful response. When stream is true, the response is a stream of SSE events.

id
string

Message identifier returned by the API.

type
enum<string>

Always message.

Available options:
message
role
enum<string>

Always assistant.

Available options:
assistant
content
object[]

The response content blocks. May include text, thinking, tool_use, and other block types.

model
string

Model ID reported by the response.

stop_reason
enum<string>

Why the model stopped generating. refusal can be returned as a successful HTTP response when the model declines a request.

Available options:
end_turn,
max_tokens,
stop_sequence,
tool_use,
pause_turn,
refusal
stop_sequence
string | null

The stop sequence that caused the model to stop, if applicable.

usage
object

Token usage statistics.

Last modified on September 7, 2026