0
# Core Type Definitions
1

2
Complete reference for all type definitions in the Anthropic Python SDK. These types are used throughout the SDK for request parameters, response objects, and configuration.
3

4
## Core Imports
5

6
```python
7
from anthropic.types import (
8
    Message, MessageParam, ContentBlock, TextBlock, ToolUseBlock,
9
    Usage, StopReason, MessageTokensCount
10
)
11
```
12

13
For beta features:
14

15
```python
16
from anthropic.types.beta import (
17
    BetaMessage, ParsedBetaMessage, BetaContentBlock, BetaUsage
18
)
19
```
20

21
## Type Categories
22

23
### Message Types
24

25
Core types for message requests and responses, including content blocks, usage tracking, and stop reasons.
26

27
```python { .api }
28
class Message:
29
    """Message response from the API."""
30
    id: str  # Unique message ID
31
    type: Literal["message"]  # Type identifier
32
    role: Literal["assistant"]  # Role of message
33
    content: List[ContentBlock]  # Message content blocks
34
    model: str  # Model used
35
    stop_reason: StopReason | None  # Why generation stopped
36
    stop_sequence: str | None  # Stop sequence matched
37
    usage: Usage  # Token usage information
38

39
class Usage:
40
    """Token usage information."""
41
    input_tokens: int  # Input tokens used
42
    output_tokens: int  # Output tokens generated
43
    cache_creation_input_tokens: int | None  # Cache creation tokens
44
    cache_read_input_tokens: int | None  # Cache read tokens
45
    cache_creation: CacheCreation | None  # Breakdown of cache creation by TTL
46
    server_tool_use: ServerToolUsage | None  # Server tool usage metrics
47
    service_tier: Literal["standard", "priority", "batch"] | None  # Service tier used
48

49
class MessageTokensCount:
50
    """Token count result."""
51
    input_tokens: int  # Number of input tokens
52

53
class CacheCreation:
54
    """Cache creation breakdown by TTL."""
55
    ephemeral_5m_input_tokens: int  # Tokens cached with 5 minute TTL
56
    ephemeral_1h_input_tokens: int  # Tokens cached with 1 hour TTL
57

58
class ServerToolUsage:
59
    """Server tool usage metrics."""
60
    web_search_requests: int  # Number of web search requests made
61
```
62

63
[Message Types](./types/message-types.md)
64

65
### Content Block Types
66

67
Content blocks represent different types of content in messages, including text, tool use, and thinking blocks.
68

69
```python { .api }
70
# Union type for content blocks
71
ContentBlock = Union[
72
    TextBlock,
73
    ThinkingBlock,
74
    RedactedThinkingBlock,
75
    ToolUseBlock,
76
    ServerToolUseBlock,
77
    WebSearchResultBlock
78
]
79

80
class TextBlock:
81
    """Text content block."""
82
    type: Literal["text"]  # Block type
83
    text: str  # Text content
84
    citations: List[TextCitation] | None  # Text citations
85

86
class ThinkingBlock:
87
    """Thinking content block."""
88
    type: Literal["thinking"]  # Block type
89
    signature: str  # Thinking signature
90
    thinking: str  # Thinking content
91

92
class RedactedThinkingBlock:
93
    """Redacted thinking content block."""
94
    type: Literal["redacted_thinking"]  # Block type
95
    data: str  # Redacted thinking data
96

97
class ToolUseBlock:
98
    """Tool use block."""
99
    type: Literal["tool_use"]  # Block type
100
    id: str  # Tool use ID
101
    name: str  # Tool name
102
    input: dict  # Tool input
103

104
class ServerToolUseBlock:
105
    """Server tool use block."""
106
    type: Literal["server_tool_use"]  # Block type
107
    id: str  # Tool use ID
108
    name: Literal["web_search"]  # Tool name (currently only web_search)
109
    input: Dict[str, object]  # Tool input
110

111
class WebSearchResultBlock:
112
    """Web search result block."""
113
    type: Literal["web_search_result"]  # Block type
114
    encrypted_content: str  # Encrypted result content
115
    title: str  # Result title
116
    url: str  # Result URL
117
    page_age: str | None  # Page age information
118
```
119

