Skip to content
Clawdemy

Summary: Your first Claude API call

The Track 22 opener. One HTTP POST to https://api.anthropic.com/v1/messages with three required headers (x-api-key, anthropic-version, Content-Type: application/json) and a JSON body with three required fields (model, max-tokens, messages) is a working Claude API call. The response is structured, not a string: content is an array of blocks (iterate, do not index), stop_reason tells you why generation ended (check it on every response), usage gives input and output token counts (the cost unit, log from day one), and id identifies the specific generation (log it for production debugging). The most important conceptual jump is that the API is stateless: to have a multi-turn conversation, your application sends the entire conversation history with every request as the messages list (alternating user and assistant, ending with user); the API holds nothing between calls, which keeps it simple and trivially scaled but means your code owns conversation state and pays for the full history on every turn. Standing instructions (persona, format, constraint) belong in the system parameter, separate from the messages list; it is a sidecar that tells the model how to behave for the whole call, not a message with a role. The smallest end-to-end pattern in this lesson is what every later lesson in Track 22 extends.

Core ideas

Section titled “Core ideas”
  • One endpoint. https://api.anthropic.com/v1/messages, POST, JSON body. Three required headers: x-api-key, anthropic-version: 2023-06-01, Content-Type: application/json. Three required body fields: model, max-tokens, messages. Optional system for standing instructions.
  • Two SDK forms shown. Python (pip install anthropic) and TypeScript (npm install @anthropic-ai/sdk). Both auto-read ANTHROPIC_API_KEY from the environment. Java, Go, C-sharp, PHP, Ruby SDKs exist and follow the same shape.
  • Current canonical model names. claude-opus-4-8 (flagship Opus), claude-sonnet-4-6 (frontier intelligence at scale), claude-haiku-4-5 (fastest, near-frontier). Lesson 3 covers selection.
  • Response shape. id, type (message), role (assistant), content (array of blocks), model, stop_reason, usage (input_tokens + output_tokens).
  • Content is an array of blocks, iterate not index. Plain text response is one block of type: text; tool use, vision, and later features return multiple blocks. Code that does response.content[0].text breaks the first time the model returns two blocks.
  • stop_reason is application control flow. end_turn (normal), max_tokens (truncated, response is incomplete), stop_sequence (custom stop string), tool_use (tool call requested; lesson 4).
  • The API is stateless. Conversation state lives in your application, not the API. To talk multi-turn, send the full messages history every call. Cost shape: every turn pays for the full prior history as input tokens (lesson 7 covers prompt caching).
  • System parameter is the home for instructions. Persona, format, constraint. Separate from the messages list; not a message; no role. Putting the system instruction as a first user message is the common cross-API mistake.
  • Five common pitfalls. API key not set; wrong model name; max-tokens too small (response truncates with stop_reason of max_tokens); content read as a string; treating the API as stateful.
  • What this lesson does NOT cover (each lands later in T22). Streaming (lesson 2). Tools (lessons 4 and 5). Model Context Protocol (lesson 6). Prompt caching (lesson 7). Agent loop (lessons 8 onward).

What changes for you

Section titled “What changes for you”

Before this lesson, Claude was a product you visited. After this lesson, Claude is a component your application controls. The whole rest of Track 22 (twelve lessons across four phases) is a more interesting variation on what this lesson establishes: the same endpoint, the same request shape, the same response shape, the same stateless-multi-turn pattern. Lesson 2 extends the response side (streaming, batches, error handling); lesson 3 extends the model-selection side (Opus versus Sonnet versus Haiku, extended thinking, the effort dial); Phase 2 (lessons 4-7) extends what one call can do (tools, MCP, caching, context management); Phase 3 (lessons 8-11) extends the loop (agent patterns, Agent Skills, subagents); Phase 4 (lesson 12) extends to production (monitoring, cost, Messages API versus Managed Agents).

The single highest-leverage thing you can do this week is the Try-it-yourself exercise in the practice artifact: make three calls of your own (simplest possible, multi-turn, system parameter). Twenty minutes of hands-on at the smallest scale removes the “I have not actually done this yet” friction that often blocks the next twenty lessons. The smallest primitive working end to end on your own machine is the bar; every later lesson extends from there.