# Anthropic Python SDK Type Definitions: TypedDicts and Pydantic Models Explained

> Explore Anthropic Python SDK type definitions including TypedDicts for requests and Pydantic models for responses. Access all type structures within src/anthropic/types.

- Repository: [Anthropic/anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python)
- Tags: api-reference
- Published: 2026-02-23

---

**The Anthropic Python SDK uses TypedDicts for request parameters and Pydantic BaseModels for API responses, all located in the `src/anthropic/types/` directory.**

The `anthropics/anthropic-sdk-python` repository provides comprehensive type definitions that ensure type safety when interacting with the Anthropic API. These Anthropic Python SDK type definitions separate request specifications from response objects, offering developers precise autocomplete support and runtime validation while maintaining parity with the OpenAPI specification.

## TypedDict Request Definitions

The SDK represents all request parameters using **TypedDicts** with the naming convention `<resource>_<action>_params`. These files reside in `src/anthropic/types/` and use `total=False` with `typing_extensions.Required` to mark optional versus required fields.

### Core Request Types

- **`MessageCreateParams`** – The top-level body sent to `client.messages.create()`. Defined in [[`src/anthropic/types/message_create_params.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/message_create_params.py)](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/message_create_params.py).

- **`CompletionCreateParams`** – Parameters for legacy completion endpoints. Located in [[`src/anthropic/types/completion_create_params.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/completion_create_params.py)](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/completion_create_params.py).