120
[Content Block Types](./types/content-blocks.md)
121

122
### Request Parameter Types
123

124
Types for constructing message requests, including message parameters and content block parameters.
125

126
```python { .api }
127
class MessageParam(TypedDict):
128
    """Message in conversation history."""
129
    role: Literal["user", "assistant"]  # Message role
130
    content: str | List[ContentBlockParam]  # Message content
131

132
# Union type for content block parameters
133
ContentBlockParam = Union[
134
    TextBlockParam,
135
    ImageBlockParam,
136
    DocumentBlockParam,
137
    SearchResultBlockParam,
138
    ThinkingBlockParam,
139
    RedactedThinkingBlockParam,
140
    ToolUseBlockParam,
141
    ToolResultBlockParam,
142
    ServerToolUseBlockParam,
143
    WebSearchToolResultBlockParam
144
]
145

146
class TextBlockParam(TypedDict):
147
    """Text content block parameter."""
148
    type: Literal["text"]
149
    text: str
150
    cache_control: CacheControlEphemeralParam | None
151

152
class ImageBlockParam(TypedDict):
153
    """Image content block parameter."""
154
    type: Literal["image"]
155
    source: Base64ImageSourceParam | URLImageSourceParam
156
    cache_control: CacheControlEphemeralParam | None
157

158
class DocumentBlockParam(TypedDict):
159
    """Document content block parameter."""
160
    type: Literal["document"]
161
    source: Base64PDFSourceParam | URLPDFSourceParam | PlainTextSourceParam | ContentBlockSourceParam
162
    cache_control: CacheControlEphemeralParam | None
163
    citations: CitationsConfigParam | None  # Citations configuration
164
    context: str | None  # Document context
165
    title: str | None  # Document title
166

167
class SearchResultBlockParam(TypedDict):
168
    """Search result content block parameter."""
169
    type: Literal["search_result"]
170
    content: Iterable[TextBlockParam]  # Result content (text blocks)
171
    source: str  # Result source URL
172
    title: str  # Result title
173
    cache_control: CacheControlEphemeralParam | None
174
    citations: CitationsConfigParam | None  # Citations configuration
175

176
class ThinkingBlockParam(TypedDict):
177
    """Thinking content block parameter."""
178
    type: Literal["thinking"]
179
    thinking: str  # Thinking content
180
    cache_control: CacheControlEphemeralParam | None
181

182
class RedactedThinkingBlockParam(TypedDict):
183
    """Redacted thinking content block parameter."""
184
    type: Literal["redacted_thinking"]
185
    data: str  # Redacted data
186
    cache_control: CacheControlEphemeralParam | None
187

188
class ToolUseBlockParam(TypedDict):
189
    """Tool use block parameter."""
190
    type: Literal["tool_use"]
191
    id: str  # Tool use ID
192
    name: str  # Tool name
193
    input: dict  # Tool input
194
    cache_control: CacheControlEphemeralParam | None
195

196
class ToolResultBlockParam(TypedDict):
197
    """Tool result block parameter."""
198
    type: Literal["tool_result"]
199
    tool_use_id: str  # ID of tool use
200
    content: str | Iterable[Union[TextBlockParam, ImageBlockParam, SearchResultBlockParam, DocumentBlockParam]]  # Result content
201
    is_error: bool | None  # Whether result is error
202
    cache_control: CacheControlEphemeralParam | None
203

204
class ServerToolUseBlockParam(TypedDict):
205
    """Server tool use block parameter."""
206
    type: Literal["server_tool_use"]
207
    tool_use_id: str  # Tool use ID
208
    name: Literal["web_search"]  # Tool name
209
    input: Dict[str, object]  # Tool input
210
    cache_control: CacheControlEphemeralParam | None
211

212
class WebSearchToolResultBlockParam(TypedDict):
213
    """Web search tool result block parameter."""
214
    type: Literal["web_search_tool_result"]
215
    tool_use_id: str  # Tool use ID
216
    content: object  # Result content (structured data)
217
    cache_control: CacheControlEphemeralParam | None
218
```
219

