Claude API DOCS

Using the API
Getting started
​
Accessing the API
The API is made available via our web Console. You can use the Workbench to try out the API in the browser and then generate API keys in Account Settings. Use workspaces to segment your API keys and control spend by use case.

​
Authentication
All requests to the Anthropic API must include an x-api-key header with your API key. If you are using the Client SDKs, you will set the API when constructing a client, and then the SDK will send the header on your behalf with every request. If integrating directly with the API, you’ll need to send this header yourself.

​
Content types
The Anthropic API always accepts JSON in request bodies and returns JSON in response bodies. You will need to send the content-type: application/json header in requests. If you are using the Client SDKs, this will be taken care of automatically.

​
Response Headers
The Anthropic API includes the following headers in every response:

request-id: A globally unique identifier for the request.

anthropic-organization-id: The organization ID associated with the API key used in the request.

​
Examples
curl
Python
TypeScript
Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}'
Was this page helpful?


Yes

No
IP addresses
x
linkedin

Using the API
IP addresses
Anthropic services live at a fixed range of IP addresses. You can add these to your firewall to open the minimum amount of surface area for egress traffic when accessing the Anthropic API and Console. These ranges will not change without notice.

​
IPv4
160.79.104.0/23

​
IPv6
2607:6bc0::/48

Was this page helpful?


Yes

No
Getting started
Versions
x
linkedin

Using the API
Versions
When making API requests, you must send an anthropic-version request header. For example, anthropic-version: 2023-06-01. If you are using our client libraries, this is handled for you automatically.

For any given API version, we will preserve:

Existing input parameters
Existing output parameters
However, we may do the following:

Add additional optional inputs
Add additional values to the output
Change conditions for specific error types
Add new variants to enum-like output values (for example, streaming event types)
Generally, if you are using the API as documented in this reference, we will not break your usage.

​
Version history
We always recommend using the latest API version whenever possible. Previous versions are considered deprecated and may be unavailable for new users.

2023-06-01
New format for streaming server-sent events (SSE):
Completions are incremental. For example, " Hello", " my", " name", " is", " Claude." instead of " Hello", " Hello my", " Hello my name", " Hello my name is", " Hello my name is Claude.".
All events are named events, rather than data-only events.
Removed unnecessary data: [DONE] event.
Removed legacy exception and truncated values in responses.
2023-01-01: Initial release.

Using the API
Errors
​
HTTP errors
Our API follows a predictable HTTP error code format:

400 - invalid_request_error: There was an issue with the format or content of your request. We may also use this error type for other 4XX status codes not listed below.

401 - authentication_error: There’s an issue with your API key.

403 - permission_error: Your API key does not have permission to use the specified resource.

404 - not_found_error: The requested resource was not found.

413 - request_too_large: Request exceeds the maximum allowed number of bytes.

429 - rate_limit_error: Your account has hit a rate limit.

500 - api_error: An unexpected error has occurred internal to Anthropic’s systems.

529 - overloaded_error: Anthropic’s API is temporarily overloaded.

Sudden large increases in usage may lead to an increased rate of 529 errors. We recommend ramping up gradually and maintaining consistent usage patterns.

When receiving a streaming response via SSE, it’s possible that an error can occur after returning a 200 response, in which case error handling wouldn’t follow these standard mechanisms.

​
Error shapes
Errors are always returned as JSON, with a top-level error object that always includes a type and message value. For example:

JSON

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  }
}
In accordance with our versioning policy, we may expand the values within these objects, and it is possible that the type values will grow over time.

​
Request id
Every API response includes a unique request-id header. This header contains a value such as req_018EeWyXxfu5pfWkrYcMdjWG. When contacting support about a specific request, please include this ID to help us quickly resolve your issue.

Our official SDKs provide this value as a property on top-level response objects, containing the value of the x-request-id header:


Python

TypeScript

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)
print(f"Request ID: {message._request_id}")
​
Long requests
We highly encourage using the streaming Messages API or Message Batches API for long running requests, especially those over 10 minutes.

We do not recommend setting a large max_tokens values without using our streaming Messages API or Message Batches API:

Some networks may drop idle connections after a variable period of time, which can cause the request to fail or timeout without receiving a response from Anthropic.
Networks differ in reliablity; our Message Batches API can help you manage the risk of network issues by allowing you to poll for results rather than requiring an uninterrupted network connection.
If you are building a direct API integration, you should be aware that setting a TCP socket keep-alive can reduce the impact of idle connection timeouts on some networks.

Our SDKs will validate that your non-streaming Messages API requests are not expected to exceed a 10 minute timeout and also will set a socket option for TCP keep-alive.

Using the API
Rate limits
To mitigate misuse and manage capacity on our API, we have implemented limits on how much an organization can use the Claude API.

We have two types of limits:

Spend limits set a maximum monthly cost an organization can incur for API usage.
Rate limits set the maximum number of API requests an organization can make over a defined period of time.
We enforce service-configured limits at the organization level, but you may also set user-configurable limits for your organization’s workspaces.

​
About our limits
Limits are designed to prevent API abuse, while minimizing impact on common customer usage patterns.
Limits are defined by usage tier, where each tier is associated with a different set of spend and rate limits.
Your organization will increase tiers automatically as you reach certain thresholds while using the API. Limits are set at the organization level. You can see your organization’s limits in the Limits page in the Anthropic Console.
You may hit rate limits over shorter time intervals. For instance, a rate of 60 requests per minute (RPM) may be enforced as 1 request per second. Short bursts of requests at a high volume can surpass the rate limit and result in rate limit errors.
The limits outlined below are our standard limits. If you’re seeking higher, custom limits, contact sales through the Anthropic Console.
We use the token bucket algorithm to do rate limiting. This means that your capacity is continuously replenished up to your maximum limit, rather than being reset at fixed intervals.
All limits described here represent maximum allowed usage, not guaranteed minimums. These limits are intended to reduce unintentional overspend and ensure fair distribution of resources among users.
​
Spend limits
Each usage tier has a limit on how much you can spend on the API each calendar month. Once you reach the spend limit of your tier, until you qualify for the next tier, you will have to wait until the next month to be able to use the API again.

To qualify for the next tier, you must meet a deposit requirement. To minimize the risk of overfunding your account, you cannot deposit more than your monthly spend limit.

​
Requirements to advance tier
Usage Tier	Credit Purchase	Max Usage per Month
Tier 1	$5	$100
Tier 2	$40	$500
Tier 3	$200	$1,000
Tier 4	$400	$5,000
Monthly Invoicing	N/A	N/A
​
Rate limits
Our rate limits for the Messages API are measured in requests per minute (RPM), input tokens per minute (ITPM), and output tokens per minute (OTPM) for each model class. If you exceed any of the rate limits you will get a 429 error describing which rate limit was exceeded, along with a retry-after header indicating how long to wait.

ITPM rate limits are estimated at the beginning of each request, and the estimate is adjusted during the request to reflect the actual number of input tokens used. The final adjustment counts input_tokens and cache_creation_input_tokens towards ITPM rate limits, while cache_read_input_tokens are not (though they are still billed). In some instances, cache_read_input_tokens are counted towards ITPM rate limits.

OTPM rate limits are estimated based on max_tokens at the beginning of each request, and the estimate is adjusted at the end of the request to reflect the actual number of output tokens used. If you’re hitting OTPM limits earlier than expected, try reducing max_tokens to better approximate the size of your completions.

Rate limits are applied separately for each model; therefore you can use different models up to their respective limits simultaneously. You can check your current rate limits and behavior in the Anthropic Console.

Tier 1
Tier 2
Tier 3
Tier 4
Custom
Model	Maximum requests per minute (RPM)	Maximum input tokens per minute (ITPM)	Maximum output tokens per minute (OTPM)
Claude 3.7 Sonnet	50	20,000	8,000
Claude 3.5 Sonnet
2024-10-22	50	40,000*	8,000
Claude 3.5 Sonnet
2024-06-20	50	40,000*	8,000
Claude 3.5 Haiku	50	50,000*	10,000
Claude 3 Opus	50	20,000*	4,000
Claude 3 Sonnet	50	40,000*	8,000
Claude 3 Haiku	50	50,000*	10,000
Limits marked with asterisks (*) count cache_read_input_tokens towards ITPM usage.

​
Message Batches API
The Message Batches API has its own set of rate limits which are shared across all models. These include a requests per minute (RPM) limit to all API endpoints and a limit on the number of batch requests that can be in the processing queue at the same time. A “batch request” here refers to part of a Message Batch. You may create a Message Batch containing thousands of batch requests, each of which count towards this limit. A batch request is considered part of the processing queue when it has yet to be successfully processed by the model.

Tier 1
Tier 2
Tier 3
Tier 4
Custom
Maximum requests per minute (RPM)	Maximum batch requests in processing queue	Maximum batch requests per batch
50	100,000	100,000
​
Setting lower limits for Workspaces
In order to protect Workspaces in your Organization from potential overuse, you can set custom spend and rate limits per Workspace.

Example: If your Organization’s limit is 40,000 input tokens per minute and 8,000 output tokens per minute, you might limit one Workspace to 30,000 total tokens per minute. This protects other Workspaces from potential overuse and ensures a more equitable distribution of resources across your Organization. The remaining unused tokens per minute (or more, if that Workspace doesn’t use the limit) are then available for other Workspaces to use.

Note:

You can’t set limits on the default Workspace.
If not set, Workspace limits match the Organization’s limit.
Organization-wide limits always apply, even if Workspace limits add up to more.
Support for input and output token limits will be added to Workspaces in the future.
​
Response headers
The API response includes headers that show you the rate limit enforced, current usage, and when the limit will be reset.

The following headers are returned:

Header	Description
retry-after	The number of seconds to wait until you can retry the request. Earlier retries will fail.
anthropic-ratelimit-requests-limit	The maximum number of requests allowed within any rate limit period.
anthropic-ratelimit-requests-remaining	The number of requests remaining before being rate limited.
anthropic-ratelimit-requests-reset	The time when the request rate limit will be fully replenished, provided in RFC 3339 format.
anthropic-ratelimit-tokens-limit	The maximum number of tokens allowed within any rate limit period.
anthropic-ratelimit-tokens-remaining	The number of tokens remaining (rounded to the nearest thousand) before being rate limited.
anthropic-ratelimit-tokens-reset	The time when the token rate limit will be fully replenished, provided in RFC 3339 format.
anthropic-ratelimit-input-tokens-limit	The maximum number of input tokens allowed within any rate limit period.
anthropic-ratelimit-input-tokens-remaining	The number of input tokens remaining (rounded to the nearest thousand) before being rate limited.
anthropic-ratelimit-input-tokens-reset	The time when the input token rate limit will be fully replenished, provided in RFC 3339 format.
anthropic-ratelimit-output-tokens-limit	The maximum number of output tokens allowed within any rate limit period.
anthropic-ratelimit-output-tokens-remaining	The number of output tokens remaining (rounded to the nearest thousand) before being rate limited.
anthropic-ratelimit-output-tokens-reset	The time when the output token rate limit will be fully replenished, provided in RFC 3339 format.
The anthropic-ratelimit-tokens-* headers display the values for the most restrictive limit currently in effect. For instance, if you have exceeded the Workspace per-minute token limit, the headers will contain the Workspace per-minute token rate limit values. If Workspace limits do not apply, the headers will return the total tokens remaining, where total is the sum of input and output tokens. This approach ensures that you have visibility into the most relevant constraint on your current API usage.

Using the API
Client SDKs
We provide libraries in Python and TypeScript that make it easier to work with the Anthropic API.

Additional configuration is needed to use Anthropic’s Client SDKs through a partner platform. If you are using Amazon Bedrock, see this guide; if you are using Google Cloud Vertex AI, see this guide.

​
Python
Python library GitHub repo

Example:

Python

import anthropic

client = anthropic.Anthropic(
    # defaults to os.environ.get("ANTHROPIC_API_KEY")
    api_key="my_api_key",
)
message = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)
print(message.content)
​
TypeScript
TypeScript library GitHub repo

While this library is in TypeScript, it can also be used in JavaScript libraries.

Example:

TypeScript

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: 'my_api_key', // defaults to process.env["ANTHROPIC_API_KEY"]
});

const msg = await anthropic.messages.create({
  model: "claude-3-7-sonnet-20250219",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});
console.log(msg);
​
Java
Java library GitHub repo

Example:

Java

import com.anthropic.models.Message;
import com.anthropic.models.MessageCreateParams;
import com.anthropic.models.Model;

MessageCreateParams params = MessageCreateParams.builder()
    .maxTokens(1024L)
    .addUserMessage("Hello, Claude")
    .model(Model.CLAUDE_3_7_SONNET)
    .build();
Message message = client.messages().create(params);
​
Go
Go library GitHub repo

The Anthropic Go SDK is currently in beta. If you see any issues with it, please file an issue on GitHub!

Example:

Go

package main

import (
	"context"
	"fmt"
	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
	client := anthropic.NewClient(
		option.WithAPIKey("my-anthropic-api-key"),
	)
	message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     anthropic.F(anthropic.ModelClaude3_7Sonnet),
		MaxTokens: anthropic.F(int64(1024)),
		Messages: anthropic.F([]anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("What is a quaternion?")),
		}),
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", message.Content)
}

Using the API
Supported regions
Here are the countries, regions, and territories we can currently support access from:

Albania
Algeria
Andorra
Angola
Antigua and Barbuda
Argentina
Armenia
Australia
Austria
Azerbaijan
Bahamas
Bahrain
Bangladesh
Barbados
Belgium
Belize
Benin
Bhutan
Bolivia
Bosnia and Herzegovina
Botswana
Brazil
Brunei
Bulgaria
Burkina Faso
Burundi
Cabo Verde
Cambodia
Cameroon
Canada
Chad
Chile
Colombia
Comoros
Congo, Republic of the
Costa Rica
Côte d’Ivoire
Croatia
Cyprus
Czechia (Czech Republic)
Denmark
Djibouti
Dominica
Dominican Republic
Ecuador
Egypt
El Salvador
Equatorial Guinea
Estonia
Eswatini
Fiji
Finland
France
Gabon
Gambia
Georgia
Germany
Ghana
Greece
Grenada
Guatemala
Guinea
Guinea-Bissau
Guyana
Haiti
Holy See (Vatican City)
Honduras
Hungary
Iceland
India
Indonesia
Iraq
Ireland
Israel
Italy
Jamaica
Japan
Jordan
Kazakhstan
Kenya
Kiribati
Kuwait
Kyrgyzstan
Laos
Latvia
Lebanon
Lesotho
Liberia
Liechtenstein
Lithuania
Luxembourg
Madagascar
Malawi
Malaysia
Maldives
Malta
Marshall Islands
Mauritania
Mauritius
Mexico
Micronesia
Moldova
Monaco
Mongolia
Montenegro
Morocco
Mozambique
Namibia
Nauru
Nepal
Netherlands
New Zealand
Niger
Nigeria
North Macedonia
Norway
Oman
Pakistan
Palau
Palestine
Panama
Papua New Guinea
Paraguay
Peru
Philippines
Poland
Portugal
Qatar
Romania
Rwanda
Saint Kitts and Nevis
Saint Lucia
Saint Vincent and the Grenadines
Samoa
San Marino
Sao Tome and Principe
Saudi Arabia
Senegal
Serbia
Seychelles
Sierra Leone
Singapore
Slovakia
Slovenia
Solomon Islands
South Africa
South Korea
Spain
Sri Lanka
Suriname
Sweden
Switzerland
Taiwan
Tajikistan
Tanzania
Thailand
Timor-Leste, Democratic Republic of
Togo
Tonga
Trinidad and Tobago
Tunisia
Turkey
Turkmenistan
Tuvalu
Uganda
Ukraine (except Crimea, Donetsk, and Luhansk regions)
United Arab Emirates
United Kingdom
United States of America
Uruguay
Uzbekistan
Vanuatu
Vietnam
Zambia
Zimbabwe

Messages
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

POST
/
v1
/
messages
Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Body
application/json
​
max_tokens
integer
required
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.

Different models have different maximum values for this parameter. See models for details.

Required range: x > 1
​
messages
object[]
required
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.

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:

[
  {"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"}]}
Starting with Claude 3 models, you can also send image content blocks:

{"role": "user", "content": [
  {
    "type": "image",
    "source": {
      "type": "base64",
      "media_type": "image/jpeg",
      "data": "/9j/4AAQSkZJRg...",
    }
  },
  {"type": "text", "text": "What is in this image?"}
]}
We currently support the base64 source type for images, and the image/jpeg, image/png, image/gif, and image/webp media types.

See examples for more input examples.

Note that if you want to include a system prompt, you can use the top-level system parameter — there is no "system" role for input messages in the Messages API.

There is a limit of 100000 messages in a single request.


Show child attributes

​
model
string
required
The model that will complete your prompt.

See models for additional details and options.

Required string length: 1 - 256
​
metadata
object
An object describing metadata about the request.


Show child attributes

​
stop_sequences
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
boolean
Whether to incrementally stream the response using server-sent events.

See streaming for details.

