Claude API

What the Claude API is and when to use it

The Claude API is Anthropic's direct developer interface for sending requests to Claude models from your own application. The main endpoint is the Messages API at https://api.anthropic.com/v1/messages. A request can contain system instructions, a sequence of user and assistant messages, optional images or documents, and tools that Claude may request your application to run.

The API is stateless: your application is responsible for retaining conversation history and sending the relevant messages with each request. This makes it suitable for chat applications, document analysis, coding assistants, structured-data extraction, customer-service workflows, and agents that call external systems.

Use the direct API when you want to control application logic, data storage, tool execution, authentication, and deployment. Anthropic also provides higher-level options such as the Claude Agent SDK and Claude Managed Agents for applications that need more managed agent execution.

Who is it for?

The platform is aimed at developers building production services or prototypes that need Claude model access. Beginners can start with a single HTTPS request or an official SDK. Intermediate developers can add streaming, validated structured output, reusable files, client-side tools, server-side tools, prompt caching, batch processing, or MCP connectivity.

Getting access and obtaining credentials

1. Create a Claude Console account.
2. Create an Anthropic API key.
3. Store the key in the ANTHROPIC_API_KEY environment variable rather than placing it directly in source code.
4. Install an official SDK or send HTTPS requests to the API.

Direct requests authenticate with the x-api-key header and must include the anthropic-version header. SDKs normally read ANTHROPIC_API_KEY automatically. Keep the key on a server or other protected runtime; do not expose it in browser code or public repositories.

Choosing the API and model

For new direct integrations, use the Messages API rather than older Claude completion-style endpoints. Select an active model identifier from Anthropic's current models catalog. Model availability, capabilities, pricing, and retirement dates can change, so avoid hard-coding a model that has been deprecated and review Anthropic's model lifecycle documentation periodically.

Model choice affects cost, response speed, context handling, and available features. The supplied research does not specify a single universally appropriate model or fixed price, so applications should compare the currently active models against their workload and budget.

Making the first request

The following raw HTTP example uses a placeholder model identifier. Replace active-model-id with an active model from Anthropic's current catalog.

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": "active-model-id",
    "max_tokens": 512,
    "system": "You are a concise technical assistant.",
    "messages": [
      {
        "role": "user",
        "content": "Explain exponential backoff in three sentences."
      }
    ]
  }'

The request specifies a model, an output-token limit, an optional system instruction, and a messages array. The API key is read from the environment, which reduces the risk of accidentally committing it to source control.

The same request with the Python SDK

Anthropic provides official SDKs for Python, TypeScript, C#, Go, Java, PHP, and Ruby. This example uses the current Python client pattern.

pip install anthropic

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

response = client.messages.create(
    model="active-model-id",
    max_tokens=512,
    system="You are a concise technical assistant.",
    messages=[
        {"role": "user", "content": "Explain exponential backoff in three sentences."}
    ],
)

print("n".join(
    block.text for block in response.content if block.type == "text"
))

Understanding the response

A Messages API response is not simply a plain text string. It contains content blocks, and each block has a type. Text responses use text blocks; tool requests use tool-use blocks; other capabilities can produce other block types. Code should inspect the block type and extract text deliberately.

For a basic text response, applications commonly select blocks where block.type == "text". Tool-enabled applications instead look for a tool-use block, execute the requested function, and send the result back in a subsequent user message. This content-block design lets one response contain more than one kind of output.

How pricing generally works

Claude API pricing is usage-based. Charges generally depend on the selected model's input and output token rates, with different models having different prices. A token is a unit of text processed by the model; the exact number depends on the content and tokenization.

Additional pricing rules may apply to prompt-cache writes and reads, long-context usage, batch processing, and server-side tools. The Message Batches API provides discounted asynchronous processing for eligible workloads. Web search and other server-side tools may also add feature-specific charges.

Because model prices change and the research does not provide a single current rate, check Anthropic's pricing page before estimating costs. In production, record token usage, model selection, tool activity, and request volume so that application-level cost can be monitored.

Important capabilities

Streaming responses

Streaming sends response events as they are generated instead of waiting for the complete message. It is useful for chat interfaces and long responses because the application can display text progressively and reduce the time before users see output.

