API Overview

The Claude API is a RESTful API at https://api.anthropic.com that provides programmatic access to Claude models. The primary API is the Messages API (POST /v1/messages) for conversational interactions.

New to Claude? Start with Get started for prerequisites and your first API call, or see Working with Messages for request/response patterns and examples.

Prerequisites

To use the Claude API, you’ll need:

An Anthropic Console account
An API key

For step-by-step setup instructions, see Get started.

Available APIs

The Claude API includes the following APIs: General Availability:

Messages API: Send messages to Claude for conversational interactions (POST /v1/messages)
Message Batches API: Process large volumes of Messages requests asynchronously with 50% cost reduction (POST /v1/messages/batches)
Token Counting API: Count tokens in a message before sending to manage costs and rate limits (POST /v1/messages/count_tokens)
Models API: List available Claude models and their details (GET /v1/models)

Beta:

Files API: Upload and manage files for use across multiple API calls (POST /v1/files, GET /v1/files)
Skills API: Create and manage custom agent skills (POST /v1/skills, GET /v1/skills)

For the complete API reference with all endpoints, parameters, and response schemas, explore the API reference pages listed in the navigation. To access beta features, see Beta headers.

Authentication

All requests to the Claude API must include these headers:

Header	Value	Required
`x-api-key`	Your API key from Console	Yes
`anthropic-version`	API version (e.g., `2023-06-01`)	Yes
`content-type`	`application/json`	Yes

If you are using the Client SDKs, the SDK will send these headers automatically. For API versioning details, see API versions.

Getting API Keys

The API is made available via the 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.

Client SDKs

Anthropic provides official SDKs that simplify API integration by handling authentication, request formatting, error handling, and more. Benefits:

Automatic header management (x-api-key, anthropic-version, content-type)
Type-safe request and response handling
Built-in retry logic and error handling
Streaming support
Request timeouts and connection management

Example (Python):

from anthropic import Anthropic

client = Anthropic()  # Reads ANTHROPIC_API_KEY from environment
message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}]
)

For a list of client SDKs and their respective installation instructions, see Client SDKs.

Claude API vs Third-Party Platforms

Claude is available through Anthropic’s direct API and through partner platforms. Choose based on your infrastructure, compliance requirements, and pricing preferences.

Claude API

Direct access to the latest models and features first
Anthropic billing and support
Best for: New integrations, full feature access, direct relationship with Anthropic

Third-Party Platform APIs

Access Claude through AWS, Google Cloud, or Microsoft Azure:

Integrated with cloud provider billing and IAM
May have feature delays or differences from the direct API
Best for: Existing cloud commitments, specific compliance requirements, consolidated cloud billing

Platform	Provider	Documentation
Amazon Bedrock	AWS	Claude on Amazon Bedrock
Vertex AI	Google Cloud	Claude on Vertex AI
Azure AI	Microsoft Azure	Claude on Azure AI

For feature availability across platforms, see the Features overview.

Request and Response Format

Request Size Limits

The API has different maximum request sizes depending on the endpoint:

Endpoint	Maximum Size
Standard endpoints (Messages, Token Counting)	32 MB
Batch API	256 MB
Files API	500 MB

If you exceed these limits, you’ll receive a 413 request_too_large error.

Response Headers

The Claude 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

Rate Limits and Availability

Rate Limits

The API enforces rate limits and spend limits to prevent misuse and manage capacity. Limits are organized into usage tiers that increase automatically as you use the API. Each tier has:

Spend limits: Maximum monthly cost for API usage
Rate limits: Maximum number of requests per minute (RPM) and tokens per minute (TPM)

You can view your organization’s current limits in the Console. For higher limits or Priority Tier (enhanced service levels with committed spend), contact sales through the Console. For detailed information about limits, tiers, and the token bucket algorithm used for rate limiting, see Rate limits.

Availability

The Claude API is available in many countries and regions worldwide. Check the supported regions page to confirm availability in your location.

Basic Example

Here’s a minimal request using the Messages API:

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-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude"}
    ]
  }'

Response:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I assist you today?"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8
  }
}

For complete examples and tutorials, see Get started and Working with Messages.

Next Steps

Get started

Prerequisites, step-by-step tutorial, and examples in multiple languages

Working with Messages

Request/response patterns, multi-turn conversations, and best practices

Messages API Reference

Complete API specification: parameters, responses, and error codes

Client SDKs

Installation guides for Python, TypeScript, Java, Go, C#, Ruby, and PHP

Features overview

Explore capabilities: caching, vision, tool use, streaming, and more

Rate limits

Usage tiers, spend limits, and rate limiting with token bucket algorithm

Client SDKs

We provide client libraries in a number of popular languages that make it easier to work with the Claude API.

This page includes brief installation instructions and links to the open-source GitHub repositories for Anthropic’s Client SDKs. For basic usage instructions, see the API reference For detailed usage instructions, refer to each SDK’s GitHub repository.

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; if you are using Microsoft Foundry, see this guide.

Python

Python library GitHub repo Requirements: Python 3.8+ Installation:

pip install anthropic

TypeScript

TypeScript library GitHub repo

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

Installation:

npm install @anthropic-ai/sdk

Java

Java library GitHub repo Requirements: Java 8 or later Installation: Gradle:

implementation("com.anthropic:anthropic-java:2.10.0")

