# Core Types Reference

Complete type definitions for the Anthropic TypeScript SDK. This document covers all public types, interfaces, and enums used throughout the SDK.

## Messages API Types

### Message Types

```typescript { .api }
interface Message {
  id: string;
  type: 'message';
  role: 'assistant';
  content: ContentBlock[];
  model: string;
  stop_reason: StopReason | null;
  stop_sequence: string | null;
  usage: Usage;
}

interface MessageParam {
  role: 'user' | 'assistant';
  content: string | ContentBlockParam[];
}

type StopReason =
  | 'end_turn'
  | 'max_tokens'
  | 'stop_sequence'
  | 'tool_use'
  | 'server_tool_use';

interface Usage {
  input_tokens: number;
  output_tokens: number;
  cache_creation_input_tokens?: number;
  cache_read_input_tokens?: number;
}
```

### Content Block Types (Output)

```typescript { .api }
type ContentBlock =
  | TextBlock
  | ThinkingBlock
  | RedactedThinkingBlock
  | ToolUseBlock
  | ServerToolUseBlock
  | WebSearchResultBlock;

interface TextBlock {
  type: 'text';
  text: string;
  citations?: TextCitation[];
}

interface ThinkingBlock {
  type: 'thinking';
  thinking: string;
  signature?: string;
}

interface RedactedThinkingBlock {
  type: 'redacted_thinking';
  signature: string;
}

interface ToolUseBlock {
  type: 'tool_use';
  id: string;
  name: string;
  input: Record<string, any>;
}

interface ServerToolUseBlock {
  type: 'server_tool_use';
  id: string;
  name: string;
  input: Record<string, any>;
}

interface WebSearchResultBlock {
  type: 'web_search_result';
  query: string;
  results: Array<{
    url: string;
    title: string;
    snippet: string;
  }>;
}
```

### Content Block Params (Input)

```typescript { .api }
type ContentBlockParam =
  | TextBlockParam
  | ImageBlockParam
  | DocumentBlockParam
  | ToolUseBlockParam
  | ToolResultBlockParam
  | ThinkingBlockParam
  | RedactedThinkingBlockParam
  | ServerToolUseBlockParam
  | SearchResultBlockParam
  | WebSearchResultBlockParam;

interface TextBlockParam {
  type: 'text';
  text: string;
  cache_control?: CacheControlEphemeral;
  citations?: TextCitationParam[];
}

interface ImageBlockParam {
  type: 'image';
  source: Base64ImageSource | URLImageSource | BetaFileImageSource;
  cache_control?: CacheControlEphemeral;
}

interface DocumentBlockParam {
  type: 'document';
  source: Base64PDFSource | URLPDFSource | PlainTextSource | BetaFileDocumentSource;
  cache_control?: CacheControlEphemeral;
}

interface ToolUseBlockParam {
  type: 'tool_use';
  id: string;
  name: string;
  input: Record<string, any>;
  cache_control?: CacheControlEphemeral;
}

interface ToolResultBlockParam {
  type: 'tool_result';
  tool_use_id: string;
  content?: string | ContentBlockParam[];
  is_error?: boolean;
  cache_control?: CacheControlEphemeral;
}

interface ThinkingBlockParam {
  type: 'thinking';
  thinking: string;
  cache_control?: CacheControlEphemeral;
}

interface RedactedThinkingBlockParam {
  type: 'redacted_thinking';
  signature: string;
  cache_control?: CacheControlEphemeral;
}

interface ServerToolUseBlockParam {
  type: 'server_tool_use';
  id: string;
  name: string;
  input: Record<string, any>;
  cache_control?: CacheControlEphemeral;
}

interface SearchResultBlockParam {
  type: 'search_result';
  url: string;
  title: string;
  content: string;
  cache_control?: CacheControlEphemeral;
}

interface WebSearchResultBlockParam {
  type: 'web_search_result';
  query: string;
  results: WebSearchToolResultBlockParam[];
  cache_control?: CacheControlEphemeral;
}
```

### Image and Document Sources

```typescript { .api }
interface Base64ImageSource {
  type: 'base64';
  media_type: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
  data: string;
}

interface URLImageSource {
  type: 'url';
  url: string;
}

interface Base64PDFSource {
  type: 'base64';
  media_type: 'application/pdf';
  data: string;
}

interface URLPDFSource {
  type: 'url';
  url: string;
  media_type: 'application/pdf';
}

interface PlainTextSource {
  type: 'text';
  media_type: 'text/plain';
  data: string;
}

// Beta file sources
interface BetaFileImageSource {
  type: 'file';
  file_id: string;
}

interface BetaFileDocumentSource {
  type: 'file';
  file_id: string;
}
```

