The Claude API for builders
- 01The request, a single point of entry6 min
Every interaction with Claude goes through a single HTTP entry point, the POST /v1/messages request, which receives an array of turns and always returns the same response structure.
- 02Roles that hold, not a prefill that breaks7 min
Prefilling the assistant turn, a practice that used to start Claude's response in its place, is now rejected with a 400 error on current models; a stable system instruction or a constrained output replace it.
- 03Tools: Claude proposes, the code decides7 min
A tool is declared with a schema named input_schema; Claude never executes it itself, it returns a usage request that the code executes before returning the result so the conversation can continue.
- 04Receiving the response as it streams6 min
Streaming mode keeps a single HTTP connection open and delivers text in fragments as it is generated, and the cumulative token count is read in the last message_delta event received, never in the final message_stop event.
- 05Two cost levers: cached memory and batch processing8 min
A request prefix marked as reusable costs a reduced fraction of the normal price when read back from the cache, and a set of non-urgent requests processed in a batch costs less than immediate processing, two discounts that stack with each other and with the other pricing modifiers.
- 06Counting before sending: the context window6 min
A dedicated counting endpoint returns the number of tokens in a request before it is sent, and the context window to compare against this figure is no longer one shared value across a whole model range, it now varies sharply from one family to another.
- 07Choosing a model, switching models, and handling a refusal9 min
The choice of a model is a trade-off between quality, speed and cost that gets revisited with every new generation, and a refusal returned by a safety classifier is handled as a normal case of the protocol, not as a failure.