Claude API Fundamentals
Shape of a request
A Claude request is a JSON object with three essential parts: a model identifier, a max_tokens cap, and a messages array. Optionally you add a top-level system string, a tools list, temperature/top_p, stop_sequences, and stream: true. The most common exam trap lives here: the system prompt is a top-level parameter, not a message with role: "system". Messages alternate user and assistant and must begin with user; consecutive same-role turns are rejected, so merge them yourself.
Content blocks and stop reasons
content is a list of blocks, not a bare string - text blocks, tool_use, tool_result, images, documents. A response with stop_reason: "tool_use" is not an error; it is a request for your code to act. Other stop reasons (end_turn, max_tokens, stop_sequence, pause_turn) each imply different follow-up handling. Output truncated at max_tokens may be a half-finished JSON blob - always check before parsing.
Tokens and usage
Tokens are subword units; there is no exact characters-per-token law, only rough estimates, so never hard-code budget math from character counts. The usage object reports input_tokens, output_tokens, and cache fields; output tokens dominate latency because generation is sequential.
Worked example
You want a JSON-only reply. Set max_tokens generously (truncation breaks parsers), put format instructions and the schema in system, include one valid example, and prefill the assistant turn with an opening brace to suppress preamble. Then assert stop_reason == "end_turn" before parsing - if it is max_tokens, retry with a larger cap rather than patching broken JSON.