Claude API SDK TypeScript Quickstart Guide

If you're searching for a Claude API SDK TypeScript quickstart guide, you want to go from zero to a working request in your terminal or app as fast as possible, with correct types and no guesswork about authentication. This guide covers installing the official SDK, setting up your API key, sending your first message, streaming a response, and the common mistakes that trip up a first integration.

By the end you'll have a typed, working Claude client in a Node.js or TypeScript project, plus a note on an alternative setup if you'd rather manage access through a plain HTTPS API instead of juggling SDK versions across services.

Prerequisites

You need three things before writing any code:

• Node.js 18+ (for native fetch and modern ESM support)
• An API key from Anthropic, or from a service that issues Claude-compatible keys
• TypeScript 5+ if you want full type inference from the SDK

Check your Node version:

node -v

If you're below v18, upgrade first — the SDK relies on features that don't exist in older runtimes.

Step 1: Install the SDK

In an existing or new TypeScript project:

npm install @anthropic-ai/sdk
npm install -D typescript ts-node @types/node

If you don't have a tsconfig.json yet, generate one:

npx tsc --init

Set "module": "ESNext" and "target": "ES2022" in tsconfig.json so async iterators and top-level await work cleanly with the SDK's streaming methods.

Step 2: Set your API key

Never hardcode keys. Store it as an environment variable:

export ANTHROPIC_API_KEY="your-key-here"

Or use a .env file with dotenv:

npm install dotenv

import "dotenv/config";

The SDK reads ANTHROPIC_API_KEY automatically if you don't pass a key explicitly, which keeps your code portable across environments.

Step 3: Your first message

Create index.ts:

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

const client = new Anthropic();

async function main() {
  const message = await client.messages.create({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 1024,
    messages: [
      { role: "user", content: "Explain promises in TypeScript in two sentences." },
    ],
  });

  console.log(message.content);
}

main();

Run it:

npx ts-node index.ts

You should get a typed Message object back, with content as an array of content blocks (usually a single text block for simple prompts). This is the core shape you'll build everything else on top of — system prompts, multi-turn history, tool calls, and streaming all extend this same messages.create call.

Step 4: Add a system prompt and conversation history

Real apps need more than one message. Pass a system string and an array of prior turns:

const message = await client.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 1024,
  system: "You are a terse code reviewer. Answer in bullet points only.",
  messages: [
    { role: "user", content: "Review this function for bugs." },
    { role: "assistant", content: "Please paste the function." },
    { role: "user", content: "function add(a, b) { return a - b }" },
  ],
});

TypeScript will enforce that role is "user" or "assistant" — if you mistype it, you get a compile error instead of a runtime surprise.

Step 5: Stream responses

For chat UIs or long completions, streaming avoids making users wait for the full response:

const stream = client.messages.stream({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Write a haiku about async/await." }],
});

stream.on("text", (text) => {
  process.stdout.write(text);
});

await stream.finalMessage();

The .stream() method returns an event emitter with typed events for text deltas, content blocks, and the final assembled message — useful when you need both the live tokens and the complete object afterward.

Common quickstart mistakes

• Forgetting max_tokens: it's required on every call, not optional.
• Mixing up role values: Claude's Messages API doesn't use "system" as a message role — system instructions go in the separate system field.
• Not handling rate limits: wrap calls in retry logic or check error.status === 429 before assuming a transient failure means your code is broken.
• Hardcoding model strings everywhere: define a const MODEL = "claude-3-5-sonnet-20241022" once and import it, so upgrading models later is a one-line change.

An alternative: skip SDK version management entirely

If you're building a product on top of Claude rather than a one-off script, managing SDK versions, key rotation, and per-model request formatting across multiple services gets tedious fast — especially once you have a team sharing one Claude subscription.

SubToAPI turns your existing Claude access into a standard HTTPS API with its own sub_live_... application keys, so your TypeScript code talks to a stable REST endpoint instead of juggling provider SDKs directly:

const res = await fetch("https://api.subtoapi.app/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello" }],
  }),
});

This is a plain HTTP call — no SDK install required — and it works the same whether you're calling it from TypeScript, a mobile app, or a backend in another language. It also gives you streaming, tool use, usage metadata per key, and team seats in one dashboard, which matters once more than one developer is burning through the same quota. See the quickstart and messages docs for the full request shape, or check pricing — plans start at Solo €9/month with a free trial at signup.

questions

Do I need the official Anthropic SDK, or can I just use fetch? Either works. The SDK gives you TypeScript types, retry handling, and streaming helpers out of the box. Plain fetch works fine too if you want zero dependencies or are calling the API from an environment where installing the SDK isn't practical.

Why am I getting a type error on the role field? The Messages API only accepts "user" and "assistant" as message roles — system instructions belong in the separate top-level system parameter, not inside the messages array.

How do I handle streaming in a TypeScript backend serving multiple users? Use the SDK's .stream() event emitter per request and pipe the text events into your own response stream (e.g., Server-Sent Events). Keep one Claude client instance reused across requests rather than instantiating it per call. See /docs/streaming for a concrete pattern if you're proxying through an HTTP API layer.