​
system

string
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.

​
temperature
number
Amount of randomness injected into the response.

Defaults to 1.0. Ranges from 0.0 to 1.0. Use temperature closer to 0.0 for analytical / multiple choice, and closer to 1.0 for creative and generative tasks.

Note that even with temperature of 0.0, the results will not be fully deterministic.

Required range: 0 < x < 1
​
thinking
object
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.

Enabled
Disabled

Show child attributes

​
tool_choice
object
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.

Auto
Any
Tool
ToolChoiceNone

Show child attributes

​
tools
object[]
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.

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.

Custom Tool
ComputerUseTool_20241022
BashTool_20241022
TextEditor_20241022
ComputerUseTool_20250124
BashTool_20250124
TextEditor_20250124

Show child attributes

​
top_k
integer
Only sample from the top K options for each subsequent token.

Used to remove "long tail" low probability responses. Learn more technical details here.

Recommended for advanced use cases only. You usually only need to use temperature.

Required range: x > 0
​
top_p
number
Use nucleus sampling.

In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by top_p. You should either alter temperature or top_p, but not both.

Recommended for advanced use cases only. You usually only need to use temperature.

Required range: 0 < x < 1
Response
200 - application/json
​
content
object[]
required
Content generated by the model.

This is an array of content blocks, each of which has a type that determines its shape.

Example:

[{"type": "text", "text": "Hi, I'm Claude."}]
If the request input messages ended with an assistant turn, then the response content will continue directly from that last turn. You can use this to constrain the model's output.

For example, if the input messages were:

[
  {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "The best answer is ("}
]
Then the response content might be:

[{"type": "text", "text": "B)"}]
Text
Tool Use
Thinking
Redacted Thinking

Show child attributes

​
id
string
required
Unique object identifier.

The format and length of IDs may change over time.

​
model
string
required
The model that handled the request.

Required string length: 1 - 256
​
role
enum<string>
default:
assistant
required
Conversational role of the generated message.

This will always be "assistant".

Available options: assistant 
​
stop_reason
enum<string> | null
required
The reason that we stopped.

This may be one the following values:

"end_turn": the model reached a natural stopping point
"max_tokens": we exceeded the requested max_tokens or the model's maximum
"stop_sequence": one of your provided custom stop_sequences was generated
"tool_use": the model invoked one or more tools
In non-streaming mode this value is always non-null. In streaming mode, it is null in the message_start event and non-null otherwise.

Available options: end_turn, max_tokens, stop_sequence, tool_use 
​
stop_sequence
string | null
required
Which custom stop sequence was generated, if any.

This value will be a non-null string if one of your custom stop sequences was generated.

​
type
enum<string>
default:
message
required
Object type.

For Messages, this is always "message".

Available options: message 
​
usage
object
required
Billing and rate-limit usage.

Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems.

Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in usage will not match one-to-one with the exact visible content of an API request or response.

For example, output_tokens will be non-zero, even for an empty string response from Claude.

Total input tokens in a request is the summation of input_tokens, cache_creation_input_tokens, and cache_read_input_tokens.


Show child attributes

Was this page helpful?


Yes

No
Getting help
Count Message tokens
x
linkedin

cURL

Python

JavaScript

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}'

200

4XX

{
  "content": [
    {
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "model": "claude-3-7-sonnet-20250219",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2095,
    "output_tokens": 503
  }
}
Messages - Anthropic

Messages
Count Message tokens
Count the number of tokens in a Message.

The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it.

Learn more about token counting in our user guide

POST
/
v1
/
messages
/
count_tokens
Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Body
application/json
​
messages
object[]
required
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.

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:

[
  {"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"}]}
Starting with Claude 3 models, you can also send image content blocks:

{"role": "user", "content": [
  {
    "type": "image",
    "source": {
      "type": "base64",
      "media_type": "image/jpeg",
      "data": "/9j/4AAQSkZJRg...",
    }
  },
  {"type": "text", "text": "What is in this image?"}
]}
We currently support the base64 source type for images, and the image/jpeg, image/png, image/gif, and image/webp media types.

See examples for more input examples.

Note that if you want to include a system prompt, you can use the top-level system parameter — there is no "system" role for input messages in the Messages API.

There is a limit of 100000 messages in a single request.


Show child attributes

​
model
string
required
The model that will complete your prompt.

See models for additional details and options.

Required string length: 1 - 256
​
system

string
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.

​
thinking
object
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.

Enabled
Disabled

Show child attributes

​
tool_choice
object
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.

Auto
Any
Tool
ToolChoiceNone

Show child attributes

​
tools
object[]
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.

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.

Custom Tool
ComputerUseTool_20241022
BashTool_20241022
TextEditor_20241022
ComputerUseTool_20250124
BashTool_20250124
TextEditor_20250124

Show child attributes

Response
200 - application/json
​
input_tokens
integer
required
The total number of tokens across the provided list of messages, system prompt, and tools.

Was this page helpful?


Yes

No
Messages
Streaming Messages
x
linkedin

cURL

Python

JavaScript

curl https://api.anthropic.com/v1/messages/count_tokens \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}'

200

4XX

{
  "input_tokens": 2095
}
Count Message tokens - Anthropic

Messages
Streaming Messages
When creating a Message, you can set "stream": true to incrementally stream the response using server-sent events (SSE).

​
Streaming with SDKs
Our Python and TypeScript SDKs offer multiple ways of streaming. The Python SDK allows both sync and async streams. See the documentation in each SDK for details.


Python

TypeScript

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-3-7-sonnet-20250219",
) as stream:
  for text in stream.text_stream:
      print(text, end="", flush=True)
​
Event types
Each server-sent event includes a named event type and associated JSON data. Each event will use an SSE event name (e.g. event: message_stop), and include the matching event type in its data.

Each stream uses the following event flow:

message_start: contains a Message object with empty content.
A series of content blocks, each of which have a content_block_start, one or more content_block_delta events, and a content_block_stop event. Each content block will have an index that corresponds to its index in the final Message content array.
One or more message_delta events, indicating top-level changes to the final Message object.
A final message_stop event.
​
Ping events
Event streams may also include any number of ping events.

​
Error events
We may occasionally send errors in the event stream. For example, during periods of high usage, you may receive an overloaded_error, which would normally correspond to an HTTP 529 in a non-streaming context:

Example error
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}
​
Other events
In accordance with our versioning policy, we may add new event types, and your code should handle unknown event types gracefully.

​
Delta types
Each content_block_delta event contains a delta of a type that updates the content block at a given index.

​
Text delta
A text content block delta looks like:

Text delta
event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}
​
Input JSON delta
The deltas for tool_use content blocks correspond to updates for the input field of the block. To support maximum granularity, the deltas are partial JSON strings, whereas the final tool_use.input is always an object.

You can accumulate the string deltas and parse the JSON once you receive a content_block_stop event, by using a library like Pydantic to do partial JSON parsing, or by using our SDKs, which provide helpers to access parsed incremental values.

A tool_use content block delta looks like:

Input JSON delta
event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}
Note: Our current models only support emitting one complete key and value property from input at a time. As such, when using tools, there may be delays between streaming events while the model is working. Once an input key and value are accumulated, we emit them as multiple content_block_delta events with chunked partial json so that the format can automatically support finer granularity in future models.

​
Thinking delta
When using extended thinking with streaming enabled, you’ll receive thinking content via thinking_delta events. These deltas correspond to the thinking field of the thinking content blocks.

For thinking content, a special signature_delta event is sent just before the content_block_stop event. This signature is used to verify the integrity of the thinking block.

A typical thinking delta looks like:

Thinking delta
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}
The signature delta looks like:

Signature delta
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}
​
Raw HTTP Stream response
We strongly recommend that use our client SDKs when using streaming mode. However, if you are building a direct API integration, you will need to handle these events yourself.

A stream response is comprised of:

A message_start event
Potentially multiple content blocks, each of which contains: a. A content_block_start event b. Potentially multiple content_block_delta events c. A content_block_stop event
A message_delta event
A message_stop event
There may be ping events dispersed throughout the response as well. See Event types for more details on the format.

​
Basic streaming request
Request
curl https://api.anthropic.com/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --data \
'{
  "model": "claude-3-7-sonnet-20250219",
  "messages": [{"role": "user", "content": "Hello"}],
  "max_tokens": 256,
  "stream": true
}'
Response
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

​
Streaming request with tool use
In this request, we ask Claude to use a tool to tell us the weather.

Request
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-3-7-sonnet-20250219",
      "max_tokens": 1024,
      "tools": [
        {
          "name": "get_weather",
          "description": "Get the current weather in a given location",
          "input_schema": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              }
            },
            "required": ["location"]
          }
        }
      ],
      "tool_choice": {"type": "any"},
      "messages": [
        {
          "role": "user",
          "content": "What is the weather like in San Francisco?"
        }
      ],
      "stream": true
    }'
Response
event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-3-haiku-20240307","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Okay"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" let"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"'s"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" check"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" for"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Francisco"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" CA"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":":"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":", "}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"unit\": \"fah"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"renheit\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}

event: message_stop
data: {"type":"message_stop"}
​
Streaming request with extended thinking
In this request, we enable extended thinking with streaming to see Claude’s step-by-step reasoning.

Request
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 20000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is 27 * 453?"
        }
    ]
}'
Response
event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n3. 27 * 400 = 10,800"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n4. 27 * 50 = 1,350"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n5. 27 * 3 = 81"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n6. 10,800 + 1,350 + 81 = 12,231"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}
Was this page helpful?


Yes

No
Count Message tokens
Migrating from Text Completions
x
linkedin
On this page
Streaming with SDKs
Event types
Ping events
Error events
Other events
Delta types
Text delta
Input JSON delta
Thinking delta
Raw HTTP Stream response
Basic streaming request
Streaming request with tool use
Streaming request with extended thinking
Streaming Messages - Anthropic

Messages
Migrating from Text Completions
Migrating from Text Completions to Messages

When migrating from from Text Completions to Messages, consider the following changes.

​
Inputs and outputs
The largest change between Text Completions and the Messages is the way in which you specify model inputs and receive outputs from the model.

With Text Completions, inputs are raw strings:

Python

prompt = "\n\nHuman: Hello there\n\nAssistant: Hi, I'm Claude. How can I help?\n\nHuman: Can you explain Glycolysis to me?\n\nAssistant:"
With Messages, you specify a list of input messages instead of a raw prompt:


Shorthand

Expanded

messages = [
  {"role": "user", "content": "Hello there."},
  {"role": "assistant", "content": "Hi, I'm Claude. How can I help?"},
  {"role": "user", "content": "Can you explain Glycolysis to me?"},
]
Each input message has a role and content.

Role names

The Text Completions API expects alternating \n\nHuman: and \n\nAssistant: turns, but the Messages API expects user and assistant roles. You may see documentation referring to either “human” or “user” turns. These refer to the same role, and will be “user” going forward.

With Text Completions, the model’s generated text is returned in the completion values of the response:

Python

>>> response = anthropic.completions.create(...)
>>> response.completion
" Hi, I'm Claude"
With Messages, the response is the content value, which is a list of content blocks:

Python

>>> response = anthropic.messages.create(...)
>>> response.content
[{"type": "text", "text": "Hi, I'm Claude"}]
​
Putting words in Claude’s mouth
With Text Completions, you can pre-fill part of Claude’s response:

Python

prompt = "\n\nHuman: Hello\n\nAssistant: Hello, my name is"
With Messages, you can achieve the same result by making the last input message have the assistant role:

Python

messages = [
  {"role": "human", "content": "Hello"},
  {"role": "assistant", "content": "Hello, my name is"},
]
When doing so, response content will continue from the last input message content:

JSON

{
  "role": "assistant",
  "content": [{"type": "text", "text": " Claude. How can I assist you today?" }],
  ...
}
​
System prompt
With Text Completions, the system prompt is specified by adding text before the first \n\nHuman: turn:

Python

prompt = "Today is January 1, 2024.\n\nHuman: Hello, Claude\n\nAssistant:"
With Messages, you specify the system prompt with the system parameter:

Python

anthropic.Anthropic().messages.create(
    model="claude-3-opus-20240229",
    max_tokens=1024,
    system="Today is January 1, 2024.", # <-- system prompt
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)
​
Model names
The Messages API requires that you specify the full model version (e.g. claude-3-opus-20240229).

We previously supported specifying only the major version number (e.g. claude-2), which resulted in automatic upgrades to minor versions. However, we no longer recommend this integration pattern, and Messages do not support it.

​
Stop reason
Text Completions always have a stop_reason of either:

"stop_sequence": The model either ended its turn naturally, or one of your custom stop sequences was generated.
"max_tokens": Either the model generated your specified max_tokens of content, or it reached its absolute maximum.
Messages have a stop_reason of one of the following values:

"end_turn": The conversational turn ended naturally.
"stop_sequence": One of your specified custom stop sequences was generated.
"max_tokens": (unchanged)
​
Specifying max tokens
Text Completions: max_tokens_to_sample parameter. No validation, but capped values per-model.
Messages: max_tokens parameter. If passing a value higher than the model supports, returns a validation error.
​
Streaming format
When using "stream": true in with Text Completions, the response included any of completion, ping, and error server-sent-events. See Text Completions streaming for details.

Messages can contain multiple content blocks of varying types, and so its streaming format is somewhat more complex. See Messages streaming for details.

Was this page helpful?


Yes

No
Streaming Messages
Messages examples
x
linkedin
On this page
Inputs and outputs
Putting words in Claude’s mouth
System prompt
Model names
Stop reason
Specifying max tokens
Streaming format
Migrating from Text Completions - Anthropic

Messages
Messages examples
Request and response examples for the Messages API

See the API reference for full documentation on available parameters.

​
Basic request and response

Shell

Python

TypeScript

#!/bin/sh
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}'
JSON

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}
​
Multiple conversational turns
The Messages API is stateless, which means that you always send the full conversational history to the API. You can use this pattern to build up a conversation over time. Earlier conversational turns don’t necessarily need to actually originate from Claude — you can use synthetic assistant messages.

Shell

#!/bin/sh
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"}

    ]
}'
Python

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-3-7-sonnet-20250219",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"}
    ],
)
print(message)

TypeScript

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

await anthropic.messages.create({
  model: 'claude-3-7-sonnet-20250219',
  max_tokens: 1024,
  messages: [
    {"role": "user", "content": "Hello, Claude"},
    {"role": "assistant", "content": "Hello!"},
    {"role": "user", "content": "Can you describe LLMs to me?"}
  ]
});
JSON

{
    "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
    "type": "message",
    "role": "assistant",
    "content": [
        {
            "type": "text",
            "text": "Sure, I'd be happy to provide..."
        }
    ],
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 30,
      "output_tokens": 309
    }
}
​
Putting words in Claude’s mouth
You can pre-fill part of Claude’s response in the last position of the input messages list. This can be used to shape Claude’s response. The example below uses "max_tokens": 1 to get a single multiple choice answer from Claude.


Shell

Python

TypeScript

#!/bin/sh
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1,
    "messages": [
        {"role": "user", "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"},
        {"role": "assistant", "content": "The answer is ("}
    ]
}'
JSON

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}
​
Vision
Claude can read both text and images in requests. We support both base64 and url source types for images, and the image/jpeg, image/png, image/gif, and image/webp media types. See our vision guide for more details.


Shell

Python

TypeScript

#!/bin/sh

# Option 1: Base64-encoded image
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "What is in the above image?"}
        ]}
    ]
}'

# Option 2: URL-referenced image
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "url",
                "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
            }},
            {"type": "text", "text": "What is in the above image?"}
        ]}
    ]
}'
JSON

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}
​
Tool use, JSON mode, and computer use (beta)
See our guide for examples for how to use tools with the Messages API. See our computer use (beta) guide for examples of how to control desktop computer environments with the Messages API.

Was this page helpful?


Yes

No
Migrating from Text Completions
List Models
x
linkedin
On this page
Basic request and response
Multiple conversational turns
Putting words in Claude’s mouth
Vision
Tool use, JSON mode, and computer use (beta)
Messages examples - Anthropic

Models
List Models
List available models.

The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first.

GET
/
v1
/
models
Headers
​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Query Parameters
​
before_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

​
after_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

​
limit
integer
default:
20
Number of items to return per page.

Defaults to 20. Ranges from 1 to 1000.

Required range: 1 < x < 1000
Response
200 - application/json
​
data
object[]
required

Show child attributes

​
first_id
string | null
required
First ID in the data list. Can be used as the before_id for the previous page.

​
has_more
boolean
required
Indicates if there are more results in the requested page direction.

​
last_id
string | null
required
Last ID in the data list. Can be used as the after_id for the next page.

Was this page helpful?


Yes

No
Messages examples
Get a Model
x
linkedin

cURL

Python

JavaScript

curl https://api.anthropic.com/v1/models \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01"

200

4XX

{
  "data": [
    {
      "created_at": "2025-02-19T00:00:00Z",
      "display_name": "Claude 3.7 Sonnet",
      "id": "claude-3-7-sonnet-20250219",
      "type": "model"
    }
  ],
  "first_id": "<string>",
  "has_more": true,
  "last_id": "<string>"
}
List Models - Anthropic

