Claude API tutorial: your first call in Python and TypeScript

Before you start

You need a Claude Console account and an API key. In the Console, open the API keys page, click Create key, name it and pick an expiration. The Console shows the full key, which starts with sk-ant-, only once, so copy it into a secrets manager. A personal key stops working when you leave the organization, which is why the docs point shared workloads to a service account key. Anthropic's key page covers both types.

The SDKs want Python 3.10 or later, or Node.js 20 LTS or later with TypeScript 5.0 or later. Both read ANTHROPIC_API_KEY from the environment by default, so the key never appears in your code. The TypeScript SDK refuses to run in a browser until you set dangerouslyAllowBrowser, and the name is fair warning: anyone who can open the page can read the key.

Make the first call in Python

This is the docs' quickstart with a system prompt and a usage line added. The model id comes from the models page, which is also where you check it before you copy it.

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    system="You are a concise assistant. Answer in three bullet points.",
    messages=[
        {
            "role": "user",
            "content": "What should I search for to find the latest developments in renewable energy?",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

print(message.stop_reason, message.usage)

1. Export the key in the shell that will run the script: export ANTHROPIC_API_KEY="your-api-key-here".
2. Create a project folder and a virtual environment, then install the SDK with python3 -m venv .venv && source .venv/bin/activate and pip install anthropic.
3. Save the code above as quickstart.py.
4. Run python quickstart.py. You get the answer text, then one line with the stop reason and the token counts.
5. Change max_tokens to 20 and run it again. The answer ends mid-sentence and stop_reason reads max_tokens.

The same call in TypeScript

Run npm init -y, npm pkg set type=module and npm install @anthropic-ai/sdk, save the code as quickstart.ts and start it with npx tsx quickstart.ts, as the quickstart does.

TypeScript keeps the HTTP API's field names, so max_tokens and stop_reason keep their underscores. The Messages API reference marks model, max_tokens and messages as the required fields.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY

const message = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1000,
  system: "You are a concise assistant. Answer in three bullet points.",
  messages: [
    {
      role: "user",
      content: "What should I search for to find the latest developments in renewable energy?"
    }
  ]
});

for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

console.log(message.stop_reason, message.usage);

Read the response: blocks, usage and stop_reason

message.content is a list of blocks, not a string. A plain answer has one text block, but the same list can hold tool_use and thinking blocks, which is why the quickstart loops and picks the text ones. Writing content[0].text works until the day it does not.

usage holds input_tokens and output_tokens, the units the API meters. What are tokens in AI explains them. The Python SDK can also count before you send: client.messages.count_tokens(model=..., messages=[...]) returns input_tokens.

stop_reason says why generation ended. Check it on every response, because code that only reads text returns a cut-off answer without complaint.

Stream long answers

Waiting for a full reply feels slow and, for large outputs, fails on some networks. The SDK helper sends the request as server-sent events and gives you the text as it arrives. get_final_message() in Python, or finalMessage() in TypeScript, returns the same Message object that a plain call returns.

Streaming is not optional at the top of the range. The Python SDK raises a ValueError when a non-streaming request is expected to run past about 10 minutes, and both SDKs advise streaming for any large max_tokens.

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-5-5",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    message = stream.get_final_message()

print()
print(message.stop_reason, message.usage)

• The event order is message_start, then for each block content_block_start, one or more content_block_delta and content_block_stop, then message_delta and message_stop. Unknown event types can appear, so ignore what you do not handle (streaming page).
• stop_reason is null in message_start and arrives in message_delta. The token counts in message_delta are cumulative.
• An error can arrive after the API has already sent a 200. It shows up as an error event, for example overloaded_error, so a streaming loop needs its own error branch.

Pick a model id and expect it to change

On 5 November 2026 the docs list four current models. Each id is a pinned snapshot with no date in it, and Anthropic commits to keeping each one available at least until the date in the table, for the platforms it runs. The models overview suggests Opus 5.5 as the starting point for most workloads.

The SDK sends the anthropic-version header for you, and a new API version arrives with a new SDK major version. Python SDK 2.0.0 is the first to use 2026-10-21, and for the TypeScript SDK it is 1.0.0.

All four models shipped within about five weeks, and the API version followed two weeks after the last one. A tutorial written in August names none of them, which is why the release notes are worth a look before you copy an id.

