Claude API Tutorial: Your First Request in 5 Minutes

April 1, 2026

This is a zero-to-working-code tutorial for the Claude API. By the end, you will have made a successful API call and received a response. No prior API experience required, though you should be comfortable running commands in a terminal.

Step 1: Get an API Key

Go to console.anthropic.com and create an account. Once you are in the dashboard, navigate to API Keys and create a new key. Copy it immediately — you will not be able to see it again after closing the dialog.

Store the key as an environment variable so you do not accidentally commit it to version control:

export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

Add this line to your ~/.bashrc or ~/.zshrc so it persists across terminal sessions.

Step 2: Make Your First Request with curl

The fastest way to test the API is with curl. Copy and paste this into your terminal:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

You should get a JSON response within a few seconds. The actual answer is in response.content[0].text. The response also includes usage information showing how many tokens were used for input and output.

Step 3: Understanding the Request Format

Let us break down each part of the request:

model: Which Claude model to use. claude-sonnet-4-20250514 is the best balance of speed and quality for most tasks. Use claude-opus-4-20250514 for the most complex reasoning tasks, or claude-haiku-4-20250514 for fast, simple tasks.
max_tokens: The maximum number of tokens Claude can generate in its response. One token is roughly 4 characters. Set this based on how long you expect the response to be. 256 tokens is about 200 words.
messages: An array of message objects, each with a role ("user" or "assistant") and content (the text). For a simple request, you just need one user message.
system (optional): A system prompt that sets Claude's behavior. Think of it as background instructions that apply to the entire conversation.
temperature (optional): Controls randomness. 0.0 gives deterministic output, 1.0 gives more creative output. Default is 1.0. Use 0.0-0.3 for factual tasks, 0.7-1.0 for creative tasks.

Step 4: Use the Python SDK

For real projects, use the official Python SDK. Install it:

pip install anthropic

Then write your first script:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful coding assistant.",
    messages=[
        {"role": "user", "content": "Write a Python function that reverses a string."}
    ]
)

print(message.content[0].text)

The SDK automatically reads your ANTHROPIC_API_KEY environment variable. No need to pass it explicitly.

Step 5: Add a System Prompt

System prompts dramatically improve response quality for specific tasks. They tell Claude how to behave before the user says anything. Here is an example that turns Claude into a JSON-only responder:

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=256,
    temperature=0.0,
    system="You are a data extraction assistant. Always respond with valid JSON only. No markdown, no explanation, just JSON.",
    messages=[
        {"role": "user", "content": "Extract the name, age, and city from: John Smith, 34, lives in Portland."}
    ]
)

# Output: {"name": "John Smith", "age": 34, "city": "Portland"}

The temperature is set to 0.0 for deterministic output, which is important when you need consistent JSON formatting.

Step 6: Handle Multi-Turn Conversations

To have a conversation, include previous messages in the messages array:

messages = [
    {"role": "user", "content": "What is the population of Tokyo?"},
    {"role": "assistant", "content": "The population of Tokyo is approximately 14 million in the city proper and about 37 million in the greater metropolitan area."},
    {"role": "user", "content": "How does that compare to New York?"}
]

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=512,
    messages=messages
)

print(message.content[0].text)

Claude will use the full conversation history as context. Messages must alternate between "user" and "assistant" roles, starting with "user".

Common Gotchas

401 Unauthorized: Your API key is wrong or not set. Double-check the environment variable with echo $ANTHROPIC_API_KEY.

400 Bad Request: Usually a malformed request body. The most common mistake is forgetting that messages is an array of objects, not a string. The HeyTensor debugging tools can help trace API request issues.

Rate limited (429): You are sending too many requests. Add exponential backoff with retries. The SDK handles this automatically if you use client.messages.create.

Unexpected truncation: If the response cuts off mid-sentence, increase max_tokens. Check message.stop_reason in the response. If it says "max_tokens", the response was truncated.

Next Steps

You now have a working Claude API integration. To explore more options interactively, try the ClaudKit playground where you can adjust all parameters visually and see the generated code update in real time.

For production applications, read the official Anthropic documentation which covers streaming responses, function calling, vision (image inputs), and best practices for prompt engineering.