Build with Claude

Start here

What is a REST API, really?

An API ("Application Programming Interface") is just a way for your code to ask another computer to do something. A REST API does it over the web, using the same plumbing your browser already uses. Five ideas cover almost everything:

📤

Request & response

You send a request to a web address (an endpoint). The server does the work and sends back a response. With Claude: you send a message, Claude sends back a reply. That's the whole loop.

🔀

The method (verb)

Every request has a verb. GET means "read something," POST means "send data and make something happen." Talking to Claude is always a POST — you're sending a message for it to act on.

🏷️

Headers

Headers are metadata that ride along with the request — like the envelope around a letter. For Claude they carry your API key (who you are), the API version, and the fact that you're sending JSON.

{ }

JSON — the body

The actual content travels as JSON: a simple text format of "key": value pairs. You send JSON describing your message; Claude replies with JSON containing its answer. Every language can read and write it.

🚦

Status codes

The response comes with a number. 200 = success. 4xx (like 401, 429) = you need to fix something. 5xx = the server had a problem; retry. We list the ones you'll actually hit below.

🔑

Authentication

The server needs to know it's really you (and who to bill). You prove it with an API key — a long secret string — sent in a header. Treat it like a password: it never goes in your code or a public repo.

💡

That's the entire mental model. A Claude API call is one POST to one endpoint, with three headers and a small JSON body. Everything else — tools, streaming, vision — is just more fields in that same body.

Hands on

Your first Claude program, in three steps

Pick your language with the toggle on each step — the samples stay in sync. Copy, run, done.

Get an API key & store it safely

Create a key in the Claude Console, then put it in an environment variable — never in your code.

Sign in at console.anthropic.com → API keys, create a key (it starts with sk-ant-), and copy it. Then set it as an environment variable so your program can read it without the secret ever appearing in your source:

terminal · macOS / Linux

export ANTHROPIC_API_KEY="sk-ant-...your-key..."   # add to ~/.zshrc to persist

⚠️

Never paste your key into code, a webpage, or a git commit. A leaked key can run up your bill. Read it from the environment (the SDKs do this automatically), and rotate it in the Console immediately if it's ever exposed.

Send your first message

One POST to /v1/messages. This is the whole API — learn this and the rest is variations.

Language:

terminal · curl

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-8",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Hello, Claude. In one sentence, what are you?" }
    ]
  }'

No install needed — curl ships with macOS and Linux. This is the rawest form of the call; it shows exactly what every language sends under the hood.

terminal · install once

pip install anthropic

first_call.py

import anthropic

# Reads ANTHROPIC_API_KEY from the environment automatically.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude. In one sentence, what are you?"}
    ],
)

print(message.content[0].text)

The official SDK handles auth, JSON, retries and timeouts for you. Run it with python first_call.py.

terminal · install once

npm install @anthropic-ai/sdk

first-call.ts

import Anthropic from "@anthropic-ai/sdk";

// Reads ANTHROPIC_API_KEY from the environment automatically.
const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Hello, Claude. In one sentence, what are you?" },
  ],
});

const first = message.content[0];
if (first.type === "text") console.log(first.text);

Works with Node.js and TypeScript (plain JavaScript too — same SDK). Run with npx tsx first-call.ts.

What every part means

Part	What it is
`/v1/messages`	The one endpoint you talk to. `v1` is the API version path; `messages` is the "have a conversation" operation.
`x-api-key`	Your secret key — this is how Anthropic knows it's you and what to bill. (The SDKs read it from the environment so you never type it.)
`anthropic-version`	Pins the API's behavior to a known date so your code doesn't break when the API evolves. Always `2023-06-01`.
`model`	Which Claude to use. `claude-opus-4-8` is the most capable; see Models for cheaper/faster options.
`max_tokens`	The longest reply you'll allow, in tokens (≈¾ of a word each). A safety cap — set it comfortably above what you expect.
`messages`	The conversation, as a list. Each entry has a `role` (`"user"` or `"assistant"`) and its `content`. Your first message is always `user`.

Read the response

The reply is JSON. You mostly care about three fields.

response · JSON

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    { "type": "text", "text": "I'm Claude, an AI assistant made by Anthropic." }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 18, "output_tokens": 12 }
}

Field	What to do with it
`content`	A list of blocks. The text reply is `content[0].text`. (It's a list because a response can also contain tool calls or thinking — more on that later.)
`stop_reason`	Why Claude stopped. `"end_turn"` = finished normally ✅. `"max_tokens"` = ran out of room (raise `max_tokens`). `"tool_use"` = it wants to call a tool. Check this before trusting the output.
`usage`	Tokens in and out — this is what you're billed on. Handy for tracking cost (see pricing).

🎉

That's a complete Claude program. You sent a message and read the answer. Everything below makes it more useful — but you already know the core loop.

The everyday toolkit

Four concepts you'll use in almost every app

Samples here are in Python for readability — the shape is identical in every SDK.

System prompt · who Claude is

A top-level instruction that sets the role, tone and rules for the whole conversation. It's separate from the user messages and carries the most weight.

system.py

client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system="You are a terse expert. Answer in one sentence, no preamble.",
    messages=[{"role":"user", "content":"What is a REST API?"}],
)

Multi-turn · the API has no memory

Each call is independent — Claude remembers nothing between requests. To continue a conversation you resend the whole history every time, appending Claude's last reply.

conversation.py

messages = [
    {"role":"user",      "content":"My name is J."},
    {"role":"assistant", "content":"Nice to meet you, J!"},
    {"role":"user",      "content":"What's my name?"},
]
# Claude only knows "J" because the history is resent.