### Tool Types

```typescript { .api }
interface Tool {
  type?: 'custom';
  name: string;
  description: string;
  input_schema: {
    type: 'object';
    properties: Record<string, JSONSchema>;
    required?: string[];
  };
  cache_control?: CacheControlEphemeral;
}

interface ToolBash20250124 {
  type: 'bash_20250124';
  name: 'bash';
  cache_control?: CacheControlEphemeral;
}

interface ToolTextEditor20250124 {
  type: 'text_editor_20250124';
  name: 'str_replace_editor';
  cache_control?: CacheControlEphemeral;
}

interface ToolTextEditor20250429 {
  type: 'text_editor_20250429';
  name: 'str_replace_editor';
  cache_control?: CacheControlEphemeral;
}

interface ToolTextEditor20250728 {
  type: 'text_editor_20250728';
  name: 'str_replace_editor';
  cache_control?: CacheControlEphemeral;
}

interface WebSearchTool20250305 {
  type: 'web_search_20250305';
  name: 'web_search';
  cache_control?: CacheControlEphemeral;
}

type ToolUnion =
  | Tool
  | ToolBash20250124
  | ToolTextEditor20250124
  | ToolTextEditor20250429
  | ToolTextEditor20250728
  | WebSearchTool20250305;
```

### Tool Choice

```typescript { .api }
type ToolChoice =
  | ToolChoiceAuto
  | ToolChoiceAny
  | ToolChoiceNone
  | ToolChoiceTool;

interface ToolChoiceAuto {
  type: 'auto';
}

interface ToolChoiceAny {
  type: 'any';
}

interface ToolChoiceNone {
  type: 'none';
}

interface ToolChoiceTool {
  type: 'tool';
  name: string;
}
```

### Citations

```typescript { .api }
interface TextCitation {
  type: 'citation';
  cited_text: string;
  location: CitationLocation;
}

interface TextCitationParam {
  type: 'citation';
  cited_text: string;
  location: CitationLocationParam;
}

type CitationLocation =
  | CitationCharLocation
  | CitationContentBlockLocation
  | CitationPageLocation
  | CitationsSearchResultLocation
  | CitationsWebSearchResultLocation;

type CitationLocationParam =
  | CitationCharLocationParam
  | CitationContentBlockLocationParam
  | CitationPageLocationParam
  | CitationSearchResultLocationParam
  | CitationWebSearchResultLocationParam;

interface CitationCharLocation {
  type: 'char_location';
  document_index: number;
  document_title: string | null;
  cited_text: string;
  start_char_index: number;
  end_char_index: number;
  file_id: string | null;
}

interface CitationContentBlockLocation {
  type: 'content_block_location';
  document_index: number;
  document_title: string | null;
  cited_text: string;
  start_block_index: number;
  end_block_index: number;
  file_id: string | null;
}

interface CitationPageLocation {
  type: 'page_location';
  document_index: number;
  document_title: string | null;
  cited_text: string;
  page_number: number;
  file_id: string | null;
}

interface CitationsSearchResultLocation {
  type: 'search_result_location';
  cited_text: string;
  search_result_index: number;
}

interface CitationsWebSearchResultLocation {
  type: 'web_search_result_location';
  cited_text: string;
  web_search_result_index: number;
}

interface CitationsConfigParam {
  enabled: boolean;
}
```

### Thinking Configuration

```typescript { .api }
type ThinkingConfigParam =
  | ThinkingConfigEnabled
  | ThinkingConfigDisabled;

interface ThinkingConfigEnabled {
  type: 'enabled';
  budget_tokens?: number;
}

interface ThinkingConfigDisabled {
  type: 'disabled';
}
```

### Caching

```typescript { .api }
interface CacheControlEphemeral {
  type: 'ephemeral';
  ttl?: '5m' | '1h';
}

interface CacheCreation {
  ephemeral_5m_input_tokens: number;
  ephemeral_1h_input_tokens: number;
}
```

### Metadata

```typescript { .api }
interface Metadata {
  user_id?: string;
  [key: string]: string | undefined;
}
```

### Models

