Foundations

The Messages API

Now that you know the API is just an HTTP doorway, let's walk through the one request you'll send a thousand times — and the reply that comes back. We'll use the Python SDK (with the raw HTTP shown alongside, so you always see what it builds). Every agent, tool, and prompt in this whole cert is this call, dressed up.

messages.create()role: user / assistant systemthe response object stateless

Explain like I'm 10

Talking to Claude is like passing notes in class. Each note says who's talking ("me" or "Claude") and what they said. Here's the twist: Claude has no memory. To continue a chat you don't send just your new note — you re-hand Claude the whole stack of notes from the beginning, every single time. The "conversation" is really you giving back the entire notebook on each turn, and Claude reading it fresh.

Your very first call (Python)

Three lines of setup, one call. Read it top to bottom — the comments say what each piece is. (No API key yet? Getting your API key is a 5-minute detour.)

# one-time: pip install anthropic   +   export ANTHROPIC_API_KEY=sk-...
import anthropic

client = anthropic.Anthropic()          # finds your key in the environment

msg = client.messages.create(           # ← THE call. everything is this.
    model="claude-sonnet-4-6",       # which Claude
    max_tokens=300,                 # longest reply you'll allow
    system="You are a concise, friendly assistant.",  # standing instructions
    messages=[                           # the conversation so far
        {"role": "user", "content": "Suggest a name for a tabby cat."},
    ],
)

print(msg.content[0].text)              # → "How about Marmalade?"

Java bridge: if you did the Java/HTTP version, client.messages.create(...) is exactly your HttpClient.send(POST /v1/messages, body) — the SDK is that POST, pre-written. The msg object is the parsed JSON response.

What you send vs what "the API" sees

Toggle between the Python you write and the raw HTTP it becomes. Same request — the SDK is just filling out the order slip for you:

The reply you get back

The response is a JSON object (the SDK hands it to you as msg). You'll reach for four fields constantly. Hover/click each field to see what it's for:

Click a field above.

The rule that trips everyone: it's stateless

The API remembers nothing between calls — there is no conversation stored on the server. To have a multi-turn chat, you keep the messages list and resend the growing array each turn, appending Claude's last reply as an assistant message. Watch the notebook grow:

Exam traps & gotchas: the API is stateless — "Claude remembers our last chat" is false unless you resend the messages (this is why long conversations fill the context window in Domain 5). system is a separate top-level parameter, not a message with role:"system". Roles must alternate user → assistant → user. And you must set max_tokens — it caps the reply, reserving output room in the window.

Takeaways: one call — client.messages.create(...) — is the whole API. You pass a model, a top-level system prompt, an alternating user/assistant messages list, and max_tokens. You get back a response object; grab the text at content[0].text, check stop_reason, and read usage for token counts. It's stateless — you resend the full history every turn. The SDK is just this HTTP call, pre-written.

Next: the parameters that matter — what each knob does and when to turn it. Then how to read the API docs so you can answer your own questions. Practice it for real in the runnable Python exercises.