220
[Request Parameter Types](./types/request-params.md)
221

222
### Tool Types
223

224
Types for tool definitions, tool choice configuration, and built-in tools.
225

226
```python { .api }
227
class ToolParam(TypedDict):
228
    """Tool definition."""
229
    name: str  # Tool name
230
    input_schema: dict  # JSON schema for tool input
231
    description: str | None  # Tool description
232
    cache_control: CacheControlEphemeralParam | None  # Cache control
233
    type: Literal["custom"] | None  # Tool type (optional, defaults to "custom")
234

235
# Union of all tool types including built-in tools
236
ToolUnionParam = Union[
237
    ToolParam,
238
    ToolBash20250124Param,
239
    ToolTextEditor20250124Param,
240
    ToolTextEditor20250429Param,
241
    ToolTextEditor20250728Param,
242
    WebSearchTool20250305Param
243
]
244

245
# Union of tool choice options
246
ToolChoiceParam = Union[
247
    ToolChoiceAutoParam,
248
    ToolChoiceAnyParam,
249
    ToolChoiceToolParam,
250
    ToolChoiceNoneParam
251
]
252

253
class ToolChoiceAutoParam(TypedDict):
254
    """Auto tool selection."""
255
    type: Literal["auto"]
256
    disable_parallel_tool_use: bool | None
257

258
class ToolChoiceAnyParam(TypedDict):
259
    """Must use a tool."""
260
    type: Literal["any"]
261
    disable_parallel_tool_use: bool | None
262

263
class ToolChoiceToolParam(TypedDict):
264
    """Use specific tool."""
265
    type: Literal["tool"]
266
    name: str  # Tool name
267
    disable_parallel_tool_use: bool | None
268

269
class ToolChoiceNoneParam(TypedDict):
270
    """Don't use tools."""
271
    type: Literal["none"]
272
```
273

274
[Tool Types](./types/tool-types.md)
275

276
### Built-in Tool Types
277

278
Types for Claude's built-in tools including bash, text editor, computer use, and web search.
279

280
```python { .api }
281
class ToolBash20250124Param(TypedDict):
282
    """Bash tool for command execution."""
283
    type: Literal["bash_20250124"]
284
    name: str
285
    cache_control: CacheControlEphemeralParam | None
286

287
class ToolTextEditor20250728Param(TypedDict):
288
    """Text editor tool for file editing."""
289
    type: Literal["text_editor_20250728"]
290
    name: str
291
    cache_control: CacheControlEphemeralParam | None
292

293
class ToolComputerUse20250124Param(TypedDict):
294
    """Computer use tool for GUI interaction."""
295
    type: Literal["computer_use_20250124"]
296
    name: str
297
    display_width_px: int
298
    display_height_px: int
299
    display_number: int | None
300
    cache_control: CacheControlEphemeralParam | None
301

302
class WebSearchTool20250305Param(TypedDict):
303
    """Web search tool."""
304
    type: Literal["web_search_20250305"]
305
    name: str
306
    cache_control: CacheControlEphemeralParam | None
307
```
308

309
[Built-in Tool Types](./types/builtin-tools.md)
310

311
### Model Types
312

313
Types for model information and model parameters.
314

315
```python { .api }
316
class ModelInfo:
317
    """Information about a model."""
318
    id: str  # Model ID (e.g., "claude-3-5-sonnet-20241022")
319
    type: Literal["model"]  # Type
320
    display_name: str  # Human-readable name
321
    created_at: datetime  # Creation timestamp
322

323
# Model identifier - can be a specific model string or any string
324
ModelParam = str
325
```
326

327
[Model Types](./types/model-types.md)
328

