Using the Claude API with Node.js: A Team Guide

Install the SDK and set the key in your environment (or your platform’s secret store):

npm install @anthropic-ai/sdk

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

const client = new Anthropic(); // reads ANTHROPIC_API_KEY
const msg = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Summarize what an SDK is." }],
});
console.log(msg.content[0].type === "text" ? msg.content[0].text : "");

Response content is a discriminated union — TypeScript will force you to narrow on block.type before reading .text, which is the compiler catching a real runtime hazard. Plain JavaScript projects use the same package; the types simply become editor hints. One team convention worth adopting immediately: construct the client once in a shared module and import it, rather than instantiating per request.

The single most important architectural rule: the API key lives server-side, always. A key shipped in frontend JavaScript is public within minutes, and anyone holding it can spend your budget. The standard architecture is:

• Browser calls your backend endpoint (Express route, Next.js route handler, serverless function).
• Your backend authenticates the user, applies rate limits and input validation, then calls Claude with the server-held key.
• The response — streamed or complete — is relayed to the browser.

This proxy layer is also where team-level controls belong: per-user quotas, prompt-injection filtering on user input, logging with request IDs, and cost attribution by feature. Use distinct API keys per environment, store them in your platform’s secret manager, and rotate on any suspected exposure — practices we drill in corporate Claude AI training sessions.

Claude streams via server-sent events, and the SDK wraps this in an async iterable that pairs naturally with a streaming HTTP response. An Express example relaying text deltas as SSE:

app.post("/api/chat", async (req, res) => {
  res.setHeader("Content-Type", "text/event-stream");
  const stream = client.messages.stream({
    model: "claude-sonnet-5", max_tokens: 2048,
    messages: req.body.messages,
  });
  stream.on("text", (delta) => res.write(`data: ${JSON.stringify(delta)}\n\n`));
  const final = await stream.finalMessage();
  res.end();
});

Use finalMessage() to get the assembled message and usage counts — do not hand-wire event listeners into a Promise. The same pattern works in Next.js route handlers with web-standard ReadableStreams, and streaming is required behavior for large max_tokens values to avoid HTTP timeouts.

Tool use turns Claude from a text generator into an orchestrator of your backend: you define functions with JSON schemas, Claude decides when to call them, your code executes and returns results. The raw loop is: send tools with the request, watch for stop_reason: “tool_use”, execute each tool_use block, and send back matching tool_result blocks in a user message.

The SDK’s beta tool runner automates that loop — you pass tool definitions with attached run functions (plain JSON Schema or Zod) and it iterates until Claude finishes. Team guidelines that prevent pain later:

• Write tool descriptions that say when to call the tool, not just what it does.
• Validate every tool input server-side; model output is untrusted input.
• Gate destructive operations (sends, writes, deletes) behind explicit checks or human approval.

Multi-developer Claude codebases stay healthy with a few enforced conventions:

• One client module: a single configured Anthropic instance exported from lib/claude.ts, so timeouts and retries are set in one place.
• Use SDK types: Anthropic.MessageParam, Anthropic.Tool, and friends — never redefine parallel interfaces.
• Prompts as reviewed artifacts: keep system prompts in versioned files with owners, not inline template literals scattered across handlers.
• Centralized model config: map task names to model IDs (claude-haiku-4-5 for cheap paths, claude-sonnet-5 default, claude-opus-4-8 for hard reasoning) so tier changes are one-line diffs — our model guide helps calibrate the mapping.
• A tiny eval script in CI: a handful of golden cases catches prompt and model regressions before deploy.