Anthropic Messages API Reference

Status: Draft

Verified against official sources on: 2026-03-23

Confidence: Low. This file still contains unverified or speculative details and should not yet be treated as a source of truth.

Official sources:

• Anthropic Messages API
• Anthropic Messages examples
• Anthropic computer use
• Anthropic text editor tool
• Anthropic bash tool
• Anthropic web search tool

Endpoint

POST https://api.anthropic.com/v1/messages

Required Headers

Request Parameters

Required

Optional

Thinking Configuration

Adaptive (Recommended for Claude Opus 4.6+)

{
  "thinking": {
    "type": "adaptive",
    "effort": "high"
  }
}

Enabled (Legacy, deprecated for Opus 4.6)

{
  "thinking": {
    "type": "enabled",
    "budget_tokens": 15000
  }
}

Note: budget_tokens is deprecated on Claude Opus 4.6 and will be removed in a future model release. Use adaptive thinking with effort instead.

Disabled

{
  "thinking": {
    "type": "disabled"
  }
}

Content Block Types

Text Block

{"type": "text", "text": "Hello, world!"}

Image Block

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/jpeg",
    "data": "<base64>"
  }
}

Or URL source:

{
  "type": "image",
  "source": {
    "type": "url",
    "url": "https://..."
  }
}

Supported: image/jpeg, image/png, image/gif, image/webp.

Document Block

{
  "type": "document",
  "source": {
    "type": "base64",
    "media_type": "application/pdf",
    "data": "<base64>"
  }
}

Also supports text/plain, text/html, text/csv, application/vnd.openxmlformats-officedocument.*.

Tool Use Block (in assistant messages)

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "get_weather",
  "input": {"city": "Paris"}
}

Tool Result Block (in user messages)

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "22°C, sunny"
}

Content can be a string or array of content blocks (text, image).

Thinking Block (in assistant messages)

{
  "type": "thinking",
  "thinking": "Let me reason through this...",
  "signature": "<opaque_signature>"
}

The signature field is required when replaying thinking blocks in multi-turn conversations. The thinking content may be summarized when display: "summarized" is used with adaptive thinking.

Server Tool Use Block

{
  "type": "server_tool_use",
  "id": "srvtoolu_abc123",
  "name": "web_search",
  "input": {"query": "latest news"}
}

Server Tool Result Block

{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": [...]
}

Tool Types

Custom Function Tool

{
  "name": "get_weather",
  "description": "Get current weather for a city",
  "input_schema": {
    "type": "object",
    "properties": {"city": {"type": "string"}},
    "required": ["city"]
  }
}

Computer Use Tool

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

Versions:

• computer_20241022 — original version
• computer_20250124 — added hold_key, left_mouse_down, left_mouse_up, scroll, triple_click, wait
• computer_20251124 — latest version

Text Editor Tool

{
  "type": "text_editor_20250728",
  "name": "str_replace_editor"
}

Versions:

• text_editor_20241022 — original
• text_editor_20250124 — updated
• text_editor_20250429 — deprecated
• text_editor_20250728 — current recommended

Bash Tool

{
  "type": "bash_20250124",
  "name": "bash"
}

Versions:

• bash_20241022 — original
• bash_20250124 — current recommended

Web Search Tool (Server-Side)

{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 5
}

Executes on Anthropic's servers. No beta header required (GA).

tool_choice Options

Response Object

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-20250514",
  "content": [
    {"type": "text", "text": "Hello!"}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 10,
    "output_tokens": 20,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

stop_reason Values

Usage Fields

Note: Anthropic's input_tokens count INCLUDES cached tokens. The cache fields are supplementary information for billing purposes.

Streaming Events

When stream: true, the API sends SSE events in this order:

Event Flow

message_start →
  content_block_start → content_block_delta* → content_block_stop →
  (repeat for each content block) →
message_delta → message_stop

Event Types

Delta Types (in content_block_delta)

Prompt Caching

Add cache_control to content blocks:

{
  "type": "text",
  "text": "Long reference document...",
  "cache_control": {"type": "ephemeral"}
}

Cache breakpoints can be placed on:

• System prompt blocks
• User message content blocks
• Tool definitions (on the last tool in the array)

Cache TTL: 5 minutes, extended on each hit.

Context Window Sizes