Models
Get a Model
Get a specific model.

The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID.

GET
/
v1
/
models
/
{model_id}
Headers
​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Path Parameters
​
model_id
string
required
Model identifier or alias.

Response
200 - application/json
​
created_at
string
required
RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.

​
display_name
string
required
A human-readable name for the model.

​
id
string
required
Unique model identifier.

​
type
enum<string>
default:
model
required
Object type.

For Models, this is always "model".

Available options: model 
Was this page helpful?


Yes

No
List Models
Create a Message Batch
x
linkedin

cURL

Python

JavaScript

curl https://api.anthropic.com/v1/models/claude-3-7-sonnet-20250219 \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01"

200

4XX

{
  "created_at": "2025-02-19T00:00:00Z",
  "display_name": "Claude 3.7 Sonnet",
  "id": "claude-3-7-sonnet-20250219",
  "type": "model"
}
Get a Model - Anthropic

Message Batches
Create a Message Batch
Send a batch of Message creation requests.

The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete.

Learn more about the Message Batches API in our user guide

POST
/
v1
/
messages
/
batches
​
Feature Support
The Message Batches API supports the following models: Claude 3 Haiku, Claude 3 Opus, Claude 3.5 Sonnet, Claude 3.5 Sonnet v2, and Claude 3.7 Sonnet. All features available in the Messages API, including beta features, are available through the Message Batches API.

Batches may contain up to 100,000 requests and be up to 256 MB in total size.

Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Body
application/json
​
requests
object[]
required
List of requests for prompt completion. Each is an individual request to create a Message.


Show child attributes

Response
200 - application/json
​
archived_at
string | null
required
RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

​
cancel_initiated_at
string | null
required
RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

​
created_at
string
required
RFC 3339 datetime string representing the time at which the Message Batch was created.

​
ended_at
string | null
required
RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

​
expires_at
string
required
RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.

​
id
string
required
Unique object identifier.

The format and length of IDs may change over time.

​
processing_status
enum<string>
required
Processing status of the Message Batch.

Available options: in_progress, canceling, ended 
​
request_counts
object
required
Tallies requests within the Message Batch, categorized by their status.

Requests start as processing and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.


Show child attributes

​
results_url
string | null
required
URL to a .jsonl file containing the results of the Message Batch requests. Specified only once processing ends.

Results in the file are not guaranteed to be in the same order as requests. Use the custom_id field to match results to requests.

​
type
enum<string>
default:
message_batch
required
Object type.

For Message Batches, this is always "message_batch".

Available options: message_batch 
Was this page helpful?


Yes

No
Get a Model
Retrieve a Message Batch
x
linkedin

cURL

Python

JavaScript

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-3-7-sonnet-20250219",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-3-7-sonnet-20250219",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

200

4XX

{
  "archived_at": "2024-08-20T18:37:24.100435Z",
  "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
  "created_at": "2024-08-20T18:37:24.100435Z",
  "ended_at": "2024-08-20T18:37:24.100435Z",
  "expires_at": "2024-08-20T18:37:24.100435Z",
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "processing_status": "in_progress",
  "request_counts": {
    "canceled": 10,
    "errored": 30,
    "expired": 10,
    "processing": 100,
    "succeeded": 50
  },
  "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
  "type": "message_batch"
}
Create a Message Batch - Anthropic

Message Batches
Retrieve a Message Batch
This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the results_url field in the response.

Learn more about the Message Batches API in our user guide

GET
/
v1
/
messages
/
batches
/
{message_batch_id}
Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Path Parameters
​
message_batch_id
string
required
ID of the Message Batch.

Response
200 - application/json
​
archived_at
string | null
required
RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

​
cancel_initiated_at
string | null
required
RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

​
created_at
string
required
RFC 3339 datetime string representing the time at which the Message Batch was created.

​
ended_at
string | null
required
RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

​
expires_at
string
required
RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.

​
id
string
required
Unique object identifier.

The format and length of IDs may change over time.

​
processing_status
enum<string>
required
Processing status of the Message Batch.

Available options: in_progress, canceling, ended 
​
request_counts
object
required
Tallies requests within the Message Batch, categorized by their status.

Requests start as processing and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.


Show child attributes

​
results_url
string | null
required
URL to a .jsonl file containing the results of the Message Batch requests. Specified only once processing ends.

Results in the file are not guaranteed to be in the same order as requests. Use the custom_id field to match results to requests.

​
type
enum<string>
default:
message_batch
required
Object type.

For Message Batches, this is always "message_batch".

Available options: message_batch 
Was this page helpful?


Yes

No
Create a Message Batch
Retrieve Message Batch Results
x
linkedin

cURL

Python

JavaScript

curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \

200

4XX

{
  "archived_at": "2024-08-20T18:37:24.100435Z",
  "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
  "created_at": "2024-08-20T18:37:24.100435Z",
  "ended_at": "2024-08-20T18:37:24.100435Z",
  "expires_at": "2024-08-20T18:37:24.100435Z",
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "processing_status": "in_progress",
  "request_counts": {
    "canceled": 10,
    "errored": 30,
    "expired": 10,
    "processing": 100,
    "succeeded": 50
  },
  "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
  "type": "message_batch"
}
Retrieve a Message Batch - Anthropic

Message Batches
Retrieve Message Batch Results
Streams the results of a Message Batch as a .jsonl file.

Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the custom_id field to match results to requests.

Learn more about the Message Batches API in our user guide

GET
/
v1
/
messages
/
batches
/
{message_batch_id}
/
results
The path for retrieving Message Batch results should be pulled from the batch’s results_url. This path should not be assumed and may change.
Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Path Parameters
​
message_batch_id
string
required
ID of the Message Batch.

Response
200 - application/x-jsonl
This is a single line in the response .jsonl file and does not represent the response as a whole.

​
custom_id
string
required
Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.

Must be unique for each request within the Message Batch.

​
result
object
required
Processing result for this request.

Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.

SucceededResult
ErroredResult
CanceledResult
ExpiredResult

Show child attributes

Was this page helpful?


Yes

No
Retrieve a Message Batch
List Message Batches
x
linkedin

cURL

Python

JavaScript
curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d/results \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \

200

4XX
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-3-5-sonnet-20240620","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-3-5-sonnet-20240620","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}
Retrieve Message Batch Results - Anthropic

Message Batches
List Message Batches
List all Message Batches within a Workspace. Most recently created batches are returned first.

Learn more about the Message Batches API in our user guide

GET
/
v1
/
messages
/
batches
Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Query Parameters
​
before_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

​
after_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

​
limit
integer
default:
20
Number of items to return per page.

Defaults to 20. Ranges from 1 to 1000.

Required range: 1 < x < 1000
Response
200 - application/json
​
data
object[]
required

Show child attributes

​
first_id
string | null
required
First ID in the data list. Can be used as the before_id for the previous page.

​
has_more
boolean
required
Indicates if there are more results in the requested page direction.

​
last_id
string | null
required
Last ID in the data list. Can be used as the after_id for the next page.

Was this page helpful?


Yes

No
Retrieve Message Batch Results
Cancel a Message Batch
x
linkedin

cURL

Python

JavaScript

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \

200

4XX

{
  "data": [
    {
      "archived_at": "2024-08-20T18:37:24.100435Z",
      "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
      "created_at": "2024-08-20T18:37:24.100435Z",
      "ended_at": "2024-08-20T18:37:24.100435Z",
      "expires_at": "2024-08-20T18:37:24.100435Z",
      "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
      "processing_status": "in_progress",
      "request_counts": {
        "canceled": 10,
        "errored": 30,
        "expired": 10,
        "processing": 100,
        "succeeded": 50
      },
      "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
      "type": "message_batch"
    }
  ],
  "first_id": "<string>",
  "has_more": true,
  "last_id": "<string>"
}
List Message Batches - Anthropic

Message Batches
Cancel a Message Batch
Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a canceling state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation.

The number of canceled requests is specified in request_counts. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible.

Learn more about the Message Batches API in our user guide

POST
/
v1
/
messages
/
batches
/
{message_batch_id}
/
cancel
Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Path Parameters
​
message_batch_id
string
required
ID of the Message Batch.

Response
200 - application/json
​
archived_at
string | null
required
RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

​
cancel_initiated_at
string | null
required
RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

​
created_at
string
required
RFC 3339 datetime string representing the time at which the Message Batch was created.

​
ended_at
string | null
required
RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

​
expires_at
string
required
RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.

​
id
string
required
Unique object identifier.

The format and length of IDs may change over time.

​
processing_status
enum<string>
required
Processing status of the Message Batch.

Available options: in_progress, canceling, ended 
​
request_counts
object
required
Tallies requests within the Message Batch, categorized by their status.

Requests start as processing and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.


Show child attributes

​
results_url
string | null
required
URL to a .jsonl file containing the results of the Message Batch requests. Specified only once processing ends.

Results in the file are not guaranteed to be in the same order as requests. Use the custom_id field to match results to requests.

​
type
enum<string>
default:
message_batch
required
Object type.

For Message Batches, this is always "message_batch".

Available options: message_batch 
Was this page helpful?


Yes

No
List Message Batches
Delete a Message Batch
x
linkedin

cURL

Python

JavaScript

curl --request POST https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d/cancel \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \

200

4XX

{
  "archived_at": "2024-08-20T18:37:24.100435Z",
  "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
  "created_at": "2024-08-20T18:37:24.100435Z",
  "ended_at": "2024-08-20T18:37:24.100435Z",
  "expires_at": "2024-08-20T18:37:24.100435Z",
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "processing_status": "in_progress",
  "request_counts": {
    "canceled": 10,
    "errored": 30,
    "expired": 10,
    "processing": 100,
    "succeeded": 50
  },
  "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
  "type": "message_batch"
}
Cancel a Message Batch - Anthropic

Message Batches
Delete a Message Batch
Delete a Message Batch.

Message Batches can only be deleted once they’ve finished processing. If you’d like to delete an in-progress batch, you must first cancel it.

Learn more about the Message Batches API in our user guide

DELETE
/
v1
/
messages
/
batches
/
{message_batch_id}
Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Path Parameters
​
message_batch_id
string
required
ID of the Message Batch.

Response
200 - application/json
​
id
string
required
ID of the Message Batch.

​
type
enum<string>
default:
message_batch_deleted
required
Deleted object type.

For Message Batches, this is always "message_batch_deleted".

Available options: message_batch_deleted 
Was this page helpful?


Yes

No
Cancel a Message Batch
Message Batches examples
x
linkedin

cURL

Python

JavaScript

curl -X DELETE https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \

200

4XX

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch_deleted"
}
Delete a Message Batch - Anthropic

Message Batches
Message Batches examples
Example usage for the Message Batches API

The Message Batches API supports the same set of features as the Messages API. While this page focuses on how to use the Message Batches API, see Messages API examples for examples of the Messages API featureset.

​
Creating a Message Batch

Python

TypeScript

Shell

import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-3-7-sonnet-20250219",
                max_tokens=1024,
                messages=[{
                    "role": "user",
                    "content": "Hello, world",
                }]
            )
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-3-7-sonnet-20250219",
                max_tokens=1024,
                messages=[{
                    "role": "user",
                    "content": "Hi again, friend",
                }]
            )
        )
    ]
)
print(message_batch)
JSON

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}
​
Polling for Message Batch completion
To poll a Message Batch, you’ll need its id, which is provided in the response when creating request or by listing batches. Example id: msgbatch_013Zva2CMHLNnXjNJJKqJ2EF.


Python

TypeScript

Shell

import anthropic

client = anthropic.Anthropic()

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(
        MESSAGE_BATCH_ID
    )
    if message_batch.processing_status == "ended":
        break
              
    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)
​
Listing all Message Batches in a Workspace

Python

TypeScript

Shell

import anthropic

client = anthropic.Anthropic()

# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(
    limit=20
):
    print(message_batch)
Output

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  ...
}
{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  ...
}
​
Retrieving Message Batch Results
Once your Message Batch status is ended, you will be able to view the results_url of the batch and retrieve results in the form of a .jsonl file.


Python

TypeScript

Shell

import anthropic

client = anthropic.Anthropic()

# Stream results file in memory-efficient chunks, processing one at a time
for result in client.messages.batches.results(
    MESSAGE_BATCH_ID,
):
    print(result)
Output

{
  "id": "my-second-request",
  "result": {
    "type": "succeeded",
    "message": {
      "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
      "type": "message",
      ...
    }
  }
}
{
  "custom_id": "my-first-request",
  "result": {
    "type": "succeeded",
    "message": {
      "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
      "type": "message",
      ...
    }
  }
}
​
Canceling a Message Batch
Immediately after cancellation, a batch’s processing_status will be canceling. You can use the same polling for batch completion technique to poll for when cancellation is finalized as canceled batches also end up ended and may contain results.


Python

TypeScript

Shell

import anthropic

client = anthropic.Anthropic()

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)
JSON

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}
Was this page helpful?


Yes

No
Delete a Message Batch
Create a Text Completion
x
linkedin
On this page
Creating a Message Batch
Polling for Message Batch completion
Listing all Message Batches in a Workspace
Retrieving Message Batch Results
Canceling a Message Batch
Message Batches examples - Anthropic

Text Completions (Legacy)
Create a Text Completion
[Legacy] Create a Text Completion.

The Text Completions API is a legacy API. We recommend using the Messages API going forward.

Future models and features will not be compatible with Text Completions. See our migration guide for guidance in migrating from Text Completions to Messages.

POST
/
v1
/
complete
Headers
​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Body
application/json
​
max_tokens_to_sample
integer
required
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.

Required range: x > 1
​
model
string
required
The model that will complete your prompt.

See models for additional details and options.

​
prompt
string
required
The prompt that you want Claude to complete.

For proper response generation you will need to format your prompt using alternating \n\nHuman: and \n\nAssistant: conversational turns. For example:

"\n\nHuman: {userQuestion}\n\nAssistant:"
See prompt validation and our guide to prompt design for more details.

Minimum length: 1
​
metadata
object
An object describing metadata about the request.


Show child attributes

​
stop_sequences
string[]
Sequences that will cause the model to stop generating.

Our models stop on "\n\nHuman:", and may include additional built-in stop sequences in the future. By providing the stop_sequences parameter, you may include additional strings that will cause the model to stop generating.

​
stream
boolean
Whether to incrementally stream the response using server-sent events.

See streaming for details.

​
temperature
number
Amount of randomness injected into the response.

Defaults to 1.0. Ranges from 0.0 to 1.0. Use temperature closer to 0.0 for analytical / multiple choice, and closer to 1.0 for creative and generative tasks.

Note that even with temperature of 0.0, the results will not be fully deterministic.

Required range: 0 < x < 1
​
top_k
integer
Only sample from the top K options for each subsequent token.

Used to remove "long tail" low probability responses. Learn more technical details here.

Recommended for advanced use cases only. You usually only need to use temperature.

Required range: x > 0
​
top_p
number
Use nucleus sampling.

In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by top_p. You should either alter temperature or top_p, but not both.

Recommended for advanced use cases only. You usually only need to use temperature.

Required range: 0 < x < 1
Response
200 - application/json
​
completion
string
required
The resulting completion up to and excluding the stop sequences.

​
id
string
required
Unique object identifier.

The format and length of IDs may change over time.

​
model
string
required
The model that handled the request.

​
stop_reason
string | null
required
The reason that we stopped.

This may be one the following values:

"stop_sequence": we reached a stop sequence — either provided by you via the stop_sequences parameter, or a stop sequence built into the model
"max_tokens": we exceeded max_tokens_to_sample or the model's maximum
​
type
enum<string>
default:
completion
required
Object type.

For Text Completions, this is always "completion".

Available options: completion 
Was this page helpful?


Yes

No
Message Batches examples
Streaming Text Completions
x
linkedin

cURL

Python

JavaScript

curl https://api.anthropic.com/v1/complete \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-2.1",
    "max_tokens_to_sample": 1024,
    "prompt": "\n\nHuman: Hello, Claude\n\nAssistant:"
}'

200

4XX

{
  "completion": " Hello! My name is Claude.",
  "id": "compl_018CKm6gsux7P8yMcwZbeCPw",
  "model": "claude-2.1",
  "stop_reason": "stop_sequence",
  "type": "completion"
}Text Completions (Legacy)
Streaming Text Completions
Legacy API

The Text Completions API is a legacy API. Future models and features will require use of the Messages API, and we recommend migrating as soon as possible.

When creating a Text Completion, you can set "stream": true to incrementally stream the response using server-sent events (SSE). If you are using our client libraries, parsing these events will be handled for you automatically. However, if you are building a direct API integration, you will need to handle these events yourself.

​
Example
Request

curl https://api.anthropic.com/v1/complete \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --data '
{
  "model": "claude-2",
  "prompt": "\n\nHuman: Hello, world!\n\nAssistant:",
  "max_tokens_to_sample": 256,
  "stream": true
}
'
Response

event: completion
data: {"type": "completion", "completion": " Hello", "stop_reason": null, "model": "claude-2.0"}

