Messages API fundamentals

## The shape of the request Every call to Claude goes to one endpoint, `POST https://api.anthropic.com/v1/messages`, with the headers `x-api-key`, `anthropic-version: 2023-06-01` and `content-type: application/json`. The JSON body has three required fields — `model`, `max_tokens`, `messages` — and a set of optional top-level fields. **`system` is one of those top-level fields.** It is not a role, not a header, and not a special content block. ``` { "model": "...", "max_tokens": 1024, "system": "You are a terse SQL assistant.", "messages": [{"role": "user", "content": "count the orders table"}] } ``` ## Why it is not a message role The `messages` array models a dialogue: it alternates between `user` and `assistant` turns and represents things that were *said*. The system prompt is not a turn — it is operator configuration that applies to the whole exchange. Anthropic made that distinction structural rather than conventional. The practical consequences are worth knowing: - You cannot accidentally lose the system prompt by trimming the front of the history. Truncating old turns for context reasons touches `messages` only; `system` is untouched. - There is exactly one system prompt per request, so there is no ambiguity about which of several system messages wins. - Because the server renders `tools` → `system` → `messages` when building the prompt, a system prompt that never changes sits in a stable prefix position, which is what makes it reusable across requests. ## String or content blocks `system` accepts two forms. The simple form is a plain string. The structured form is an array of text content blocks: ``` "system": [ {"type": "text", "text": "You are a terse SQL assistant."}, {"type": "text", "text": "<50KB of schema documentation>"} ] ``` The array form exists so you can attach per-block metadata — most commonly a cache breakpoint on the last stable block — and so you can compose the prompt from independently-managed pieces. Only text blocks are valid here; images and documents belong in a user message's content. ## Porting from an OpenAI-shaped API In OpenAI-shaped chat APIs the system prompt is the first element of the messages list. Translating such code to Claude is not a field rename: you lift that entry out of the array entirely and assign its text to the top-level `system` parameter. If you leave it in the array as `{"role": "system", ...}`, the classic result is a `400 invalid_request_error` complaining about roles — historically the array accepted only `user` and `assistant`. Note one 2026 refinement: some current Claude models (the Opus 5 / Opus 4.8 class) additionally accept a mid-conversation `{"role": "system", "content": ...}` entry *inside* `messages`, with placement rules, as a way to inject an operator instruction later in a long conversation without disturbing the cached prefix. That is an addition for mid-conversation steering, not a change to where the primary system prompt goes — it still belongs in the top-level parameter, and support is model-dependent, so do not write it as the default. ## What belongs in it Role, tone, output-format rules, domain constraints, and any long reference material that is constant across requests. What does not belong: the user's actual question (that is a `user` message), and per-request volatile data such as a timestamp or a request id, which is better placed after the stable material so it does not destabilise the prefix. ## Failure modes to recognise - Sending `system` as a header or as `messages[0]` — rejected or ignored, and the model behaves as though it has no instructions. - Sending `system` as an array containing message objects (`{"role": ..., "content": ...}`) instead of text blocks — a validation error; the array form takes content blocks. - Rebuilding the system string on every request with an interpolated clock or UUID — it still works, but you have made a constant prefix volatile for no benefit. - Assuming the system prompt is free. It is input, it is re-sent on every request, and it is counted in the request's input token usage like everything else.