Introduction

The Claude API is your gateway to integrating Anthropic's powerful language model into your own applications, workflows, and services. Whether you're building a chatbot, a content generation tool, a code assistant, or an analysis pipeline, the API provides a flexible, programmatic interface to Claude's capabilities.

This guide will take you from zero to production-ready. You'll learn how to authenticate, format requests, handle responses (including streaming), and follow best practices that save time, money, and headaches.

Prerequisites

Before you start, you'll need:

• An Anthropic account (sign up at console.anthropic.com)
• An API key from the Anthropic Console
• Basic familiarity with HTTP requests and JSON
• Python 3.8+ or Node.js 18+ installed locally

Step 1: Authentication

Every API request requires an x-api-key header containing your secret key. Never expose your API key in client-side code, version control, or public repositories. Use environment variables or a secrets manager.

Setting your API key

# Terminal (Linux/macOS)
export ANTHROPIC_API_KEY="sk-ant-..."
Windows (Command Prompt)
set ANTHROPIC_API_KEY=sk-ant-...

Step 2: Your First API Call

Let's send a simple message to Claude. We'll use the messages endpoint, which is the recommended way to interact with the model.

Python example

import os
import requests
API_KEY = os.environ.get("ANTHROPIC_API_KEY")
API_URL = "https://api.anthropic.com/v1/messages"
headers = {
    "x-api-key": API_KEY,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
}
data = {
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude! What can you do?"}
    ]
}
response = requests.post(API_URL, headers=headers, json=data)
print(response.json()["content"][0]["text"])

TypeScript example

const API_KEY = process.env.ANTHROPIC_API_KEY;
const API_URL = "https://api.anthropic.com/v1/messages";
const response = await fetch(API_URL, {
  method: "POST",
  headers: {
    "x-api-key": API_KEY!,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 1024,
    messages: [
      { role: "user", content: "Hello, Claude! What can you do?" }
    ]
  })
});
const data = await response.json();
console.log(data.content[0].text);

Step 3: Understanding the Request Body

The /v1/messages endpoint expects a JSON body with these key fields:

Messages array

Each message has:

• role: "user" or "assistant"
• content: string (text) or array of content blocks (for images, tools)

For multi-turn conversations, include the full 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?"}
]

Step 4: Streaming Responses

For real-time applications, use streaming to receive tokens as they're generated. This dramatically improves perceived latency.

Python streaming

import os
import requests
API_KEY = os.environ.get("ANTHROPIC_API_KEY")
headers = {
    "x-api-key": API_KEY,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
}
data = {
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Write a short poem about coding."}
    ]
}
with requests.post("https://api.anthropic.com/v1/messages",
                  headers=headers, json=data, stream=True) as response:
    for line in response.iter_lines():
        if line:
            # Parse SSE event
            if line.startswith(b"data: "):
                event_data = line[6:]
                if event_data != b"[DONE]":
                    import json
                    chunk = json.loads(event_data)
                    if chunk["type"] == "content_block_delta":
                        print(chunk["delta"]["text"], end="", flush=True)

TypeScript streaming

const response = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ANTHROPIC_API_KEY!,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "Write a short poem about coding." }]
  })
});
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  
  const lines = buffer.split("\n");
  buffer = lines.pop() || "";
  
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = line.slice(6);
      if (data !== "[DONE]") {
        const chunk = JSON.parse(data);
        if (chunk.type === "content_block_delta") {
          process.stdout.write(chunk.delta.text);
        }
      }
    }
  }
}

Step 5: Error Handling

The API returns standard HTTP status codes. Common ones:

Always implement retry logic with exponential backoff for 429 and 5xx errors.

import time
import requests
def call_claude_with_retry(data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(API_URL, headers=headers, json=data)
        if response.status_code == 200:
            return response.json()
        elif response.status_code in [429, 500, 502, 503]:
            wait = 2 ** attempt + random.uniform(0, 1)
            time.sleep(wait)
        else:
            response.raise_for_status()
    raise Exception("Max retries exceeded")

Best Practices

1. Use system prompts effectively

System prompts set the tone, role, and constraints for Claude. Be specific:

data = {
    "system": "You are a senior software engineer reviewing code. "
              "Provide concise, actionable feedback. "
              "Always suggest specific improvements with code examples.",
    "messages": [{"role": "user", "content": code_snippet}]
}

2. Set appropriate max_tokens

Don't request more tokens than you need. Shorter responses are faster and cheaper. For classification tasks, max_tokens=50 is often sufficient.

3. Implement rate limiting

The API has rate limits per tier. Check your limits in the Anthropic Console. Implement client-side throttling to avoid 429s.

4. Cache common responses

If you're asking the same question repeatedly (e.g., "Summarize this article"), cache the response keyed by input hash. This saves cost and latency.

5. Monitor token usage

Track both input and output tokens. The usage field in the response tells you exactly how many tokens were consumed:

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 43
  }
}

Conclusion

The Claude API is straightforward to integrate but rewards careful design. By following the patterns in this guide—proper authentication, structured messages, streaming for responsiveness, and robust error handling—you'll be well on your way to building reliable, production-quality applications powered by Claude.

For more advanced topics like tool use (function calling), vision, and embeddings, check out the official Anthropic documentation.

Key Takeaways

• Authenticate every request with the x-api-key header and keep your key secret using environment variables.
• Use the /v1/messages endpoint with a structured array of messages for both single-turn and multi-turn conversations.
• Enable streaming (stream: true) for real-time applications to improve user experience.
• Implement exponential backoff retry logic for 429 and 5xx errors to build resilient integrations.
• Monitor token usage via the usage field in responses and set max_tokens conservatively to control costs.