event: completion
data: {"type": "completion", "completion": "!", "stop_reason": null, "model": "claude-2.0"}

event: ping
data: {"type": "ping"}

event: completion
data: {"type": "completion", "completion": " My", "stop_reason": null, "model": "claude-2.0"}

event: completion
data: {"type": "completion", "completion": " name", "stop_reason": null, "model": "claude-2.0"}

event: completion
data: {"type": "completion", "completion": " is", "stop_reason": null, "model": "claude-2.0"}

event: completion
data: {"type": "completion", "completion": " Claude", "stop_reason": null, "model": "claude-2.0"}

event: completion
data: {"type": "completion", "completion": ".", "stop_reason": null, "model": "claude-2.0"}

event: completion
data: {"type": "completion", "completion": "", "stop_reason": "stop_sequence", "model": "claude-2.0"}

​
Events
Each event includes a named event type and associated JSON data.

Event types: completion, ping, error.

​
Error event types
We may occasionally send errors in the event stream. For example, during periods of high usage, you may receive an overloaded_error, which would normally correspond to an HTTP 529 in a non-streaming context:

Example error

event: completion
data: {"completion": " Hello", "stop_reason": null, "model": "claude-2.0"}

event: error
data: {"error": {"type": "overloaded_error", "message": "Overloaded"}}
​
Older API versions
If you are using an API version prior to 2023-06-01, the response shape will be different. See versioning for details.

Text Completions (Legacy)
Prompt validation
With Text Completions

Legacy API

The Text Completions API is a legacy API. Future models and features will require use of the Messages API, and we recommend migrating as soon as possible.

The Anthropic API performs basic prompt sanitization and validation to help ensure that your prompts are well-formatted for Claude.

When creating Text Completions, if your prompt is not in the specified format, the API will first attempt to lightly sanitize it (for example, by removing trailing spaces). This exact behavior is subject to change, and we strongly recommend that you format your prompts with the recommended alternating \n\nHuman: and \n\nAssistant: turns.

Then, the API will validate your prompt under the following conditions:

The first conversational turn in the prompt must be a \n\nHuman: turn
The last conversational turn in the prompt be an \n\nAssistant: turn
The prompt must be less than 100,000 - 1 tokens in length.
​
Examples
The following prompts will results in API errors:

Python

# Missing "\n\nHuman:" and "\n\nAssistant:" turns
prompt = "Hello, world"

# Missing "\n\nHuman:" turn
prompt = "Hello, world\n\nAssistant:"

# Missing "\n\nAssistant:" turn
prompt = "\n\nHuman: Hello, Claude"

# "\n\nHuman:" turn is not first
prompt = "\n\nAssistant: Hello, world\n\nHuman: Hello, Claude\n\nAssistant:"

# "\n\nAssistant:" turn is not last
prompt = "\n\nHuman: Hello, Claude\n\nAssistant: Hello, world\n\nHuman: How many toes do dogs have?"

# "\n\nAssistant:" only has one "\n"
prompt = "\n\nHuman: Hello, Claude \nAssistant:"
The following are currently accepted and automatically sanitized by the API, but you should not rely on this behavior, as it may change in the future:

Python

# No leading "\n\n" for "\n\nHuman:"
prompt = "Human: Hello, Claude\n\nAssistant:"

# Trailing space after "\n\nAssistant:"
prompt = "\n\nHuman: Hello, Claude:\n\nAssistant: "

Organization Member Management
Get User
GET
/
v1
/
organizations
/
users
/
{user_id}
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
user_id
string
required
ID of the User.

Response
200 - application/json
​
added_at
string
required
RFC 3339 datetime string indicating when the User joined the Organization.

​
email
string
required
Email of the User.

​
id
string
required
ID of the User.

​
name
string
required
Name of the User.

​
role
enum<string>
required
Organization role of the User.

Available options: user, developer, billing, admin 
​
type
enum<string>
default:
user
required
Object type.

For Users, this is always "user".

Available options: user 
Was this page helpful?


Yes

No
Prompt validation
List Users
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/users/user_01WCz1FkmYMm4gnmykNKUu3Q" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
  "type": "user",
  "email": "user@emaildomain.com",
  "name": "Jane Doe",
  "role": "user",
  "added_at": "2024-10-30T23:58:27.427722Z"
}

Organization Member Management
List Users
GET
/
v1
/
organizations
/
users
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Query Parameters
​
before_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

​
after_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

​
limit
integer
default:
20
Number of items to return per page.

Defaults to 20. Ranges from 1 to 1000.

Required range: 1 < x < 1000
​
email
string
Filter by user email.

Response
200 - application/json
​
data
object[]
required

Show child attributes

​
first_id
string | null
required
First ID in the data list. Can be used as the before_id for the previous page.

​
has_more
boolean
required
Indicates if there are more results in the requested page direction.

​
last_id
string | null
required
Last ID in the data list. Can be used as the after_id for the next page.

Was this page helpful?


Yes

No
Get User
Update User
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/users" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "data": [
    {
      "id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
      "type": "user",
      "email": "user@emaildomain.com",
      "name": "Jane Doe",
      "role": "user",
      "added_at": "2024-10-30T23:58:27.427722Z"
    }
  ],
  "has_more": true,
  "first_id": "<string>",
  "last_id": "<string>"
}

Organization Member Management
Update User
POST
/
v1
/
organizations
/
users
/
{user_id}
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
user_id
string
required
ID of the User.

Body
application/json
​
role
enum<string>
required
New role for the User. Cannot be "admin".

Available options: user, developer, billing 
Response
200 - application/json
​
added_at
string
required
RFC 3339 datetime string indicating when the User joined the Organization.

​
email
string
required
Email of the User.

​
id
string
required
ID of the User.

​
name
string
required
Name of the User.

​
role
enum<string>
required
Organization role of the User.

Available options: user, developer, billing, admin 
​
type
enum<string>
default:
user
required
Object type.

For Users, this is always "user".

Available options: user 
Was this page helpful?


Yes

No
List Users
Remove User
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/users/user_01WCz1FkmYMm4gnmykNKUu3Q" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{
    "role": "user"
  }'

200

4XX

{
  "id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
  "type": "user",
  "email": "user@emaildomain.com",
  "name": "Jane Doe",
  "role": "user",
  "added_at": "2024-10-30T23:58:27.427722Z"
}


Organization Member Management
Remove User
DELETE
/
v1
/
organizations
/
users
/
{user_id}
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
user_id
string
required
ID of the User.

Response
200 - application/json
​
id
string
required
ID of the User.

​
type
enum<string>
default:
user_deleted
required
Deleted object type.

For Users, this is always "user_deleted".

Available options: user_deleted 
Was this page helpful?


Yes

No
Update User
Get Invite
x
linkedin

cURL

curl --request DELETE "https://api.anthropic.com/v1/organizations/users/user_01WCz1FkmYMm4gnmykNKUu3Q" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
  "type": "user_deleted"
}
Organization Invites
Get Invite
GET
/
v1
/
organizations
/
invites
/
{invite_id}
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
invite_id
string
required
ID of the Invite.

Response
200 - application/json
​
email
string
required
Email of the User being invited.

​
expires_at
string
required
RFC 3339 datetime string indicating when the Invite expires.

​
id
string
required
ID of the Invite.

​
invited_at
string
required
RFC 3339 datetime string indicating when the Invite was created.

​
role
enum<string>
required
Organization role of the User.

Available options: user, developer, billing, admin 
​
status
enum<string>
required
Status of the Invite.

Available options: accepted, expired, deleted, pending 
​
type
enum<string>
default:
invite
required
Object type.

For Invites, this is always "invite".

Available options: invite 
Was this page helpful?


Yes

No
Remove User
List Invites
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/invites/invite_015gWxCN9Hfg2QhZwTK7Mdeu" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
  "type": "invite",
  "email": "user@emaildomain.com",
  "role": "user",
  "invited_at": "2024-10-30T23:58:27.427722Z",
  "expires_at": "2024-11-20T23:58:27.427722Z",
  "status": "pending"
}

Organization Invites
List Invites
GET
/
v1
/
organizations
/
invites
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Query Parameters
​
before_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

​
after_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

​
limit
integer
default:
20
Number of items to return per page.

Defaults to 20. Ranges from 1 to 1000.

Required range: 1 < x < 1000
Response
200 - application/json
​
data
object[]
required

Show child attributes

​
first_id
string | null
required
First ID in the data list. Can be used as the before_id for the previous page.

​
has_more
boolean
required
Indicates if there are more results in the requested page direction.

​
last_id
string | null
required
Last ID in the data list. Can be used as the after_id for the next page.

Was this page helpful?


Yes

No
Get Invite
Create Invite
x
linkedin

cURL

curl https://api.anthropic.com/v1/organizations/invites \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01"

200

4XX

{
  "data": [
    {
      "id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
      "type": "invite",
      "email": "user@emaildomain.com",
      "role": "user",
      "invited_at": "2024-10-30T23:58:27.427722Z",
      "expires_at": "2024-11-20T23:58:27.427722Z",
      "status": "pending"
    }
  ],
  "has_more": true,
  "first_id": "<string>",
  "last_id": "<string>"
}
List Invites - Anthropic

Organization Invites
Create Invite
POST
/
v1
/
organizations
/
invites
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Body
application/json
​
email
string
required
Email of the User.

​
role
enum<string>
required
Role for the invited User. Cannot be "admin".

Available options: user, developer, billing 
Response
200 - application/json
​
email
string
required
Email of the User being invited.

​
expires_at
string
required
RFC 3339 datetime string indicating when the Invite expires.

​
id
string
required
ID of the Invite.

​
invited_at
string
required
RFC 3339 datetime string indicating when the Invite was created.

​
role
enum<string>
required
Organization role of the User.

Available options: user, developer, billing, admin 
​
status
enum<string>
required
Status of the Invite.

Available options: accepted, expired, deleted, pending 
​
type
enum<string>
default:
invite
required
Object type.

For Invites, this is always "invite".

Available options: invite 
Was this page helpful?


Yes

No
List Invites
Delete Invite
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/invites" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{
    "email": "user@emaildomain.com",
    "role": "user"
  }'

200

4XX

{
  "id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
  "type": "invite",
  "email": "user@emaildomain.com",
  "role": "user",
  "invited_at": "2024-10-30T23:58:27.427722Z",
  "expires_at": "2024-11-20T23:58:27.427722Z",
  "status": "pending"
}
Create Invite - Anthropic

Organization Invites
Delete Invite
DELETE
/
v1
/
organizations
/
invites
/
{invite_id}
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
invite_id
string
required
ID of the Invite.

Response
200 - application/json
​
id
string
required
ID of the Invite.

​
type
enum<string>
default:
invite_deleted
required
Deleted object type.

For Invites, this is always "invite_deleted".

Available options: invite_deleted 
Was this page helpful?


Yes

No
Create Invite
Get Workspace
x
linkedin

cURL

curl --request DELETE "https://api.anthropic.com/v1/organizations/invites/invite_015gWxCN9Hfg2QhZwTK7Mdeu" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
  "type": "invite_deleted"
}
Delete Invite - Anthropic

Workspace Management
Get Workspace
GET
/
v1
/
organizations
/
workspaces
/
{workspace_id}
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
workspace_id
string
required
ID of the Workspace.

Response
200 - application/json
​
archived_at
string | null
required
RFC 3339 datetime string indicating when the Workspace was archived, or null if the Workspace is not archived.

​
created_at
string
required
RFC 3339 datetime string indicating when the Workspace was created.

​
display_color
string
required
Hex color code representing the Workspace in the Anthropic Console.

​
id
string
required
ID of the Workspace.

​
name
string
required
Name of the Workspace.

​
type
enum<string>
default:
workspace
required
Object type.

For Workspaces, this is always "workspace".

Available options: workspace 
Was this page helpful?


Yes

No
Delete Invite
List Workspaces
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  "type": "workspace",
  "name": "Workspace Name",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "archived_at": "2024-11-01T23:59:27.427722Z",
  "display_color": "#6C5BB9"
}

Workspace Management
List Workspaces
GET
/
v1
/
organizations
/
workspaces
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Query Parameters
​
include_archived
boolean
default:
false
Whether to include Workspaces that have been archived in the response

​
before_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

​
after_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

​
limit
integer
default:
20
Number of items to return per page.

Defaults to 20. Ranges from 1 to 1000.

Required range: 1 < x < 1000
Response
200 - application/json
​
data
object[]
required

Show child attributes

​
first_id
string | null
required
First ID in the data list. Can be used as the before_id for the previous page.

​
has_more
boolean
required
Indicates if there are more results in the requested page direction.

​
last_id
string | null
required
Last ID in the data list. Can be used as the after_id for the next page.

Was this page helpful?


Yes

No
Get Workspace
Update Workspace
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/workspaces" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "data": [
    {
      "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
      "type": "workspace",
      "name": "Workspace Name",
      "created_at": "2024-10-30T23:58:27.427722Z",
      "archived_at": "2024-11-01T23:59:27.427722Z",
      "display_color": "#6C5BB9"
    }
  ],
  "has_more": true,
  "first_id": "<string>",
  "last_id": "<string>"
}
List Workspaces - Anthropic

Workspace Management
Update Workspace
POST
/
v1
/
organizations
/
workspaces
/
{workspace_id}
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
workspace_id
string
required
ID of the Workspace.

Body
application/json
​
name
string
required
Name of the Workspace.

Required string length: 1 - 40
Response
200 - application/json
​
archived_at
string | null
required
RFC 3339 datetime string indicating when the Workspace was archived, or null if the Workspace is not archived.

​
created_at
string
required
RFC 3339 datetime string indicating when the Workspace was created.

​
display_color
string
required
Hex color code representing the Workspace in the Anthropic Console.

​
id
string
required
ID of the Workspace.

​
name
string
required
Name of the Workspace.

​
type
enum<string>
default:
workspace
required
Object type.

For Workspaces, this is always "workspace".

Available options: workspace 
Was this page helpful?


Yes

No
List Workspaces
Create Workspace
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{
    "name": "Workspace Name"
  }'

200

4XX

{
  "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  "type": "workspace",
  "name": "Workspace Name",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "archived_at": "2024-11-01T23:59:27.427722Z",
  "display_color": "#6C5BB9"
}


Workspace Management
Create Workspace
POST
/
v1
/
organizations
/
workspaces
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Body
application/json
​
name
string
required
Name of the Workspace.

Required string length: 1 - 40
Response
200 - application/json
​
archived_at
string | null
required
RFC 3339 datetime string indicating when the Workspace was archived, or null if the Workspace is not archived.

​
created_at
string
required
RFC 3339 datetime string indicating when the Workspace was created.

​
display_color
string
required
Hex color code representing the Workspace in the Anthropic Console.

​
id
string
required
ID of the Workspace.

​
name
string
required
Name of the Workspace.

​
type
enum<string>
default:
workspace
required
Object type.

For Workspaces, this is always "workspace".

Available options: workspace 
Was this page helpful?


Yes

No
Update Workspace
Archive Workspace
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/workspaces" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{
    "name": "Workspace Name"
  }'

200

4XX

{
  "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  "type": "workspace",
  "name": "Workspace Name",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "archived_at": "2024-11-01T23:59:27.427722Z",
  "display_color": "#6C5BB9"
}



Workspace Management
Archive Workspace
POST
/
v1
/
organizations
/
workspaces
/
{workspace_id}
/
archive
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
workspace_id
string
required
ID of the Workspace.

Response
200 - application/json
​
archived_at
string | null
required
RFC 3339 datetime string indicating when the Workspace was archived, or null if the Workspace is not archived.

​
created_at
string
required
RFC 3339 datetime string indicating when the Workspace was created.

​
display_color
string
required
Hex color code representing the Workspace in the Anthropic Console.

​
id
string
required
ID of the Workspace.

​
name
string
required
Name of the Workspace.

​
type
enum<string>
default:
workspace
required
Object type.

For Workspaces, this is always "workspace".

Available options: workspace 
Was this page helpful?


Yes

No
Create Workspace
Get Workspace Member
x
linkedin

cURL

curl --request POST "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  "type": "workspace",
  "name": "Workspace Name",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "archived_at": "2024-11-01T23:59:27.427722Z",
  "display_color": "#6C5BB9"
}
Workspace Member Management
Get Workspace Member
GET
/
v1
/
organizations
/
workspaces
/
{workspace_id}
/
members
/
{user_id}
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
user_id
string
required
ID of the User.

​
workspace_id
string
required
ID of the Workspace.

Response
200 - application/json
​
type
enum<string>
default:
workspace_member
required
Object type.

For Workspace Members, this is always "workspace_member".

Available options: workspace_member 
​
user_id
string
required
ID of the User.

​
workspace_id
string
required
ID of the Workspace.

​
workspace_role
enum<string>
required
Role of the Workspace Member.

Available options: workspace_user, workspace_developer, workspace_admin, workspace_billing 
Was this page helpful?


Yes

