# Anthropic content blocks — request and response shapes

**Status:** `DOCUMENTED`; `text`, `image`, `document`, `tool_use`, `tool_result`, `thinking` `LIVE_VERIFIED` 2026-09-18 (Haiku 4.5). Beta blocks `BETA`.
**Sources:** https://platform.claude.com/docs/en/api/messages (Domain types) · https://platform.claude.com/docs/en/api/beta/messages · https://platform.claude.com/docs/en/build-with-claude/vision · https://platform.claude.com/docs/en/build-with-claude/pdf-support
**Machine-readable:** `generated/fragments/objects/anthropic-messages-objects.json` (`ContentBlock:*`), `generated/fragments/parameters/anthropic-messages.json` (`messages[].content[].*`)
**Last verified:** 2026-09-18

`messages[].content` is a string (shorthand for one `text` block) or an array of blocks. Every request block may carry `cache_control: {type: "ephemeral", ttl?: "5m"|"1h"}`. Response blocks come back in `Message.content[]` and must be replayed **verbatim** (thinking/redacted_thinking especially) in later turns.

## Request-side blocks (`ContentBlockParam`)

| `type` | Fields | Notes |
|---|---|---|
| `text` | `text` (min 1 char), `citations?: TextCitationParam[]`, `cache_control?` | also the shape of `system[]` and of `search_result.content[]` |
| `image` | `source`: `{type: base64, media_type: image/jpeg\|png\|gif\|webp, data}` \| `{type: url, url}` \| `{type: file, file_id}`; `transformations?: {oversized_image: downsize\|error}`; `cache_control?` | `downsize` (default) silently rescales; `error` → 400. count_tokens rejects `url`/`file` sources. *1×1 PNG = +5 tokens live* |
| `document` | `source`: `{type: base64, media_type: application/pdf, data}` \| `{type: text, media_type: text/plain, data}` \| `{type: content, content: string \| (text\|image)[]}` \| `{type: url, url}` \| `{type: file, file_id}`; `title?`, `context?`, `citations?: {enabled: bool}`, `cache_control?` | citations type depends on source: PDF → `page_location`, text → `char_location`, content → `content_block_location`. *text doc + citations.enabled = 562 tokens vs 11 (fixed citation overhead)* |
| `search_result` | `source` (string), `title`, `content: TextBlockParam[]`, `citations?: {enabled}`, `cache_control?` | your own RAG results; cited as `search_result_location` |
| `thinking` | `thinking`, `signature` | replay unmodified, in order — modified → 400 "`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified" |
| `redacted_thinking` | `data` (opaque) | replay unchanged |
| `tool_use` | `id` (toolu_…), `name`, `input` (object), `caller?`, `toolset_name?`, `cache_control?` | replayed assistant tool call |
| `tool_result` | `tool_use_id`, `content?: string \| (text\|image\|search_result\|document\|tool_reference\|browser_state)[]`, `is_error?`, `toolset_name?`, `cache_control?` | must immediately follow, one per `tool_use`, alone in the user message. *Missing → 400 "messages.2: `tool_use` ids were found without `tool_result` blocks immediately after: …"* |
| `server_tool_use` | `id` (srvtoolu_…), `name ∈ web_search\|web_fetch\|code_execution\|bash_code_execution\|text_editor_code_execution\|tool_search_tool_regex\|tool_search_tool_bm25` (+beta `advisor`), `input`, `caller?` | replayed server-tool call |
| `web_search_tool_result` | `tool_use_id`, `content: web_search_result[] {url, title, encrypted_content, page_age}` \| `{type: web_search_tool_result_error, error_code}` | error codes: `invalid_tool_input`, `unavailable`, `max_uses_exceeded`, `too_many_requests`, `query_too_long`, `request_too_large` |
| `web_fetch_tool_result` | `tool_use_id`, `content: {type: web_fetch_result, url, content: document, retrieved_at}` \| `{type: web_fetch_tool_result_error, error_code}` | error codes: `invalid_tool_input`, `url_too_long`, `url_not_allowed`, `url_not_in_prior_context`, `url_not_accessible`, `unsupported_content_type`, `too_many_requests`, `max_uses_exceeded`, `unavailable`, `content_too_large` |
| `code_execution_tool_result` | `tool_use_id`, `content: {type: code_execution_result, stdout, stderr, return_code, content: [{type: code_execution_output, file_id}]}` \| error `{error_code}` | codes: `invalid_tool_input`, `unavailable`, `too_many_requests`, `execution_time_exceeded` (encrypted variant exists for ZDR) |
| `bash_code_execution_tool_result` | `{type: bash_code_execution_result, stdout, stderr, return_code, content[]}` \| error | + `output_file_too_large` |
| `text_editor_code_execution_tool_result` | view `{content, file_type, num_lines, start_line, total_lines}` · create `{is_file_update}` · str_replace `{lines, new_lines, new_start, old_lines, old_start}` \| error | + `file_not_found` |
| `tool_search_tool_result` | `{type: tool_search_tool_search_result, tool_references: [{type: tool_reference, tool_name}]}` \| error | codes as code_execution |
| `container_upload` | `file_id`, `cache_control?` | puts a Files-API file in the container input dir |
| `tool_reference` | `tool_name` | only inside `tool_result.content` (tool search) |
| `browser_state` | tabs/changes/screenshot | only inside `tool_result.content` (browser toolset 20260801) |
| **beta** `mcp_tool_use` / `mcp_tool_result` | `{id, name, server_name, input}` / `{tool_use_id, is_error, content: string \| text[]}` | `mcp-client-2025-11-20` |
| **beta** `advisor_tool_result` | `{tool_use_id, content: advisor_result \| advisor_redacted_result \| error}` | `advisor-tool-2026-03-01` |
| **beta** `compaction` | `{content: string\|null, encrypted_content, signature}` | round-trip verbatim; null content = failed compaction (no-op); empty string not allowed |
| **beta** `fallback` | `{from: {model}, to: {model}, trigger: {type: refusal}}` | boundary between declining model and fallback model |