Streaming · tokens as they're written

Instead of waiting for the whole reply, receive it word-by-word — like watching it type. Use it for chat UIs and any long output (it also avoids timeouts).

stream.py

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role":"user","content":"Write a haiku about APIs."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Choosing a model · speed vs. smarts vs. cost

One string swaps the brain. Reach for Opus on hard reasoning, Sonnet for the everyday balance, Haiku when speed and price matter most.

models.py

model="claude-opus-4-8"     # most capable
model="claude-sonnet-4-6"   # balanced workhorse
model="claude-haiku-4-5"    # fastest & cheapest

Troubleshooting

When things go wrong

The status code tells you what happened. Here are the ones you'll actually meet, and how to fix each.

Code	Meaning	Retry?	What to do
400	Bad request	no	Something in your JSON is wrong — a typo, a bad field, messages not starting with `user`. Read the `message` in the error; it usually names the field.
401	Not authenticated	no	Your API key is missing, wrong, or revoked. Check `ANTHROPIC_API_KEY` is set and current.
403	Forbidden	no	The key is valid but lacks access to this model or feature. Check your Console permissions/plan.
404	Not found	no	Almost always a misspelled model ID. Use an exact ID from the table below — e.g. `claude-opus-4-8`, not `claude-opus-4.8`.
429	Rate limited	yes	You're sending too fast. Wait and retry — the `retry-after` header says how long. The SDKs back off and retry automatically.
529	Overloaded	yes	Anthropic's side is briefly busy. Retry with a short, increasing delay (the SDKs handle this for you).

🛟

The official SDKs already retry 429 and 5xx errors with sensible backoff. That's one more reason to use the SDK rather than raw HTTP once you're past your first request.

Model	Model ID	Context	Max output	Input $/M	Output $/M	Best for
Claude Opus 4.8 default	claude-opus-4-8	1M	128K	$5.00	$25.00	The hardest reasoning & long agentic work
Claude Sonnet 4.6	claude-sonnet-4-6	1M	64K	$3.00	$15.00	The everyday balance of speed & smarts
Claude Haiku 4.5	claude-haiku-4-5	200K	64K	$1.00	$5.00	Fast, cheap, high-volume simple tasks
Claude Opus 4.7	claude-opus-4-7	1M	128K	$5.00	$25.00	Previous-gen Opus; pin for reproducibility
Claude Fable 5	claude-fable-5	1M	128K	$10.00	$50.00	The most demanding, longest-horizon work

Hints from the field

Gotchas worth knowing on day one

The small things that trip up everyone the first time.

✓ Keep your key in the environment

Read it from ANTHROPIC_API_KEY (the SDKs do this for you). A key in source code, a webpage, or a public repo is a compromised key — rotate it instantly if it leaks.

✓ The API has no memory

Every request is independent. To continue a conversation, resend the full messages history each time. Forgetting this is the #1 "why doesn't it remember?" question.

✓ Set `max_tokens` generously

Too low and the reply is cut off mid-sentence (stop_reason: "max_tokens"). 1024 is fine for a sentence; use 4096+ for real answers and stream anything large.

✓ Parse JSON — don't regex it

Read fields like content[0].text from the parsed object. Never pattern-match the raw response text; escaping and formatting will eventually break it.

✓ Check `stop_reason` before trusting output

end_turn means done; max_tokens means truncated; tool_use means it wants a tool; refusal means it declined. Branch on it instead of assuming success.

✓ Prefer the SDK over raw HTTP

Past your first curl, use anthropic (Python) or @anthropic-ai/sdk (TS/JS). You get retries, streaming helpers, and typed responses for free.

📚

Studying for the CCA-F exam? These same API fundamentals — stop_reason, the agentic loop, tool design, structured output — are exactly what Domains 1, 3 and 4 test. Drill them in the practice quiz and ask the AI coach anything.

What is a REST API, really?

Request & response

The method (verb)

Headers

JSON — the body

Status codes

Authentication

Your first Claude program, in three steps

Get an API key & store it safely

Send your first message

What every part means

Read the response

Four concepts you'll use in almost every app

System prompt · who Claude is

Multi-turn · the API has no memory

Streaming · tokens as they're written

Choosing a model · speed vs. smarts vs. cost

Go further

Tool use

Structured output

Prompt caching

Vision & PDFs

Streaming

Batch processing

When things go wrong

Current models & pricing

Gotchas worth knowing on day one

✓ Keep your key in the environment

✓ The API has no memory

✓ Set `max_tokens` generously

✓ Parse JSON — don't regex it

✓ Check `stop_reason` before trusting output

✓ Prefer the SDK over raw HTTP

Build with Claude

What is a REST API, really?

Request & response

The method (verb)

Headers

JSON — the body

Status codes

Authentication

Your first Claude program, in three steps

Get an API key & store it safely

Send your first message

What every part means

Read the response

Four concepts you'll use in almost every app

System prompt · who Claude is

Multi-turn · the API has no memory

Streaming · tokens as they're written

Choosing a model · speed vs. smarts vs. cost

Go further

Tool use

Structured output

Prompt caching

Vision & PDFs

Streaming

Batch processing

When things go wrong

Current models & pricing

Gotchas worth knowing on day one

✓ Keep your key in the environment

✓ The API has no memory

✓ Set max_tokens generously

✓ Parse JSON — don't regex it

✓ Check stop_reason before trusting output

✓ Prefer the SDK over raw HTTP

✓ Set `max_tokens` generously

✓ Check `stop_reason` before trusting output