```typescript { .api }
type Model =
  | 'claude-opus-4-5-20250514'
  | 'claude-sonnet-4-5-20250929'
  | 'claude-3-5-sonnet-20241022'
  | 'claude-3-5-haiku-20241022'
  | 'claude-3-opus-20240229'
  | 'claude-3-sonnet-20240229'
  | 'claude-3-haiku-20240307'
  | (string & {});  // Allow other strings
```

## Streaming Types

### Stream Events

```typescript { .api }
type MessageStreamEvent =
  | MessageStartEvent
  | MessageDeltaEvent
  | MessageStopEvent
  | ContentBlockStartEvent
  | ContentBlockDeltaEvent
  | ContentBlockStopEvent;

interface MessageStartEvent {
  type: 'message_start';
  message: Message;
}

interface MessageDeltaEvent {
  type: 'message_delta';
  delta: {
    stop_reason: StopReason | null;
    stop_sequence: string | null;
  };
  usage: MessageDeltaUsage;
}

interface MessageStopEvent {
  type: 'message_stop';
}

interface ContentBlockStartEvent {
  type: 'content_block_start';
  index: number;
  content_block: ContentBlock;
}

interface ContentBlockDeltaEvent {
  type: 'content_block_delta';
  index: number;
  delta: RawContentBlockDelta;
}

interface ContentBlockStopEvent {
  type: 'content_block_stop';
  index: number;
}

interface MessageDeltaUsage {
  output_tokens: number;
}
```

### Delta Types

```typescript { .api }
type RawContentBlockDelta =
  | TextDelta
  | ThinkingDelta
  | InputJSONDelta
  | CitationsDelta
  | SignatureDelta;

interface TextDelta {
  type: 'text_delta';
  text: string;
}

interface ThinkingDelta {
  type: 'thinking_delta';
  thinking: string;
}

interface InputJSONDelta {
  type: 'input_json_delta';
  partial_json: string;
}

interface CitationsDelta {
  type: 'citations_delta';
  citations: TextCitation[];
}

interface SignatureDelta {
  type: 'signature_delta';
  signature: string;
}
```

## Beta Types

### Beta Messages

All message types have Beta equivalents with `Beta` prefix:

```typescript { .api }
interface BetaMessage extends Message {
  // Additional beta-specific fields
}

interface BetaMessageParam extends MessageParam {
  // Additional beta-specific fields
}

type BetaContentBlock = ContentBlock | /* beta-specific blocks */;
type BetaContentBlockParam = ContentBlockParam | /* beta-specific params */;
```

### Beta Tools

```typescript { .api }
interface BetaCodeExecutionTool20250522 {
  type: 'code_execution_20250522';
  name: 'code_execution';
}

interface BetaCodeExecutionTool20250825 {
  type: 'code_execution_20250825';
  name: 'code_execution';
}

interface BetaToolBash20241022 {
  type: 'bash_20241022';
  name: 'bash';
}

interface BetaToolBash20250124 {
  type: 'bash_20250124';
  name: 'bash';
}

interface BetaToolTextEditor20241022 {
  type: 'text_editor_20241022';
  name: 'str_replace_editor';
}

interface BetaToolTextEditor20250124 {
  type: 'text_editor_20250124';
  name: 'str_replace_editor';
}

interface BetaToolTextEditor20250429 {
  type: 'text_editor_20250429';
  name: 'str_replace_editor';
}

interface BetaToolTextEditor20250728 {
  type: 'text_editor_20250728';
  name: 'str_replace_editor';
}

interface BetaToolComputerUse20241022 {
  type: 'computer_use_20241022';
  name: 'computer';
  display_width_px: number;
  display_height_px: number;
  display_number?: number;
}

interface BetaToolComputerUse20250124 {
  type: 'computer_use_20250124';
  name: 'computer';
  display_width_px: number;
  display_height_px: number;
  display_number?: number;
}

interface BetaWebFetchTool20250910 {
  type: 'web_fetch_20250910';
  name: 'web_fetch';
}

interface BetaWebSearchTool20250305 {
  type: 'web_search_20250305';
  name: 'web_search';
}

interface BetaMemoryTool20250818 {
  type: 'memory_20250818';
  name: 'memory';
  commands: {
    create?: BetaMemoryTool20250818CreateCommand;
    view?: BetaMemoryTool20250818ViewCommand;
    delete?: BetaMemoryTool20250818DeleteCommand;
    insert?: BetaMemoryTool20250818InsertCommand;
    str_replace?: BetaMemoryTool20250818StrReplaceCommand;
    rename?: BetaMemoryTool20250818RenameCommand;
  };
}
```

### Beta Context Management