329
### Image and Document Source Types
330

331
Types for providing images and documents as base64 data or URLs.
332

333
```python { .api }
334
class Base64ImageSourceParam(TypedDict):
335
    """Base64 encoded image source."""
336
    type: Literal["base64"]
337
    media_type: str  # MIME type (e.g., "image/jpeg", "image/png")
338
    data: str  # Base64 encoded data
339

340
class URLImageSourceParam(TypedDict):
341
    """Image from URL."""
342
    type: Literal["url"]
343
    url: str  # Image URL
344

345
class Base64PDFSourceParam(TypedDict):
346
    """Base64 encoded PDF source."""
347
    type: Literal["base64"]
348
    media_type: Literal["application/pdf"]
349
    data: str  # Base64 encoded data
350

351
class URLPDFSourceParam(TypedDict):
352
    """PDF from URL."""
353
    type: Literal["url"]
354
    url: str  # PDF URL
355

356
class PlainTextSourceParam(TypedDict):
357
    """Plain text document source."""
358
    type: Literal["text"]
359
    media_type: Literal["text/plain"]
360
    data: str  # Plain text data
361

362
class ContentBlockSourceParam(TypedDict):
363
    """Content block document source."""
364
    type: Literal["content"]
365
    content: str | Iterable[object]  # Content as string or blocks
366
```
367

368
[Image and Document Types](./types/source-types.md)
369

370
### Cache Control Types
371

372
Types for prompt caching configuration.
373

374
```python { .api }
375
class CacheControlEphemeralParam(TypedDict):
376
    """Prompt caching configuration."""
377
    type: Literal["ephemeral"]  # Cache type
378
```
379

380
[Cache Control Types](./types/cache-control.md)
381

382
### Citations Configuration
383

384
Types for configuring citation behavior in documents and search results.
385

386
```python { .api }
387
class CitationsConfigParam(TypedDict):
388
    """Citations configuration."""
389
    enabled: bool  # Whether to enable citations
390
```
391

392
[Citations Configuration](./types/citations-config.md)
393

394
### Citation Types
395

396
Types for citations in text responses, supporting multiple location types.
397

398
```python { .api }
399
# TextCitation is a discriminated union of citation location types
400
TextCitation = Union[
401
    CitationCharLocation,
402
    CitationPageLocation,
403
    CitationContentBlockLocation,
404
    CitationsWebSearchResultLocation,
405
    CitationsSearchResultLocation
406
]
407

408
class CitationCharLocation:
409
    """Character-based citation location."""
410
    type: Literal["char_location"]
411
    cited_text: str  # The cited text
412
    document_index: int  # Document index
413
    document_title: str | None  # Document title
414
    start_char_index: int  # Start character index
415
    end_char_index: int  # End character index
416
    file_id: str | None  # File ID if applicable
417

418
class CitationPageLocation:
419
    """Page-based citation location."""
420
    type: Literal["page_location"]
421
    cited_text: str  # The cited text
422
    document_index: int  # Document index
423
    document_title: str | None  # Document title
424
    page_number: int  # Page number
425
    file_id: str | None  # File ID if applicable
426

427
class CitationContentBlockLocation:
428
    """Content block citation location."""
429
    type: Literal["content_block_location"]
430
    cited_text: str  # The cited text
431
    content_block_index: int  # Content block index
432

433
class CitationsSearchResultLocation:
434
    """Search result citation location."""
435
    type: Literal["search_result_location"]
436
    search_result_index: int  # Search result index
437

438
class CitationsWebSearchResultLocation:
439
    """Web search result citation location."""
440
    type: Literal["web_search_result_location"]
441
    cited_text: str  # The cited text
442
    web_search_result_index: int  # Web search result index
443
```
444

445
[Citation Types](./types/citations.md)
446

447
### Configuration Types
448

449
Types for request configuration and metadata.
450