No
Archive Workspace
List Workspace Members
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members/user_01WCz1FkmYMm4gnmykNKUu3Q" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "type": "workspace_member",
  "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
  "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  "workspace_role": "workspace_user"
}
Get Workspace Member - Anthropic

Workspace Member Management
List Workspace Members
GET
/
v1
/
organizations
/
workspaces
/
{workspace_id}
/
members
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
workspace_id
string
required
ID of the Workspace.

Query Parameters
​
before_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

​
after_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

​
limit
integer
default:
20
Number of items to return per page.

Defaults to 20. Ranges from 1 to 1000.

Required range: 1 < x < 1000
Response
200 - application/json
​
data
object[]
required

Show child attributes

​
first_id
string | null
required
First ID in the data list. Can be used as the before_id for the previous page.

​
has_more
boolean
required
Indicates if there are more results in the requested page direction.

​
last_id
string | null
required
Last ID in the data list. Can be used as the after_id for the next page.

Was this page helpful?


Yes

No
Get Workspace Member
Add Workspace Member
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "data": [
    {
      "type": "workspace_member",
      "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
      "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
      "workspace_role": "workspace_user"
    }
  ],
  "has_more": true,
  "first_id": "<string>",
  "last_id": "<string>"
}

Workspace Member Management
Add Workspace Member
POST
/
v1
/
organizations
/
workspaces
/
{workspace_id}
/
members
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
workspace_id
string
required
ID of the Workspace.

Body
application/json
​
user_id
string
required
ID of the User.

​
workspace_role
enum<string>
required
Role of the new Workspace Member. Cannot be "workspace_billing".

Available options: workspace_user, workspace_developer, workspace_admin 
Response
200 - application/json
​
type
enum<string>
default:
workspace_member
required
Object type.

For Workspace Members, this is always "workspace_member".

Available options: workspace_member 
​
user_id
string
required
ID of the User.

​
workspace_id
string
required
ID of the Workspace.

​
workspace_role
enum<string>
required
Role of the Workspace Member.

Available options: workspace_user, workspace_developer, workspace_admin, workspace_billing 
Was this page helpful?


Yes

No
List Workspace Members
Update Workspace Member
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{
    "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
    "workspace_role": "workspace_user"
  }'

200

4XX

{
  "type": "workspace_member",
  "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
  "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  "workspace_role": "workspace_user"
}

Workspace Member Management
Update Workspace Member
POST
/
v1
/
organizations
/
workspaces
/
{workspace_id}
/
members
/
{user_id}
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
user_id
string
required
ID of the User.

​
workspace_id
string
required
ID of the Workspace.

Body
application/json
​
workspace_role
enum<string>
required
New workspace role for the User.

Available options: workspace_user, workspace_developer, workspace_admin, workspace_billing 
Response
200 - application/json
​
type
enum<string>
default:
workspace_member
required
Object type.

For Workspace Members, this is always "workspace_member".

Available options: workspace_member 
​
user_id
string
required
ID of the User.

​
workspace_id
string
required
ID of the Workspace.

​
workspace_role
enum<string>
required
Role of the Workspace Member.

Available options: workspace_user, workspace_developer, workspace_admin, workspace_billing 
Was this page helpful?


Yes

No
Add Workspace Member
Delete Workspace Member
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members/user_01WCz1FkmYMm4gnmykNKUu3Q" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{
    "workspace_role": "workspace_user"
  }'

200

4XX

{
  "type": "workspace_member",
  "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
  "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  "workspace_role": "workspace_user"
}
Workspace Member Management
Delete Workspace Member
DELETE
/
v1
/
organizations
/
workspaces
/
{workspace_id}
/
members
/
{user_id}
The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
user_id
string
required
ID of the User.

​
workspace_id
string
required
ID of the Workspace.

Response
200 - application/json
​
type
enum<string>
default:
workspace_member_deleted
required
Deleted object type.

For Workspace Members, this is always "workspace_member_deleted".

Available options: workspace_member_deleted 
​
user_id
string
required
ID of the User.

​
workspace_id
string
required
ID of the Workspace.

Was this page helpful?


Yes

No
Update Workspace Member
Get API Key
x
linkedin

cURL

curl --request DELETE "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members/user_01WCz1FkmYMm4gnmykNKUu3Q" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
  "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  "type": "workspace_member_deleted"
}


API Keys
Get API Key
GET
/
v1
/
organizations
/
api_keys
/
{api_key_id}
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
api_key_id
string
required
ID of the API key.

Response
200 - application/json
​
created_at
string
required
RFC 3339 datetime string indicating when the API Key was created.

​
created_by
object
required
The ID and type of the actor that created the API key.


Show child attributes

​
id
string
required
ID of the API key.

​
name
string
required
Name of the API key.

​
partial_key_hint
string | null
required
Partially redacted hint for the API key.

​
status
enum<string>
required
Status of the API key.

Available options: active, inactive, archived 
​
type
enum<string>
default:
api_key
required
Object type.

For API Keys, this is always "api_key".

Available options: api_key 
​
workspace_id
string | null
required
ID of the Workspace associated with the API key, or null if the API key belongs to the default Workspace.

Was this page helpful?


Yes

No
Delete Workspace Member
List API Keys
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/api_keys/apikey_01Rj2N8SVvo6BePZj99NhmiT" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
  "type": "api_key",
  "name": "Developer Key",
  "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "created_by": {
    "id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
    "type": "user"
  },
  "partial_key_hint": "sk-ant-api03-R2D...igAA",
  "status": "active"
}
Get API Key - Anthropic


API Keys
List API Keys
GET
/
v1
/
organizations
/
api_keys
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Query Parameters
​
before_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

​
after_id
string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

​
limit
integer
default:
20
Number of items to return per page.

Defaults to 20. Ranges from 1 to 1000.

Required range: 1 < x < 1000
​
status
enum<string> | null
Filter by API key status.

Available options: active, inactive, archived 
​
workspace_id
string | null
Filter by Workspace ID.

​
created_by_user_id
string | null
Filter by the ID of the User who created the object.

Response
200 - application/json
​
data
object[]
required

Show child attributes

​
first_id
string | null
required
First ID in the data list. Can be used as the before_id for the previous page.

​
has_more
boolean
required
Indicates if there are more results in the requested page direction.

​
last_id
string | null
required
Last ID in the data list. Can be used as the after_id for the next page.

Was this page helpful?


Yes

No
Get API Key
Update API Keys
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/api_keys" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

200

4XX

{
  "data": [
    {
      "id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
      "type": "api_key",
      "name": "Developer Key",
      "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
      "created_at": "2024-10-30T23:58:27.427722Z",
      "created_by": {
        "id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
        "type": "user"
      },
      "partial_key_hint": "sk-ant-api03-R2D...igAA",
      "status": "active"
    }
  ],
  "has_more": true,
  "first_id": "<string>",
  "last_id": "<string>"
}

API Keys
Update API Keys
POST
/
v1
/
organizations
/
api_keys
/
{api_key_id}
Headers
​
x-api-key
string
required
Your unique Admin API key for authentication.

This key is required in the header of all Admin API requests, to authenticate your account and access Anthropic's services. Get your Admin API key through the Console.

​
anthropic-version
string
required
The version of the Anthropic API you want to use.

Read more about versioning and our version history here.

Path Parameters
​
api_key_id
string
required
ID of the API key.

Body
application/json
​
name
string
Name of the API key.

Required string length: 1 - 500
​
status
enum<string> | null
Status of the API key.

Available options: active, inactive, archived 
Response
200 - application/json
​
created_at
string
required
RFC 3339 datetime string indicating when the API Key was created.

​
created_by
object
required
The ID and type of the actor that created the API key.


Show child attributes

​
id
string
required
ID of the API key.

​
name
string
required
Name of the API key.

​
partial_key_hint
string | null
required
Partially redacted hint for the API key.

​
status
enum<string>
required
Status of the API key.

Available options: active, inactive, archived 
​
type
enum<string>
default:
api_key
required
Object type.

For API Keys, this is always "api_key".

Available options: api_key 
​
workspace_id
string | null
required
ID of the Workspace associated with the API key, or null if the API key belongs to the default Workspace.

Was this page helpful?


Yes

No
List API Keys
OpenAI SDK compatibility (beta)
x
linkedin

cURL

curl "https://api.anthropic.com/v1/organizations/api_keys/apikey_01Rj2N8SVvo6BePZj99NhmiT" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{
    "status": "active",
    "name": "Developer Key"
  }'

200

4XX

{
  "id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
  "type": "api_key",
  "name": "Developer Key",
  "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "created_by": {
    "id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
    "type": "user"
  },
  "partial_key_hint": "sk-ant-api03-R2D...igAA",
  "status": "active"
}
Prompt tools
Generate a prompt
Generate a well-written prompt

POST
/
v1
/
experimental
/
generate_prompt
The prompt tools APIs are in a closed research preview. Request to join the closed research preview.

​
Before you begin
The prompt tools are a set of APIs to generate and improve prompts. Unlike our other APIs, this is an experimental API: you’ll need to request access, and it doesn’t have the same level of commitment to long-term support as other APIs.

These APIs are similar to what’s available in the Anthropic Workbench, and are intented for use by other prompt engineering platforms and playgrounds.

​
Getting started with the prompt generator
To use the prompt generation API, you’ll need to:

Have joined the closed research preview for the prompt tools APIs
Use the API directly, rather than the SDK
Add the beta header prompt-tools-2025-04-02
This API is not available in the SDK

​
Generate a prompt
Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Body
application/json
​
task
string
required
Description of the prompt's purpose.

The task parameter tells Claude what the prompt should do or what kind of role or functionality you want to create. This helps guide the prompt generation process toward your intended use case.

Example:

{"task": "a chef for a meal prep planning service"}
​
target_model
string | null
default:
The model this prompt will be used for. This optional parameter helps us understand which models our prompt tools are being used with, but it doesn't currently affect functionality.

Example:

"claude-3-7-sonnet-20250219"
Required string length: 1 - 256
Response
200 - application/json
Response Generate Prompt V1 Experimental Generate Prompt Post
Response Generate Prompt V1 Experimental Generate Prompt Post
​
messages
object[]
required
The response contains a list of message objects in the same format used by the Messages API. Typically includes a user message with the complete generated prompt text, and may include an assistant message with a prefill to guide the model's initial response.

These messages can be used directly in a Messages API request to start a conversation with the generated prompt.

Example:

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "You are a chef for a meal prep planning service..."
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "<recipe_planning>"
        }
      ]
    }
  ]
}

Show child attributes

​
system
string
default:
required
Currently, the system field is always returned as an empty string (""). In future iterations, this field may contain generated system prompts.

Directions similar to what would normally be included in a system prompt are included in messages when generating a prompt.

​
usage
object
required
Usage information


Show child attributes

Was this page helpful?


Yes

No
OpenAI SDK compatibility (beta)
Improve a prompt
x
linkedin

cURL

Python

JavaScript

curl -X POST https://api.anthropic.com/v1/experimental/generate_prompt \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: prompt-tools-2025-04-02" \
     --header "content-type: application/json" \
     --data \
'{
    "task": "a chef for a meal prep planning service",
    "target_model": "claude-3-7-sonnet-20250219",
}'

200

4XX

{
  "messages": [
    {
      "content": [
        {
          "text": "<generated prompt>",
          "type": "text"
        }
      ],
      "role": "user"
    }
  ],
  "system": "",
  "usage": [
    {
      "input_tokens": 490,
      "output_tokens": 661
    }
  ]
}
Generate a prompt - Anthropic



Prompt tools
Improve a prompt
Create a new-and-improved prompt guided by feedback

POST
/
v1
/
experimental
/
improve_prompt
The prompt tools APIs are in a closed research preview. Request to join the closed research preview.

​
Before you begin
The prompt tools are a set of APIs to generate and improve prompts. Unlike our other APIs, this is an experimental API: you’ll need to request access, and it doesn’t have the same level of commitment to long-term support as other APIs.

These APIs are similar to what’s available in the Anthropic Workbench, and are intented for use by other prompt engineering platforms and playgrounds.

​
Getting started with the prompt improver
To use the prompt generation API, you’ll need to:

Have joined the closed research preview for the prompt tools APIs
Use the API directly, rather than the SDK
Add the beta header prompt-tools-2025-04-02
This API is not available in the SDK

​
Improve a prompt
Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Body
application/json
​
messages
object[]
required
The prompt to improve, structured as a list of message objects.

Each message in the messages array must:

Contain only text-only content blocks
Not include tool calls, images, or prompt caching blocks
As a simple text prompt:

[
  {
    "role": "user", 
    "content": [
      {
        "type": "text",
        "text": "Concise recipe for {{food}}"
      }
    ]
  }
]
With example interactions to guide improvement:

[
  {
    "role": "user", 
    "content": [
      {
        "type": "text",
        "text": "Concise for {{food}}.\n\nexample\mandu: Put the mandu in the air fryer at 380F for 7 minutes."
      }
    ]
  }
]
Note that only contiguous user messages with text content are allowed. Assistant prefill is permitted, but other content types will cause validation errors.


Show child attributes

​
feedback
string | null
Feedback for improving the prompt.

Use this parameter to share specific guidance on what aspects of the prompt should be enhanced or modified.

Example:

{
  "messages": [...],
  "feedback": "Make the recipes shorter"
}
When not set, the API will improve the prompt using general prompt engineering best practices.

​
system
string | null
The existing system prompt to incorporate, if any.

{
  "system": "You are a professional meal prep chef",
  [...]
}
Note that while system prompts typically appear as separate parameters in standard API calls, in the improve_prompt response, the system content will be incorporated directly into the returned user message.

​
target_model
string | null
default:
The model this prompt will be used for. This optional parameter helps us understand which models our prompt tools are being used with, but it doesn't currently affect functionality.

Example:

"claude-3-7-sonnet-20250219"
Required string length: 1 - 256
Response
200 - application/json
Response Improve Prompt V1 Experimental Improve Prompt Post
Response Improve Prompt V1 Experimental Improve Prompt Post
​
messages
object[]
required
Contains the result of the prompt improvement process in a list of message objects.

Includes a user-role message with the improved prompt text and may optionally include an assistant-role message with a prefill. These messages follow the standard Messages API format and can be used directly in subsequent API calls.


Show child attributes

​
system
string
required
Currently, the system field is always returned as an empty string (""). In future iterations, this field may contain generated system prompts.

Directions similar to what would normally be included in a system prompt are included in messages when improving a prompt.

​
usage
object
required
Usage information


Show child attributes

Was this page helpful?


Yes

No
Generate a prompt
Templatize a prompt
x
linkedin

cURL

Python

JavaScript

curl -X POST https://api.anthropic.com/v1/experimental/improve_prompt \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: prompt-tools-2025-04-02" \
     --header "content-type: application/json" \
     --data \
'{
    "messages": [{"role": "user", "content": [{"type": "text", "text": "Create a recipe for {{food}}"}]}],
    "system": "You are a professional chef",
    "feedback": "Make it more detailed and include cooking times",
    "target_model": "claude-3-7-sonnet-20250219"
}'

200

4XX

{
  "messages": [
    {
      "content": [
        {
          "text": "<improved prompt>",
          "type": "text"
        }
      ],
      "role": "user"
    },
    {
      "content": [
        {
          "text": "<assistant prefill>",
          "type": "text"
        }
      ],
      "role": "assistant"
    }
  ],
  "system": "",
  "usage": [
    {
      "input_tokens": 490,
      "output_tokens": 661
    }
  ]
}
Improve a prompt - Anthropic


Prompt tools
Templatize a prompt
Templatize a prompt by indentifying and extracting variables

POST
/
v1
/
experimental
/
templatize_prompt
The prompt tools APIs are in a closed research preview. Request to join the closed research preview.

​
Before you begin
The prompt tools are a set of APIs to generate and improve prompts. Unlike our other APIs, this is an experimental API: you’ll need to request access, and it doesn’t have the same level of commitment to long-term support as other APIs.

These APIs are similar to what’s available in the Anthropic Workbench, and are intented for use by other prompt engineering platforms and playgrounds.

​
Getting started with the prompt improver
To use the prompt generation API, you’ll need to:

Have joined the closed research preview for the prompt tools APIs
Use the API directly, rather than the SDK
Add the beta header prompt-tools-2025-04-02
This API is not available in the SDK

​
Templatize a prompt
Headers
​
anthropic-beta
string[]
Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​
x-api-key
string
required
Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Body
application/json
​
messages
object[]
required
The prompt to templatize, structured as a list of message objects.

Each message in the messages array must:

Contain only text-only content blocks
Not include tool calls, images, or prompt caching blocks
Example of a simple text prompt:

[
  {
    "role": "user", 
    "content": [
      {
        "type": "text",
        "text": "Translate hello to German"
      }
    ]
  }
]
Note that only contiguous user messages with text content are allowed. Assistant prefill is permitted, but other content types will cause validation errors.


Show child attributes

​
system
string | null
The existing system prompt to templatize.

{
  "system": "You are a professional English to German translator",
  [...]
}
Note that this differs from the Messages API; it is strictly a string.