```typescript { .api }
interface BetaContextManagementConfig {
  input_tokens_clear_at_least?: number;
  tool_uses?: BetaToolUsesTrigger;
  thinking_turns?: BetaThinkingTurns;
}

interface BetaToolUsesTrigger {
  keep: number;
}

type BetaThinkingTurns =
  | { keep: 'all' }
  | { keep: 'none' };

interface BetaContextManagementResponse {
  input_tokens_clear_at_least?: number;
  tool_uses_kept?: number;
  thinking_turns_kept?: 'all' | 'none';
}
```

### Beta Output Formats

```typescript { .api }
interface BetaJSONOutputFormat {
  type: 'json_schema';
  schema: JSONSchema;
}

interface AutoParseableBetaOutputFormat<ParsedT> {
  type: 'json_schema';
  schema: JSONSchema;
  parse: (content: string) => ParsedT;
}
```

### Beta MCP

```typescript { .api }
interface BetaRequestMCPServerToolConfiguration {
  url: string;
  tools: string[] | '*';
}

interface BetaRequestMCPServerURLDefinition {
  url: string;
}
```

### Beta Container

```typescript { .api }
interface BetaContainer {
  id: string;
  type: 'container';
  status: 'running' | 'stopped';
}

interface BetaContainerParams {
  container_id?: string;
}
```

### Beta Skills

```typescript { .api }
interface BetaSkill {
  type: 'skill';
  skill_id: string;
  version?: string;
}

interface BetaSkillParams {
  type: 'skill';
  skill_id: string;
  version?: string;
}
```

## Batch Types

```typescript { .api }
interface MessageBatch {
  id: string;
  type: 'message_batch';
  processing_status: 'in_progress' | 'canceling' | 'ended';
  request_counts: MessageBatchRequestCounts;
  ended_at: string | null;
  created_at: string;
  expires_at: string;
  archived_at: string | null;
  cancel_initiated_at: string | null;
  results_url: string | null;
}

interface MessageBatchRequestCounts {
  processing: number;
  succeeded: number;
  errored: number;
  canceled: number;
  expired: number;
}

interface MessageBatchIndividualResponse {
  custom_id: string;
  result: MessageBatchResult;
}

type MessageBatchResult =
  | MessageBatchSucceededResult
  | MessageBatchErroredResult
  | MessageBatchCanceledResult
  | MessageBatchExpiredResult;

interface MessageBatchSucceededResult {
  type: 'succeeded';
  message: Message;
}

interface MessageBatchErroredResult {
  type: 'errored';
  error: {
    type: string;
    message: string;
  };
}

interface MessageBatchCanceledResult {
  type: 'canceled';
}

interface MessageBatchExpiredResult {
  type: 'expired';
}

interface DeletedMessageBatch {
  id: string;
  type: 'message_batch';
  deleted: boolean;
}
```

## Model Types

```typescript { .api }
interface ModelInfo {
  type: 'model';
  id: string;
  display_name: string;
  created_at: string;
}
```

## File Types (Beta)

```typescript { .api }
interface FileMetadata {
  id: string;
  type: 'file';
  filename: string;
  size: number;
  created_at: string;
}

interface DeletedFile {
  id: string;
  type: 'file';
  deleted: boolean;
}
```

## Skill Types (Beta)

```typescript { .api }
interface SkillCreateResponse {
  id: string;
  type: 'skill';
  name: string;
  description: string;
  created_at: string;
}

interface SkillRetrieveResponse {
  id: string;
  type: 'skill';
  name: string;
  description: string;
  created_at: string;
  versions: VersionListResponse[];
}

interface SkillListResponse {
  id: string;
  type: 'skill';
  name: string;
  description: string;
  created_at: string;
}

interface SkillDeleteResponse {
  id: string;
  type: 'skill';
  deleted: boolean;
}

interface VersionCreateResponse {
  id: string;
  skill_id: string;
  version: string;
  created_at: string;
}

interface VersionRetrieveResponse {
  id: string;
  skill_id: string;
  version: string;
  definition: any;
  created_at: string;
}

interface VersionListResponse {
  id: string;
  version: string;
  created_at: string;
}

interface VersionDeleteResponse {
  id: string;
  deleted: boolean;
}
```

## Error Types