with client.messages.stream(
    model="active-model-id",
    max_tokens=512,
    messages=[
        {"role": "user", "content": "Explain server-sent events briefly."}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
print()

At the HTTP level, streaming uses server-sent events. A streaming client should process event types rather than assuming every event contains displayable text.

Tool and function calling

Tool use lets Claude request that your application run a function. You provide a tool name, description, and JSON input schema. Your code performs the operation—such as querying a database or calling a weather service—and sends the result back to Claude. Anthropic also supports strict tool schemas for validating tool inputs.

tools = [
    {
        "name": "get_weather",
        "description": "Return current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
            "additionalProperties": False,
        },
        "strict": True,
    }
]

response = client.messages.create(
    model="active-model-id",
    max_tokens=512,
    tools=tools,
    messages=[
        {"role": "user", "content": "What is the weather in Boston?"}
    ],
)

for block in response.content:
    if block.type == "tool_use":
        print(block.name, block.input)

The application must validate authorization, arguments, and side effects before executing a requested tool. The model does not directly gain permission to access your systems; your application controls whether and how each requested operation runs.

Structured JSON outputs

Structured outputs let an application request JSON text that follows a supplied JSON Schema. This is useful for extraction, classification, and downstream workflows that need predictable fields. Structured output is different from ordinary prompting for JSON because the request specifies a schema for validation.

response = client.messages.create(
    model="active-model-id",
    max_tokens=512,
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "priority": {"type": "string"}
                },
                "required": ["name", "priority"],
                "additionalProperties": False
            }
        }
    },
    messages=[
        {"role": "user", "content": "Extract: Alex Kim has high priority."}
    ],
)

json_text = next(
    block.text for block in response.content if block.type == "text"
)

Parse and validate the returned text in your application before using it. Strict tool use validates tool inputs separately from structured response output.

Files, documents, and images

Vision-capable Claude models can accept images through supported base64 data, URLs, or file references. Documents and PDFs can also be supplied directly or through the Files API. The Files API supports uploading, listing, retrieving, downloading, and deleting reusable files.

File expiration can be configured from 3,600 seconds to 7,776,000 seconds, or 90 days. After expiration, file content is no longer retrievable through the API, although metadata may remain readable for up to 30 days. Expiration should not be treated as an immediate guaranteed-deletion control; explicitly delete sensitive files when they are no longer needed.

Server-side tools and agent features

Depending on the model, account, tool version, and release status, Anthropic provides server-side tools such as web search, web fetch, code execution, tool search, memory, computer use, browser use, and MCP connectivity. The platform also includes Claude Agent SDK functionality and Claude Managed Agents for higher-level agent workflows.

These features can reduce the amount of infrastructure an application must build, but they introduce additional permissions, cost, latency, and operational considerations. Confirm availability and current terms for the specific account and model before designing around a feature.

Playground and developer tools

The Claude Console provides a place to create API keys and experiment with requests. Anthropic's official SDKs provide typed or idiomatic clients, streaming, retries, and error handling across Python, TypeScript, C#, Go, Java, PHP, and Ruby.

For a first prototype, the Console and a short SDK script are usually enough. For production, use environment-based secrets, structured logging, request and cost monitoring, retry handling, and tests for tool and schema behavior.

Limits and production considerations

Rate limits are measured using requests per minute, input tokens per minute, and output tokens per minute. Limits vary by model and organization tier. The supplied documentation reports that current maximums for several active model classes can reach 1,000 RPM, 2,000,000 input tokens per minute, and 400,000 output tokens per minute, but those figures are not universal guarantees.

When a request is throttled, a 429 response can include retry-after and rate-limit headers. Production clients should honor the server-provided delay, use exponential backoff, and monitor remaining request and token capacity. Managed Agents and the Files API have separate limits.

Latency depends on the model, prompt size, output length, reasoning settings, tools, and service tier. Streaming can reduce time to the first visible output. Tool loops also add network round trips and should have explicit timeouts, failure handling, and limits on repeated calls.

Privacy and data handling

Anthropic's commercial terms state that Anthropic may not train models on customer content from its commercial services. Organizations should still review current commercial terms, service-specific terms, privacy documentation, supported-region requirements, retention controls, and any enterprise or zero-data-retention agreement before sending sensitive information.

Advantages and limitations

When the Claude API is a good or poor choice

The API is a good fit when an application needs Claude's instruction following, long-context processing, reasoning, coding assistance, document analysis, multimodal input, structured extraction, tool use, or agent orchestration. It is also a practical choice when the team wants direct control over the request lifecycle rather than only a prebuilt chat interface.

It may be a poor fit when a workload requires a general-purpose public fine-tuning API, fixed predictable costs independent of usage, capabilities unavailable in the selected model or account, or a fully managed agent system without application-side tool and security work. Confirm model availability, pricing, rate limits, retention terms, and required server-side tools before committing to the design.

For a reliable first implementation, begin with one Messages API request, extract content blocks explicitly, add retries and usage monitoring, and introduce streaming, tools, files, or structured outputs only when the application needs them.