or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

batches.mdbeta-features.mdclient.mdcompletions.mderrors.mdfiles.mdindex.mdmessages.mdmodels.mdskills.mdstreaming.mdtools.mdtypes.md
tile.json

types.mddocs/

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

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)

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)

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

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

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

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

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

type ThinkingConfigParam =
  | ThinkingConfigEnabled
  | ThinkingConfigDisabled;

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

interface ThinkingConfigDisabled {
  type: 'disabled';
}

Caching

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

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

Metadata

interface Metadata {
  user_id?: string;
  [key: string]: string | undefined;
}

Models

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

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

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:

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

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

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

interface BetaJSONOutputFormat {
  type: 'json_schema';
  schema: JSONSchema;
}

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

Beta MCP

interface BetaRequestMCPServerToolConfiguration {
  url: string;
  tools: string[] | '*';
}

interface BetaRequestMCPServerURLDefinition {
  url: string;
}

Beta Container

interface BetaContainer {
  id: string;
  type: 'container';
  status: 'running' | 'stopped';
}

interface BetaContainerParams {
  container_id?: string;
}

Beta Skills

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

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

Batch Types

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

interface ModelInfo {
  type: 'model';
  id: string;
  display_name: string;
  created_at: string;
}

File Types (Beta)

interface FileMetadata {
  id: string;
  type: 'file';
  filename: string;
  size: number;
  created_at: string;
}

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

Skill Types (Beta)

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

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

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

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

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.

/**
 * 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.

/**
 * 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

// 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 - Using message types
  • Streaming - Stream event types
  • Tools - Tool type definitions
  • Beta Features - Beta type definitions
  • Errors - Error type definitions