Response
200 - application/json
Response Templatize Prompt V1 Experimental Templatize Prompt Post
Response Templatize Prompt V1 Experimental Templatize Prompt Post
​
messages
object[]
required
The templatized prompt with variable placeholders.

The response includes the input messages with specific values replaced by variable placeholders. These messages maintain the original message structure but contain uppercase variable names in place of concrete values.

For example, an input message content like "Translate hello to German" would be transformed to "Translate {{WORD_TO_TRANSLATE}} to {{TARGET_LANGUAGE}}".

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Translate {{WORD_TO_TRANSLATE}} to {{TARGET_LANGUAGE}}"
        }
      ]
    }
  ]
}

Show child attributes

​
system
string
required
The input system prompt with variables identified and replaced.

If no system prompt was provided in the original request, this field will be an empty string.

​
usage
object
required
Usage information


Show child attributes

​
variable_values
object
required
A mapping of template variable names to their original values, as extracted from the input prompt during templatization. Each key represents a variable name identified in the templatized prompt, and each value contains the corresponding content from the original prompt that was replaced by that variable.

Example:

"variable_values": {
  "WORD_TO_TRANSLATE": "hello",
  "TARGET_LANGUAGE": "German"
}
In this example response, the original prompt – Translate hello to German – was templatized to Translate WORD_TO_TRANSLATE to TARGET_LANGUAGE, with the variable values extracted as shown.


Show child attributes

Was this page helpful?


Yes

No
Improve a prompt
Amazon Bedrock API
x
linkedin

cURL

Python

JavaScript

curl -X POST https://api.anthropic.com/v1/experimental/templatize_prompt \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: prompt-tools-2025-04-02" \
     --header "content-type: application/json" \
     --data \
'{
    "messages": [{"role": "user", "content": "Translate hello to German"}],
    "system": "You are an English to German translator"
}'

200

4XX

{
  "messages": [
    {
      "content": [
        {
          "text": "Translate {{WORD_TO_TRANSLATE}} to {{TARGET_LANGUAGE}}",
          "type": "text"
        }
      ],
      "role": "user"
    }
  ],
  "system": "You are a professional English to {{TARGET_LANGUAGE}} translator",
  "usage": [
    {
      "input_tokens": 490,
      "output_tokens": 661
    }
  ],
  "variable_values": {
    "TARGET_LANGUAGE": "German",
    "WORD_TO_TRANSLATE": "hello"
  }
}
Templatize a prompt - Anthropic

Amazon Bedrock API
Amazon Bedrock API
Anthropic’s Claude models are now generally available through Amazon Bedrock.

Calling Claude through Bedrock slightly differs from how you would call Claude when using Anthropic’s client SDK’s. This guide will walk you through the process of completing an API call to Claude on Bedrock in either Python or TypeScript.

Note that this guide assumes you have already signed up for an AWS account and configured programmatic access.

​
Install and configure the AWS CLI
Install a version of the AWS CLI at or newer than version 2.13.23
Configure your AWS credentials using the AWS configure command (see Configure the AWS CLI) or find your credentials by navigating to “Command line or programmatic access” within your AWS dashboard and following the directions in the popup modal.
Verify that your credentials are working:
Shell

aws sts get-caller-identity
​
Install an SDK for accessing Bedrock
Anthropic’s client SDKs support Bedrock. You can also use an AWS SDK like boto3 directly.


Python

TypeScript

Boto3 (Python)

pip install -U "anthropic[bedrock]"
​
Accessing Bedrock
​
Subscribe to Anthropic models
Go to the AWS Console > Bedrock > Model Access and request access to Anthropic models. Note that Anthropic model availability varies by region. See AWS documentation for latest information.

​
API model names
Model	Bedrock API model name
Claude 3 Haiku	anthropic.claude-3-haiku-20240307-v1:0
Claude 3 Sonnet	anthropic.claude-3-sonnet-20240229-v1:0
Claude 3 Opus	anthropic.claude-3-opus-20240229-v1:0
Claude 3.5 Haiku	anthropic.claude-3-5-haiku-20241022-v1:0
Claude 3.5 Sonnet	anthropic.claude-3-5-sonnet-20241022-v2:0
Claude 3.7 Sonnet	anthropic.claude-3-7-sonnet-20250219-v1:0
​
List available models
The following examples show how to print a list of all the Claude models available through Bedrock:


AWS CLI

Boto3 (Python)

aws bedrock list-foundation-models --region=us-west-2 --by-provider anthropic --query "modelSummaries[*].modelId"
​
Making requests
The following examples shows how to generate text from Claude 3 Sonnet on Bedrock:


Python

TypeScript

Boto3 (Python)

from anthropic import AnthropicBedrock

client = AnthropicBedrock(
    # Authenticate by either providing the keys below or use the default AWS credential providers, such as
    # using ~/.aws/credentials or the "AWS_SECRET_ACCESS_KEY" and "AWS_ACCESS_KEY_ID" environment variables.
    aws_access_key="<access key>",
    aws_secret_key="<secret key>",
    # Temporary credentials can be used with aws_session_token.
    # Read more at https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html.
    aws_session_token="<session_token>",
    # aws_region changes the aws region to which the request is made. By default, we read AWS_REGION,
    # and if that's not present, we default to us-east-1. Note that we do not read ~/.aws/config for the region.
    aws_region="us-west-2",
)

message = client.messages.create(
    model="anthropic.claude-3-7-sonnet-20250219-v1:0",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello, world"}]
)
print(message.content)
See our client SDKs for more details, and the official Bedrock docs here.

Was this page helpful?


Yes

No
Templatize a prompt
Vertex AI API
x
linkedin
On this page
Install and configure the AWS CLI
Install an SDK for accessing Bedrock
Accessing Bedrock
Subscribe to Anthropic models
API model names
List available models
Making requests
Amazon Bedrock API - Anthropic


Vertex AI
Vertex AI API
Anthropic’s Claude models are now generally available through Vertex AI.

The Vertex API for accessing Claude is nearly-identical to the Messages API and supports all of the same options, with two key differences:

In Vertex, model is not passed in the request body. Instead, it is specified in the Google Cloud endpoint URL.
In Vertex, anthropic_version is passed in the request body (rather than as a header), and must be set to the value vertex-2023-10-16.
Vertex is also supported by Anthropic’s official client SDKs. This guide will walk you through the process of making a request to Claude on Vertex AI in either Python or TypeScript.

Note that this guide assumes you have already have a GCP project that is able to use Vertex AI. See using the Claude 3 models from Anthropic for more information on the setup required, as well as a full walkthrough.

​
Install an SDK for accessing Vertex AI
First, install Anthropic’s client SDK for your language of choice.


Python

TypeScript

pip install -U google-cloud-aiplatform "anthropic[vertex]"
​
Accessing Vertex AI
​
Model Availability
Note that Anthropic model availability varies by region. Search for “Claude” in the Vertex AI Model Garden or go to Use Claude 3 for the latest information.

​
API model names
Model	Vertex AI API model name
Claude 3 Haiku	claude-3-haiku@20240307
Claude 3 Sonnet	claude-3-sonnet@20240229
Claude 3 Opus (Public Preview)	claude-3-opus@20240229
Claude 3.5 Haiku	claude-3-5-haiku@20241022
Claude 3.5 Sonnet	claude-3-5-sonnet-v2@20241022
Claude 3.7 Sonnet	claude-3-7-sonnet@20250219
​
Making requests
Before running requests you may need to run gcloud auth application-default login to authenticate with GCP.

The following examples shows how to generate text from Claude 3.7 Sonnet on Vertex AI:


Python

TypeScript

cURL

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
# Where the model is running
region = "us-east5"

client = AnthropicVertex(project_id=project_id, region=region)

message = client.messages.create(
    model="claude-3-7-sonnet@20250219",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Hey Claude!",
        }
    ],
)
print(message)
See our client SDKs and the official Vertex AI docs for more details.

Was this page helpful?


Yes

No
Amazon Bedrock API
x
linkedin
On this page
Install an SDK for accessing Vertex AI
Accessing Vertex AI
Model Availability
API model names
Making requests
Vertex AI API - Anthropic

MCP Java SDK Migration Guide: 0.7.0 to 0.8.0
This document outlines the breaking changes and provides guidance on how to migrate your code from version 0.7.0 to 0.8.0.

The 0.8.0 refactoring introduces a session-based architecture for server-side MCP implementations. It improves the SDK's ability to handle multiple concurrent client connections and provides an API better aligned with the MCP specification. The main changes include:

Introduction of a session-based architecture
New transport provider abstraction
Exchange objects for client interaction
Renamed and reorganized interfaces
Updated handler signatures
Breaking Changes
1. Interface Renaming
Several interfaces have been renamed to better reflect their roles:

0.7.0 (Old)	0.8.0 (New)
ClientMcpTransport	McpClientTransport
ServerMcpTransport	McpServerTransport
DefaultMcpSession	McpClientSession, McpServerSession
2. New Server Transport Architecture
The most significant change is the introduction of the McpServerTransportProvider interface, which replaces direct usage of ServerMcpTransport when creating servers. This new pattern separates the concerns of:

Transport Provider: Manages connections with clients and creates individual transports for each connection
Server Transport: Handles communication with a specific client connection
0.7.0 (Old)	0.8.0 (New)
ServerMcpTransport	McpServerTransportProvider + McpServerTransport
Direct transport usage	Session-based transport usage
Before (0.7.0):
// Create a transport
ServerMcpTransport transport = new WebFluxSseServerTransport(objectMapper, "/mcp/message");

// Create a server with the transport
McpServer.sync(transport)
    .serverInfo("my-server", "1.0.0")
    .build();
After (0.8.0):
// Create a transport provider
McpServerTransportProvider transportProvider = new WebFluxSseServerTransportProvider(objectMapper, "/mcp/message");

// Create a server with the transport provider
McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();
3. Handler Method Signature Changes
Tool, resource, and prompt handlers now receive an additional exchange parameter that provides access to client capabilities and methods to interact with the client:

0.7.0 (Old)	0.8.0 (New)
(args) -> result	(exchange, args) -> result
The exchange objects (McpAsyncServerExchange and McpSyncServerExchange) provide context for the current session and access to session-specific operations.

Before (0.7.0):
// Tool handler
.tool(calculatorTool, args -> new CallToolResult("Result: " + calculate(args)))

// Resource handler
.resource(fileResource, req -> new ReadResourceResult(readFile(req)))

// Prompt handler
.prompt(analysisPrompt, req -> new GetPromptResult("Analysis prompt"))
After (0.8.0):
// Tool handler
.tool(calculatorTool, (exchange, args) -> new CallToolResult("Result: " + calculate(args)))

// Resource handler
.resource(fileResource, (exchange, req) -> new ReadResourceResult(readFile(req)))

// Prompt handler
.prompt(analysisPrompt, (exchange, req) -> new GetPromptResult("Analysis prompt"))
4. Registration vs. Specification
The naming convention for handlers has changed from "Registration" to "Specification":

0.7.0 (Old)	0.8.0 (New)
AsyncToolRegistration	AsyncToolSpecification
SyncToolRegistration	SyncToolSpecification
AsyncResourceRegistration	AsyncResourceSpecification
SyncResourceRegistration	SyncResourceSpecification
AsyncPromptRegistration	AsyncPromptSpecification
SyncPromptRegistration	SyncPromptSpecification
5. Roots Change Handler Updates
The roots change handlers now receive an exchange parameter:

Before (0.7.0):
.rootsChangeConsumers(List.of(
    roots -> {
        // Process roots
    }
))
After (0.8.0):
.rootsChangeHandlers(List.of(
    (exchange, roots) -> {
        // Process roots with access to exchange
    }
))
6. Server Creation Method Changes
The McpServer factory methods now accept McpServerTransportProvider instead of ServerMcpTransport:

0.7.0 (Old)	0.8.0 (New)
McpServer.async(ServerMcpTransport)	McpServer.async(McpServerTransportProvider)
McpServer.sync(ServerMcpTransport)	McpServer.sync(McpServerTransportProvider)
The method names for creating servers have been updated:

Root change handlers now receive an exchange object:

0.7.0 (Old)	0.8.0 (New)
rootsChangeConsumers(List<Consumer<List<Root>>>)	rootsChangeHandlers(List<BiConsumer<McpSyncServerExchange, List<Root>>>)
rootsChangeConsumer(Consumer<List<Root>>)	rootsChangeHandler(BiConsumer<McpSyncServerExchange, List<Root>>)
7. Direct Server Methods Moving to Exchange
Several methods that were previously available directly on the server are now accessed through the exchange object:

0.7.0 (Old)	0.8.0 (New)
server.listRoots()	exchange.listRoots()
server.createMessage()	exchange.createMessage()
server.getClientCapabilities()	exchange.getClientCapabilities()
server.getClientInfo()	exchange.getClientInfo()
The direct methods are deprecated and will be removed in 0.9.0:

McpSyncServer.listRoots()
McpSyncServer.getClientCapabilities()
McpSyncServer.getClientInfo()
McpSyncServer.createMessage()
McpAsyncServer.listRoots()
McpAsyncServer.getClientCapabilities()
McpAsyncServer.getClientInfo()
McpAsyncServer.createMessage()
Deprecation Notices
The following components are deprecated in 0.8.0 and will be removed in 0.9.0:

ClientMcpTransport interface (use McpClientTransport instead)
ServerMcpTransport interface (use McpServerTransport instead)
DefaultMcpSession class (use McpClientSession instead)
WebFluxSseServerTransport class (use WebFluxSseServerTransportProvider instead)
WebMvcSseServerTransport class (use WebMvcSseServerTransportProvider instead)
StdioServerTransport class (use StdioServerTransportProvider instead)
All *Registration classes (use corresponding *Specification classes instead)
Direct server methods for client interaction (use exchange object instead)
Migration Examples
Example 1: Creating a Server
Before (0.7.0):
// Create a transport
ServerMcpTransport transport = new WebFluxSseServerTransport(objectMapper, "/mcp/message");

// Create a server with the transport
var server = McpServer.sync(transport)
    .serverInfo("my-server", "1.0.0")
    .tool(calculatorTool, args -> new CallToolResult("Result: " + calculate(args)))
    .rootsChangeConsumers(List.of(
        roots -> System.out.println("Roots changed: " + roots)
    ))
    .build();

// Get client capabilities directly from server
ClientCapabilities capabilities = server.getClientCapabilities();
After (0.8.0):
// Create a transport provider
McpServerTransportProvider transportProvider = new WebFluxSseServerTransportProvider(objectMapper, "/mcp/message");

// Create a server with the transport provider
var server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .tool(calculatorTool, (exchange, args) -> {
        // Get client capabilities from exchange
        ClientCapabilities capabilities = exchange.getClientCapabilities();
        return new CallToolResult("Result: " + calculate(args));
    })
    .rootsChangeHandlers(List.of(
        (exchange, roots) -> System.out.println("Roots changed: " + roots)
    ))
    .build();
Example 2: Implementing a Tool with Client Interaction
Before (0.7.0):
McpServerFeatures.SyncToolRegistration tool = new McpServerFeatures.SyncToolRegistration(
    new Tool("weather", "Get weather information", schema),
    args -> {
        String location = (String) args.get("location");
        // Cannot interact with client from here
        return new CallToolResult("Weather for " + location + ": Sunny");
    }
);

var server = McpServer.sync(transport)
    .tools(tool)
    .build();

// Separate call to create a message
CreateMessageResult result = server.createMessage(new CreateMessageRequest(...));
After (0.8.0):
McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(
    new Tool("weather", "Get weather information", schema),
    (exchange, args) -> {
        String location = (String) args.get("location");
        
        // Can interact with client directly from the tool handler
        CreateMessageResult result = exchange.createMessage(new CreateMessageRequest(...));
        
        return new CallToolResult("Weather for " + location + ": " + result.content());
    }
);

var server = McpServer.sync(transportProvider)
    .tools(tool)
    .build();
Example 3: Converting Existing Registration Classes
If you have custom implementations of the registration classes, you can convert them to the new specification classes:

Before (0.7.0):
McpServerFeatures.AsyncToolRegistration toolReg = new McpServerFeatures.AsyncToolRegistration(
    tool,
    args -> Mono.just(new CallToolResult("Result"))
);

McpServerFeatures.AsyncResourceRegistration resourceReg = new McpServerFeatures.AsyncResourceRegistration(
    resource,
    req -> Mono.just(new ReadResourceResult(List.of()))
);
After (0.8.0):
// Option 1: Create new specification directly
McpServerFeatures.AsyncToolSpecification toolSpec = new McpServerFeatures.AsyncToolSpecification(
    tool,
    (exchange, args) -> Mono.just(new CallToolResult("Result"))
);

// Option 2: Convert from existing registration (during transition)
McpServerFeatures.AsyncToolRegistration oldToolReg = /* existing registration */;
McpServerFeatures.AsyncToolSpecification toolSpec = oldToolReg.toSpecification();

