Messages

Overview

Every request to the Claude API is built around the messages array. This is the core data structure that carries the conversation — who said what, in what order, and what type of content was exchanged. Understanding the messages array is the foundation of everything else in this reference.

Structure

The messages array is a list of objects. Each object represents one turn in the conversation and has two required fields:

Field	Type	Description
`role`	string	Who is speaking. Either `user` or `assistant`.
`content`	string or array	What was said. Can be plain text or a structured content block.

A basic messages array looks like this:

"messages": [
  {
    "role": "user",
    "content": "What is a REST API?"
  }
]

Roles

The Claude API uses two roles inside the messages array:

Role	Who it represents
`user`	The person or system sending input to Claude
`assistant`	Claude’s response

The system role does not go inside the messages array. System instructions are passed as a separate top-level system field in the request body. See the System Prompts guide for details.

Multi-turn Conversations

The Claude API is stateless — Claude has no memory between requests. Every time you send a request, Claude only knows what you include in that request. To maintain context across a conversation, your application must pass the full conversation history with every request:

"messages": [
  {
    "role": "user",
    "content": "My name is Chisaneme and I am a technical writer."
  },
  {
    "role": "assistant",
    "content": "Nice to meet you, Chisaneme! How can I help you today?"
  },
  {
    "role": "user",
    "content": "What is my name and what do I do?"
  }
]

Claude reads the entire array on every request and responds based on the full history you provide.

This is how every LLM API works…context is not stored server-side. Your application is responsible for maintaining and passing conversation history.

Alternating Roles

Messages must follow a strict alternating pattern: user → assistant → user → assistant → user The array must always:

Start with a user message
Alternate between user and assistant roles

The API does not always throw an error for consecutive messages of the same role — but the behavior is unpredictable. In testing, two consecutive user messages caused Claude to answer only the second message and ignore the first, silently dropping context. Always maintain the alternating pattern for reliable behavior.

Content Types

The content field accepts two formats:

Plain Text

The simplest format — a string directly:

{
  "role": "user",
  "content": "What is a webhook?"
}

Structured Content Blocks

An array of typed content objects. Used for tool results, images, and multi-part messages:

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What is a webhook?"
    }
  ]
}

For most use cases, plain text content is sufficient. Structured content blocks are required when working with tool use or sending images.

Token Accumulation

Every message in the history consumes input tokens. As a conversation grows longer, the input token count increases with every request — because you are sending the full history each time.

Turn 1: 17 input tokens
Turn 2: 45 input tokens (history + new message)
Turn 3: 89 input tokens (longer history + new message)

For applications with long conversations, this has two implications:

Cost — input tokens are billed on every request
Context limits — the total conversation history must fit within the model’s context window

For long-running conversations, consider summarizing older messages into a single context block rather than passing the full raw history. This keeps token counts manageable without losing important context.

Context Window

The context window is the maximum number of tokens a model can process in a single request — including both the input (your messages) and the output (Claude’s response).

Model	Context Window
`claude-sonnet-4-6`	200,000 tokens
`claude-opus-4-6`	200,000 tokens
`claude-haiku-4-5`	200,000 tokens

200,000 tokens is approximately 150,000 words, enough for several novels worth of conversation history. For most applications this limit is rarely reached, but it is worth planning for in long-running or document-heavy use cases.

What Happens When the Limit Is Reached

If your messages array exceeds the context window, the API returns an error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "prompt is too long: 201000 tokens > 200000 maximum"
  }
}

Your application should handle this gracefully — either by summarizing history, truncating older messages, or alerting the user.

Next Steps

Tokens

Understand how tokens are counted and how they affect cost

System Prompts

Learn how to set Claude’s behavior before the conversation starts

Tool Use

See how structured content blocks are used in tool use responses

API Reference

Full endpoint reference for the messages endpoint

Getting Started

Core Concepts

Guides

Overview

Structure

Roles

Multi-turn Conversations

Alternating Roles

Content Types

Plain Text

Structured Content Blocks

Token Accumulation

Context Window

What Happens When the Limit Is Reached

Next Steps

Tokens

System Prompts

Tool Use

API Reference

​Overview

​Structure

​Roles

​Multi-turn Conversations

​Alternating Roles

​Content Types

​Plain Text

​Structured Content Blocks

​Token Accumulation

​Context Window

​What Happens When the Limit Is Reached

​Next Steps

Tokens

System Prompts

Tool Use

API Reference

Overview

Structure

Roles

Multi-turn Conversations

Alternating Roles

Content Types

Plain Text

Structured Content Blocks

Token Accumulation

Context Window

What Happens When the Limit Is Reached

Next Steps