```typescript { .api }
interface ErrorResponse {
  type: 'error';
  error: ErrorObject;
}

type ErrorObject =
  | InvalidRequestError
  | AuthenticationError
  | BillingError
  | PermissionError
  | NotFoundError
  | RateLimitError
  | GatewayTimeoutError
  | APIErrorObject
  | OverloadedError;

interface InvalidRequestError {
  type: 'invalid_request_error';
  message: string;
}

interface AuthenticationError {
  type: 'authentication_error';
  message: string;
}

interface BillingError {
  type: 'billing_error';
  message: string;
}

interface PermissionError {
  type: 'permission_error';
  message: string;
}

interface NotFoundError {
  type: 'not_found_error';
  message: string;
}

interface RateLimitError {
  type: 'rate_limit_error';
  message: string;
}

interface GatewayTimeoutError {
  type: 'gateway_timeout_error';
  message: string;
}

interface APIErrorObject {
  type: 'api_error';
  message: string;
}

interface OverloadedError {
  type: 'overloaded_error';
  message: string;
}
```

## Pagination Types

```typescript { .api }
interface Page<Item> {
  data: Item[];
  has_more: boolean;
  first_id: string | null;
  last_id: string | null;
}

interface TokenPage<Item> {
  data: Item[];
  has_more: boolean;
  next_page: string | null;
}

interface PageCursor<Item> {
  data: Item[];
  has_more: boolean;
  next_page: string | null;
}

interface PageParams {
  before_id?: string;
  after_id?: string;
  limit?: number;
}

interface TokenPageParams {
  page_token?: string;
  limit?: number;
}

interface PageCursorParams {
  next_page?: string;
  limit?: number;
}
```

## Request Options

```typescript { .api }
interface RequestOptions {
  timeout?: number;
  maxRetries?: number;
  headers?: HeadersLike;
  query?: Record<string, string | undefined>;
  signal?: AbortSignal;
  idempotencyKey?: string;
}

type HeadersLike = Record<string, string | string[] | undefined> | Headers;
```

## Utility Types

```typescript { .api }
type Promisable<T> = T | Promise<T>;

type Uploadable = File | Blob | ReadStream | Response;

interface FileLike {
  name: string;
  type: string;
  size: number;
  arrayBuffer(): Promise<ArrayBuffer>;
  slice(start?: number, end?: number): Blob;
}

type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'off';

interface Logger {
  debug(...args: any[]): void;
  info(...args: any[]): void;
  warn(...args: any[]): void;
  error(...args: any[]): void;
}

type AnthropicBeta = string;  // See beta-features.md for full list
```

## Promise Utilities

### APIPromise

A subclass of `Promise` providing additional helper methods for interacting with the SDK.

```typescript { .api }
/**
 * A Promise subclass with additional helper methods.
 * All API methods return this type to provide extra functionality.
 */
class APIPromise<T> extends Promise<WithRequestID<T>> {
  /**
   * Gets the raw Response instance instead of parsing the response data.
   * If you want to parse the response body but still get the Response instance,
   * use withResponse() instead.
   */
  asResponse(): Promise<Response>;

  /**
   * Gets the parsed response data, the raw Response instance, and the request ID
   * returned via the 'request-id' header (useful for debugging and reporting issues).
   */
  withResponse(): Promise<{
    data: T;
    response: Response;
    request_id: string | null | undefined;
  }>;
}

interface WithRequestID<T> extends T {
  _request_id?: string | null;
}
```

### PagePromise

A Promise subclass for paginated responses that also implements `AsyncIterable` for auto-paginating iteration.

```typescript { .api }
/**
 * Promise that resolves to a Page instance.
 * Also implements AsyncIterable for auto-paginating iteration.
 *
 * Example:
 *   for await (const item of client.models.list()) {
 *     console.log(item);
 *   }
 */
class PagePromise<PageClass extends AbstractPage<Item>, Item>
  extends APIPromise<PageClass>
  implements AsyncIterable<Item>
{
  [Symbol.asyncIterator](): AsyncIterator<Item>;
}
```

## Type Utilities

```typescript { .api }
// Extract parsed type from beta params
type ExtractParsedContentFromBetaParams<Params> =
  Params extends { output_format: AutoParseableBetaOutputFormat<infer T> }
    ? T
    : never;

// Merge request init options
interface MergedRequestInit extends RequestInit {
  // Runtime-specific extensions
}
```

## See Also

- [Messages API](./messages.md) - Using message types
- [Streaming](./streaming.md) - Stream event types
- [Tools](./tools.md) - Tool type definitions
- [Beta Features](./beta-features.md) - Beta type definitions
- [Errors](./errors.md) - Error type definitions