- **`ToolParam`** – Definition of tools supplied to requests. Found in [[`src/anthropic/types/tool_param.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/tool_param.py)](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/tool_param.py).

### Web Search and Tool Result Types

The SDK includes specific TypedDicts for web search functionality:

- **`WebSearchToolResultBlockParam`** – Parameters for web search tool result blocks. Source: [`src/anthropic/types/web_search_tool_result_block_param.py#L19`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/web_search_tool_result_block_param.py#L19).

- **`WebSearchToolResultBlockParamContentParam`** – The nested `content` field definition. Located in [[`src/anthropic/types/web_search_tool_result_block_param_content_param.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/web_search_tool_result_block_param_content_param.py)](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/web_search_tool_result_block_param_content_param.py).

- **`WebSearchToolResultErrorParam`** – Error block parameters for web search tools. Found in [[`src/anthropic/types/web_search_tool_result_error_param.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/web_search_tool_result_error_param.py)](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/web_search_tool_result_error_param.py).

### Cache Control and Caller Types

- **`CacheControlEphemeralParam`** – Optional cache-control information for content blocks. Defined in [[`src/anthropic/types/cache_control_ephemeral_param.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/cache_control_ephemeral_param.py)](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/cache_control_ephemeral_param.py).

- **`DirectCallerParam`**, **`ServerToolCallerParam`**, **`ServerToolCaller20260120Param`** – Different tool calling mechanisms. Located in [[`src/anthropic/types/direct_caller_param.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/direct_caller_param.py)](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/direct_caller_param.py) and related files.

## Pydantic BaseModel Response Definitions

Every object returned by the API is represented as a **Pydantic BaseModel** subclass. These models inherit from the SDK-specific `BaseModel` defined in [`src/anthropic/_models.py#L97`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_models.py#L97), which adds helpers like `to_dict()`, `to_json()`, and request-ID handling.

### Core Response Models

- **`Message`** – The primary message object returned by `client.messages.create()`. Defined in [`src/anthropic/types/message.py#L16`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/message.py#L16).

- **`Completion`** – Legacy completion response payload. Located in [`src/anthropic/types/completion.py#L12`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/completion.py#L12).

- **`Usage`** – Token usage details attached to responses. Found in [`src/anthropic/types/usage.py#L13`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/usage.py#L13).

### Tool and Block Models

- **`ToolUseBlock`** – Represents a tool-use block inside a message. Source: [`src/anthropic/types/tool_use_block.py#L19`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/tool_use_block.py#L19).

- **`ToolResultBlock`** – Result returned by tool execution. Located in [`src/anthropic/types/tool_result_block.py#L22`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/tool_result_block.py#L22).

### Error and Beta Models

- **`ErrorResponse`** – Structured error payload base class. Defined in [`src/anthropic/types/shared/error_response.py#L12`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/shared/error_response.py#L12).

- **`BetaMessageBatchSucceededResult`** – Beta-specific batch handling models. Found in [`src/anthropic/types/beta/messages/beta_message_batch_succeeded_result.py#L11`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/beta/messages/beta_message_batch_succeeded_result.py#L11).

### Specialized Feature Models

- **`CitationsConfig`**, **`CitationsDelta`**, **`CitationsWebSearchResultLocation`** – Types for the citations feature. Located in [`src/anthropic/types/citations_config.py#L8`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/citations_config.py#L8).

- **`CacheCreation`** – Cache-related response models. Found in [`src/anthropic/types/cache_creation.py#L8`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/cache_creation.py#L8).

- **`ModelInfo`** – Information about available models. Located in [`src/anthropic/types/model_info.py#L11`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/model_info.py#L11).

## Practical Usage Examples

### Building Requests with TypedDicts

When constructing API requests, import the appropriate TypedDict definitions to ensure type safety:

```python
from anthropic import Anthropic
from anthropic.types.message_create_params import MessageCreateParams
from anthropic.types.tool_param import ToolParam

# Define tool using TypedDict

search_tool: ToolParam = {
    "name": "web_search",
    "description": "Search the web for a query",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string"}
        }
    },
}

# Build request parameters

params: MessageCreateParams = {
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Find the latest news about AI safety."}
    ],
    "tools": [search_tool],
}

client = Anthropic()
response = client.messages.create(**params)

```

The `MessageCreateParams` TypedDict is defined in [`src/anthropic/types/message_create_params.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/message_create_params.py), while `ToolParam` lives in [`src/anthropic/types/tool_param.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/tool_param.py).

### Handling Web Search Tool Results

For web search tool results, use the specific TypedDicts designed for this feature:

```python
from anthropic.types.web_search_tool_result_block_param import (
    WebSearchToolResultBlockParam,
    Caller,
)

result_block: WebSearchToolResultBlockParam = {
    "type": "web_search_tool_result",
    "tool_use_id": "toolu_01ABC",
    "content": {
        "type": "text",
        "text": "The most recent AI safety paper discusses..."
    },
    "cache_control": {"type": "ephemeral"},
}

```

This structure is defined in [`src/anthropic/types/web_search_tool_result_block_param.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/web_search_tool_result_block_param.py) at line 19.

### Accessing Response Data with BaseModels

Responses from the API are Pydantic models with convenient accessor methods:

```python
import anthropic

# Assume msg is the Message returned from client.messages.create()

msg = client.messages.create(...)

# Access usage statistics

print(f"Input tokens: {msg.usage.input_tokens}")
print(f"Output tokens: {msg.usage.output_tokens}")

# Iterate over content blocks

for block in msg.content:
    if isinstance(block, anthropic.types.tool_use_block.ToolUseBlock):
        print(f"Tool call: {block.name} with input {block.input}")
    elif isinstance(block, anthropic.types.text_block.TextBlock):
        print(f"Text: {block.text}")

# Convert to dictionary or JSON

dict_data = msg.to_dict()
json_str = msg.to_json()

```

The `Message` model is defined in [`src/anthropic/types/message.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/message.py), while `ToolUseBlock` and `TextBlock` are in [`src/anthropic/types/tool_use_block.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/tool_use_block.py) and [`src/anthropic/types/text_block.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/text_block.py) respectively. All inherit from the custom `BaseModel` in [`src/anthropic/_models.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_models.py).

## Summary

- **TypedDicts** in `src/anthropic/types/*_param.py` files define request parameter structures with `total=False` and `Required` markers for OpenAPI compliance.
- **Pydantic BaseModels** in `src/anthropic/types/*.py` (non-param files) represent API responses, inheriting from the custom `BaseModel` defined in [`src/anthropic/_models.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_models.py).
- **Web search tools** have dedicated TypedDicts like `WebSearchToolResultBlockParam` located in [`src/anthropic/types/web_search_tool_result_block_param.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/web_search_tool_result_block_param.py).
- **Beta features** maintain separate type definitions in `src/anthropic/types/beta/` to isolate experimental APIs.
- All type definitions are auto-generated from the OpenAPI specification, ensuring request and response shapes remain synchronized.

## Frequently Asked Questions

### What is the difference between TypedDicts and Pydantic models in the Anthropic SDK?

TypedDicts are used exclusively for request parameters (files ending in [`_param.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/_param.py)), allowing you to pass plain dictionaries to methods like `client.messages.create()` while maintaining type safety. Pydantic BaseModels are used for all API responses, providing runtime validation, serialization methods like `.to_dict()` and `.to_json()`, and attribute access. The separation mirrors the OpenAPI specification's distinction between input schemas and output objects.

### Where are the type definitions located in the repository?

All type definitions reside in the `src/anthropic/types/` directory. Request parameter TypedDicts follow the pattern `src/anthropic/types/<resource>_<action>_params.py` (e.g., [`message_create_params.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/message_create_params.py)), while response Pydantic models use `src/anthropic/types/<model_name>.py` (e.g., [`message.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/message.py), [`tool_use_block.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/tool_use_block.py)). Beta-specific types are isolated in `src/anthropic/types/beta/`.

### How do I import and use specific type definitions like MessageCreateParams?

Import TypedDicts directly from their respective modules under `anthropic.types`:

```python
from anthropic.types.message_create_params import MessageCreateParams
from anthropic.types.tool_param import ToolParam

params: MessageCreateParams = {
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
}

```

For response models, import from the main types module:

```python
from anthropic.types import Message, ToolUseBlock

```

### Are beta features typed differently in the SDK?

Yes, beta features maintain separate type definitions to prevent breaking changes in stable code. Beta TypedDicts and Pydantic models are located in `src/anthropic/types/beta/` and typically include `Beta` prefixes in their class names (e.g., `BetaMessageBatchSucceededResult` in [`src/anthropic/types/beta/messages/beta_message_batch_succeeded_result.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/types/beta/messages/beta_message_batch_succeeded_result.py)). These follow the same TypedDict/BaseModel separation as stable types but may change without notice as the beta APIs evolve.