The Messages API: Format and Structure
Understand the messages format — system, user, assistant roles.
What You Will Learn
- Understand messages format.
- Use system, user, assistant roles.
- Build multi-turn conversations.
- Use prefill technique.
- Handle responses.
Why This Matters
The messages format is the core of the API. Understanding roles, multi-turn, and prefill unlocks most API capabilities.
Concept Explained
Messages API uses roles: system (optional, sets behavior), user (your input), assistant (Claude's response). Multi-turn conversations alternate user/assistant messages.
How It Works
POST to /v1/messages with messages array. Each message has role and content. System message is separate (top-level field).
Step-by-Step Tutorial
1. Basic message
Single user message: [{role: 'user', content: 'Hello!'}]2. System message
Top-level system field: system: 'You are a helpful assistant.'3. Multi-turn
Alternate user/assistant: [{user}, {assistant}, {user}, ...]4. Prefill technique
End with assistant message to prefill Claude's response.5. Handle response
Response has content (array), stop_reason, usage.Real-World Example
A developer built a multi-turn chatbot using the messages API. Each turn: append user message, call API, append assistant response. Conversations felt natural.
Example Prompts / Commands / Code
"""{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1000,
"messages": [
{"role": "user", "content": "Hello!"}
]
}
"""
"""{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1000,
"system": "You are a helpful assistant. Be concise.",
"messages": [
{"role": "user", "content": "Hello!"}
]
}
"""
"""{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1000,
"messages": [
{"role": "user", "content": "What's 2+2?"},
{"role": "assistant", "content": "4"},
{"role": "user", "content": "And 3+3?"}
]
}
"""
"""{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1000,
"messages": [
{"role": "user", "content": "List 3 colors."},
{"role": "assistant", "content": "1. Red\n2."}
]
}
# Claude continues from '2.' — useful for structured output
"""
Common Mistakes
- Putting system in messages array — should be top-level.
- Not alternating user/assistant in multi-turn.
- Forgetting max_tokens (required).
- Not handling stop_reason.
Best Practices
- System message is top-level, not in messages array.
- Alternate user/assistant for multi-turn.
- Always set max_tokens.
- Handle stop_reason (end_turn, max_tokens, stop_sequence).
- Use prefill for structured output.
Troubleshooting
| Problem | How to Fix |
|---|---|
| 400 Bad request | Check messages format. Verify role alternation. |
| Response truncated | Increase max_tokens. |
Practical Exercise
Your Turn
Make 3 API calls: (1) basic, (2) with system, (3) multi-turn. Verify each works.
Professional Challenge
Build a multi-turn chatbot using the messages API. Handle conversation history.
Key Takeaways
- Messages API uses roles: system, user, assistant.
- System is top-level, not in messages.
- Alternate user/assistant for multi-turn.
- Always set max_tokens.
- Use prefill for structured output.
Frequently Asked Questions
Can I have multiple system messages?
What's prefill?
Further Reading
Official References
SEO Metadata
SEO title: The Messages API: Format and Structure
Meta description: Understand the messages format — system, user, assistant roles.
Primary keyword: claude messages api
Secondary keywords: claude api messages, claude message format, claude conversation api
Search intent: Informational
URL slug: /claude-messages-api-format-structure
Categories: AI Tools, Claude
Tags: Claude, Intermediate, API, Messages, Format, IMCSEIAN, Tutorial, IMCSEIAN
Featured image concept: Messages API format with system, user, assistant roles.
Comments
Comments
Post a Comment