451
```python { .api }
452
class MetadataParam(TypedDict):
453
    """Request metadata."""
454
    user_id: str | None  # User identifier
455

456
# Union of thinking config options
457
ThinkingConfigParam = Union[
458
    ThinkingConfigEnabledParam,
459
    ThinkingConfigDisabledParam
460
]
461

462
class ThinkingConfigEnabledParam(TypedDict):
463
    """Enable extended thinking."""
464
    type: Literal["enabled"]
465
    budget_tokens: int  # Token budget for thinking
466

467
class ThinkingConfigDisabledParam(TypedDict):
468
    """Disable extended thinking."""
469
    type: Literal["disabled"]
470

471
class RequestOptions(TypedDict):
472
    """Options for individual requests."""
473
    extra_headers: Headers | None
474
    extra_query: Query | None
475
    extra_body: Body | None
476
    timeout: float | httpx.Timeout | None | NotGiven
477

478
# Type aliases
479
Timeout = httpx.Timeout
480
Transport = httpx.BaseTransport
481
ProxiesTypes = Union[str, httpx.Proxy, Dict[str, httpx.Proxy]]
482
```
483

484
[Configuration Types](./types/configuration.md)
485

486
### Special Values
487

488
Sentinel values for optional parameters and omitted values.
489

490
```python { .api }
491
# Sentinel value for "not provided"
492
NOT_GIVEN: NotGiven
493

494
# Type for NOT_GIVEN
495
class NotGiven:
496
    """Type for NOT_GIVEN sentinel value."""
497
    pass
498

499
# Type for omitted values
500
class Omit:
501
    """Type for omitted values."""
502
    pass
503

504
# Omit sentinel value
505
omit: Omit
506

507
# NoneType for type hints
508
NoneType = type(None)
509
```
510

511
[Special Values](./types/special-values.md)
512

513
### Message Batch Types
514

515
Types for batch processing of messages.
516

517
```python { .api }
518
class MessageBatch:
519
    """Batch processing job."""
520
    id: str  # Batch ID
521
    type: Literal["message_batch"]  # Type
522
    processing_status: str  # Processing status
523
    request_counts: MessageBatchRequestCounts  # Request counts
524
    created_at: datetime  # Creation time
525
    expires_at: datetime  # Expiration time
526
    results_url: str | None  # Results download URL
527

528
class MessageBatchRequestCounts:
529
    """Request counts in a batch."""
530
    processing: int  # Processing count
531
    succeeded: int  # Success count
532
    errored: int  # Error count
533
    canceled: int  # Canceled count
534
    expired: int  # Expired count
535

536
class DeletedMessageBatch:
537
    """Deleted batch confirmation."""
538
    id: str  # Batch ID
539
    type: Literal["message_batch_deleted"]  # Type
540
    deleted: bool  # Deletion status
541

542
class MessageBatchIndividualResponse:
543
    """Individual batch result."""
544
    custom_id: str  # Custom request ID
545
    result: MessageBatchResult  # Result data
546

547
# Union of batch result types
548
MessageBatchResult = Union[
549
    MessageBatchSucceededResult,
550
    MessageBatchErroredResult,
551
    MessageBatchCanceledResult,
552
    MessageBatchExpiredResult
553
]
554

555
class MessageBatchSucceededResult:
556
    """Successful batch result."""
557
    type: Literal["succeeded"]
558
    message: Message  # Generated message
559

560
class MessageBatchErroredResult:
561
    """Errored batch result."""
562
    type: Literal["errored"]
563
    error: ErrorObject  # Error details
564

565
class MessageBatchCanceledResult:
566
    """Canceled batch result."""
567
    type: Literal["canceled"]
568

569
class MessageBatchExpiredResult:
570
    """Expired batch result."""
571
    type: Literal["expired"]
572
```
573

574
[Message Batch Types](./types/batch-types.md)
575

576
### Delta Types
577

578
Types for incremental updates during streaming.
579

