Getting Started with Claude: Your First API Call and Beyond

Introduction

Claude is a powerful AI assistant developed by Anthropic, designed to handle a wide range of tasks from simple Q&A to complex multi-step reasoning and tool use. Whether you're building a chatbot, automating workflows, or integrating AI into your application, the Claude API gives you direct access to Claude's capabilities.

This guide will take you from zero to your first API call, explain the core patterns of the Messages API, and point you toward advanced features like tools, streaming, and structured outputs.

Prerequisites

Before you start, you'll need:

• An Anthropic Console account – Sign up at console.anthropic.com.
• An API key – Generate one in the Console under API Keys.
• A development environment – You can use cURL, Python, TypeScript, or any language that supports HTTP requests.

Security tip: Never hardcode your API key in client-side code or public repositories. Use environment variables or a secrets manager.

Making Your First API Call

Let's start with the simplest possible request: asking Claude a question.

Using cURL

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": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Using Python

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

Using TypeScript

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

What you'll see: Claude will respond with a friendly greeting. The response object contains the model's reply, token usage, and a stop reason (typically "end_turn" for a complete response).

Understanding the Messages API

The Messages API is the primary way to interact with Claude. Here are the key concepts:

Message Roles

• user – Messages from the end user.
• assistant – Messages from Claude (you can include these for multi-turn context).
• system – A special instruction that sets Claude's behavior (passed as a separate parameter, not in the messages array).

Multi-Turn Conversations

To continue a conversation, include the full history:

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

System Prompts

Use system prompts to set the tone, role, or constraints:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    system="You are a helpful assistant that speaks like a pirate.",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ]
)

Stop Reasons

Each response includes a stop_reason field:

• "end_turn" – Claude finished naturally.
• "max_tokens" – The response was cut off; you may need to continue.
• "stop_sequence" – Claude hit a custom stop sequence you defined.
• "tool_use" – Claude wants to call a tool (see below).

Next Steps: Explore Claude's Capabilities

Once you've mastered the basics, dive into these powerful features:

1. Tools (Function Calling)

Claude can use external tools to perform actions like fetching data, running code, or interacting with APIs. Define tools in your request and handle tool_use stop reasons.

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-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "What's the weather in London?"}
    ]
)

2. Streaming

Get responses token-by-token for a real-time experience:

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

3. Structured Outputs

Ask Claude to return JSON or follow a specific schema:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "List three fruits as a JSON array of objects with 'name' and 'color' fields."}
    ]
)

4. 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 math problem step by step: 15 * 23 + 7"}
    ]
)

5. Prompt Caching

Reduce costs and latency by caching repeated system prompts or large context:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a legal assistant...",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Summarize this contract."}
    ]
)

Best Practices

• Start with a small model – Use claude-sonnet-4-20250514 for testing; it's fast and cost-effective.
• Set appropriate max_tokens – Avoid truncation by setting a value that matches your expected response length.
• Handle errors gracefully – Implement retry logic for rate limits and transient errors.
• Monitor token usage – Track input and output tokens to manage costs.
• Use environment variables – Store your API key securely.

Key Takeaways

• Get started quickly – With an API key and a few lines of code, you can make your first Claude API call using cURL, Python, or TypeScript.
• Master the Messages API – Understand roles, system prompts, multi-turn conversations, and stop reasons to build robust integrations.
• Explore advanced features – Tools, streaming, structured outputs, extended thinking, and prompt caching unlock Claude's full potential.
• Follow best practices – Secure your API key, set appropriate limits, and handle errors to build production-ready applications.
• Keep learning – The Claude API ecosystem is rich with capabilities; dive into the official docs for models, features, and SDKs.