Getting Started with the Claude API: From Zero to Your First Integration

Anthropic provides two primary ways to build with Claude: the Messages API for direct model access and Claude Managed Agents for pre-built agent harnesses. This guide focuses on the Messages API—the recommended path for developers who want fine-grained control over their agent loops, custom integrations, and scalable production applications.

By the end of this guide, you'll have made your first API call, understood the core request/response structure, and know which features to explore next.

Prerequisites

Before you start, you'll need:

• An Anthropic account and an API key from the Developer Console
• Python 3.8+ or Node.js 18+ installed on your machine
• Basic familiarity with REST APIs and JSON

Step 1: Make Your First API Call

Let's set up your environment and send your first message to Claude.

Install the SDK

Anthropic provides official SDKs for Python and TypeScript. Install the one for your language:

Python

pip install anthropic

TypeScript/JavaScript

npm install @anthropic-ai/sdk

Set Your API Key

Store your API key as an environment variable for security:

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

Send Your First Message

Here's a minimal example that asks Claude to explain itself:

Python

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

TypeScript

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

Expected output: Claude will respond with a friendly introduction to its capabilities, such as text generation, code assistance, analysis, and more.

Tip: If you see an authentication error, double-check that your ANTHROPIC_API_KEY environment variable is set correctly and that your API key is active.

Step 2: Understand the Messages API

The Messages API is the core interface for interacting with Claude. Let's break down its structure.

Request Structure

Every API call includes:

• model: The model identifier (e.g., claude-sonnet-4-20250514)
• max_tokens: Maximum number of tokens in the response
• messages: An array of message objects, each with a role and content

Supported roles:

• user: Messages from the end user
• assistant: Claude's responses (used for multi-turn conversations)

Multi-Turn Conversations

To continue a conversation, include the entire message history:

messages = [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "What is its population?"}
]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=256,
    messages=messages
)

System Prompts

Use a system parameter to set Claude's behavior and persona:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful coding assistant. Always provide code examples.",
    messages=[
        {"role": "user", "content": "How do I read a CSV file in Python?"}
    ]
)

Stop Reasons

The response includes a stop_reason field that tells you why Claude stopped generating:

• end_turn: Claude finished naturally
• max_tokens: The response hit the token limit
• stop_sequence: Claude encountered a custom stop sequence you defined
• tool_use: Claude wants to call a tool (more on this later)

Step 3: Choose the Right Model

Anthropic offers several Claude models optimized for different use cases:

Recommendations:

• Start with Claude Sonnet 4.6 for most applications—it balances capability and cost.
• Use Claude Haiku 4.5 for high-volume, low-latency tasks like classification or summarization.
• Reserve Claude Opus 4.7 for tasks requiring deep reasoning or complex multi-step agentic workflows.

Step 4: Explore Key Features

Once you've made your first call, you can unlock Claude's full potential with these features:

Extended Thinking

For complex reasoning tasks, enable extended thinking to let Claude "think" before responding:

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

Tool Use (Function Calling)

Claude can call external tools and APIs. Define tools in your request:

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

When Claude decides to use a tool, the response will contain a tool_use content block with the tool name and input arguments. You then execute the tool and return the result in a follow-up message.

Structured Outputs

Request JSON-formatted responses by specifying a response_format:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    response_format={"type": "json_object"},
    messages=[
        {"role": "user", "content": "List three programming languages and their primary use cases as JSON."}
    ]
)

Streaming

For real-time applications, stream responses token by token:

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

Vision (Image Processing)

Claude can analyze images. Pass image data as base64 or via a URL:

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

Developer Tools

Anthropic provides several resources to accelerate your development:

• Developer Console: Prototype prompts with the Workbench and use the prompt generator to optimize your system prompts.
• API Reference: Full documentation for all endpoints and SDK methods.
• Claude Cookbook: Interactive Jupyter notebooks covering PDF processing, embeddings, tool use, and more.

Best Practices

• Start with a clear system prompt – Define Claude's role and constraints upfront.
• Use prompt caching for repeated system prompts or large context to reduce latency and cost.
• Handle stop reasons in your code – especially max_tokens and tool_use.
• Implement error handling for API rate limits and authentication issues.
• Monitor token usage to stay within your budget and optimize prompts.

Next Steps

Now that you've made your first API call and understand the fundamentals, here's what to explore next:

• Build a tool-using agent that can interact with external APIs
• Implement batch processing for high-volume tasks
• Learn about prompt caching to optimize performance
• Dive into Claude Managed Agents for long-running, asynchronous workflows

Key Takeaways

• The Messages API is the primary way to integrate Claude into your applications, offering full control over conversations, system prompts, and tool use.
• Choose your model based on your use case: Haiku for speed, Sonnet for balance, Opus for complex reasoning.
• Key features like extended thinking, tool use, structured outputs, and streaming enable sophisticated applications.
• Always handle stop reasons and implement proper error handling for production deployments.
• Start with the quickstart, then explore the Developer Console and Cookbook for deeper learning.