580
```python { .api }
581
# Union of all content block delta types
582
RawContentBlockDelta = Union[
583
    TextDelta,
584
    ThinkingDelta,
585
    InputJSONDelta,
586
    CitationsDelta,
587
    SignatureDelta
588
]
589

590
class TextDelta:
591
    """Text content delta."""
592
    type: Literal["text_delta"]
593
    text: str  # Incremental text content
594

595
class ThinkingDelta:
596
    """Thinking content delta."""
597
    type: Literal["thinking_delta"]
598
    thinking: str  # Incremental thinking content
599

600
class InputJSONDelta:
601
    """Tool input JSON delta."""
602
    type: Literal["input_json_delta"]
603
    partial_json: str  # Partial JSON string
604

605
class CitationsDelta:
606
    """Citations delta."""
607
    type: Literal["citations_delta"]
608
    citation: object  # Citation object
609

610
class SignatureDelta:
611
    """Signature delta."""
612
    type: Literal["signature_delta"]
613
    signature: str  # Signature content
614

615
# Alias for backward compatibility
616
ContentBlockDelta = RawContentBlockDelta
617

618
class MessageDelta:
619
    """Message-level delta."""
620
    stop_reason: StopReason | None  # Stop reason if changed
621
    stop_sequence: str | None  # Stop sequence if matched
622

623
class MessageDeltaUsage:
624
    """Usage delta in message updates."""
625
    output_tokens: int  # Additional output tokens generated
626
```
627

628
[Delta Types](./types/delta-types.md)
629

630
### Stream Event Types
631

632
Types for streaming message events.
633

634
```python { .api }
635
# Union of all message stream events
636
MessageStreamEvent = Union[
637
    MessageStartEvent,
638
    MessageDeltaEvent,
639
    MessageStopEvent,
640
    ContentBlockStartEvent,
641
    ContentBlockDeltaEvent,
642
    ContentBlockStopEvent
643
]
644

645
class MessageStartEvent:
646
    """Message stream started."""
647
    type: Literal["message_start"]
648
    message: Message  # Initial message state
649

650
class MessageDeltaEvent:
651
    """Message delta update."""
652
    type: Literal["message_delta"]
653
    delta: MessageDelta  # Delta changes
654
    usage: MessageDeltaUsage  # Usage delta
655

656
class MessageStopEvent:
657
    """Message stream stopped."""
658
    type: Literal["message_stop"]
659

660
class ContentBlockStartEvent:
661
    """Content block started."""
662
    type: Literal["content_block_start"]
663
    index: int  # Block index
664
    content_block: ContentBlock  # Block data
665

666
class ContentBlockDeltaEvent:
667
    """Content block delta."""
668
    type: Literal["content_block_delta"]
669
    index: int  # Block index
670
    delta: ContentBlockDelta  # Delta changes
671

672
class ContentBlockStopEvent:
673
    """Content block stopped."""
674
    type: Literal["content_block_stop"]
675
    index: int  # Block index
676

677
# Raw stream events (lower-level)
678
RawMessageStreamEvent = Union[
679
    RawMessageStartEvent,
680
    RawMessageDeltaEvent,
681
    RawMessageStopEvent,
682
    RawContentBlockStartEvent,
683
    RawContentBlockDeltaEvent,
684
    RawContentBlockStopEvent
685
]
686
```
687

688
[Stream Event Types](./types/stream-events.md)
689

690
### Completion Types (Legacy)
691

692
Types for the legacy text completion API.
693

694
```python { .api }
695
class Completion:
696
    """Text completion response (legacy API)."""
697
    id: str  # Completion ID
698
    type: Literal["completion"]  # Type
699
    completion: str  # Generated text
700
    model: str  # Model used
701
    stop_reason: str | None  # Stop reason
702
```
703

704
[Completion Types](./types/completion.md)
705

706
### Response Types
707

708
Wrapper types for API responses.
709

