Home / The Claude API for builders

The request, a single point of entry

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.

The Claude API has only one point of entry: the POST /v1/messages request, called the Messages API. Every exchange, whether it fits in a single turn or strings together a long conversation, goes through this same entry point, with a body that carries a messages array and a chosen model. An ordinary HTTP client is enough: there is no other route to memorise, whatever model is called or whatever the request is about.

A required field, with no default value

The request body carries a field named exactly max_tokens, which sets the maximum number of tokens the model can generate before stopping. This field has no default value: it is required on every request, on the same footing as the model and the messages array. This field also drives the cost and duration of the generation, without forcing it: the model can very well stop before reaching this limit, as soon as it judges its response complete. One special case exists: sending max_tokens as 0 requests no generation at all, only pre-filling the prompt cache ahead of a following request.

// Minimal body of a request to the Messages API
{
  "model": "claude-sonnet-5",
  "max_tokens": 300,
  "messages": [
    { "role": "user", "content": "Résume ce texte en une phrase." }
  ]
}

A response always structured the same way

The response returned by the API always follows the same shape, whatever model is called. The content field carries an array of blocks, the model field confirms the model actually used, and the stop_reason field indicates why generation stopped: end_turn for a response completed naturally, max_tokens for a cutoff at the set limit, stop_sequence for a stop sequence encountered, and depending on the request's context, tool_use, refusal, pause_turn or model_context_window_exceeded. When a stop sequence triggered the cutoff, it is repeated in the stop_sequence field.

The usage field closes out the response with four counters: input_tokens, output_tokens, cache_creation_input_tokens and cache_read_input_tokens. These four numbers are enough to calculate the exact cost of an exchange without consulting any other source, and they come back on every request, even the simplest one. Reading input_tokens before sending the next turn also shows how much headroom remains in the ongoing conversation.

This same response structure comes back in declaring a tool, where the stop_reason field takes the value tool_use to signal a usage request rather than a completed response.