Introduction

Claude isn't just a chat interface. Behind the scenes, Anthropic provides a powerful API that lets you integrate Claude directly into your own applications, workflows, and products. Whether you're building a customer support bot, a code review assistant, or a content generation pipeline, the Claude API gives you the flexibility to control every aspect of the interaction.

This guide will take you from zero to your first API call, explain the two main development surfaces (Messages API and Managed Agents), and help you choose the right approach for your project. By the end, you'll have a clear path from idea to production.

Prerequisites

Before you start, you'll need:

• A Claude API account (separate from the free Claude.ai chat)
• Basic familiarity with Python or TypeScript
• A terminal and a code editor

Step 1: Get Your API Key

Your API key is the credential that authenticates your requests. To get one:

• Log in to the Anthropic Console.
• Navigate to API Keys in the sidebar.
• Click Create Key and give it a descriptive name (e.g., "My App Key").
• Copy the key immediately — you won't be able to see it again.

Security tip: Never hardcode your API key in your source code. Use environment variables instead. On macOS/Linux:

> export ANTHROPIC_API_KEY="sk-ant-..."

>

Step 2: Choose Your Model

Claude comes in several flavors, each optimized for different use cases. Here's a quick overview:

For your first call, start with Sonnet — it's fast enough for experimentation but smart enough to give meaningful results.

Step 3: Install an SDK

Anthropic provides official SDKs for Python, TypeScript, Go, Java, Ruby, PHP, and C#. We'll focus on Python here.

pip install anthropic

For TypeScript:

npm install @anthropic-ai/sdk

Step 4: Make Your First API Call

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

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

Run it:

python hello_claude.py

You should see Claude's friendly greeting. Congratulations — you've made your first API call!

What's happening under the hood?

• The client.messages.create() method sends a POST request to the Claude API.
• You specify the model, max_tokens (maximum response length), and the messages array (conversation history).
• Claude returns a response object. The actual text is in message.content[0].text.

Step 5: Understand the Two Development Surfaces

Anthropic gives you two fundamentally different ways to build with Claude. Your choice depends on how much control you need vs. how much infrastructure you want to manage.

Option A: Messages API (Direct Model Access)

With the Messages API, you are in 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 to inject business logic between turns
• Applications that require fine-grained control over context windows

Example: Multi-turn conversation

import anthropic
client = anthropic.Anthropic()
First turn
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ]
)
assistant_reply = response.content[0].text
print(f"Claude: {assistant_reply}")
Second turn — you must include the full history
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "What is the capital of France?"},
        {"role": "assistant", "content": assistant_reply},
        {"role": "user", "content": "Tell me more about its history."}
    ]
)
print(f"Claude: {response.content[0].text}")

Option B: Managed Agents (Fully Managed Infrastructure)

Managed Agents are a newer, higher-level abstraction. You define an agent, and Anthropic handles conversation state, session persistence, and even tool execution. This is ideal for:

• Autonomous agents that run over long periods
• Applications where you don't want to manage state yourself
• Deploying agents that need persistent event history

Quickstart with Managed Agents:

import anthropic
client = anthropic.Anthropic()
Define your agent
agent = client.agents.create(
    name="my-support-agent",
    model="claude-sonnet-4-6",
    instructions="You are a helpful customer support agent."
)
Start a session
session = client.agents.sessions.create(
    agent_id=agent.id
)
Send a message
response = client.agents.sessions.send_message(
    session_id=session.id,
    content="I need help with my order."
)
print(response.content[0].text)

Managed Agents automatically maintain conversation history across multiple turns, so you don't need to pass the full message array each time.

Step 6: Explore Key Features

Once you've made your first call, you'll want to explore the features that make Claude powerful:

Extended Thinking

Claude can show its reasoning process before giving a final answer. Enable it with the thinking parameter:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    thinking={"type": "enabled", "budget_tokens": 1024},
    messages=[{"role": "user", "content": "Solve this math problem step by step..."}]
)

Tool Use (Function Calling)

Give Claude the ability to call external APIs or functions:

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

Vision

Claude can analyze images. Pass image data in the content array:

import base64
with open("chart.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What does this chart show?"},
                {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": image_data}}
            ]
        }
    ]
)

Prompt Caching

Reduce latency and cost for repeated system prompts by caching them:

response = 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": "Hello"}]
)

Step 7: Evaluate and Ship

Before going to production, consider these best practices:

• Run evals — Test your prompts systematically with a set of evaluation cases.
• Batch testing — Use the API's batch endpoint to test many inputs at once.
• Rate limits — Be aware of your tier's rate limits and implement retry logic with exponential backoff.
• Cost optimization — Use Haiku for simple tasks, Sonnet for balanced workloads, and Opus only when you need deep reasoning.
• Safety & guardrails — Implement content filtering and user input validation on your side.

Next Steps

Now that you've made your first API call, here's where to go next:

• Try the Workbench — Anthropic's web-based tool for experimenting with prompts before writing code.
• Explore the Cookbook — Find code samples and patterns for common use cases.
• Deploy a starter app — Use Anthropic's quickstart templates to get a full application running in minutes.
• Learn about Claude Code — An agentic coding assistant that runs in your terminal.

Key Takeaways

• Get your API key from the Anthropic Console and store it as an environment variable.
• Choose the right model: Opus for deep reasoning, Sonnet for balanced production, Haiku for high-speed tasks.
• Two development surfaces: Messages API for full control, Managed Agents for hands-off state management.
• Explore advanced features like extended thinking, tool use, vision, and prompt caching to unlock Claude's full potential.
• Plan for production by running evals, respecting rate limits, and optimizing costs from the start.