Introduction

Claude is more than just a chatbot. With the Claude API, you can embed powerful AI capabilities directly into your own applications—whether you're building a customer support assistant, a code review tool, or a content generation pipeline. This guide covers everything you need to know to go from your first API call to a production-ready integration.

By the end, you'll understand:

• How to authenticate and make your first API request
• The two main development surfaces: Messages API and Managed Agents
• How to choose the right Claude model for your use case
• Best practices for evaluation, safety, and cost optimization

Getting Started: Your First API Call

1. Get Your API Key

Before you can talk to Claude, you need an API key. Head to the Claude Console and generate a new key. Keep it secret—treat it like a password.

2. Install an SDK

Anthropic provides official SDKs for Python, TypeScript, Go, Java, Ruby, PHP, and C#. Here's how to install the two most popular ones:

Python

pip install anthropic

TypeScript

npm install @anthropic-ai/sdk

3. Make Your First Request

Here's the simplest possible call using the Python SDK:

import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)
print(message.content[0].text)

And the equivalent in TypeScript:

import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
async function main() {
  const message = await client.messages.create({
    model: 'claude-opus-4-7',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello, Claude' }]
  });
console.log(message.content[0].text);
}
main();

Note: The SDK automatically reads the ANTHROPIC_API_KEY environment variable. You can also pass the key directly: Anthropic(api_key='your-key-here').

Two Ways to Build: Messages API vs. Managed Agents

Claude offers two distinct development surfaces. Choose the one that matches your architecture.

Messages API (Direct Model Access)

With the Messages API, you have full control. You construct every turn of the conversation, manage conversation state yourself, and write your own tool loop. This is ideal for:

• Custom chat interfaces
• Workflows where you need fine-grained control over context
• Integrating Claude into existing backend systems

Key features:

• You manage conversation history
• You handle tool calls and responses manually
• Full access to advanced features like extended thinking, structured outputs, and prompt caching

Managed Agents (Fully Managed Infrastructure)

Managed Agents are a higher-level abstraction. You define an agent with instructions and tools, and Anthropic handles the rest—stateful sessions, persistent event history, and automatic tool execution.

Key features:

• No need to manage conversation state
• Built-in persistence and session management
• Ideal for autonomous agents that run over long periods

Quickstart for Managed Agents:

import anthropic
client = anthropic.Anthropic()
Define your agent
agent = client.agents.create(
    name="CustomerSupportAgent",
    instructions="You are a helpful customer support agent. Answer questions politely and escalate if needed.",
    tools=["web_search", "file_search"]
)
Start a session
session = client.agents.sessions.create(agent_id=agent.id)
Send a message
response = client.agents.sessions.message(
    session_id=session.id,
    content="How do I reset my password?"
)
print(response.content[0].text)

Choosing the Right Claude Model

The Claude model family has three tiers. Picking the right one can save you money and improve latency.

Rule of thumb: Start with Sonnet for most use cases. Switch to Opus when you need deeper reasoning. Use Haiku when speed and cost are critical.

Advanced Features to Supercharge Your App

Once you have the basics down, explore these capabilities:

Extended Thinking

Claude can show its reasoning process before giving a final answer. This is useful for debugging or when you need transparency.

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    thinking={"type": "enabled", "budget_tokens": 1024},
    messages=[{"role": "user", "content": "Solve this math problem step by step: 23 * 47"}]
)

Structured Outputs

Get responses in a structured format like JSON, making it easy to parse programmatically.

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "List three fruits as JSON"}],
    response_format={"type": "json_object"}
)

Tool Use

Give Claude the ability to call external functions, search the web, fetch URLs, or execute code.

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "input_schema": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"}
                },
                "required": ["city"]
            }
        }
    ],
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}]
)

Prompt Caching

Reduce latency and cost by caching repeated system prompts or conversation prefixes.

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a helpful assistant.",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "Tell me a joke."}]
)

Streaming

Get tokens as they're generated for a more responsive user experience.

stream = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a short poem."}],
    stream=True
)
for event in stream:
    if event.type == "content_block_delta":
        print(event.delta.text, end="")

From Prototype to Production

Building a prototype is one thing; shipping to production is another. Here's what you need to think about:

1. Evaluate Your Prompts

Use the Evaluation Tool in Console to test your prompts against a set of test cases before deploying.

2. Strengthen Guardrails

Add safety instructions to your system prompt and test for edge cases like jailbreak attempts or prompt leaks.

3. Reduce Hallucinations

• Use structured outputs to constrain the response format
• Provide grounding context (e.g., retrieved documents)
• Set appropriate temperature (lower = more deterministic)

4. Monitor Costs

• Use Haiku for simple tasks, Sonnet for most, Opus only when needed
• Enable prompt caching for repeated prefixes
• Set max_tokens to the minimum you need

5. Handle Rate Limits

Check the rate limits documentation and implement retry logic with exponential backoff.

Resources to Keep Learning

• Interactive Courses – Master Claude step by step
• Cookbook – Code samples and patterns
• Quickstarts – Deployable starter apps
• Release Notes – Stay up to date with new features

Key Takeaways

• Start with the SDKs: Python and TypeScript SDKs make your first API call trivial. Use environment variables for your API key.
• Choose your surface wisely: Use the Messages API for full control, or Managed Agents for hands-off state management.
• Pick the right model: Opus for deep reasoning, Sonnet for balanced production use, Haiku for speed and cost savings.
• Leverage advanced features: Extended thinking, structured outputs, tool use, and prompt caching can dramatically improve your application.
• Plan for production: Evaluate prompts, monitor costs, handle rate limits, and implement guardrails before shipping.