Using the Anthropic Claude API: A Practical Guide

Claude's API takes a list of messages that alternate between user and assistant turns, and the response's useful text is under content. The system prompt is a separate top-level field rather than a message, which is the first thing that trips people moving from other APIs.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "<a model id>",
    "max_tokens": 1024,
    "system": "You are a precise technical editor.",
    "messages": [
      {"role": "user", "content": "Tighten this paragraph."}
    ]
  }'

• max_tokens is required. There is no default, and omitting it is an error rather than a default.
• The version header pins behaviour; send it explicitly so an update does not silently change your responses.
• The key goes in a header, not a query string — query strings end up in logs and history.

A very large context window means you can send whole documents, but it is not free and it is not magic. Position matters: material placed in the middle of a very long prompt is attended to less reliably than the same material at the beginning or end. Put the instructions after the document, not before it.

Tool use is how you stop the model inventing facts. You describe your functions, the model decides when to call one, your code actually performs the action, and you return the result. Search, database lookups and calculations all go through this, which is what makes answers verifiable instead of confident.

• Describe each tool in plain language, including what it is for and what it is not for.
• Return real data as the tool result, and say plainly when a lookup found nothing.
• Keep the tool set small. Fifteen near-identical tools produce worse selection than four clear ones.
• Do your own validation on the arguments before executing anything with a side effect.

• Stream for anything a person reads; a long non-streaming response feels broken even when it is fast.
• Set a timeout and a retry policy. Retry 429s and 5xx with backoff; do not retry a 400.
• Cap max_tokens so a runaway generation cannot cost more than you intended.
• Log token usage per request from day one. It is the only way to find a cost problem before your invoice does.
• Use a prompt as a constant so a tuning change is one edit, not a hunt through your codebase.