Foundations

How to read the API docs

A doc link dropped on you cold is disorienting. But the reference has a predictable shape — once you know the map, you can answer almost any "how do I…?" yourself in 30 seconds. This page teaches the map, then walks a real question end to end so you're never lost in the docs again.

endpoint referencerequest vs response required vs optionalexamples errors

Explain like I'm 10

API docs are like the instruction booklet for a board game. Every booklet has the same sections in roughly the same order: what you need to start, the list of moves you can make, what each move does, and a few example turns. Once you know booklets are always laid out that way, you stop reading cover-to-cover and just flip to the section that answers your question.

The map: every API reference has these parts

The Claude API docs (and honestly most REST docs) are organized the same way. Learn these five parts and the fog lifts:

Section	Answers the question…	What to look for
Overview / Getting started	"How do I make my first call?"	install the SDK, set the API key, a copy-paste example. Start here once, then skip it.
Endpoint reference (e.g. Messages)	"What can I send, and what comes back?"	the request body params and the response fields — the two lists you'll consult forever.
Parameter details	"What exactly does `X` do? Is it required? What type?"	each param's type, required/optional, default, and allowed values.
Guides / capabilities	"How do I do tool use / streaming / caching?"	task-focused walkthroughs. Read the guide for the feature, not the whole site.
Errors	"I got a 4xx/5xx — what now?"	status codes + what each means (401 = key, 429 = rate limit, 400 = bad request).

Reading a parameter entry — the 4 things to check

When you look up any parameter, scan for exactly four things. Click through a real one:

look up this parameter

1. Type

2. Required?

3. Default

4. Constraints / notes

Worked example: "How do I make Claude stop at a certain word?"

Guess the section. It's about the request, so → Messages endpoint → request body.
Scan the param list for something stop-shaped. You find stop_sequences.
Read its 4 facts: type = array of strings, optional, no default, "Claude stops when it generates one of these."
Check the response side: when it triggers, stop_reason becomes "stop_sequence" — so you can detect it in code.
Copy the example, adapt, run. Done — without reading the whole site.

Why the doc links stopped making sense before: they were dropped without a question attached. Docs aren't meant to be read front-to-back — they're a lookup. Arrive with a specific question ("is system a message or a parameter?"), jump to the matching section, read the 4 facts, leave. From now on our curated links say which section and why — treat them as lookups, not homework.

Takeaways: every API reference has the same shape — overview, endpoint reference (request params + response fields), parameter details, feature guides, and errors. Don't read it cover-to-cover: arrive with a question, jump to the section, and for any parameter check its type, required?, default, constraints. That's how you answer your own "how do I…?" in 30 seconds.

Bookmark (as lookups, not reading): Messages API reference (the request/response tables) · Errors (status codes).