Anthropic Messages Array Builder

Anthropic messages array builder

The Anthropic Messages API has a specific shape: a top-level system string and a messages array of strictly alternating user and assistant turns that must begin with the user. Hand-writing that JSON is error-prone and the API returns opaque errors when the structure is wrong. This visual builder lets you add turns, see structural problems immediately, and export a clean request body.

How it works

You add turns and type content for each; the system prompt lives in its own field to match Anthropic’s format. As you edit, the builder validates the array live — it confirms the first turn is user and that roles alternate, surfacing the exact errors the API would otherwise return. When the structure is valid, it serialises a request body with the system field (when filled) and the messages array, ready to copy. No request is ever sent; you supply your own key when you call the API.

The exact request shape

The Messages API expects this JSON structure:

{
  "model": "claude-opus-4-5",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [
    { "role": "user", "content": "Hello, can you help me?" },
    { "role": "assistant", "content": "Of course! What do you need?" },
    { "role": "user", "content": "Explain exponential backoff." }
  ]
}

Key rules the API enforces:

• The messages array must not be empty.
• The first message must have "role": "user".
• Roles must strictly alternate: user → assistant → user → assistant.
• Two consecutive messages with the same role will return a 400 error.
• The system field is a top-level string, not a message with "role": "system" — that pattern works in OpenAI’s API but is rejected by Anthropic’s.

Prefilling the assistant’s reply

Ending the messages array on an assistant turn is a valid and useful technique called assistant prefill. Claude will continue generating from exactly that text rather than starting fresh. For example:

"messages": [
  { "role": "user", "content": "List three causes in JSON." },
  { "role": "assistant", "content": "[" }
]

Claude will start its output from [, effectively forcing a JSON array response without additional prompting. Use this for: locking an output format, steering toward a specific starting word, or skipping preamble in a structured generation task.

Tips for getting clean results

• Start with the user — the builder flags a leading assistant turn before you waste an API call.
• Keep system instructions in the system field — do not add a "role": "system" message; Anthropic ignores it and expects the top-level field.
• Copy and curl — the exported body drops straight into a curl call with -d @body.json or your SDK’s request method for a quick test.
• Merge consecutive user turns if your logic produced two in a row rather than splitting them across alternating turns — the builder shows exactly where the structure breaks.