📡Your First API Call

Send a message to Claude and understand the response

Your First API Call

Now let's make a real API call and understand every piece of the request and response.

The Basic Request Structure

Every Claude API call needs these parts:

JavaScript
const response = await client.messages.create({
  model: "claude-sonnet-4-6",      // Which Claude model
  max_tokens: 1024,                 // Max response length
  messages: [                       // The conversation
    {
      role: "user",                 // Who's talking
      content: "Hello, Claude!"     // What they said
    }
  ]
});

Understanding the Response

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

Let's break down each field:

Field	What It Means
`id`	Unique ID for this message
`role`	"assistant" means Claude is responding
`content`	Array of content blocks (usually text)
`stop_reason`	Why Claude stopped: "end_turn" = done naturally
`usage`	How many tokens were used (affects billing)

Stop Reasons Explained

Stop Reason	Meaning
`end_turn`	Claude finished naturally
`max_tokens`	Hit the token limit you set
`stop_sequence`	Found a custom stop word
`tool_use`	Claude wants to use a tool

Using System Prompts

A system prompt sets Claude's behavior for the entire conversation:

JavaScript
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: "You are a friendly teacher who explains things simply. Use analogies and examples.",
  messages: [
    { role: "user", content: "What is recursion?" }
  ]
});

Multi-Turn Conversations

The API is stateless — you must send the full conversation each time:

JavaScript
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "What is the capital of France?" },
    { role: "assistant", content: "Paris is the capital of France." },
    { role: "user", content: "What is its population?" }
  ]
});
// Claude knows "its" refers to Paris because of the conversation history

Using cURL (Command Line)

You can also call the API directly from your terminal:

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

Practice Exercise

Try these prompts and observe how Claude responds differently:

"Explain what an API is" — straightforward question
"Explain what an API is like I'm 5 years old" — simplified response
"Explain what an API is in exactly 3 bullet points" — constrained format

Next up: We'll install and learn Claude Code CLI — the game-changing terminal tool.

Module 2

3/6

🔧 Setting Up Your Environment

Choosing the Right Model 🎯

3/6