Calling the Claude API over REST: endpoints, headers and SDKs

1.Endpoints under one base URL

Every Claude API feature sits at a path under https://api.anthropic.com, and each path is named after what it does. Most of your traffic goes to POST /v1/messages. Other jobs have their own endpoints: counting tokens before you send a prompt, submitting a large asynchronous batch, listing the models you can call, or uploading a file once so later requests can refer to it. In a raw integration the URL and the HTTP method pick the operation, and the JSON body carries the parameters.

The Agents, Sessions and Environments APIs, which power Claude Managed Agents, are in beta and sit alongside these. List endpoints such as GET /v1/models return results in pages. You pass a limit and a page cursor, and each response carries a data array plus a next_page cursor that is null once you reach the end.

Sources1

2.The headers a raw HTTP call must carry

Without the right headers, a request with a valid body is still rejected. A direct integration, such as a curl script, a language with no official SDK, or an HTTP client you wrote yourself, has to send three things on every call. First, a credential, normally your Console API key in x-api-key. Second, anthropic-version with a dated value such as 2023-06-01. Third, content-type: application/json. Leave out anthropic-version and the request fails even though the key is fine. That header pins the API behaviour your code was written against, as explained in [API versions and feature classifications (beta vs GA)](lesson:2.2).

You can send the credential as Authorization: Bearer <token> instead of x-api-key. The Bearer form is also how short-lived Workload Identity Federation tokens are sent, while x-api-key remains supported as the legacy fallback. Exam scenarios still use the classic set: x-api-key, anthropic-version and content-type.

Moving a raw call into an SDK turns those headers from per-request code into client configuration. You hand the credential to the client once, delete the three header lines from every call site, and keep only anthropic-workspace-id when your key spans several workspaces. A migrated script that still sets anthropic-version by hand is carrying a line the client already owns.

Sources1

3.What the client SDKs add on top of REST

The official SDKs make the same REST calls as a raw integration and handle the repetitive parts. Anthropic publishes client SDKs for Python, TypeScript, C#, Go, Java, PHP and Ruby. Each one does the following:

- sends the authentication, anthropic-version and content-type headers automatically - gives you typed request and response objects instead of raw dictionaries - retries transient failures with built-in logic and raises typed exceptions - supports streaming - manages request timeouts and connections

Some defaults matter in practice. The Python client reads ANTHROPIC_API_KEY from the environment if you don't pass a key, and it has both sync (Anthropic) and async (AsyncAnthropic) clients. The TypeScript SDK runs on Node.js, Deno, Bun and edge runtimes, but it refuses to run in a web browser unless you set dangerouslyAllowBrowser. That default protects your secret key from being shipped to end users.

Each SDK method is a thin wrapper over one endpoint, so what you know about the REST surface carries over directly. client.messages.create is POST /v1/messages, client.messages.batches.create is POST /v1/messages/batches, and token counting is a method on the same messages object that maps to POST /v1/messages/count_tokens. The parameters keep their REST names, so a JSON body from a curl script translates almost field for field into keyword arguments.

count = client.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": "Hello, world"}],
)
print(count.input_tokens)  # 10

Retries and pagination are the two chores an SDK takes off your hands, and each is a setting to tune rather than code to write. The client retries connection errors, rate limits and 5xx responses twice by default, with exponential backoff, and it honors a retry-after header when the API sends one. max_retries on the client changes or disables that. A hand-written retry loop around an SDK call multiplies attempts with the built-in ones, so set max_retries to match whichever layer you want in charge.

For list endpoints, the SDK's auto-paginating iterator follows next_page for you, so a for loop walks every result without you touching a cursor. It only moves forward. Going back a page is the case where you read prev_page from the response and pass it back as page yourself.

import os
from anthropic import Anthropic

client = Anthropic(
    # This is the default and can be omitted
    api_key=os.environ.get(" ? "),
)

Sources12345

4.The response side of the contract: request IDs, errors and size limits

The HTTP contract also covers what comes back. Every response carries a request-id header with a value like req_018EeWyXxfu5pfWkrYcMdjWG, and that is the identifier support will ask for. Responses also report which organization and workspace the credential resolved to, in anthropic-organization-id and anthropic-workspace-id. The Python and TypeScript SDKs expose the ID as _request_id on the response object. To read other headers, use with_raw_response.

Failures come back as JSON in a single, fixed shape. The top-level type is error, and the error object holds a machine-readable type and a human-readable message. The same request ID is repeated in the body as request_id, so a logged error body is enough to trace the call. Which status codes are worth retrying is covered in [API error types and recovery](lesson:4.1). On this page, the point is that every failure has this shape, and that the SDKs turn it into typed exceptions such as anthropic.NotFoundError rather than handing you raw JSON.

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Request bodies have a size limit that depends on the endpoint. Messages and Token Counting accept up to 32 MB, Message Batches up to 256 MB and the Files API up to 500 MB. A request over its limit fails with 413 request_too_large before it reaches the API servers. If an application embeds large documents directly in a Messages request, it can hit this limit, which is a reason to upload those documents through the Files API instead.

Sources5

Exam traps

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

1. 1.A raw HTTP call only needs an API key and a JSON content type, and the API version is implied by the model.Why is that wrong?

   anthropic-version is required on every request. The SDKs hide this because they add it automatically, along with the authentication and content-type headers.

   Covered in The headers a raw HTTP call must carry

2. 2.Once you use an SDK, no header is your responsibility any more.Why is that wrong?

   The SDK sends the authentication, version and content-type headers, but anthropic-workspace-id depends on your key, so you pass it yourself when the key needs it.

   Covered in What the client SDKs add on top of REST

3. 3.Error responses differ by endpoint, so clients have to string-match the message to tell failures apart.Why is that wrong?

   Every error uses the same JSON shape with a typed error object. The SDKs raise typed exceptions, which you should catch instead of matching message strings.

   Covered in The response side of the contract: request IDs, errors and size limits