Claude API as a REST and JSON Service: Endpoints, Headers, Streaming and Batches

1.One base URL, one endpoint per job

Much of this subdomain is ordinary software engineering applied to one particular service. The Claude API is a RESTful API at https://api.anthropic.com, so what you already do with any HTTP service still applies: a verb plus a resource path, a JSON body, and a status code when something goes wrong. What you have to learn is which endpoint does which job. Exam questions often describe a need, such as "check the size before sending" or "process thousands of prompts cheaply", and expect you to pick the endpoint that was built for it.

Two details in that table matter in practice. First, counting tokens has its own endpoint. You don't set a flag on the Messages call; you ask a separate endpoint before sending anything, which lets you decide ahead of time whether a large prompt needs splitting. Second, the size limits behave like normal REST limits: a request over the limit gets a 413 request_too_large error. The overview also lists beta APIs for Claude Managed Agents (Agents, Sessions and Environments), which you reach through beta headers.

Sources1

2.Headers, JSON bodies and what the SDK does for you

Every request carries a small, fixed set of headers. Each one maps to a familiar engineering concern: authentication, versioning, wire format and tenancy.

Because content-type is application/json, JSON is the wire format for the Messages API, just as it would be between any two internal microservices. The anthropic-version header pins the API version your code was written against. Treat it like any other version pin in your configuration: change it on purpose, never by accident. Responses carry headers too. The most useful is request-id, a globally unique identifier you include when contacting support about a specific call, so it belongs in your logs.

The official SDKs remove most of this boilerplate. They handle headers automatically (authentication, anthropic-version, content-type) and add type-safe request and response handling, built-in retry logic and error handling, streaming support, and request timeouts. There is one exception: when your key needs anthropic-workspace-id, you pass it yourself.

Sources1

3.Streaming: asynchronous delivery over server-sent events

Streaming is the first asynchronous pattern. The connection stays open while the response is still being produced, and the response arrives as a series of events. In the SDKs, .stream() keeps the HTTP connection alive with server-sent events. .get_final_message() in Python, or .finalMessage() in TypeScript, then collects every event and returns the complete Message object. The event order is fixed: message_start, which carries a Message with empty content; then, for each content block, a content_block_start, one or more content_block_delta events and a content_block_stop; then one or more message_delta events; and finally message_stop. Each block has an index that matches its position in the final Message content array. Ping events can appear anywhere in the stream.

event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

It is something else. Tool input deltas are fragments of a JSON string, and only the final tool_use.input is an object. You collect the fragments and parse them once content_block_stop arrives, either with a library that handles partial JSON, such as Pydantic, or with the SDK helpers. A 200 response doesn't guarantee a clean stream, either. Errors can arrive inside the stream: an overloaded_error during heavy usage, for example, which would normally be an HTTP 529 in a non-streaming call.

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

Sources2

4.Batches, rate limits and pagination

The second asynchronous pattern is about volume, not latency. The Message Batches API processes large volumes of Messages requests asynchronously at a 50% cost reduction, and it accepts requests of up to 256 MB, against 32 MB for Messages. Streaming delivers one response bit by bit over an open connection. Batching hands over many requests and collects the results later.

Whichever you use, your client runs inside limits. Organisations are placed on usage tiers automatically. Each tier has a spend limit (maximum monthly cost) and rate limits measured in requests per minute (RPM) and tokens per minute (TPM). That is another reason the Token Counting endpoint is useful before a large submission.

List endpoints follow standard REST pagination. You set limit for the page size, pass an opaque page cursor, and read next_page from each response until it comes back null. In Python and TypeScript you can simply iterate over the list result and the SDK follows next_page for you. That auto-pagination only goes forward; to go back, you read prev_page yourself, and only GET /v1/sessions returns it.

Sources1

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Each streamed tool_use delta contains a complete input object that you can parse on arrival.Why is that wrong?

   The deltas are fragments of a JSON string. You collect them and parse once content_block_stop arrives; only the final tool_use.input is an object.

   Covered in Streaming: asynchronous delivery over server-sent events

2. 2.Once a streaming request returns HTTP 200, the stream can't fail, so error handling only needs to check status codes.Why is that wrong?

   Errors such as overloaded_error can arrive as an error event inside a stream that has already started, so the stream consumer has to handle them.

   Covered in Streaming: asynchronous delivery over server-sent events

3. 3.When you use an official SDK, you still have to set the anthropic-version and content-type headers on every request yourself.Why is that wrong?

   The SDKs send the authentication, version and content-type headers automatically. The one header you may still have to pass is anthropic-workspace-id, when your key needs it.

   Covered in Headers, JSON bodies and what the SDK does for you