Claude API REST API Quickstart Example

If you want to send your first request to Claude's REST API and get a working response in under five minutes, here's the shortest path: get an API key, send a POST request to the messages endpoint with a model name and a message array, and parse the JSON response. That's the entire core loop — everything else (streaming, tools, system prompts) builds on top of it.

This guide walks through that loop with copy-pasteable curl and JavaScript examples, explains the required fields, and covers the mistakes that trip up most people on their first attempt — wrong auth headers, missing max_tokens, and confusing the chat-style message format with a single prompt string.

What You Need Before You Start

• An API key. This can be a direct Anthropic key, or an application key from a proxy layer like SubToAPI if you want usage metadata, team seats, or multiple app-scoped keys instead of one shared secret.
• A model name (e.g. a Claude 3-family or Claude 4-family identifier, depending on what's available to your account).
• An HTTP client — curl for testing, fetch or axios for actual integration.

No SDK is required. The REST API is plain JSON over HTTPS, which is why it's worth understanding the raw request/response shape even if you later wrap it in a library.

The Minimal Request

Every Claude REST API call to the messages endpoint needs four things: the endpoint URL, an auth header, a model, and a messages array. Here's the smallest version that works:

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-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain REST APIs in two sentences."}
    ]
  }'

Three details matter here:

1. max_tokens is required, not optional. Forgetting it is the single most common first-request error.
2. messages is an array of role/content objects, not a flat string. Even a one-off question needs the role: "user" wrapper.
3. The anthropic-version header is required when calling Anthropic directly — it pins you to a specific API contract so responses don't silently change shape.

The response is JSON with a content array (Claude can return multiple content blocks, including text and tool-use blocks), a stop_reason, and token usage counts under usage.

Same Request Through SubToAPI

If you're already using Claude through a subscription-based setup, or you want a single HTTPS endpoint with bearer-token auth, streaming, and per-key usage tracking instead of managing raw Anthropic credentials across environments, SubToAPI exposes the same request shape with a simpler auth header:

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain REST APIs in two sentences."}
    ]
  }'

The message format is identical — this matters because it means any code you write against the standard Claude messages schema works whether you point it at a raw key or an application key issued from your dashboard. Full field-by-field details are in the docs and messages reference.

JavaScript Example

For an actual app, you'll call this from server-side code, not curl. A minimal Node example:

async function askClaude(prompt) {
  const res = await fetch("https://api.subtoapi.app/v1/messages", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      model: "claude-sonnet-4-20250514",
      max_tokens: 1024,
      messages: [{ role: "user", content: prompt }],
    }),
  });

  const data = await res.json();
  return data.content[0].text;
}

Keep the API key server-side only. Never call this endpoint from browser JavaScript with your key embedded — that exposes it to anyone who opens dev tools.

Adding a System Prompt and Conversation History

A quickstart example is incomplete without showing multi-turn context, since that's how most real integrations use the API. The system field sets behavior instructions once, outside the message array; the messages array carries the actual back-and-forth:

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "system": "You are a concise technical assistant. Answer in plain text, no markdown.",
  "messages": [
    {"role": "user", "content": "What's a REST API?"},
    {"role": "assistant", "content": "An HTTP interface for CRUD-style operations using standard verbs and status codes."},
    {"role": "user", "content": "Give one weakness of that design."}
  ]
}

Claude has no server-side memory of previous calls — your application is responsible for storing and resending the conversation history on every request.

Streaming Responses

For chat UIs, waiting for the full response before showing anything feels slow. Add "stream": true to get incremental tokens via server-sent events instead of one blocking JSON blob:

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Write a haiku about APIs."}]
  }'

You'll need an SSE-aware client to consume this properly — the streaming guide covers parsing event types and handling partial JSON on the client side.

Calling Tools

Once the basic request/response loop is working, the next step for most real applications is giving Claude access to functions it can call — database lookups, calculators, internal APIs. You define a tools array with JSON schemas, and Claude responds with a tool_use content block instead of plain text when it decides to call one. Implementation details are in tool use docs, but the mental model is simple: Claude never executes anything itself — it tells you what it wants to call, you run it, and you send the result back in a follow-up message.

Getting Set Up Fast

If you're evaluating options rather than building against raw Anthropic credentials, sign up for a free trial, generate a sub_live_... key, and follow the quickstart — it walks through the exact request shown above with your own key pre-filled. Pricing for ongoing use starts at Solo for solo devs, with Team and Scale tiers for per-seat access; see pricing for details.

Questions

Do I need an SDK to use the Claude REST API? No. It's plain JSON over HTTPS, so curl, fetch, or any HTTP client works. SDKs just add convenience methods and typing on top of the same requests shown here.

Why does my first request fail with a missing field error? The most common cause is omitting max_tokens, which is required on every request, or sending content as a plain string instead of a messages array with role/content objects.

Can I use this quickstart example with a proxy API key instead of a direct Anthropic key? Yes — the request and response shape is the same; only the base URL and auth header change, as shown in the SubToAPI example above.