Maven:

<dependency>
    <groupId>com.anthropic</groupId>
    <artifactId>anthropic-java</artifactId>
    <version>2.10.0</version>
</dependency>

Go

Go library GitHub repo Requirements: Go 1.22+ Installation:

go get -u 'github.com/anthropics/anthropic-sdk-go@v1.17.0'

C#

C# library GitHub repo

The C# SDK is currently in beta.

Requirements: .NET 8 or later Installation:

dotnet add package Anthropic

Ruby

Ruby library GitHub repo Requirements: Ruby 3.2.0 or later Installation: Add to your Gemfile:

gem "anthropic", "~> 1.13.0"

Then run:

bundle install

PHP

PHP library GitHub repo

The PHP SDK is currently in beta.

Requirements: PHP 8.1.0 or higher Installation:

composer require "anthropic-ai/sdk 0.3.0"

Beta namespace in client SDKs

Every SDK has a beta namespace that is available for accessing new features that Anthropic releases in beta versions. Use this in conjunction with beta headers to access these features. Refer to each SDK’s GitHub repository for specific usage examples.

Beta headers

Documentation for using beta headers with the Claude API

Beta headers allow you to access experimental features and new model capabilities before they become part of the standard API. These features are subject to change and may be modified or removed in future releases.

Beta headers are often used in conjunction with the beta namespace in the client SDKs

How to use beta headers

To access beta features, include the anthropic-beta header in your API requests:

POST /v1/messages
Content-Type: application/json
X-API-Key: YOUR_API_KEY
anthropic-beta: BETA_FEATURE_NAME

When using the SDK, you can specify beta headers in the request options:

from anthropic import Anthropic

client = Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ],
    betas=["beta-feature-name"]
)

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

const anthropic = new Anthropic();

const msg = await anthropic.beta.messages.create({
  model: 'claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Claude' }
  ],
  betas: ['beta-feature-name']
});

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: beta-feature-name" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude"}
    ]
  }'

Beta features are experimental and may:

Have breaking changes without notice
Be deprecated or removed
Have different rate limits or pricing
Not be available in all regions

Multiple beta features

To use multiple beta features in a single request, include all feature names in the header separated by commas:

anthropic-beta: feature1,feature2,feature3

Version naming conventions

Beta feature names typically follow the pattern: feature-name-YYYY-MM-DD, where the date indicates when the beta version was released. Always use the exact beta feature name as documented.

Error handling

If you use an invalid or unavailable beta header, you’ll receive an error response:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Unsupported beta header: invalid-beta-name"
  }
}

Getting help

For questions about beta features:

Check the documentation for the specific feature
Review the API changelog for updates
Contact support for assistance with production usage

Remember that beta features are provided “as-is” and may not have the same SLA guarantees as stable API features.

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. The maximum request size is 32 MB for standard API endpoints.
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: The API is temporarily overloaded.
529 errors can occur when APIs experience high traffic across all users.In rare cases, if your organization has a sharp increase in usage, you might see 429 errors due to acceleration limits on the API. To avoid hitting acceleration limits, ramp up your traffic gradually and maintain 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.

Request size limits

The API enforces request size limits to ensure optimal performance:

Endpoint Type	Maximum Request Size
Messages API	32 MB
Token Counting API	32 MB
Batch API	256 MB
Files API	500 MB

If you exceed these limits, you’ll receive a 413 request_too_large error. The error is returned from Cloudflare before the request reaches our API servers.

Error shapes

Errors are always returned as JSON, with a top-level error object that always includes a type and message value. The response also includes a request_id field for easier tracking and debugging. For example:

JSON

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

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 request-id header:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)
print(f"Request ID: {message._request_id}")

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

const client = new Anthropic();

const message = await client.messages.create({
  model: 'claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [
    {"role": "user", "content": "Hello, Claude"}
  ]
});
console.log('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 reliability; 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.

​API Overview

​Prerequisites

​Available APIs

​Authentication

​Getting API Keys

​Client SDKs

​Claude API vs Third-Party Platforms

​Claude API

​Third-Party Platform APIs

​Request and Response Format

​Request Size Limits

​Response Headers

​Rate Limits and Availability

​Rate Limits

​Availability

​Basic Example

​Next Steps

Get started

Working with Messages

Messages API Reference

Client SDKs

Features overview

Rate limits

​Client SDKs

​Python

​TypeScript

​Java

​Go

​C#

​Ruby

​PHP

​Beta namespace in client SDKs

​Beta headers

​How to use beta headers

​Multiple beta features

​Version naming conventions

​Error handling

​Getting help

​Errors

​HTTP errors

​Request size limits

​Error shapes

​Request id

​Long requests

API Overview

Prerequisites

Available APIs

Authentication

Getting API Keys

Client SDKs

Claude API vs Third-Party Platforms

Claude API

Third-Party Platform APIs

Request and Response Format

Request Size Limits

Response Headers

Rate Limits and Availability

Rate Limits

Availability

Basic Example

Next Steps

Client SDKs

Python

TypeScript

Java

Go

C#

Ruby

PHP

Beta namespace in client SDKs

Beta headers

How to use beta headers

Multiple beta features

Version naming conventions

Error handling

Getting help

Errors

HTTP errors

Request size limits

Error shapes

Request id

Long requests