Introduction

Claude's API is more than just a text-in, text-out interface. It's a comprehensive platform designed to handle everything from simple Q&A to complex, multi-step agentic workflows. Whether you're building a customer support bot, a code analysis tool, or a research assistant, understanding the five core areas of the API surface will help you build faster, cheaper, and more reliably.

This guide breaks down each area with practical examples, feature availability notes, and code snippets you can use today.

The Five Pillars of the Claude API

Claude's API surface is organized into five areas:

• Model capabilities – Control how Claude reasons and formats responses.
• Tools – Let Claude take actions on the web or in your environment.
• Tool infrastructure – Handle discovery and orchestration at scale.
• Context management – Keep long-running sessions efficient.
• Files and assets – Manage the documents and data you provide to Claude.

If you're new, start with model capabilities and tools. Return to the other sections when you're ready to optimize cost, latency, or scale.

1. Model Capabilities: Steering Claude's Outputs

Model capabilities are the direct levers you pull to control how Claude thinks and responds. Key features include:

Extended Thinking (Adaptive Thinking)

Claude can now dynamically decide when and how much to "think" before responding. This is especially useful for complex reasoning tasks like math, code generation, or multi-step planning.

Availability: GA on Claude API, Claude Platform on AWS, Bedrock, and Vertex AI. Beta on Microsoft Foundry.

import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    thinking={"type": "enabled", "budget_tokens": 2048},
    messages=[
        {"role": "user", "content": "Solve this: A train leaves New York at 60 mph. Another leaves Chicago at 70 mph. Distance is 800 miles. When do they meet?"}
    ]
)
print(response.content[0].text)

Structured Outputs

Need JSON, YAML, or a specific schema? Use structured outputs to guarantee Claude's response format.

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "List three famous scientists and their discoveries."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "scientists",
            "schema": {
                "type": "object",
                "properties": {
                    "scientists": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "discovery": {"type": "string"},
                                "year": {"type": "integer"}
                            },
                            "required": ["name", "discovery", "year"]
                        }
                    }
                },
                "required": ["scientists"]
            }
        }
    }
)
print(response.content[0].text)

Citations

Ground Claude's responses in source documents. Claude can reference exact sentences from your provided text.

Availability: GA on Claude API and Claude Platform on AWS.

Batch Processing

Send large volumes of requests asynchronously and save 50% on API costs. Ideal for data enrichment, content classification, or bulk summarization.

Availability: GA on all major platforms. Not ZDR eligible.

2. Tools: Let Claude Take Action

Tools extend Claude's capabilities beyond text generation. Claude can call functions, fetch web pages, execute code, and even control a computer.

How Tool Use Works

You define tools as JSON schemas. Claude decides when to call them based on the conversation context.

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["city"]
        }
    }
]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What's the weather in Paris?"}]
)
Claude will respond with a tool_use block
print(response.content)

Built-in Tools

Claude comes with several pre-built tools you can enable immediately:

• Web search tool – Fetch real-time information from the web.
• Code execution tool – Run Python, JavaScript, or bash in a sandbox.
• Computer use tool – Let Claude control a virtual desktop.
• Memory tool – Persist information across conversations.
• Text editor tool – Edit files programmatically.

Parallel Tool Use

Claude can call multiple tools in a single turn, dramatically speeding up multi-step tasks.

# Claude may call get_weather and get_time in parallel
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[get_weather_tool, get_time_tool],
    messages=[{"role": "user", "content": "What's the weather and time in Tokyo?"}]
)

3. Tool Infrastructure: Scale Your Agent

When you have dozens or hundreds of tools, you need infrastructure to manage them. Claude's platform offers:

• Tool Runner (SDK) – Automatically handles tool execution and result injection.
• Strict tool use – Force Claude to use a specific tool.
• Fine-grained tool streaming – Stream tool calls and results incrementally.
• Tool search – Let Claude discover tools dynamically.
• MCP (Model Context Protocol) – Connect remote MCP servers for tool discovery.

4. Context Management: Keep Sessions Efficient

Long conversations eat up tokens. Claude provides several mechanisms to manage context windows efficiently.

Context Windows

Claude supports up to 1 million tokens of context—enough to process entire codebases or book-length documents.

Prompt Caching

Cache repeated system prompts or large context chunks to reduce latency and cost.

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a helpful assistant with knowledge of our company policies...",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "What's the refund policy?"}]
)

Context Compaction and Editing

• Compaction – Summarize or prune older messages to stay within context limits.
• Context editing – Manually remove or modify messages in the conversation history.

5. Files and Assets: Work with Documents and Images

Claude can process PDFs, images, and other file types natively.

PDF Support

Upload PDFs directly and Claude will extract text, tables, and layout information.

import base64
with open("report.pdf", "rb") as f:
    pdf_data = base64.b64encode(f.read()).decode("utf-8")
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_data
                    }
                },
                {
                    "type": "text",
                    "text": "Summarize this report."
                }
            ]
        }
    ]
)

Image and Vision

Claude can analyze images, diagrams, and screenshots.

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
)

Feature Availability Quick Reference

Not all features are available on every platform. Here's a quick guide:

Best Practices for Production

• Start with model capabilities – Master thinking, structured outputs, and citations before adding tools.
• Use prompt caching – Cache system prompts and large context chunks to reduce costs by up to 50%.
• Leverage batch processing – For non-real-time workloads, batch API calls are half the price.
• Monitor token usage – Use the token counting endpoint to estimate costs before sending requests.
• Handle tool calls properly – Always check for tool_use stop reasons and execute tools before sending the next message.

Key Takeaways

• Claude's API is organized into five areas: model capabilities, tools, tool infrastructure, context management, and files.
• Start with model capabilities (thinking, structured outputs) and tools, then explore context management and batch processing for cost optimization.
• Use prompt caching and batch processing to reduce API costs significantly.
• Claude supports up to 1M token context windows and can process PDFs, images, and code natively.
• Feature availability varies by platform—always check the documentation for your deployment target.