Week 6: The Messages API — Requests, Responses & Streaming

1. Auth & the Messages API

Get an API key from the Anthropic Console, store it in an environment variable — never hardcode it in source, and never ship it to a browser, since anyone could read it out of your client-side code and rack up usage on your account. Every request authenticates with that key in a header.

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain what a race condition is in one paragraph."}
    ]
  }'

Every request needs a model, a max_tokens ceiling (the hard cap from Week 1's context-window discussion, but for just the response this time), and a messages array of {role, content} objects — user and assistant turns, in order. The response comes back with the generated text plus metadata: how many tokens were used, and why the response stopped (it finished naturally, hit max_tokens, or something else).

2. System Prompts in Code

Week 3 covered system prompts conceptually — in the API, it's a distinct top-level parameter, separate from the messages array, not a message with a "system" role mixed into the conversation.

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=(
        "You are a code reviewer for a production Node.js API. Flag "
        "unhandled promise rejections first. Never suggest a rewrite "
        "unless there's a real bug. Cite exact line numbers."
    ),
    messages=[
        {"role": "user", "content": "Review this function: ..."}
    ],
)

print(response.content[0].text)

Because it's a separate field, you set it once per request rather than repeating it in every message — and you can vary it call to call (different reviewer rules for different repos, say) without it competing for space in the conversation history itself the way a "system-role message" would.

3. Streaming Responses

A non-streaming call waits for the entire response before returning anything — fine for short answers, but a bad user experience for a long one, where someone stares at a blank loading state for several seconds. Streaming returns the response incrementally, token by token, as it's generated.

with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a short poem about deploying on a Friday."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)  # prints as each chunk arrives

This is exactly what powers the "typing" effect you see in claude.ai itself — the perceived speed improves dramatically even though the total time to finish the full response is roughly the same, because the user sees progress immediately instead of a blank wait.

4. Python & TypeScript SDKs, Side by Side

The official SDKs wrap the raw HTTP API with typed request/response objects, automatic retries on transient errors, and rate-limit handling — worth using instead of hand-rolling HTTP calls for anything beyond a quick test.

// Python
import anthropic
client = anthropic.Anthropic()
msg = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Say hello in three languages."}],
)
print(msg.content[0].text)

// TypeScript
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic(); // reads ANTHROPIC_API_KEY from env
const msg = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Say hello in three languages." }],
});
console.log(msg.content[0].text);

The request shape is identical between languages — same field names, same structure — which is intentional: everything you learn about the Messages API this week transfers directly regardless of which SDK your project uses. Pick based on your stack, not based on any difference in what the API itself can do.

5. Hands-on Exercise

6. Knowledge Check

Four quick questions. Expand each to check your answer.