// Similarly for resources
McpServerFeatures.AsyncResourceSpecification resourceSpec = new McpServerFeatures.AsyncResourceSpecification(
    resource,
    (exchange, req) -> Mono.just(new ReadResourceResult(List.of()))
);
Architecture Changes
Session-Based Architecture
In 0.8.0, the MCP Java SDK introduces a session-based architecture where each client connection has its own session. This allows for better isolation between clients and more efficient resource management.

The McpServerTransportProvider is responsible for creating McpServerTransport instances for each session, and the McpServerSession manages the communication with a specific client.

Exchange Objects
The new exchange objects (McpAsyncServerExchange and McpSyncServerExchange) provide access to client-specific information and methods. They are passed to handler functions as the first parameter, allowing handlers to interact with the specific client that made the request.

Conclusion
The changes in version 0.8.0 represent a significant architectural improvement to the MCP Java SDK. While they require some code changes, the new design provides a more flexible and maintainable foundation for building MCP applications.

For assistance with migration or to report issues, please open an issue on the GitHub repository.



Model Context Protocol specification
Protocol Revision: 2025-03-26
Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you’re building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.

This specification defines the authoritative protocol requirements, based on the TypeScript schema in schema.ts.

For implementation guides and examples, visit modelcontextprotocol.io.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Overview 
MCP provides a standardized way for applications to:

Share contextual information with language models
Expose tools and capabilities to AI systems
Build composable integrations and workflows
The protocol uses JSON-RPC 2.0 messages to establish communication between:

Hosts: LLM applications that initiate connections
Clients: Connectors within the host application
Servers: Services that provide context and capabilities
MCP takes some inspiration from the Language Server Protocol, which standardizes how to add support for programming languages across a whole ecosystem of development tools. In a similar way, MCP standardizes how to integrate additional context and tools into the ecosystem of AI applications.

Key Details 
Base Protocol 
JSON-RPC message format
Stateful connections
Server and client capability negotiation
Features 
Servers offer any of the following features to clients:

Resources: Context and data, for the user or the AI model to use
Prompts: Templated messages and workflows for users
Tools: Functions for the AI model to execute
Clients may offer the following feature to servers:

Sampling: Server-initiated agentic behaviors and recursive LLM interactions
Additional Utilities 
Configuration
Progress tracking
Cancellation
Error reporting
Logging
Security and Trust & Safety 
The Model Context Protocol enables powerful capabilities through arbitrary data access and code execution paths. With this power comes important security and trust considerations that all implementors must carefully address.

Key Principles 
User Consent and Control

Users must explicitly consent to and understand all data access and operations
Users must retain control over what data is shared and what actions are taken
Implementors should provide clear UIs for reviewing and authorizing activities
Data Privacy

Hosts must obtain explicit user consent before exposing user data to servers
Hosts must not transmit resource data elsewhere without user consent
User data should be protected with appropriate access controls
Tool Safety

Tools represent arbitrary code execution and must be treated with appropriate caution.
In particular, descriptions of tool behavior such as annotations should be considered untrusted, unless obtained from a trusted server.
Hosts must obtain explicit user consent before invoking any tool
Users should understand what each tool does before authorizing its use
LLM Sampling Controls

Users must explicitly approve any LLM sampling requests
Users should control:
Whether sampling occurs at all
The actual prompt that will be sent
What results the server can see
The protocol intentionally limits server visibility into prompts
Implementation Guidelines 
While MCP itself cannot enforce these security principles at the protocol level, implementors SHOULD:

Build robust consent and authorization flows into their applications
Provide clear documentation of security implications
Implement appropriate access controls and data protections
Follow security best practices in their integrations
Consider privacy implications in their feature designs

Base Protocol
Protocol Revision: 2025-03-26
The Model Context Protocol consists of several key components that work together:

Base Protocol: Core JSON-RPC message types
Lifecycle Management: Connection initialization, capability negotiation, and session control
Server Features: Resources, prompts, and tools exposed by servers
Client Features: Sampling and root directory lists provided by clients
Utilities: Cross-cutting concerns like logging and argument completion
All implementations MUST support the base protocol and lifecycle management components. Other components MAY be implemented based on the specific needs of the application.

These protocol layers establish clear separation of concerns while enabling rich interactions between clients and servers. The modular design allows implementations to support exactly the features they need.

Messages 
All messages between MCP clients and servers MUST follow the JSON-RPC 2.0 specification. The protocol defines these types of messages:

Requests 
Requests are sent from the client to the server or vice versa, to initiate an operation.

{
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: {
    [key: string]: unknown;
  };
}

Requests MUST include a string or integer ID.
Unlike base JSON-RPC, the ID MUST NOT be null.
The request ID MUST NOT have been previously used by the requestor within the same session.
Responses 
Responses are sent in reply to requests, containing the result or error of the operation.

{
  jsonrpc: "2.0";
  id: string | number;
  result?: {
    [key: string]: unknown;
  }
  error?: {
    code: number;
    message: string;
    data?: unknown;
  }
}

Responses MUST include the same ID as the request they correspond to.
Responses are further sub-categorized as either successful results or errors. Either a result or an error MUST be set. A response MUST NOT set both.
Results MAY follow any JSON object structure, while errors MUST include an error code and message at minimum.
Error codes MUST be integers.
Notifications 
Notifications are sent from the client to the server or vice versa, as a one-way message. The receiver MUST NOT send a response.

{
  jsonrpc: "2.0";
  method: string;
  params?: {
    [key: string]: unknown;
  };
}

Notifications MUST NOT include an ID.
Batching 
JSON-RPC also defines a means to batch multiple requests and notifications, by sending them in an array. MCP implementations MAY support sending JSON-RPC batches, but MUST support receiving JSON-RPC batches.

Auth 
MCP provides an Authorization framework for use with HTTP. Implementations using an HTTP-based transport SHOULD conform to this specification, whereas implementations using STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.

Additionally, clients and servers MAY negotiate their own custom authentication and authorization strategies.

For further discussions and contributions to the evolution of MCP’s auth mechanisms, join us in GitHub Discussions to help shape the future of the protocol!

Schema 
The full specification of the protocol is defined as a TypeScript schema. This is the source of truth for all protocol messages and structures.

There is also a JSON Schema, which is automatically generated from the TypeScript source of truth, for use with various automated tooling.

Transports
Protocol Revision: 2025-03-26
MCP uses JSON-RPC to encode messages. JSON-RPC messages MUST be UTF-8 encoded.

The protocol currently defines two standard transport mechanisms for client-server communication:

stdio, communication over standard in and standard out
Streamable HTTP
Clients SHOULD support stdio whenever possible.

It is also possible for clients and servers to implement custom transports in a pluggable fashion.

stdio 
In the stdio transport:

The client launches the MCP server as a subprocess.
The server reads JSON-RPC messages from its standard input (stdin) and sends messages to its standard output (stdout).
Messages may be JSON-RPC requests, notifications, responses—or a JSON-RPC batch containing one or more requests and/or notifications.
Messages are delimited by newlines, and MUST NOT contain embedded newlines.
The server MAY write UTF-8 strings to its standard error (stderr) for logging purposes. Clients MAY capture, forward, or ignore this logging.
The server MUST NOT write anything to its stdout that is not a valid MCP message.
The client MUST NOT write anything to the server’s stdin that is not a valid MCP message.
Server Process
Client
Server Process
Client
loop
[Message Exchange]
Launch subprocess
Write to stdin
Write to stdout
Optional logs on stderr
Close stdin, terminate subprocess
Streamable HTTP 
This replaces the HTTP+SSE transport from protocol version 2024-11-05. See the backwards compatibility guide below.
In the Streamable HTTP transport, the server operates as an independent process that can handle multiple client connections. This transport uses HTTP POST and GET requests. Server can optionally make use of Server-Sent Events (SSE) to stream multiple server messages. This permits basic MCP servers, as well as more feature-rich servers supporting streaming and server-to-client notifications and requests.

The server MUST provide a single HTTP endpoint path (hereafter referred to as the MCP endpoint) that supports both POST and GET methods. For example, this could be a URL like https://example.com/mcp.

Sending Messages to the Server 
Every JSON-RPC message sent from the client MUST be a new HTTP POST request to the MCP endpoint.

The client MUST use HTTP POST to send JSON-RPC messages to the MCP endpoint.
The client MUST include an Accept header, listing both application/json and text/event-stream as supported content types.
The body of the POST request MUST be one of the following:
A single JSON-RPC request, notification, or response
An array batching one or more requests and/or notifications
An array batching one or more responses
If the input consists solely of (any number of) JSON-RPC responses or notifications:
If the server accepts the input, the server MUST return HTTP status code 202 Accepted with no body.
If the server cannot accept the input, it MUST return an HTTP error status code (e.g., 400 Bad Request). The HTTP response body MAY comprise a JSON-RPC error response that has no id.
If the input contains any number of JSON-RPC requests, the server MUST either return Content-Type: text/event-stream, to initiate an SSE stream, or Content-Type: application/json, to return one JSON object. The client MUST support both these cases.
If the server initiates an SSE stream:
The SSE stream SHOULD eventually include one JSON-RPC response per each JSON-RPC request sent in the POST body. These responses MAY be batched.
The server MAY send JSON-RPC requests and notifications before sending a JSON-RPC response. These messages SHOULD relate to the originating client request. These requests and notifications MAY be batched.
The server SHOULD NOT close the SSE stream before sending a JSON-RPC response per each received JSON-RPC request, unless the session expires.
After all JSON-RPC responses have been sent, the server SHOULD close the SSE stream.
Disconnection MAY occur at any time (e.g., due to network conditions). Therefore:
Disconnection SHOULD NOT be interpreted as the client cancelling its request.
To cancel, the client SHOULD explicitly send an MCP CancelledNotification.
To avoid message loss due to disconnection, the server MAY make the stream resumable.
Listening for Messages from the Server 
The client MAY issue an HTTP GET to the MCP endpoint. This can be used to open an SSE stream, allowing the server to communicate to the client, without the client first sending data via HTTP POST.
The client MUST include an Accept header, listing text/event-stream as a supported content type.
The server MUST either return Content-Type: text/event-stream in response to this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the server does not offer an SSE stream at this endpoint.
If the server initiates an SSE stream:
The server MAY send JSON-RPC requests and notifications on the stream. These requests and notifications MAY be batched.
These messages SHOULD be unrelated to any concurrently-running JSON-RPC request from the client.
The server MUST NOT send a JSON-RPC response on the stream unless resuming a stream associated with a previous client request.
The server MAY close the SSE stream at any time.
The client MAY close the SSE stream at any time.
Multiple Connections 
The client MAY remain connected to multiple SSE streams simultaneously.
The server MUST send each of its JSON-RPC messages on only one of the connected streams; that is, it MUST NOT broadcast the same message across multiple streams.
The risk of message loss MAY be mitigated by making the stream resumable.
Resumability and Redelivery 
To support resuming broken connections, and redelivering messages that might otherwise be lost:

Servers MAY attach an id field to their SSE events, as described in the SSE standard.
If present, the ID MUST be globally unique across all streams within that session—or all streams with that specific client, if session management is not in use.
If the client wishes to resume after a broken connection, it SHOULD issue an HTTP GET to the MCP endpoint, and include the Last-Event-ID header to indicate the last event ID it received.
The server MAY use this header to replay messages that would have been sent after the last event ID, on the stream that was disconnected, and to resume the stream from that point.
The server MUST NOT replay messages that would have been delivered on a different stream.
In other words, these event IDs should be assigned by servers on a per-stream basis, to act as a cursor within that particular stream.

Session Management 
An MCP “session” consists of logically related interactions between a client and a server, beginning with the initialization phase. To support servers which want to establish stateful sessions:

A server using the Streamable HTTP transport MAY assign a session ID at initialization time, by including it in an Mcp-Session-Id header on the HTTP response containing the InitializeResult.
The session ID SHOULD be globally unique and cryptographically secure (e.g., a securely generated UUID, a JWT, or a cryptographic hash).
The session ID MUST only contain visible ASCII characters (ranging from 0x21 to 0x7E).
If an Mcp-Session-Id is returned by the server during initialization, clients using the Streamable HTTP transport MUST include it in the Mcp-Session-Id header on all of their subsequent HTTP requests.
Servers that require a session ID SHOULD respond to requests without an Mcp-Session-Id header (other than initialization) with HTTP 400 Bad Request.
The server MAY terminate the session at any time, after which it MUST respond to requests containing that session ID with HTTP 404 Not Found.
When a client receives HTTP 404 in response to a request containing an Mcp-Session-Id, it MUST start a new session by sending a new InitializeRequest without a session ID attached.
Clients that no longer need a particular session (e.g., because the user is leaving the client application) SHOULD send an HTTP DELETE to the MCP endpoint with the Mcp-Session-Id header, to explicitly terminate the session.
The server MAY respond to this request with HTTP 405 Method Not Allowed, indicating that the server does not allow clients to terminate sessions.
Sequence Diagram 
Server
Client
Server
Client
initialization
client requests
loop
[while connection remains open]
alt
[single HTTP response]
[server opens SSE stream]
client notifications/responses
server requests
loop
[while connection remains open]
POST InitializeRequest
InitializeResponse
Mcp-Session-Id: 1868a90c...
POST InitializedNotification
Mcp-Session-Id: 1868a90c...
202 Accepted
POST ... request ...
Mcp-Session-Id: 1868a90c...
... response ...
... SSE messages from server ...
SSE event: ... response ...
POST ... notification/response ...
Mcp-Session-Id: 1868a90c...
202 Accepted
GET
Mcp-Session-Id: 1868a90c...
... SSE messages from server ...
Backwards Compatibility 
Clients and servers can maintain backwards compatibility with the deprecated HTTP+SSE transport (from protocol version 2024-11-05) as follows:

Servers wanting to support older clients should:

Continue to host both the SSE and POST endpoints of the old transport, alongside the new “MCP endpoint” defined for the Streamable HTTP transport.
It is also possible to combine the old POST endpoint and the new MCP endpoint, but this may introduce unneeded complexity.
Clients wanting to support older servers should:

Accept an MCP server URL from the user, which may point to either a server using the old transport or the new transport.
Attempt to POST an InitializeRequest to the server URL, with an Accept header as defined above:
If it succeeds, the client can assume this is a server supporting the new Streamable HTTP transport.
If it fails with an HTTP 4xx status code (e.g., 405 Method Not Allowed or 404 Not Found):
Issue a GET request to the server URL, expecting that this will open an SSE stream and return an endpoint event as the first event.
When the endpoint event arrives, the client can assume this is a server running the old HTTP+SSE transport, and should use that transport for all subsequent communication.
Custom Transports 
Clients and servers MAY implement additional custom transport mechanisms to suit their specific needs. The protocol is transport-agnostic and can be implemented over any communication channel that supports bidirectional message exchange.

Implementers who choose to support custom transports MUST ensure they preserve the JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports SHOULD document their specific connection establishment and message exchange patterns to aid interoperability.

Authorization
Protocol Revision: 2025-03-26
1. Introduction 
1.1 Purpose and Scope 
The Model Context Protocol provides authorization capabilities at the transport level, enabling MCP clients to make requests to restricted MCP servers on behalf of resource owners. This specification defines the authorization flow for HTTP-based transports.

1.2 Protocol Requirements 
Authorization is OPTIONAL for MCP implementations. When supported:

Specification
2025-03-26 (Latest)
Client Features
Roots
Roots
Protocol Revision: 2025-03-26
The Model Context Protocol (MCP) provides a standardized way for clients to expose filesystem “roots” to servers. Roots define the boundaries of where servers can operate within the filesystem, allowing them to understand which directories and files they have access to. Servers can request the list of roots from supporting clients and receive notifications when that list changes.

User Interaction Model 
Roots in MCP are typically exposed through workspace or project configuration interfaces.

For example, implementations could offer a workspace/project picker that allows users to select directories and files the server should have access to. This can be combined with automatic workspace detection from version control systems or project files.

However, implementations are free to expose roots through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.

Capabilities 
Clients that support roots MUST declare the roots capability during initialization:

{
  "capabilities": {
    "roots": {
      "listChanged": true
    }
  }
}

listChanged indicates whether the client will emit notifications when the list of roots changes.

Protocol Messages 
Listing Roots 
To retrieve roots, servers send a roots/list request:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "roots/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "roots": [
      {
        "uri": "file:///home/user/projects/myproject",
        "name": "My Project"
      }
    ]
  }
}

Root List Changes 
When roots change, clients that support listChanged MUST send a notification:

{
  "jsonrpc": "2.0",
  "method": "notifications/roots/list_changed"
}

Message Flow 
Client
Server
Client
Server
Discovery
Changes
roots/list
Available roots
notifications/roots/list_changed
roots/list
Updated roots
Data Types 
Root 
A root definition includes:

uri: Unique identifier for the root. This MUST be a file:// URI in the current specification.
name: Optional human-readable name for display purposes.
Example roots for different use cases:

Project Directory 
{
  "uri": "file:///home/user/projects/myproject",
  "name": "My Project"
}

Multiple Repositories 
[
  {
    "uri": "file:///home/user/repos/frontend",
    "name": "Frontend Repository"
  },
  {
    "uri": "file:///home/user/repos/backend",
    "name": "Backend Repository"
  }
]

