What Is the Claude API?
The Claude API is Anthropic's programmatic interface for building applications with Claude. Instead of chatting with Claude through a browser interface, the API lets you send messages and receive responses directly from your code — enabling you to build your own apps, automations, and AI-powered tools.
This guide covers everything you need to make your first successful API call: setup, authentication, message structure, system prompts, and the most common beginner mistakes.
Setting Up
Before you write a single line of code, you need an API key.
1. Create an account at console.anthropic.com
2. Navigate to API Keys in your account settings
3. Click "Create Key" and copy the key immediately — you won't be able to see it again
4. Store it securely, ideally in an environment variable, never hardcoded in your source files
Install the official SDK for your language. Anthropic provides SDKs for Python and TypeScript/JavaScript, with the Python SDK being the most feature-complete.
Python:
pip install anthropic
Node.js:
npm install @anthropic-ai/sdk
Authentication
The API uses Bearer token authentication. Your API key is passed with every request. Using the official SDK, you simply set the ANTHROPIC_API_KEY environment variable and the SDK picks it up automatically:
ANTHROPIC_API_KEY=your-key-here
Or you can pass it explicitly when initialising the client:
client = Anthropic(api_key="your-key-here")
The environment variable approach is strongly preferred for any real project — it prevents your key from appearing in version control history or error logs.
Your First API Call
Here's the simplest possible call — sending a message and getting a response back:
Python pseudocode:
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello! What can you help me with?"}
]
)
print(message.content[0].text)
The response object contains the text in message.content[0].text. The model field specifies which Claude model to use — claude-haiku-4-5-20251001 for fast/cheap tasks, claude-sonnet-4-6 for most tasks, claude-opus-4-6 for the most demanding reasoning tasks.
Understanding Message Structure
The Claude API uses a conversation format where messages alternate between "user" and "assistant" roles. This is the foundation of multi-turn conversations:
messages = [
{"role": "user", "content": "What is photosynthesis?"},
{"role": "assistant", "content": "Photosynthesis is the process by which..."},
{"role": "user", "content": "How does temperature affect it?"}
]
Each time you make a new API call, you send the entire conversation history in the messages array. The API is stateless — it doesn't remember previous calls. Your application is responsible for maintaining and appending to the conversation history between turns.
System Prompts
System prompts are instructions that shape Claude's behaviour for your entire application. They're passed separately from user messages and set context like: who Claude is, what it should focus on, how it should respond, and what it should avoid.
message = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system="You are a helpful assistant for a UK accounting firm. Answer questions clearly and concisely. Always recommend consulting a qualified accountant for complex tax matters.",
messages=[
{"role": "user", "content": "Can I claim my home office as a business expense?"}
]
)
Good system prompts are specific. "Be helpful" is weak. "You are an expert Python developer helping a junior team. Explain your reasoning. Provide runnable code examples. Flag any security concerns." is strong.
Common Beginner Mistakes
**1. Hardcoding your API key.** This is the most dangerous mistake. Your key will end up in git history, logs, or error messages. Always use environment variables.
**2. Not handling max_tokens correctly.** The max_tokens parameter sets the maximum length of the response. If you set it too low, responses get cut off mid-sentence. For most tasks, 1024–4096 is appropriate. For long documents, go higher.
**3. Forgetting the API is stateless.** If you're building a chatbot and users complain it "forgets" things, you're probably not including conversation history in subsequent requests.
**4. Using the wrong model.** Haiku is 10–15x cheaper than Opus. For simple classification, summarisation, or routing tasks, Haiku is usually the right choice. Save the heavyweight models for tasks that genuinely require deep reasoning.
**5. Not reading the error response.** API errors return structured JSON with an error type and message. A 401 means your API key is wrong. A 429 means you've hit a rate limit. Read the error before assuming something complex is broken.
**6. Ignoring token costs.** Tokens add up quickly in production. Long system prompts, large context windows, and high-volume usage can generate significant bills. Build cost tracking into your application from day one.
What to Build Next
Once you have your first API call working, the natural next steps are:
The Claude API documentation at docs.anthropic.com is comprehensive and actively maintained. The prompt engineering guides and cookbook are particularly valuable for moving beyond basic usage.
The best way to learn the API is to build something real with it — even a small automation that saves you 30 minutes a week will teach you more than any tutorial.