710
```python { .api }
711
class APIResponse:
712
    """Wrapper for API responses."""
713
    http_response: httpx.Response  # Raw response
714
    headers: httpx.Headers  # Response headers
715
    status_code: int  # Status code
716
    retries_taken: int  # Number of retries
717

718
    def parse(self) -> T:
719
        """Parse response to model."""
720
        pass
721

722
class AsyncAPIResponse:
723
    """Async response wrapper."""
724
    http_response: httpx.Response  # Raw response
725
    headers: httpx.Headers  # Response headers
726
    status_code: int  # Status code
727
    retries_taken: int  # Number of retries
728

729
    async def parse(self) -> T:
730
        """Parse response to model."""
731
        pass
732
```
733

734
[Response Types](./types/response-types.md)
735

736
### Pagination Types
737

738
Types for paginated API responses.
739

740
```python { .api }
741
class SyncPage[T]:
742
    """Sync paginated response."""
743
    data: List[T]  # Page items
744

745
    def __iter__(self) -> Iterator[T]:
746
        """Iterate over items."""
747
        pass
748

749
    def has_next_page(self) -> bool:
750
        """Check for more pages."""
751
        pass
752

753
class AsyncPage[T]:
754
    """Async paginated response."""
755
    data: List[T]  # Page items
756

757
    def __aiter__(self) -> AsyncIterator[T]:
758
        """Async iterate over items."""
759
        pass
760

761
    async def has_next_page(self) -> bool:
762
        """Check for more pages."""
763
        pass
764

765
class SyncTokenPage[T]:
766
    """Token-based pagination (sync)."""
767
    data: List[T]  # Page items
768
    next_token: str | None  # Next page token
769

770
class AsyncTokenPage[T]:
771
    """Token-based pagination (async)."""
772
    data: List[T]  # Page items
773
    next_token: str | None  # Next page token
774

775
class SyncPageCursor[T]:
776
    """Cursor-based pagination (sync)."""
777
    data: List[T]  # Page items
778
    next_cursor: str | None  # Next cursor
779

780
class AsyncPageCursor[T]:
781
    """Cursor-based pagination (async)."""
782
    data: List[T]  # Page items
783
    next_cursor: str | None  # Next cursor
784
```
785

786
[Pagination Types](./types/pagination.md)
787

788
### Beta Types
789

790
Extended types for beta features with additional capabilities.
791

792
```python { .api }
793
class BetaMessage:
794
    """Beta message response with extended features."""
795
    id: str  # Unique message ID
796
    type: Literal["message"]  # Type identifier
797
    role: Literal["assistant"]  # Role of message
798
    content: List[BetaContentBlock]  # Extended content blocks
799
    model: str  # Model used
800
    stop_reason: StopReason | None  # Why generation stopped
801
    stop_sequence: str | None  # Stop sequence matched
802
    usage: BetaUsage  # Extended usage information
803

804
class ParsedBetaMessage[ResponseFormatT]:
805
    """Parsed message with structured output."""
806
    id: str  # Unique message ID
807
    type: Literal["message"]  # Type identifier
808
    role: Literal["assistant"]  # Role of message
809
    content: List[BetaContentBlock]  # Extended content blocks
810
    model: str  # Model used
811
    stop_reason: StopReason | None  # Why generation stopped
812
    stop_sequence: str | None  # Stop sequence matched
813
    usage: BetaUsage  # Extended usage information
814
    parsed_output: ResponseFormatT | None  # Parsed structured output
815

816
# Union of beta content block types
817
BetaContentBlock = Union[
818
    TextBlock,
819
    ToolUseBlock,
820
    ThinkingBlock,
821
    BetaCodeExecutionOutputBlock,
822
    BetaBashCodeExecutionOutputBlock,
823
    BetaWebSearchResultBlock,
824
    BetaWebFetchBlock,
825
    BetaMCPToolUseBlock,
826
    # ... other beta block types
827
]
828

829
class BetaUsage:
830
    """Extended usage info with additional metrics."""
831
    input_tokens: int  # Input tokens used
832
    output_tokens: int  # Output tokens generated
833
    cache_creation_input_tokens: int | None  # Cache creation tokens
834
    cache_read_input_tokens: int | None  # Cache read tokens
835
    thinking_tokens: int | None  # Thinking tokens used
836
    cache_hit_input_tokens: int | None  # Cache hit tokens
837

838
class BetaMessageTokensCount:
839
    """Token count with beta features."""
840
    input_tokens: int  # Input token count
841
```
842