Error Handling 
Clients SHOULD return standard JSON-RPC errors for common failure cases:

Client does not support roots: -32601 (Method not found)
Internal errors: -32603
Example error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Roots not supported",
    "data": {
      "reason": "Client does not have roots capability"
    }
  }
}

Security Considerations 
Clients MUST:

Only expose roots with appropriate permissions
Validate all root URIs to prevent path traversal
Implement proper access controls
Monitor root accessibility
Servers SHOULD:

Handle cases where roots become unavailable
Respect root boundaries during operations
Validate all paths against provided roots
Implementation Guidelines 
Clients SHOULD:

Prompt users for consent before exposing roots to servers
Provide clear user interfaces for root management
Validate root accessibility before exposing
Monitor for root changes
Servers SHOULD:

Check for roots capability before usage
Handle root list changes gracefully
Respect root boundaries in operations
Cache root information appropriately

Implementations using an HTTP-based transport SHOULD conform to this specification.
Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.
Implementations using alternative transports MUST follow established security best practices for their protocol.
1.3 Standards Compliance 
This authorization mechanism is based on established specifications listed below, but implements a selected subset of their features to ensure security and interoperability while maintaining simplicity:

OAuth 2.1 IETF DRAFT
OAuth 2.0 Authorization Server Metadata (RFC8414)
OAuth 2.0 Dynamic Client Registration Protocol (RFC7591)
2. Authorization Flow 
2.1 Overview 
MCP auth implementations MUST implement OAuth 2.1 with appropriate security measures for both confidential and public clients.

MCP auth implementations SHOULD support the OAuth 2.0 Dynamic Client Registration Protocol (RFC7591).

MCP servers SHOULD and MCP clients MUST implement OAuth 2.0 Authorization Server Metadata (RFC8414). Servers that do not support Authorization Server Metadata MUST follow the default URI schema.

2.2 Basic OAuth 2.1 Authorization 
When authorization is required and not yet proven by the client, servers MUST respond with HTTP 401 Unauthorized.

Clients initiate the OAuth 2.1 IETF DRAFT authorization flow after receiving the HTTP 401 Unauthorized.

The following demonstrates the basic OAuth 2.1 for public clients using PKCE.

MCP Server
Client
User-Agent (Browser)
MCP Server
Client
User-Agent (Browser)
Generate code_verifier and code_challenge
User logs in and authorizes
Begin standard MCP message exchange
MCP Request
HTTP 401 Unauthorized
Open browser with authorization URL + code_challenge
GET /authorize
Redirect to callback URL with auth code
Callback with authorization code
Token Request with code + code_verifier
Access Token (+ Refresh Token)
MCP Request with Access Token
2.3 Server Metadata Discovery 
For server capability discovery:

MCP clients MUST follow the OAuth 2.0 Authorization Server Metadata protocol defined in RFC8414.
MCP server SHOULD follow the OAuth 2.0 Authorization Server Metadata protocol.
MCP servers that do not support the OAuth 2.0 Authorization Server Metadata protocol, MUST support fallback URLs.
The discovery flow is illustrated below:

Server
Client
Server
Client
Use endpoints from metadata
Fall back to default endpoints
alt
[Discovery Success]
[Discovery Failed]
Continue with authorization flow
GET /.well-known/oauth-authorization-server
200 OK + Metadata Document
404 Not Found
2.3.1 Server Metadata Discovery Headers 
MCP clients SHOULD include the header MCP-Protocol-Version: <protocol-version> during Server Metadata Discovery to allow the MCP server to respond based on the MCP protocol version.

For example: MCP-Protocol-Version: 2024-11-05

2.3.2 Authorization Base URL 
The authorization base URL MUST be determined from the MCP server URL by discarding any existing path component. For example:

If the MCP server URL is https://api.example.com/v1/mcp, then:

The authorization base URL is https://api.example.com
The metadata endpoint MUST be at https://api.example.com/.well-known/oauth-authorization-server
This ensures authorization endpoints are consistently located at the root level of the domain hosting the MCP server, regardless of any path components in the MCP server URL.

2.3.3 Fallbacks for Servers without Metadata Discovery 
For servers that do not implement OAuth 2.0 Authorization Server Metadata, clients MUST use the following default endpoint paths relative to the authorization base URL (as defined in Section 2.3.2):

Endpoint	Default Path	Description
Authorization Endpoint	/authorize	Used for authorization requests
Token Endpoint	/token	Used for token exchange & refresh
Registration Endpoint	/register	Used for dynamic client registration
For example, with an MCP server hosted at https://api.example.com/v1/mcp, the default endpoints would be:

https://api.example.com/authorize
https://api.example.com/token
https://api.example.com/register
Clients MUST first attempt to discover endpoints via the metadata document before falling back to default paths. When using default paths, all other protocol requirements remain unchanged.

2.3 Dynamic Client Registration 
MCP clients and servers SHOULD support the OAuth 2.0 Dynamic Client Registration Protocol to allow MCP clients to obtain OAuth client IDs without user interaction. This provides a standardized way for clients to automatically register with new servers, which is crucial for MCP because:

Clients cannot know all possible servers in advance
Manual registration would create friction for users
It enables seamless connection to new servers
Servers can implement their own registration policies
Any MCP servers that do not support Dynamic Client Registration need to provide alternative ways to obtain a client ID (and, if applicable, client secret). For one of these servers, MCP clients will have to either:

Hardcode a client ID (and, if applicable, client secret) specifically for that MCP server, or
Present a UI to users that allows them to enter these details, after registering an OAuth client themselves (e.g., through a configuration interface hosted by the server).
2.4 Authorization Flow Steps 
The complete Authorization flow proceeds as follows:

MCP Server
Client
User-Agent (Browser)
MCP Server
Client
User-Agent (Browser)
alt
[Server Supports Discovery]
[No Discovery]
alt
[Dynamic Client Registration]
Generate PKCE Parameters
User /authorizes
GET /.well-known/oauth-authorization-server
Authorization Server Metadata
404 (Use default endpoints)
POST /register
Client Credentials
Open browser with authorization URL + code_challenge
Authorization Request
Redirect to callback with authorization code
Authorization code callback
Token Request + code_verifier
Access Token (+ Refresh Token)
API Requests with Access Token
2.4.1 Decision Flow Overview 
Available
Not Available
Available
Not Available
Start Auth Flow
Check Metadata Discovery
Use Metadata Endpoints
Use Default Endpoints
Check Registration Endpoint
Perform Dynamic Registration
Alternative Registration Required
Start OAuth Flow
Generate PKCE Parameters
Request Authorization
User Authorization
Exchange Code for Tokens
Use Access Token
2.5 Access Token Usage 
2.5.1 Token Requirements 
Access token handling MUST conform to OAuth 2.1 Section 5 requirements for resource requests. Specifically:

MCP client MUST use the Authorization request header field Section 5.1.1:
Authorization: Bearer <access-token>

Note that authorization MUST be included in every HTTP request from client to server, even if they are part of the same logical session.

Access tokens MUST NOT be included in the URI query string
Example request:

GET /v1/contexts HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

2.5.2 Token Handling 
Resource servers MUST validate access tokens as described in Section 5.2. If validation fails, servers MUST respond according to Section 5.3 error handling requirements. Invalid or expired tokens MUST receive a HTTP 401 response.

2.6 Security Considerations 
The following security requirements MUST be implemented:

Clients MUST securely store tokens following OAuth 2.0 best practices
Servers SHOULD enforce token expiration and rotation
All authorization endpoints MUST be served over HTTPS
Servers MUST validate redirect URIs to prevent open redirect vulnerabilities
Redirect URIs MUST be either localhost URLs or HTTPS URLs
2.7 Error Handling 
Servers MUST return appropriate HTTP status codes for authorization errors:

Status Code	Description	Usage
401	Unauthorized	Authorization required or token invalid
403	Forbidden	Invalid scopes or insufficient permissions
400	Bad Request	Malformed authorization request
2.8 Implementation Requirements 
Implementations MUST follow OAuth 2.1 security best practices
PKCE is REQUIRED for all clients
Token rotation SHOULD be implemented for enhanced security
Token lifetimes SHOULD be limited based on security requirements
2.9 Third-Party Authorization Flow 
2.9.1 Overview 
MCP servers MAY support delegated authorization through third-party authorization servers. In this flow, the MCP server acts as both an OAuth client (to the third-party auth server) and an OAuth authorization server (to the MCP client).

2.9.2 Flow Description 
The third-party authorization flow comprises these steps:

MCP client initiates standard OAuth flow with MCP server
MCP server redirects user to third-party authorization server
User authorizes with third-party server
Third-party server redirects back to MCP server with authorization code
MCP server exchanges code for third-party access token
MCP server generates its own access token bound to the third-party session
MCP server completes original OAuth flow with MCP client
Third-Party Auth Server
MCP Server
MCP Client
User-Agent (Browser)
Third-Party Auth Server
MCP Server
MCP Client
User-Agent (Browser)
User authorizes
Generate bound MCP token
Initial OAuth Request
Redirect to Third-Party /authorize
Authorization Request
Redirect to MCP Server callback
Authorization code
Exchange code for token
Third-party access token
Redirect to MCP Client callback
MCP authorization code
Exchange code for token
MCP access token
2.9.3 Session Binding Requirements 
MCP servers implementing third-party authorization MUST:

Maintain secure mapping between third-party tokens and issued MCP tokens
Validate third-party token status before honoring MCP tokens
Implement appropriate token lifecycle management
Handle third-party token expiration and renewal
2.9.4 Security Considerations 
When implementing third-party authorization, servers MUST:

Validate all redirect URIs
Securely store third-party credentials
Implement appropriate session timeout handling
Consider security implications of token chaining
Implement proper error handling for third-party auth failures
3. Best Practices 
3.1 Local clients as Public OAuth 2.1 Clients 
We strongly recommend that local clients implement OAuth 2.1 as a public client:

Utilizing code challenges (PKCE) for authorization requests to prevent interception attacks
Implementing secure token storage appropriate for the local system
Following token refresh best practices to maintain sessions
Properly handling token expiration and renewal
3.2 Authorization Metadata Discovery 
We strongly recommend that all clients implement metadata discovery. This reduces the need for users to provide endpoints manually or clients to fallback to the defined defaults.

3.3 Dynamic Client Registration 
Since clients do not know the set of MCP servers in advance, we strongly recommend the implementation of dynamic client registration. This allows applications to automatically register with the MCP server, and removes the need for users to obtain client ids manually.

Specification
2025-03-26 (Latest)
Client Features
Roots
Roots
Protocol Revision: 2025-03-26
The Model Context Protocol (MCP) provides a standardized way for clients to expose filesystem “roots” to servers. Roots define the boundaries of where servers can operate within the filesystem, allowing them to understand which directories and files they have access to. Servers can request the list of roots from supporting clients and receive notifications when that list changes.

User Interaction Model 
Roots in MCP are typically exposed through workspace or project configuration interfaces.

For example, implementations could offer a workspace/project picker that allows users to select directories and files the server should have access to. This can be combined with automatic workspace detection from version control systems or project files.

However, implementations are free to expose roots through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.

Capabilities 
Clients that support roots MUST declare the roots capability during initialization:

{
  "capabilities": {
    "roots": {
      "listChanged": true
    }
  }
}

listChanged indicates whether the client will emit notifications when the list of roots changes.

Protocol Messages 
Listing Roots 
To retrieve roots, servers send a roots/list request:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "roots/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "roots": [
      {
        "uri": "file:///home/user/projects/myproject",
        "name": "My Project"
      }
    ]
  }
}

Root List Changes 
When roots change, clients that support listChanged MUST send a notification:

{
  "jsonrpc": "2.0",
  "method": "notifications/roots/list_changed"
}

Message Flow 
Client
Server
Client
Server
Discovery
Changes
roots/list
Available roots
notifications/roots/list_changed
roots/list
Updated roots
Data Types 
Root 
A root definition includes:

uri: Unique identifier for the root. This MUST be a file:// URI in the current specification.
name: Optional human-readable name for display purposes.
Example roots for different use cases:

Project Directory 
{
  "uri": "file:///home/user/projects/myproject",
  "name": "My Project"
}

Multiple Repositories 
[
  {
    "uri": "file:///home/user/repos/frontend",
    "name": "Frontend Repository"
  },
  {
    "uri": "file:///home/user/repos/backend",
    "name": "Backend Repository"
  }
]

Error Handling 
Clients SHOULD return standard JSON-RPC errors for common failure cases:

Client does not support roots: -32601 (Method not found)
Internal errors: -32603
Example error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Roots not supported",
    "data": {
      "reason": "Client does not have roots capability"
    }
  }
}

Security Considerations 
Clients MUST:

Only expose roots with appropriate permissions
Validate all root URIs to prevent path traversal
Implement proper access controls
Monitor root accessibility
Servers SHOULD:

Handle cases where roots become unavailable
Respect root boundaries during operations
Validate all paths against provided roots
Implementation Guidelines 
Clients SHOULD:

Prompt users for consent before exposing roots to servers
Provide clear user interfaces for root management
Validate root accessibility before exposing
Monitor for root changes
Servers SHOULD:

Check for roots capability before usage
Handle root list changes gracefully
Respect root boundaries in operations
Cache root information appropriately

Specification
2025-03-26 (Latest)
Client Features
Sampling
Sampling
Protocol Revision: 2025-03-26
The Model Context Protocol (MCP) provides a standardized way for servers to request LLM sampling (“completions” or “generations”) from language models via clients. This flow allows clients to maintain control over model access, selection, and permissions while enabling servers to leverage AI capabilities—with no server API keys necessary. Servers can request text, audio, or image-based interactions and optionally include context from MCP servers in their prompts.

User Interaction Model 
Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to occur nested inside other MCP server features.

Implementations are free to expose sampling through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.

For trust & safety and security, there SHOULD always be a human in the loop with the ability to deny sampling requests.

Applications SHOULD:

Provide UI that makes it easy and intuitive to review sampling requests
Allow users to view and edit prompts before sending
Present generated responses for review before delivery
Capabilities 
Clients that support sampling MUST declare the sampling capability during initialization:

{
  "capabilities": {
    "sampling": {}
  }
}

Protocol Messages 
Creating Messages 
To request a language model generation, servers send a sampling/createMessage request:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What is the capital of France?"
        }
      }
    ],
    "modelPreferences": {
      "hints": [
        {
          "name": "claude-3-sonnet"
        }
      ],
      "intelligencePriority": 0.8,
      "speedPriority": 0.5
    },
    "systemPrompt": "You are a helpful assistant.",
    "maxTokens": 100
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "The capital of France is Paris."
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}

Message Flow 
LLM
User
Client
Server
LLM
User
Client
Server
Server initiates sampling
Human-in-the-loop review
Model interaction
Response review
Complete request
sampling/createMessage
Present request for approval
Review and approve/modify
Forward approved request
Return generation
Present response for approval
Review and approve/modify
Return approved response
Data Types 
Messages 
Sampling messages can contain:

Text Content 
{
  "type": "text",
  "text": "The message content"
}

Image Content 
{
  "type": "image",
  "data": "base64-encoded-image-data",
  "mimeType": "image/jpeg"
}

Audio Content 
{
  "type": "audio",
  "data": "base64-encoded-audio-data",
  "mimeType": "audio/wav"
}

Model Preferences 
Model selection in MCP requires careful abstraction since servers and clients may use different AI providers with distinct model offerings. A server cannot simply request a specific model by name since the client may not have access to that exact model or may prefer to use a different provider’s equivalent model.

To solve this, MCP implements a preference system that combines abstract capability priorities with optional model hints:

Capability Priorities 
Servers express their needs through three normalized priority values (0-1):

costPriority: How important is minimizing costs? Higher values prefer cheaper models.
speedPriority: How important is low latency? Higher values prefer faster models.
intelligencePriority: How important are advanced capabilities? Higher values prefer more capable models.
Model Hints 
While priorities help select models based on characteristics, hints allow servers to suggest specific models or model families:

Hints are treated as substrings that can match model names flexibly
Multiple hints are evaluated in order of preference
Clients MAY map hints to equivalent models from different providers
Hints are advisory—clients make final model selection
For example:

{
  "hints": [
    { "name": "claude-3-sonnet" }, // Prefer Sonnet-class models
    { "name": "claude" } // Fall back to any Claude model
  ],
  "costPriority": 0.3, // Cost is less important
  "speedPriority": 0.8, // Speed is very important
  "intelligencePriority": 0.5 // Moderate capability needs
}

The client processes these preferences to select an appropriate model from its available options. For instance, if the client doesn’t have access to Claude models but has Gemini, it might map the sonnet hint to gemini-1.5-pro based on similar capabilities.

Error Handling 
Clients SHOULD return errors for common failure cases:

Example error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -1,
    "message": "User rejected sampling request"
  }
}

Security Considerations 
Clients SHOULD implement user approval controls
Both parties SHOULD validate message content
Clients SHOULD respect model preference hints
Clients SHOULD implement rate limiting
Both parties MUST handle sensitive data appropriately