Mastering the Claude Messages API: A Practical Guide to Conversations and Control

When building applications with Claude AI, understanding how to effectively work with the Messages API is fundamental. Unlike some conversational AI systems that maintain state automatically, Claude's API follows a stateless design pattern that gives developers fine-grained control over conversations while requiring explicit management of dialogue history.

This guide walks through practical patterns for working with the Messages API, from basic requests to advanced techniques like response pre-filling and multi-turn conversations.

Understanding the Stateless Architecture

The Claude Messages API is stateless, meaning it doesn't remember previous interactions unless you explicitly provide them. Every API call must include the complete conversation history. This design offers several advantages:

• Complete control over what context Claude receives
• Flexibility to modify or filter conversation history
• Consistency across different sessions and users
• Transparency in what information Claude is using

While this requires more management from your application, it provides greater reliability and predictability in Claude's responses.

Basic API Request Structure

Let's start with the fundamental building block: a single message exchange. Here's a basic Python example using the Anthropic SDK:

import anthropic
Initialize the client
client = anthropic.Anthropic(
    api_key="your-api-key-here"
)
Send a simple message
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude"
        }
    ]
)
print(message.content[0].text)

Response structure:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8
  }
}

Key parameters to note:

• model: Specifies which Claude model to use
• max_tokens: Maximum number of tokens Claude can generate in response
• messages: The conversation history array
• role: Either "user" or "assistant"

Building Multi-Turn Conversations

Since the API is stateless, you need to maintain and send the entire conversation history with each request. Here's how to build a multi-turn dialogue:

# Conversation history management
conversation_history = [
    {
        "role": "user",
        "content": "Hello, Claude"
    },
    {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
    }
]
User asks a follow-up question
conversation_history.append({
    "role": "user",
    "content": "Can you explain what large language models are?"
})
Send the updated conversation
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=500,
    messages=conversation_history
)
Add Claude's response to history
conversation_history.append({
    "role": "assistant",
    "content": response.content[0].text
})
print(f"Claude's response: {response.content[0].text}")
print(f"Total tokens used: {response.usage.input_tokens} input, {response.usage.output_tokens} output")

Managing Conversation Length

As conversations grow, you'll need strategies to manage token usage:

• Truncation: Keep only the most recent messages
• Summarization: Periodically summarize older parts of the conversation
• Context window awareness: Monitor token counts and adjust accordingly

Here's a simple truncation strategy:

def manage_conversation_history(history, max_messages=10):
    """Keep only the most recent messages"""
    if len(history) > max_messages  2:  # 2 because each turn has user+assistant
        # Keep system message if present, then most recent messages
        kept_history = []
        if history[0].get("role") == "system":
            kept_history.append(history[0])
            history = history[1:]
        
        # Keep most recent messages
        kept_history.extend(history[-(max_messages*2):])
        return kept_history
    return history

Advanced Technique: Response Pre-filling

One powerful feature of the Messages API is the ability to pre-fill part of Claude's response. This technique shapes Claude's output by providing the beginning of what you want it to say.

Use case example: Multiple choice questions

# Using pre-fill to get a specific answer format
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1,  # We only want the letter
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"
        },
        {
            "role": "assistant",
            "content": "The answer is ("  # Pre-filling the start of Claude's response
        }
    ]
)
print(f"Claude's answer: {response.content[0].text}")
Output: "C"

Important limitations:

• Prefilling is not supported on Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6
• Requests using prefill with these models return a 400 error
• For these models, use structured outputs or system prompt instructions instead

Practical Applications of Pre-filling

• Structured responses: Force Claude to respond in JSON, XML, or other formats
• Code completion: Start a code block and let Claude complete it
• Form letters: Begin a standardized response template
• Creative writing: Start a story in a particular style or voice

# Example: Structured JSON response
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=200,
    messages=[
        {
            "role": "user",
            "content": "Extract the name, age, and city from: John Doe is 30 years old and lives in New York."
        },
        {
            "role": "assistant",
            "content": "{"  # Pre-fill with opening brace for JSON
        }
    ]
)
print(f"Extracted data: {response.content[0].text}")

Working with Different Content Types

The Messages API supports various content types beyond plain text. Here's how to structure different content formats:

# Mixed content example
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Please analyze this data:"
                },
                {
                    "type": "text",
                    "text": "Sales: $10,000\nExpenses: $4,000\nProfit: $6,000"
                }
            ]
        }
    ]
)

Error Handling and Best Practices

Handling Stop Reasons

Claude's responses include a stop_reason field that tells you why generation stopped:

• end_turn: Claude naturally finished its response
• max_tokens: Hit the token limit
• stop_sequence: Encountered a specified stop sequence
• tool_use: Stopped to use a tool

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=100,
    messages=[{"role": "user", "content": "Tell me a story"}]
)
if response.stop_reason == "max_tokens":
    print("Response was truncated due to token limit")
elif response.stop_reason == "end_turn":
    print("Claude completed its response naturally")

Token Management

Always monitor token usage to avoid unexpected costs and ensure responses fit within context windows:

# Track token usage
total_input_tokens = 0
total_output_tokens = 0
for turn in conversation_history:
    # Estimate tokens (for precise counting, use Anthropic's tokenizer)
    total_input_tokens += len(str(turn["content"])) // 4
print(f"Estimated context tokens: {total_input_tokens}")
print(f"Total output tokens used: {total_output_tokens}")

Real-World Implementation Pattern

Here's a complete pattern for a conversational application:

class ClaudeConversation:
    def __init__(self, api_key, model="claude-3-5-sonnet-20241022"):
        self.client = anthropic.Anthropic(api_key=api_key)
        self.model = model
        self.conversation = []
        
    def add_message(self, role, content):
        self.conversation.append({
            "role": role,
            "content": content
        })
        
    def get_response(self, max_tokens=1024, temperature=0.7):
        """Get Claude's response to the current conversation"""
        response = self.client.messages.create(
            model=self.model,
            max_tokens=max_tokens,
            temperature=temperature,
            messages=self.conversation
        )
        
        # Add Claude's response to conversation
        self.add_message("assistant", response.content[0].text)
        
        return {
            "text": response.content[0].text,
            "tokens": response.usage,
            "stop_reason": response.stop_reason
        }
    
    def trim_conversation(self, max_tokens=4000):
        """Trim conversation if it's getting too long"""
        # Simple implementation - keep only last 5 exchanges
        if len(self.conversation) > 10:  # 5 user + 5 assistant messages
            self.conversation = self.conversation[-10:]
Usage example
convo = ClaudeConversation(api_key="your-key")
convo.add_message("user", "Hello Claude!")
response = convo.get_response()
print(response["text"])

Key Takeaways

• Stateless by design: The Messages API requires you to send the complete conversation history with each request, giving you full control over context
• Pre-filling is powerful but limited: You can shape Claude's responses by providing the beginning of its answer, but this feature isn't available on all model versions
• Conversation management is essential: Implement strategies to handle long conversations through truncation, summarization, or context window management
• Monitor token usage: Keep track of input and output tokens to manage costs and ensure responses fit within model limits
• Handle stop reasons appropriately: Different stop reasons (end_turn, max_tokens, etc.) require different handling in your application logic