Errors, retries and timeouts

Both SDKs raise typed errors for 4xx and 5xx responses and retry some of them. The Python SDK page and the TypeScript SDK page give the defaults: two retries with a short exponential backoff for connection errors, 408, 409, 429 and 5xx, and a 10-minute timeout. Change them with max_retries in Python or maxRetries in TypeScript, and log message._request_id on every call, since support asks for it.

The errors page adds a case a retry cannot fix: a rate-limit error that signals a monthly spend cap. It carries no retry-after header and keeps failing until access resumes.

What ClaudeDevs posted when API version 2026-10-21 shipped

ClaudeDevs, the account Anthropic runs for developers, announced the new version on X the day it shipped. It was the first official API version since 2023. Versions will now come more often, so you can deal with a breaking change before a new model forces it on you, and 2023-06-01 is not deprecated.

The next post in the thread lists the changes. Top of the list: temperature, top_p and top_k are gone from the Messages API. Documents in assistant turns and citations in user turns now fail as well.

Search your code for those three parameter names before you move to Python SDK 2.0.0 or TypeScript SDK 1.0.0. Until you do, your current SDK keeps sending the old version.

Screenshots of X's own embeds of the posts, taken on 5 November 2026, with the time in UTC. Select one to open the post on X.

Common mistakes

• Reading content[0].text, which breaks the day the first block is a thinking or tool_use block.
• Sending only the newest message. The Messages API is stateless, so every request carries the full history, including earlier assistant turns.
• Copying temperature from an older tutorial and having a current model reject the request.
• Shipping the key in browser code. Organizations with zero data retention cannot call the API from a browser at all, and their requests fail with a 401.
• Asking for a huge max_tokens without streaming, then blaming the network when the request times out.
• Treating usage.input_tokens as the whole input once caching is on. Lesson 3 explains why it is smaller.

Try it yourself

• Add a second turn: append the assistant reply and a follow-up question to messages, then call again and watch input_tokens grow.
• Set stop_sequences=["END"], ask Claude to count to ten and finish with END, then read stop_sequence on the response.
• Export a wrong key and catch the typed error. Which class do you get, and what is the status code?
• Switch the model id to claude-haiku-5-5 and compare the latency by eye on the same prompt.

Next

Lesson 2 lets Claude call functions you write. The system prompt above is one line, and the system prompt lesson shows how to write a real one. Because you resend the whole history on every call, the context window lesson explains what that costs you.

Frequently asked questions

Sources

1. Anthropic Docs: Get started with Claude (read November 4, 2026)https://platform.claude.com/docs/en/get-started
2. Anthropic Docs: Get your Claude API key (read November 4, 2026)https://platform.claude.com/docs/en/get-api-key
3. Anthropic Docs: Using the Messages API (read November 4, 2026)https://platform.claude.com/docs/en/build-with-claude/working-with-messages
4. Anthropic Docs: Messages API reference (read November 4, 2026)https://platform.claude.com/docs/en/api/messages/create
5. Anthropic Docs: Streaming messages (read November 4, 2026)https://platform.claude.com/docs/en/build-with-claude/streaming
6. Anthropic Docs: Stop reasons and fallback (read November 4, 2026)https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons
7. Anthropic Docs: Models overview (read November 5, 2026)https://platform.claude.com/docs/en/models/overview
8. Anthropic Docs: Claude API errors (read November 4, 2026)https://platform.claude.com/docs/en/api/errors
9. Anthropic Docs: Python SDK (read November 4, 2026)https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python
10. Anthropic Docs: TypeScript SDK (read November 4, 2026)https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript
11. GitHub: anthropics/anthropic-sdk-python (read November 4, 2026)https://github.com/anthropics/anthropic-sdk-python
12. GitHub: anthropics/anthropic-sdk-typescript (read November 4, 2026)https://github.com/anthropics/anthropic-sdk-typescript
13. Claude Docs: Release notes (read November 5, 2026)https://platform.claude.com/docs/en/release-notes/overview
14. X: ClaudeDevs announces API version 2026-10-21 (read November 5, 2026)https://x.com/ClaudeDevs/status/2113013247209021918
15. X: ClaudeDevs lists what changes in API version 2026-10-21 (read November 5, 2026)https://x.com/ClaudeDevs/status/2113013248714744208