## Response-side blocks (`ContentBlock`)

Same names; differences: `text` gains `citations: TextCitation[]|null`; `tool_use` always has `caller` (*live `{type: "direct"}`*) and `toolset_name?`; `server_tool_use`/`web_*_tool_result` carry `caller`; `thinking` has `signature` filled; response never contains `image`/`document`/`search_result`/`tool_result` (those are inputs). GA response union (12): `text`, `thinking`, `redacted_thinking`, `tool_use`, `server_tool_use`, `web_search_tool_result`, `web_fetch_tool_result`, `code_execution_tool_result`, `bash_code_execution_tool_result`, `text_editor_code_execution_tool_result`, `tool_search_tool_result`, `container_upload`. Beta adds `mcp_tool_use`, `mcp_tool_result`, `advisor_tool_result`, `compaction`, `fallback`.

## Citations (`TextCitation` / `citations_delta`)

| `type` | Fields |
|---|---|
| `char_location` | `cited_text`, `document_index`, `document_title`, `start_char_index`, `end_char_index`, `file_id?` |
| `page_location` | …, `start_page_number` (≥1), `end_page_number` |
| `content_block_location` | …, `start_block_index`, `end_block_index` (exclusive) — `cited_text` = concatenated whole blocks, not billed |
| `web_search_result_location` | `cited_text`, `url`, `title`, `encrypted_index` |
| `search_result_location` | `cited_text`, `source`, `title`, `search_result_index`, `start_block_index`, `end_block_index` |

## Caller

`caller: {type: "direct"}` (model called the tool) or `{type: "code_execution_20250825" | "code_execution_20260120", tool_id: "srvtoolu_…"}` (programmatic tool calling from inside the container).