Claude HTTP API: How It Works and How to Call It

The Claude HTTP API is the REST interface Anthropic exposes so you can send prompts and receive completions over plain HTTPS, without an SDK. It uses standard HTTP verbs, JSON request/response bodies, and header-based authentication — the same shape as most modern REST APIs, which makes it easy to call from curl, JavaScript, Python, or any language with an HTTP client.

If you're looking for "claude http api," you probably want one of three things: how to make a raw HTTP request to Claude, what the request/response format looks like, or how to get an HTTP endpoint you can call from an app without setting up SDKs and key rotation yourself. This article covers all three, including a simpler path if you just want a stable HTTPS endpoint without managing Anthropic infrastructure directly.

How the Claude HTTP API is structured

Anthropic's Messages API is the core HTTP interface for Claude. It's a single POST endpoint that accepts a conversation (a list of messages) and returns a completion. The basic shape:

• Endpoint: POST /v1/messages
• Auth: an API key sent in a request header
• Body: JSON with model, messages, max_tokens, and optional parameters like system, temperature, tools, and stream
• Response: JSON containing the generated content, stop reason, and token usage

A minimal raw request looks like this:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain HTTP status codes in one paragraph."}
    ]
  }'

The response is JSON with a content array (text blocks, and tool-use blocks if you're using tools), a stop_reason, and a usage object with input/output token counts. There's no separate "chat" vs "completion" endpoint — messages, system prompts, tool definitions, and streaming flags all live in the same request body.

Headers and versioning

Two headers matter beyond auth: anthropic-version pins you to a specific API contract so future changes don't silently break your integration, and content-type: application/json is required on every POST. If you omit or mismatch the version header, you'll get a 400-level error rather than a fallback to a default version — so it's worth hardcoding it rather than guessing.

Streaming over HTTP

Claude's HTTP API supports streaming via server-sent events. Set "stream": true in the request body and the response becomes a stream of event:/data: lines instead of a single JSON blob — message_start, a sequence of content_block_delta events carrying incremental text, and a final message_stop. This is the same HTTP connection, just read incrementally rather than waiting for the full body. It's what powers the token-by-token feel in chat UIs, and it works with any HTTP client that can read a response stream (fetch's ReadableStream, Node's http module, curl's -N flag for unbuffered output).

Error handling basics

The HTTP API returns standard status codes: 401 for bad auth, 400 for malformed requests, 429 when you hit rate limits, and 5xx for upstream issues. Error bodies are JSON with a type and message field, which is enough to branch your retry logic — for example, only retrying on 429 and 5xx with exponential backoff, and failing fast on 400/401 since retrying won't fix a malformed request or bad key.

Calling it from JavaScript

Since it's plain HTTP, fetch works without any SDK:

const res = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ANTHROPIC_API_KEY,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-opus-4-20250514",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Summarize this changelog entry." }],
  }),
});

const data = await res.json();
console.log(data.content[0].text);

This is useful when you're on a runtime or platform where pulling in a full SDK is more overhead than it's worth — edge functions, serverless handlers with strict cold-start budgets, or non-JS/Python languages where an official SDK doesn't exist.

When a raw HTTP call isn't enough

Calling Claude's HTTP API directly is fine for a prototype, but production usage usually needs more: per-application API keys instead of one shared secret, usage tracking broken down by client or team member, rate limit handling that doesn't require you to build it yourself, and a way to give teammates access without sharing a single Anthropic key.

This is the gap SubToAPI fills. It sits in front of your existing Claude access and exposes it as a clean HTTPS API with its own scoped keys (sub_live_...), so each app or environment gets its own key instead of everyone sharing one secret. The request format mirrors what you already saw above — same JSON body shape, same streaming model — so switching over is mostly a base URL and header change:

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Explain HTTP status codes in one paragraph."}]
  }'

You get streaming, tool use, and usage metadata per key out of the box, plus a dashboard for team seats — useful once more than one person or one app needs to hit Claude. Solo plans start at €9/month, Team seats at €19, and Scale at €49/seat, all with a free trial at signup. Full request/response details are in the docs, with dedicated pages for messages, streaming, and tool use — or start with the quickstart if you want the fastest path from zero to a working call.

questions

Is Claude's HTTP API RESTful? Yes. It's a JSON-over-HTTPS API using standard methods and status codes, primarily a single POST /v1/messages endpoint for both completions and streaming.

Can I call Claude's HTTP API without an SDK? Yes. Any HTTP client — curl, fetch, Python's requests — can call it directly, since the SDKs are thin wrappers around the same HTTP requests shown above.

What's the difference between calling Claude directly and using SubToAPI? Calling Claude directly means managing a single Anthropic key yourself. SubToAPI gives you per-app keys, usage tracking, and team seats on top of the same request format — see pricing for plan details.