How must the messages array be structured in an Anthropic Messages API request?

## The array `messages` is one of the three required fields of `POST /v1/messages`. It is an ordered list of turns: ``` "messages": [ {"role": "user", "content": "What is a B-tree?"}, {"role": "assistant", "content": "A balanced tree structure..."}, {"role": "user", "content": "How does it differ from a B+ tree?"} ] ``` Rules that trip people up: - **Non-empty.** An empty array is a validation error. - **Starts with `user`.** The conversation begins with something for the model to respond to. - **Alternates.** Consecutive turns of the same role are rejected; the canonical error text is `messages: roles must alternate between "user" and "assistant"`, returned as `400 invalid_request_error`. - **Only conversational roles.** The operator instruction is not a turn — it belongs in the top-level `system` parameter. - **Order is meaning.** The array *is* the history; there is no server-side ordering or deduplication. ## Content: string or blocks Every turn's `content` may be a plain string or an array of content blocks. These are equivalent: ``` {"role": "user", "content": "Hello"} {"role": "user", "content": [{"type": "text", "text": "Hello"}]} ``` The block array is the real model; the string is shorthand for a single `text` block. Blocks are typed and heterogeneous — a single user turn can mix text with an image, a document, or the results of tools the model asked for. The response side is always blocks: `content` on a response is an array even when it holds one piece of text, which is why `content[0].text` (rather than a bare `content` string) is the idiom for reading an answer. The block design is what lets one endpoint carry text, vision, documents, reasoning and tool traffic without versioning the request shape each time a modality is added. ## Statelessness is the big one There is no session, thread or conversation id on this endpoint. Each request is self-contained: the server has no memory of the previous call. Multi-turn chat is implemented entirely by the client resending the accumulated array each time. The loop is: 1. Append the user's new message to your local array. 2. POST the whole array. 3. Append the assistant's response to your local array. 4. Repeat. Two consequences follow. First, **cost and latency grow with the conversation** — the whole history is re-read on every call, so a long chat pays for its own history repeatedly. Second, **you own truncation**: when the history approaches the model's context window, dropping or summarising old turns is your job, and doing it naively can break role alternation or orphan a tool block. ## Append the assistant's content, not its text The most common bug in real integrations: extracting the assistant's text with something like `response.content[0].text`, appending *that string* as the assistant turn, and discarding the rest of the array. If the response held anything besides that first text block, it is now gone from the history, and the next turn is missing state the model expected to still be there. The correct move is to append the response's `content` array as-is: ``` messages.append({"role": "assistant", "content": response.content}) ``` ## Trimming and summarising safely When you do have to shrink the history: - Keep the first turn a `user` turn after trimming, and keep alternation intact. - Never cut between a turn that references work and the turn that answers it — split pairs produce validation errors or a confused model. - Prefer summarising a prefix into a single `user` turn over deleting arbitrary middles, so the remaining array is still a coherent dialogue. ## Quick mental checklist A valid `messages` array: non-empty; first role `user`; roles alternate; every `content` is a string or a list of typed blocks; no operator instructions smuggled in as turns; the full history present because nothing is stored server-side.