5.3 SDKs, REST, and Streaming Transport

Most Claude integrations go through the official Python or TypeScript SDKs. It's easy to think of the SDK as its own thing, separate from "the API" — but that framing is backwards. Underneath the SDK are ordinary HTTPS + JSON calls to the same REST API. The SDK is a convenience layer wrapped around that API surface, and it earns its keep by handling several pieces of plumbing you would otherwise hand-roll yourself: authentication (API key management), request/response serialization (turning SDK objects into JSON and back), typed errors (structured exceptions instead of raw HTTP status codes to branch on), automatic retries with backoff on transient failures, and helpers for consuming a streamed response as a simple iterator.

Because the SDK is a convenience wrapper and not a separate protocol, you can always drop down to raw REST and make the equivalent HTTPS + JSON request directly — useful in a language without an official SDK, or any time you need finer-grained control than the SDK's abstractions expose. Nothing about the API's actual behavior changes depending on whether you reach it through the SDK or by hand; only the amount of boilerplate you write does.

Both official SDKs typically ship a synchronous client, where each call blocks until it completes, and an asynchronous client, where calls can be issued concurrently. The choice between them is really a question about how your application's work is shaped: if you need to make several independent calls to Claude — say, summarizing five unrelated documents — issuing them one at a time with a sync client means waiting for each one to fully complete before starting the next, even though none of them depend on each other's results.

An async client lets you issue those independent, I/O-bound calls concurrently instead, which reduces total wall-clock time for the batch of work. It's worth being precise about what this does and doesn't change: concurrency affects how long your application takes to finish a batch of independent requests. It does not change how many tokens any individual request costs — that's determined by the content of the request itself, not by whether it was issued synchronously or asynchronously.

By default, an API caller could simply wait for a response to finish generating entirely and then receive it all at once. Streaming changes the delivery pattern: instead of one final payload, the server keeps a persistent connection open and delivers tokens to the client incrementally as they're generated, typically using server-sent events (SSE). This lets an application start rendering or processing partial output — for example, showing text appearing progressively in a chat UI — well before generation is complete, which substantially improves perceived latency, specifically time-to-first-token.

Streaming is purely a delivery mechanism. The model still generates the same sequence of tokens it would have generated without streaming; streaming only changes when and how those tokens arrive at the client. This is worth stating plainly because it's the single most commonly tested point about streaming: a streamed response and a non-streamed response to the identical request generate and bill the same number of output tokens. Streaming does not make generation cheaper, and it does not make generation faster in the sense of producing fewer total tokens or finishing sooner in wall-clock time — it changes how early the client starts seeing output.

SSE-based streaming is one-directional: the server pushes tokens to the client as they're generated. Some integrations need genuinely bidirectional, low-latency communication over a single persistent connection instead — realtime voice interfaces or live-conversation integrations are the typical example, where the client is also continuously sending data (audio, in-progress input) rather than just receiving it. Websockets support that two-way pattern in a way a one-directional SSE stream does not.

It's important not to over-generalize from this: most streaming use cases in a typical Claude integration — a chat UI progressively rendering a response, a backend consuming partial output for early processing — only need SSE, not a websocket. Websockets solve a narrower, specifically bidirectional/realtime problem. Treating every streaming integration as if it requires a websocket overstates the requirement for the common case.

• •Server-sent events (SSE) — one-directional, server-to-client incremental delivery; fits the vast majority of streaming use cases (chat UIs, progressive rendering, early processing of partial output).
• •Websockets — bidirectional, persistent connection; fits realtime/live-conversation integrations (e.g., voice) where the client is also continuously sending data, not just receiving it.

Task Statement 5.3 tests whether you can separate three ideas that are easy to blur together: what the SDK adds on top of REST, what async buys you versus sync, and what streaming/websocket transport does and doesn't change.

• •Treating the SDK as a different API from REST. ✗ An answer implying SDK-only capabilities don't exist at the REST layer. ✓ The answer recognizing the SDK as a typed convenience wrapper over the same HTTPS + JSON calls, always droppable to raw REST.
• •Confusing concurrency with cost. ✗ An answer claiming async clients change token pricing. ✓ The answer stating async parallelizes independent, I/O-bound calls to reduce wall-clock time, without changing token cost.
• •Assuming streaming reduces token cost or count. ✗ An answer claiming a streamed response bills fewer tokens or generates faster in total. ✓ The answer stating streaming changes delivery timing (time-to-first-token), not billed tokens.
• •Over-requiring websockets. ✗ An answer defaulting to websockets for any streaming scenario. ✓ The answer reserving websockets for genuinely bidirectional/realtime cases and SSE for the common one-directional case.