Getting Started with the Claude API: Your First Integration in Minutes

Introduction

Claude is a powerful AI assistant developed by Anthropic, designed to excel at a wide range of tasks—from answering complex questions to generating code, analyzing documents, and even controlling computer interfaces. Whether you're building a chatbot, an automated research tool, or a creative writing assistant, the Claude API gives you programmatic access to Claude's capabilities.

This guide is your starting point. By the end, you'll have made your first API call, understand the core concepts of the Messages API, and know where to go next to build more advanced integrations.

Prerequisites

Before you begin, you'll need:

• An Anthropic Console account – Sign up at console.anthropic.com.
• An API key – After logging in, navigate to the API Keys section and create a new key. Keep it secret—treat it like a password.
• A tool to make HTTP requests – We'll use cURL (command line), Python, and TypeScript in the examples.

Step 1: Make Your First API Call

Let's start with the simplest possible request: sending a single message to Claude and getting a response.

Using cURL

Open your terminal and run:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

What's happening?

• You're sending a POST request to the /v1/messages endpoint.
• The x-api-key header authenticates your request.
• The anthropic-version header specifies the API version.
• The request body includes the model name, max tokens, and an array of messages.

If successful, you'll receive a JSON response like:

{
  "id": "msg_01ABC123...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 10
  }
}

Using Python

Install the Anthropic Python SDK:

pip install anthropic

Then create a script hello_claude.py:

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

Run it:

python hello_claude.py

Using TypeScript

Install the Anthropic TypeScript SDK:

npm install @anthropic-ai/sdk

Create hello_claude.ts:

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

Run with:

npx ts-node hello_claude.ts

Step 2: Understand the Messages API

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

Roles

Each message has a role:

• user – Messages from the end user.
• assistant – Messages from Claude (you can provide previous assistant responses for context).

Multi-turn Conversations

To continue a conversation, simply add more messages to the array:

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

System Prompts

System prompts set the behavior and personality of Claude. They are passed separately from the messages:

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful assistant that speaks like a pirate.",
    messages=[
        {"role": "user", "content": "What's the weather today?"}
    ]
)

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 use a tool (more on this later).

Step 3: Explore Key Features

Once you've mastered the basics, Claude's API offers a wealth of advanced capabilities:

Streaming

For real-time responses (like chatbots), use streaming:

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

Tools (Function Calling)

Claude can use external tools. Define them in the API call:

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    ],
    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. You then execute the tool, return the result, and Claude continues.

Extended Thinking

For complex reasoning tasks, enable extended thinking:

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=4096,
    thinking={"type": "enabled", "budget_tokens": 2048},
    messages=[{"role": "user", "content": "Solve this complex math problem..."}]
)

Structured Outputs

Request JSON-formatted responses by setting the response format:

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "List 3 planets in JSON"}],
    response_format={"type": "json_object"}
)

Prompt Caching

Reduce costs and latency for repeated system prompts or large contexts:

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are an expert historian...",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "Tell me about ancient Rome"}]
)

Next Steps

You've made your first API call and learned the core patterns. Here's where to go next:

• Explore the Models – Compare Claude models (Sonnet, Haiku, Opus) by capability and cost.
• Master the Messages API – Dive deeper into multi-turn conversations, system prompts, and error handling.
• Build with Tools – Create agents that can call APIs, search the web, or execute code.
• Optimize with Caching – Reduce latency and cost for production applications.
• Check the Client SDKs – Reference documentation for Python, TypeScript, Java, and more.

Key Takeaways

• Getting started is simple: Sign up for an Anthropic Console account, get an API key, and make your first call with cURL, Python, or TypeScript in minutes.
• The Messages API is your foundation: Understand roles, multi-turn conversations, system prompts, and stop reasons to build any application.
• Claude supports advanced features out of the box: Streaming, tools, extended thinking, structured outputs, and prompt caching are all available through the same API.
• Always handle stop reasons: Check stop_reason in responses to know why Claude stopped—especially "tool_use" when building agents.
• Explore the ecosystem: Beyond the API, Claude offers client SDKs, MCP for tool integration, and platform support on AWS, GCP, and Azure.