843
[Beta Types](./types/beta-types.md)
844

845
### Beta File Types
846

847
Types for file management in beta features.
848

849
```python { .api }
850
class FileMetadata:
851
    """File metadata."""
852
    id: str  # File ID
853
    type: Literal["file"]  # Type
854
    filename: str  # Original filename
855
    bytes: int  # File size
856
    purpose: str  # File purpose
857
    created_at: datetime  # Upload time
858

859
class DeletedFile:
860
    """Deleted file confirmation."""
861
    id: str  # File ID
862
    type: Literal["file_deleted"]  # Type
863
    deleted: bool  # Deletion status
864
```
865

866
[Beta File Types](./types/beta-files.md)
867

868
### Beta Skill Types
869

870
Types for skill management in beta features.
871

872
```python { .api }
873
class SkillCreateResponse:
874
    """Skill creation response."""
875
    id: str  # Skill ID
876
    name: str  # Skill name
877
    description: str  # Skill description
878
    created_at: datetime  # Creation time
879

880
class SkillRetrieveResponse:
881
    """Skill details response."""
882
    id: str  # Skill ID
883
    name: str  # Skill name
884
    description: str  # Skill description
885
    created_at: datetime  # Creation time
886
    updated_at: datetime  # Update time
887

888
class SkillListResponse:
889
    """Skill in list response."""
890
    id: str  # Skill ID
891
    name: str  # Skill name
892
    description: str  # Skill description
893

894
class SkillDeleteResponse:
895
    """Skill deletion response."""
896
    id: str  # Skill ID
897
    deleted: bool  # Deletion status
898
```
899

900
[Beta Skill Types](./types/beta-skills.md)
901

902
### Beta Version Types
903

904
Types for skill version management in beta features.
905

906
```python { .api }
907
class VersionCreateResponse:
908
    """Version creation response."""
909
    id: str  # Version ID
910
    skill_id: str  # Parent skill ID
911
    version_number: int  # Version number
912
    created_at: datetime  # Creation time
913

914
class VersionRetrieveResponse:
915
    """Version details response."""
916
    id: str  # Version ID
917
    skill_id: str  # Parent skill ID
918
    version_number: int  # Version number
919
    created_at: datetime  # Creation time
920

921
class VersionListResponse:
922
    """Version in list response."""
923
    id: str  # Version ID
924
    version_number: int  # Version number
925

926
class VersionDeleteResponse:
927
    """Version deletion response."""
928
    id: str  # Version ID
929
    deleted: bool  # Deletion status
930
```
931

932
[Beta Version Types](./types/beta-versions.md)
933

934
### Stop Reason Types
935

936
Enum values for message stop reasons.
937

938
```python { .api }
939
# Literal type for stop reasons
940
StopReason = Literal[
941
    "end_turn",      # Natural end of turn
942
    "max_tokens",    # Maximum tokens reached
943
    "stop_sequence", # Stop sequence encountered
944
    "tool_use",      # Tool use requested
945
    "pause_turn",    # Long-running turn was paused
946
    "refusal"        # Streaming classifier intervened for policy violations
947
]
948
```
949

950
[Stop Reason Types](./types/stop-reason.md)
951

952
## Type Organization
953

954
Types are organized into the following modules:
955

956
- **anthropic.types**: Core type definitions
957
- **anthropic.types.beta**: Beta feature types
958
- **anthropic.types.messages**: Message-specific types
959
- **anthropic.types.shared**: Shared error and response types
960

961
All types are exported from their respective modules and can be imported directly from `anthropic.types` or `anthropic.types.beta`.
962