@anthropic-ai/sdk/src/resources/beta/messages/messages.ts

The official TypeScript library for the Anthropic API

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { AnthropicError } from '../../../error';
import { Anthropic } from '../../../client';
import * as BatchesAPI from './batches';
import { APIPromise } from '../../../core/api-promise';
import { APIResource } from '../../../core/resource';
import { Stream } from '../../../core/streaming';
import { MODEL_NONSTREAMING_TOKENS } from '../../../internal/constants';
import { buildHeaders } from '../../../internal/headers';
import { RequestOptions } from '../../../internal/request-options';
import { stainlessHelperHeader } from '../../../internal/stainless-helper-header';
import {
  parseBetaMessage,
  type ExtractParsedContentFromBetaParams,
  type ParsedBetaMessage,
} from '../../../lib/beta-parser';
import { BetaMessageStream } from '../../../lib/BetaMessageStream';
import {
  BetaToolRunner,
  BetaToolRunnerParams,
  BetaToolRunnerRequestOptions,
} from '../../../lib/tools/BetaToolRunner';
import { ToolError } from '../../../lib/tools/ToolError';
import type { Model } from '../../messages/messages';
import * as BetaMessagesAPI from './messages';
import * as MessagesAPI from '../../messages/messages';
import * as BetaAPI from '../beta';
import {
  BatchCancelParams,
  BatchCreateParams,
  BatchDeleteParams,
  BatchListParams,
  BatchResultsParams,
  BatchRetrieveParams,
  Batches,
  BetaDeletedMessageBatch,
  BetaMessageBatch,
  BetaMessageBatchCanceledResult,
  BetaMessageBatchErroredResult,
  BetaMessageBatchExpiredResult,
  BetaMessageBatchIndividualResponse,
  BetaMessageBatchRequestCounts,
  BetaMessageBatchResult,
  BetaMessageBatchSucceededResult,
  BetaMessageBatchesPage,
} from './batches';

const DEPRECATED_MODELS: {
  [K in Model]?: string;
} = {
  'claude-1.3': 'November 6th, 2024',
  'claude-1.3-100k': 'November 6th, 2024',
  'claude-instant-1.1': 'November 6th, 2024',
  'claude-instant-1.1-100k': 'November 6th, 2024',
  'claude-instant-1.2': 'November 6th, 2024',
  'claude-3-sonnet-20240229': 'July 21st, 2025',
  'claude-3-opus-20240229': 'January 5th, 2026',
  'claude-2.1': 'July 21st, 2025',
  'claude-2.0': 'July 21st, 2025',
  'claude-3-7-sonnet-latest': 'February 19th, 2026',
  'claude-3-7-sonnet-20250219': 'February 19th, 2026',
  'claude-3-5-haiku-latest': 'February 19th, 2026',
  'claude-3-5-haiku-20241022': 'February 19th, 2026',
  'claude-opus-4-0': 'June 15th, 2026',
  'claude-opus-4-20250514': 'June 15th, 2026',
  'claude-sonnet-4-0': 'June 15th, 2026',
  'claude-sonnet-4-20250514': 'June 15th, 2026',
  'claude-opus-4-1': 'August 5th, 2026',
  'claude-opus-4-1-20250805': 'August 5th, 2026',
  'claude-mythos-preview': 'June 30th, 2026',
};

const MODELS_TO_WARN_WITH_THINKING_ENABLED: Model[] = ['claude-mythos-preview', 'claude-opus-4-6'];

export class Messages extends APIResource {
  batches: BatchesAPI.Batches = new BatchesAPI.Batches(this._client);

  /**
   * Send a structured list of input messages with text and/or image content, and the
   * model will generate the next message in the conversation.
   *
   * The Messages API can be used for either single queries or stateless multi-turn
   * conversations.
   *
   * Learn more about the Messages API in our
   * [user guide](https://platform.claude.com/docs/en/get-started)
   *
   * @example
   * ```ts
   * const betaMessage = await client.beta.messages.create({
   *   max_tokens: 1024,
   *   messages: [{ content: 'Hello, world', role: 'user' }],
   *   model: 'claude-opus-4-6',
   * });
   * ```
   */
  create(params: MessageCreateParamsNonStreaming, options?: RequestOptions): APIPromise<BetaMessage>;
  create(
    params: MessageCreateParamsStreaming,
    options?: RequestOptions,
  ): APIPromise<Stream<BetaRawMessageStreamEvent>>;
  create(
    params: MessageCreateParamsBase,
    options?: RequestOptions,
  ): APIPromise<Stream<BetaRawMessageStreamEvent> | BetaMessage>;
  create(
    params: MessageCreateParams,
    options?: RequestOptions,
  ): APIPromise<BetaMessage> | APIPromise<Stream<BetaRawMessageStreamEvent>> {
    // Transform deprecated output_format to output_config.format
    const modifiedParams = transformOutputFormat(params);

    const { betas, user_profile_id, ...body } = modifiedParams;

    if (body.model in DEPRECATED_MODELS) {
      console.warn(
        `The model '${body.model}' is deprecated and will reach end-of-life on ${
          DEPRECATED_MODELS[body.model]
        }\nPlease migrate to a newer model. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.`,
      );
    }

    if (
      MODELS_TO_WARN_WITH_THINKING_ENABLED.includes(body.model) &&
      body.thinking &&
      body.thinking.type === 'enabled'
    ) {
      console.warn(
        `Using Claude with ${body.model} and 'thinking.type=enabled' is deprecated. Use 'thinking.type=adaptive' instead which results in better model performance in our testing: https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking`,
      );
    }

    let timeout = (this._client as any)._options.timeout as number | null;
    if (!body.stream && timeout == null) {
      const maxNonstreamingTokens = MODEL_NONSTREAMING_TOKENS[body.model] ?? undefined;
      timeout = this._client.calculateNonstreamingTimeout(body.max_tokens, maxNonstreamingTokens);
    }

    // Collect helper info from tools and messages
    const helperHeader = stainlessHelperHeader(body.tools, body.messages);

    return this._client.post('/v1/messages?beta=true', {
      body,
      timeout: timeout ?? 600000,
      ...options,
      headers: buildHeaders([
        {
          ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined),
          ...(user_profile_id != null ? { 'anthropic-user-profile-id': user_profile_id } : undefined),
        },
        helperHeader,
        options?.headers,
      ]),
      stream: modifiedParams.stream ?? false,
    }) as APIPromise<BetaMessage> | APIPromise<Stream<BetaRawMessageStreamEvent>>;
  }

  /**
   * Send a structured list of input messages with text and/or image content, along with an expected `output_format` and
   * the response will be automatically parsed and available in the `parsed_output` property of the message.
   *
   * @example
   * ```ts
   * const message = await client.beta.messages.parse({
   *   model: 'claude-3-5-sonnet-20241022',
   *   max_tokens: 1024,
   *   messages: [{ role: 'user', content: 'What is 2+2?' }],
   *   output_format: zodOutputFormat(z.object({ answer: z.number() }), 'math'),
   * });
   *
   * console.log(message.parsed_output?.answer); // 4
   * ```
   */
  parse<Params extends MessageCreateParamsNonStreaming>(
    params: Params,
    options?: RequestOptions,
  ): APIPromise<ParsedBetaMessage<ExtractParsedContentFromBetaParams<Params>>> {
    options = {
      ...options,
      headers: buildHeaders([
        { 'anthropic-beta': [...(params.betas ?? []), 'structured-outputs-2025-12-15'].toString() },
        options?.headers,
      ]),
    };

    return this.create(params, options).then((message) =>
      parseBetaMessage(message, params, { logger: this._client.logger ?? console }),
    ) as APIPromise<ParsedBetaMessage<ExtractParsedContentFromBetaParams<Params>>>;
  }

  /**
   * Create a Message stream
   */
  stream<Params extends BetaMessageStreamParams>(
    body: Params,
    options?: RequestOptions,
  ): BetaMessageStream<ExtractParsedContentFromBetaParams<Params>> {
    return BetaMessageStream.createMessage(this, body, options);
  }

  /**
   * Count the number of tokens in a Message.
   *
   * The Token Count API can be used to count the number of tokens in a Message,
   * including tools, images, and documents, without creating it.
   *
   * Learn more about token counting in our
   * [user guide](https://platform.claude.com/docs/en/build-with-claude/token-counting)
   *
   * @example
   * ```ts
   * const betaMessageTokensCount =
   *   await client.beta.messages.countTokens({
   *     messages: [{ content: 'Hello, world', role: 'user' }],
   *     model: 'claude-opus-4-6',
   *   });
   * ```
   */
  countTokens(
    params: MessageCountTokensParams,
    options?: RequestOptions,
  ): APIPromise<BetaMessageTokensCount> {
    // Transform deprecated output_format to output_config.format
    const modifiedParams = transformOutputFormat(params);

    const { betas, user_profile_id, ...body } = modifiedParams;
    return this._client.post('/v1/messages/count_tokens?beta=true', {
      body,
      ...options,
      headers: buildHeaders([
        {
          'anthropic-beta': [...(betas ?? []), 'token-counting-2024-11-01'].toString(),
          ...(user_profile_id != null ? { 'anthropic-user-profile-id': user_profile_id } : undefined),
        },
        options?.headers,
      ]),
    });
  }

  toolRunner(
    body: BetaToolRunnerParams & { stream?: false },
    options?: BetaToolRunnerRequestOptions,
  ): BetaToolRunner<false>;
  toolRunner(
    body: BetaToolRunnerParams & { stream: true },
    options?: BetaToolRunnerRequestOptions,
  ): BetaToolRunner<true>;
  toolRunner(body: BetaToolRunnerParams, options?: BetaToolRunnerRequestOptions): BetaToolRunner<boolean>;
  toolRunner(body: BetaToolRunnerParams, options?: BetaToolRunnerRequestOptions): BetaToolRunner<boolean> {
    return new BetaToolRunner(this._client as Anthropic, body, options);
  }
}

/**
 * Transform deprecated output_format to output_config.format
 * Returns a modified copy of the params without mutating the original
 */
function transformOutputFormat<T extends MessageCreateParams | MessageCountTokensParams>(params: T): T {
  if (!params.output_format) {
    return params;
  }

  if (params.output_config?.format) {
    throw new AnthropicError(
      'Both output_format and output_config.format were provided. ' +
        'Please use only output_config.format (output_format is deprecated).',
    );
  }

  const { output_format, ...rest } = params;

  return {
    ...rest,
    output_config: {
      ...params.output_config,
      format: output_format,
    },
  } as T;
}

/**
 * Token usage for an advisor sub-inference iteration.
 */
export interface BetaAdvisorMessageIterationUsage {
  /**
   * Breakdown of cached tokens by TTL
   */
  cache_creation: BetaCacheCreation | null;

  /**
   * The number of input tokens used to create the cache entry.
   */
  cache_creation_input_tokens: number;

  /**
   * The number of input tokens read from the cache.
   */
  cache_read_input_tokens: number;

  /**
   * The number of input tokens which were used.
   */
  input_tokens: number;

  /**
   * The model that will complete your prompt.
   *
   * See [models](https://docs.anthropic.com/en/docs/models-overview) for additional
   * details and options.
   */
  model: MessagesAPI.Model;

  /**
   * The number of output tokens which were used.
   */
  output_tokens: number;

  /**
   * Usage for an advisor sub-inference iteration
   */
  type: 'advisor_message';
}

export interface BetaAdvisorRedactedResultBlock {
  /**
   * Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect
   * or modify.
   */
  encrypted_content: string;

  /**
   * The advisor sub-inference's stop reason (same values as the top-level message
   * `stop_reason`).
   */
  stop_reason: string | null;

  type: 'advisor_redacted_result';
}

export interface BetaAdvisorRedactedResultBlockParam {
  /**
   * Opaque blob produced by a prior response; must be round-tripped verbatim.
   */
  encrypted_content: string;

  type: 'advisor_redacted_result';

  stop_reason?: string | null;
}

export interface BetaAdvisorResultBlock {
  /**
   * The advisor sub-inference's stop reason (same values as the top-level message
   * `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the
   * tool's `max_tokens` value or the advisor model's policy cap.
   */
  stop_reason: string | null;

  text: string;

  type: 'advisor_result';
}

export interface BetaAdvisorResultBlockParam {
  text: string;

  type: 'advisor_result';

  stop_reason?: string | null;
}

export interface BetaAdvisorTool20260301 {
  /**
   * The model that will complete your prompt.
   *
   * See [models](https://docs.anthropic.com/en/docs/models-overview) for additional
   * details and options.
   */
  model: MessagesAPI.Model;

  /**
   * Name of the tool.
   *
   * This is how the tool will be called by the model and in `tool_use` blocks.
   */
  name: 'advisor';

  type: 'advisor_20260301';

  allowed_callers?: Array<
    'direct' | 'code_execution_20250825' | 'code_execution_20260120' | 'code_execution_20260521'
  >;

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;

  /**
   * Caching for the advisor's own prompt. When set, each advisor call writes a cache
   * entry at the given TTL so subsequent calls in the same conversation read the
   * stable prefix. When omitted, the advisor prompt is not cached.
   */
  caching?: BetaCacheControlEphemeral | null;

  /**
   * If true, tool will not be included in initial system prompt. Only loaded when
   * returned via tool_reference from tool search.
   */
  defer_loading?: boolean;

  /**
   * Bounds the advisor's total output (thinking + text) per call. When the advisor
   * hits this cap, the returned advisor_result or advisor_redacted_result block
   * carries stop_reason='max_tokens', and a truncation note is appended to the
   * advice text the worker model sees (inside the encrypted blob in redacted mode).
   * When set, the server also emits a remaining-tokens budget block in the advisor's
   * prompt so the advisor self-shapes toward the cap. When omitted, the advisor
   * model's default output cap applies and no budget block is emitted.
   */
  max_tokens?: number | null;

  /**
   * Maximum number of times the tool can be used in the API request.
   */
  max_uses?: number | null;

  /**
   * When true, guarantees schema validation on tool names and inputs
   */
  strict?: boolean;
}

export interface BetaAdvisorToolResultBlock {
  content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock;

  tool_use_id: string;

  type: 'advisor_tool_result';
}

export interface BetaAdvisorToolResultBlockParam {
  content:
    | BetaAdvisorToolResultErrorParam
    | BetaAdvisorResultBlockParam
    | BetaAdvisorRedactedResultBlockParam;

  tool_use_id: string;

  type: 'advisor_tool_result';

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;
}

export interface BetaAdvisorToolResultError {
  error_code:
    | 'max_uses_exceeded'
    | 'prompt_too_long'
    | 'too_many_requests'
    | 'overloaded'
    | 'unavailable'
    | 'execution_time_exceeded'
    | 'model_not_found';

  type: 'advisor_tool_result_error';
}

export interface BetaAdvisorToolResultErrorParam {
  error_code:
    | 'max_uses_exceeded'
    | 'prompt_too_long'
    | 'too_many_requests'
    | 'overloaded'
    | 'unavailable'
    | 'execution_time_exceeded'
    | 'model_not_found';

  type: 'advisor_tool_result_error';
}

export interface BetaAllThinkingTurns {
  type: 'all';
}

export type BetaMessageStreamParams = MessageCreateParamsBase;

export interface BetaBase64ImageSource {
  data: string;

  media_type: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';

  type: 'base64';
}

export interface BetaBase64PDFSource {
  data: string;

  media_type: 'application/pdf';

  type: 'base64';
}

export interface BetaBashCodeExecutionOutputBlock {
  file_id: string;

  type: 'bash_code_execution_output';
}

export interface BetaBashCodeExecutionOutputBlockParam {
  file_id: string;

  type: 'bash_code_execution_output';
}

export interface BetaBashCodeExecutionResultBlock {
  content: Array<BetaBashCodeExecutionOutputBlock>;

  return_code: number;

  stderr: string;

  stdout: string;

  type: 'bash_code_execution_result';
}

export interface BetaBashCodeExecutionResultBlockParam {
  content: Array<BetaBashCodeExecutionOutputBlockParam>;

  return_code: number;

  stderr: string;

  stdout: string;

  type: 'bash_code_execution_result';
}

export interface BetaBashCodeExecutionToolResultBlock {
  content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock;

  tool_use_id: string;

  type: 'bash_code_execution_tool_result';
}

export interface BetaBashCodeExecutionToolResultBlockParam {
  content: BetaBashCodeExecutionToolResultErrorParam | BetaBashCodeExecutionResultBlockParam;

  tool_use_id: string;

  type: 'bash_code_execution_tool_result';

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;
}

export interface BetaBashCodeExecutionToolResultError {
  error_code:
    | 'invalid_tool_input'
    | 'unavailable'
    | 'too_many_requests'
    | 'execution_time_exceeded'
    | 'output_file_too_large';

  type: 'bash_code_execution_tool_result_error';
}

export interface BetaBashCodeExecutionToolResultErrorParam {
  error_code:
    | 'invalid_tool_input'
    | 'unavailable'
    | 'too_many_requests'
    | 'execution_time_exceeded'
    | 'output_file_too_large';

  type: 'bash_code_execution_tool_result_error';
}

export interface BetaCacheControlEphemeral {
  type: 'ephemeral';

  /**
   * The time-to-live for the cache control breakpoint.
   *
   * This may be one the following values:
   *
   * - `5m`: 5 minutes
   * - `1h`: 1 hour
   *
   * Defaults to `5m`. See
   * [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
   * for details.
   */
  ttl?: '5m' | '1h';
}

export interface BetaCacheCreation {
  /**
   * The number of input tokens used to create the 1 hour cache entry.
   */
  ephemeral_1h_input_tokens: number;

  /**
   * The number of input tokens used to create the 5 minute cache entry.
   */
  ephemeral_5m_input_tokens: number;
}

export interface BetaCacheMissMessagesChanged {
  /**
   * Approximate number of input tokens that would have been read from cache had the
   * prefix matched the previous request.
   */
  cache_missed_input_tokens: number;

  type: 'messages_changed';
}

export interface BetaCacheMissModelChanged {
  /**
   * Approximate number of input tokens that would have been read from cache had the
   * prefix matched the previous request.
   */
  cache_missed_input_tokens: number;

  type: 'model_changed';
}

export interface BetaCacheMissPreviousMessageNotFound {
  type: 'previous_message_not_found';
}

export interface BetaCacheMissSystemChanged {
  /**
   * Approximate number of input tokens that would have been read from cache had the
   * prefix matched the previous request.
   */
  cache_missed_input_tokens: number;

  type: 'system_changed';
}

export interface BetaCacheMissToolsChanged {
  /**
   * Approximate number of input tokens that would have been read from cache had the
   * prefix matched the previous request.
   */
  cache_missed_input_tokens: number;

  type: 'tools_changed';
}

export interface BetaCacheMissUnavailable {
  type: 'unavailable';
}

export interface BetaCitationCharLocation {
  cited_text: string;

  document_index: number;

  document_title: string | null;

  end_char_index: number;

  file_id: string | null;

  start_char_index: number;

  type: 'char_location';
}

export interface BetaCitationCharLocationParam {
  cited_text: string;

  document_index: number;

  document_title: string | null;

  end_char_index: number;

  start_char_index: number;

  type: 'char_location';
}

export interface BetaCitationConfig {
  enabled: boolean;
}

export interface BetaCitationContentBlockLocation {
  /**
   * The full text of the cited block range, concatenated.
   *
   * Always equals the contents of `content[start_block_index:end_block_index]`
   * joined together. The text block is the minimal citable unit; this field is never
   * a substring of a single block. Not counted toward output tokens, and not counted
   * toward input tokens when sent back in subsequent turns.
   */
  cited_text: string;

  document_index: number;

  document_title: string | null;

  /**
   * Exclusive 0-based end index of the cited block range in the source's `content`
   * array.
   *
   * Always greater than `start_block_index`; a single-block citation has
   * `end_block_index = start_block_index + 1`.
   */
  end_block_index: number;

  file_id: string | null;

  /**
   * 0-based index of the first cited block in the source's `content` array.
   */
  start_block_index: number;

  type: 'content_block_location';
}

export interface BetaCitationContentBlockLocationParam {
  /**
   * The full text of the cited block range, concatenated.
   *
   * Always equals the contents of `content[start_block_index:end_block_index]`
   * joined together. The text block is the minimal citable unit; this field is never
   * a substring of a single block. Not counted toward output tokens, and not counted
   * toward input tokens when sent back in subsequent turns.
   */
  cited_text: string;

  document_index: number;

  document_title: string | null;

  /**
   * Exclusive 0-based end index of the cited block range in the source's `content`
   * array.
   *
   * Always greater than `start_block_index`; a single-block citation has
   * `end_block_index = start_block_index + 1`.
   */
  end_block_index: number;

  /**
   * 0-based index of the first cited block in the source's `content` array.
   */
  start_block_index: number;

  type: 'content_block_location';
}

export interface BetaCitationPageLocation {
  cited_text: string;

  document_index: number;

  document_title: string | null;

  end_page_number: number;

  file_id: string | null;

  start_page_number: number;

  type: 'page_location';
}

export interface BetaCitationPageLocationParam {
  cited_text: string;

  document_index: number;

  document_title: string | null;

  end_page_number: number;

  start_page_number: number;

  type: 'page_location';
}

export interface BetaCitationSearchResultLocation {
  /**
   * The full text of the cited block range, concatenated.
   *
   * Always equals the contents of `content[start_block_index:end_block_index]`
   * joined together. The text block is the minimal citable unit; this field is never
   * a substring of a single block. Not counted toward output tokens, and not counted
   * toward input tokens when sent back in subsequent turns.
   */
  cited_text: string;

  /**
   * Exclusive 0-based end index of the cited block range in the source's `content`
   * array.
   *
   * Always greater than `start_block_index`; a single-block citation has
   * `end_block_index = start_block_index + 1`.
   */
  end_block_index: number;

  /**
   * 0-based index of the cited search result among all `search_result` content
   * blocks in the request, in the order they appear across messages and tool
   * results.
   *
   * Counted separately from `document_index`; server-side web search results are not
   * included in this count.
   */
  search_result_index: number;

  source: string;

  /**
   * 0-based index of the first cited block in the source's `content` array.
   */
  start_block_index: number;

  title: string | null;

  type: 'search_result_location';
}

export interface BetaCitationSearchResultLocationParam {
  /**
   * The full text of the cited block range, concatenated.
   *
   * Always equals the contents of `content[start_block_index:end_block_index]`
   * joined together. The text block is the minimal citable unit; this field is never
   * a substring of a single block. Not counted toward output tokens, and not counted
   * toward input tokens when sent back in subsequent turns.
   */
  cited_text: string;

  /**
   * Exclusive 0-based end index of the cited block range in the source's `content`
   * array.
   *
   * Always greater than `start_block_index`; a single-block citation has
   * `end_block_index = start_block_index + 1`.
   */
  end_block_index: number;

  /**
   * 0-based index of the cited search result among all `search_result` content
   * blocks in the request, in the order they appear across messages and tool
   * results.
   *
   * Counted separately from `document_index`; server-side web search results are not
   * included in this count.
   */
  search_result_index: number;

  source: string;

  /**
   * 0-based index of the first cited block in the source's `content` array.
   */
  start_block_index: number;

  title: string | null;

  type: 'search_result_location';
}

export interface BetaCitationWebSearchResultLocationParam {
  cited_text: string;

  encrypted_index: string;

  title: string | null;

  type: 'web_search_result_location';

  url: string;
}

export interface BetaCitationsConfigParam {
  enabled?: boolean;
}

export interface BetaCitationsDelta {
  citation:
    | BetaCitationCharLocation
    | BetaCitationPageLocation
    | BetaCitationContentBlockLocation
    | BetaCitationsWebSearchResultLocation
    | BetaCitationSearchResultLocation;

  type: 'citations_delta';
}

export interface BetaCitationsWebSearchResultLocation {
  cited_text: string;

  encrypted_index: string;

  title: string | null;

  type: 'web_search_result_location';

  url: string;
}

export interface BetaClearThinking20251015Edit {
  type: 'clear_thinking_20251015';

  /**
   * Number of most recent assistant turns to keep thinking blocks for. Older turns
   * will have their thinking blocks removed.
   */
  keep?: BetaThinkingTurns | BetaAllThinkingTurns | 'all';
}

export interface BetaClearThinking20251015EditResponse {
  /**
   * Number of input tokens cleared by this edit.
   */
  cleared_input_tokens: number;

  /**
   * Number of thinking turns that were cleared.
   */
  cleared_thinking_turns: number;

  /**
   * The type of context management edit applied.
   */
  type: 'clear_thinking_20251015';
}

export interface BetaClearToolUses20250919Edit {
  type: 'clear_tool_uses_20250919';

  /**
   * Minimum number of tokens that must be cleared when triggered. Context will only
   * be modified if at least this many tokens can be removed.
   */
  clear_at_least?: BetaInputTokensClearAtLeast | null;

  /**
   * Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)
   */
  clear_tool_inputs?: boolean | Array<string> | null;

  /**
   * Tool names whose uses are preserved from clearing
   */
  exclude_tools?: Array<string> | null;

  /**
   * Number of tool uses to retain in the conversation
   */
  keep?: BetaToolUsesKeep;

  /**
   * Condition that triggers the context management strategy
   */
  trigger?: BetaInputTokensTrigger | BetaToolUsesTrigger;
}

export interface BetaClearToolUses20250919EditResponse {
  /**
   * Number of input tokens cleared by this edit.
   */
  cleared_input_tokens: number;

  /**
   * Number of tool uses that were cleared.
   */
  cleared_tool_uses: number;

  /**
   * The type of context management edit applied.
   */
  type: 'clear_tool_uses_20250919';
}

export interface BetaCodeExecutionOutputBlock {
  file_id: string;

  type: 'code_execution_output';
}

export interface BetaCodeExecutionOutputBlockParam {
  file_id: string;

  type: 'code_execution_output';
}

export interface BetaCodeExecutionResultBlock {
  content: Array<BetaCodeExecutionOutputBlock>;

  return_code: number;

  stderr: string;

  stdout: string;

  type: 'code_execution_result';
}

export interface BetaCodeExecutionResultBlockParam {
  content: Array<BetaCodeExecutionOutputBlockParam>;

  return_code: number;

  stderr: string;

  stdout: string;

  type: 'code_execution_result';
}

export interface BetaCodeExecutionTool20250522 {
  /**
   * Name of the tool.
   *
   * This is how the tool will be called by the model and in `tool_use` blocks.
   */
  name: 'code_execution';

  type: 'code_execution_20250522';

  allowed_callers?: Array<
    'direct' | 'code_execution_20250825' | 'code_execution_20260120' | 'code_execution_20260521'
  >;

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;

  /**
   * If true, tool will not be included in initial system prompt. Only loaded when
   * returned via tool_reference from tool search.
   */
  defer_loading?: boolean;

  /**
   * When true, guarantees schema validation on tool names and inputs
   */
  strict?: boolean;
}

export interface BetaCodeExecutionTool20250825 {
  /**
   * Name of the tool.
   *
   * This is how the tool will be called by the model and in `tool_use` blocks.
   */
  name: 'code_execution';

  type: 'code_execution_20250825';

  allowed_callers?: Array<
    'direct' | 'code_execution_20250825' | 'code_execution_20260120' | 'code_execution_20260521'
  >;

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;

  /**
   * If true, tool will not be included in initial system prompt. Only loaded when
   * returned via tool_reference from tool search.
   */
  defer_loading?: boolean;

  /**
   * When true, guarantees schema validation on tool names and inputs
   */
  strict?: boolean;
}

/**
 * Code execution tool with REPL state persistence (daemon mode + gVisor
 * checkpoint).
 */
export interface BetaCodeExecutionTool20260120 {
  /**
   * Name of the tool.
   *
   * This is how the tool will be called by the model and in `tool_use` blocks.
   */
  name: 'code_execution';

  type: 'code_execution_20260120';

  allowed_callers?: Array<
    'direct' | 'code_execution_20250825' | 'code_execution_20260120' | 'code_execution_20260521'
  >;

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;

  /**
   * If true, tool will not be included in initial system prompt. Only loaded when
   * returned via tool_reference from tool search.
   */
  defer_loading?: boolean;

  /**
   * When true, guarantees schema validation on tool names and inputs
   */
  strict?: boolean;
}

/**
 * Code execution tool with REPL state persistence.
 */
export interface BetaCodeExecutionTool20260521 {
  /**
   * Name of the tool.
   *
   * This is how the tool will be called by the model and in `tool_use` blocks.
   */
  name: 'code_execution';

  type: 'code_execution_20260521';

  allowed_callers?: Array<
    'direct' | 'code_execution_20250825' | 'code_execution_20260120' | 'code_execution_20260521'
  >;

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;

  /**
   * If true, tool will not be included in initial system prompt. Only loaded when
   * returned via tool_reference from tool search.
   */
  defer_loading?: boolean;

  /**
   * When true, guarantees schema validation on tool names and inputs
   */
  strict?: boolean;
}

export interface BetaCodeExecutionToolResultBlock {
  /**
   * Code execution result with encrypted stdout for PFC + web_search results.
   */
  content: BetaCodeExecutionToolResultBlockContent;

  tool_use_id: string;

  type: 'code_execution_tool_result';
}

/**
 * Code execution result with encrypted stdout for PFC + web_search results.
 */
export type BetaCodeExecutionToolResultBlockContent =
  | BetaCodeExecutionToolResultError
  | BetaCodeExecutionResultBlock
  | BetaEncryptedCodeExecutionResultBlock;

export interface BetaCodeExecutionToolResultBlockParam {
  /**
   * Code execution result with encrypted stdout for PFC + web_search results.
   */
  content: BetaCodeExecutionToolResultBlockParamContent;

  tool_use_id: string;

  type: 'code_execution_tool_result';

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;
}

/**
 * Code execution result with encrypted stdout for PFC + web_search results.
 */
export type BetaCodeExecutionToolResultBlockParamContent =
  | BetaCodeExecutionToolResultErrorParam
  | BetaCodeExecutionResultBlockParam
  | BetaEncryptedCodeExecutionResultBlockParam;

export interface BetaCodeExecutionToolResultError {
  error_code: BetaCodeExecutionToolResultErrorCode;

  type: 'code_execution_tool_result_error';
}

export type BetaCodeExecutionToolResultErrorCode =
  | 'invalid_tool_input'
  | 'unavailable'
  | 'too_many_requests'
  | 'execution_time_exceeded';

export interface BetaCodeExecutionToolResultErrorParam {
  error_code: BetaCodeExecutionToolResultErrorCode;

  type: 'code_execution_tool_result_error';
}

/**
 * Automatically compact older context when reaching the configured trigger
 * threshold.
 */
export interface BetaCompact20260112Edit {
  type: 'compact_20260112';

  /**
   * Additional instructions for summarization.
   */
  instructions?: string | null;

  /**
   * Whether to pause after compaction and return the compaction block to the user.
   */
  pause_after_compaction?: boolean;

  /**
   * When to trigger compaction. Defaults to 150000 input tokens.
   */
  trigger?: BetaInputTokensTrigger | null;
}

/**
 * A compaction block returned when autocompact is triggered.
 *
 * When content is None, it indicates the compaction failed to produce a valid
 * summary (e.g., malformed output from the model). Clients may round-trip
 * compaction blocks with null content; the server treats them as no-ops.
 */
export interface BetaCompactionBlock {
  /**
   * Summary of compacted content, or null if compaction failed
   */
  content: string | null;

  /**
   * Opaque metadata from prior compaction, to be round-tripped verbatim
   */
  encrypted_content: string | null;

  type: 'compaction';
}

/**
 * A compaction block containing summary of previous context.
 *
 * Users should round-trip these blocks from responses to subsequent requests to
 * maintain context across compaction boundaries.
 *
 * When content is None, the block represents a failed compaction. The server
 * treats these as no-ops. Empty string content is not allowed.
 */
export interface BetaCompactionBlockParam {
  type: 'compaction';

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;

  /**
   * Summary of previously compacted content, or null if compaction failed
   */
  content?: string | null;

  /**
   * Opaque metadata from prior compaction, to be round-tripped verbatim
   */
  encrypted_content?: string | null;
}

export interface BetaCompactionContentBlockDelta {
  content: string | null;

  /**
   * Opaque metadata from prior compaction, to be round-tripped verbatim
   */
  encrypted_content: string | null;

  type: 'compaction_delta';
}

/**
 * Token usage for a compaction iteration.
 */
export interface BetaCompactionIterationUsage {
  /**
   * Breakdown of cached tokens by TTL
   */
  cache_creation: BetaCacheCreation | null;

  /**
   * The number of input tokens used to create the cache entry.
   */
  cache_creation_input_tokens: number;

  /**
   * The number of input tokens read from the cache.
   */
  cache_read_input_tokens: number;

  /**
   * The number of input tokens which were used.
   */
  input_tokens: number;

  /**
   * The number of output tokens which were used.
   */
  output_tokens: number;

  /**
   * Usage for a compaction iteration
   */
  type: 'compaction';
}

/**
 * Information about the container used in the request (for the code execution
 * tool)
 */
export interface BetaContainer {
  /**
   * Identifier for the container used in this request
   */
  id: string;

  /**
   * The time at which the container will expire.
   */
  expires_at: string;

  /**
   * Skills loaded in the container
   */
  skills: Array<BetaSkill> | null;
}

/**
 * Container parameters with skills to be loaded.
 */
export interface BetaContainerParams {
  /**
   * Container id
   */
  id?: string | null;

  /**
   * List of skills to load in the container
   */
  skills?: Array<BetaSkillParams> | null;
}

/**
 * Response model for a file uploaded to the container.
 */
export interface BetaContainerUploadBlock {
  file_id: string;

  type: 'container_upload';
}

/**
 * A content block that represents a file to be uploaded to the container Files
 * uploaded via this block will be available in the container's input directory.
 */
export interface BetaContainerUploadBlockParam {
  file_id: string;

  type: 'container_upload';

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;
}

/**
 * Response model for a file uploaded to the container.
 */
export type BetaContentBlock =
  | BetaTextBlock
  | BetaThinkingBlock
  | BetaRedactedThinkingBlock
  | BetaToolUseBlock
  | BetaServerToolUseBlock
  | BetaWebSearchToolResultBlock
  | BetaWebFetchToolResultBlock
  | BetaAdvisorToolResultBlock
  | BetaCodeExecutionToolResultBlock
  | BetaBashCodeExecutionToolResultBlock
  | BetaTextEditorCodeExecutionToolResultBlock
  | BetaToolSearchToolResultBlock
  | BetaMCPToolUseBlock
  | BetaMCPToolResultBlock
  | BetaContainerUploadBlock
  | BetaCompactionBlock
  | BetaFallbackBlock;

/**
 * Regular text content.
 */
export type BetaContentBlockParam =
  | BetaTextBlockParam
  | BetaImageBlockParam
  | BetaRequestDocumentBlock
  | BetaSearchResultBlockParam
  | BetaThinkingBlockParam
  | BetaRedactedThinkingBlockParam
  | BetaToolUseBlockParam
  | BetaToolResultBlockParam
  | BetaServerToolUseBlockParam
  | BetaWebSearchToolResultBlockParam
  | BetaWebFetchToolResultBlockParam
  | BetaAdvisorToolResultBlockParam
  | BetaCodeExecutionToolResultBlockParam
  | BetaBashCodeExecutionToolResultBlockParam
  | BetaTextEditorCodeExecutionToolResultBlockParam
  | BetaToolSearchToolResultBlockParam
  | BetaMCPToolUseBlockParam
  | BetaRequestMCPToolResultBlockParam
  | BetaContainerUploadBlockParam
  | BetaCompactionBlockParam
  | BetaMidConversationSystemBlockParam
  | BetaFallbackBlockParam;

export interface BetaContentBlockSource {
  content: string | Array<BetaContentBlockSourceContent>;

  type: 'content';
}

export type BetaContentBlockSourceContent = BetaTextBlockParam | BetaImageBlockParam;

export interface BetaContextManagementConfig {
  /**
   * List of context management edits to apply
   */
  edits?: Array<BetaClearToolUses20250919Edit | BetaClearThinking20251015Edit | BetaCompact20260112Edit>;
}

export interface BetaContextManagementResponse {
  /**
   * List of context management edits that were applied.
   */
  applied_edits: Array<BetaClearToolUses20250919EditResponse | BetaClearThinking20251015EditResponse>;
}

export interface BetaCountTokensContextManagementResponse {
  /**
   * The original token count before context management was applied
   */
  original_input_tokens: number;
}

/**
 * Response envelope for request-level diagnostics. Present (possibly null)
 * whenever the caller supplied `diagnostics` on the request.
 */
export interface BetaDiagnostics {
  /**
   * Explains why the prompt cache could not fully reuse the prefix from the request
   * identified by `diagnostics.previous_message_id`. `null` means diagnosis is still
   * pending — the response was serialized before the background comparison
   * completed.
   */
  cache_miss_reason:
    | BetaCacheMissModelChanged
    | BetaCacheMissSystemChanged
    | BetaCacheMissToolsChanged
    | BetaCacheMissMessagesChanged
    | BetaCacheMissPreviousMessageNotFound
    | BetaCacheMissUnavailable
    | null;
}

/**
 * Request-level diagnostics. Currently carries the previous response id for
 * prompt-cache divergence reporting.
 */
export interface BetaDiagnosticsParam {
  /**
   * The `id` (`msg_...`) from this client's previous /v1/messages response. The
   * server compares that request's prompt fingerprint against this one and returns
   * `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be
   * reused. Pass `null` on the first turn to opt in without a prior message to
   * compare.
   */
  previous_message_id?: string | null;
}

/**
 * Tool invocation directly from the model.
 */
export interface BetaDirectCaller {
  type: 'direct';
}

export interface BetaDocumentBlock {
  /**
   * Citation configuration for the document
   */
  citations: BetaCitationConfig | null;

  source: BetaBase64PDFSource | BetaPlainTextSource;

  /**
   * The title of the document
   */
  title: string | null;

  type: 'document';
}

/**
 * Code execution result with encrypted stdout for PFC + web_search results.
 */
export interface BetaEncryptedCodeExecutionResultBlock {
  content: Array<BetaCodeExecutionOutputBlock>;

  encrypted_stdout: string;

  return_code: number;

  stderr: string;

  type: 'encrypted_code_execution_result';
}

/**
 * Code execution result with encrypted stdout for PFC + web_search results.
 */
export interface BetaEncryptedCodeExecutionResultBlockParam {
  content: Array<BetaCodeExecutionOutputBlockParam>;

  encrypted_stdout: string;

  return_code: number;

  stderr: string;

  type: 'encrypted_code_execution_result';
}

/**
 * Marks the point in `content` where one model's output gives way to the next.
 *
 * One block appears per hop where a preceding model actually ran this turn and
 * declined. A turn where no preceding model ran and declined has no such boundary
 * and carries no block — the signal for whether a fallback model served the
 * response is the presence of a `fallback_message` entry in `usage.iterations`,
 * not this block.
 *
 * The block is treated like a server-tool content block for streaming: it arrives
 * via the standard `content_block_start` / `content_block_stop` pair and carries
 * no deltas.
 */
export interface BetaFallbackBlock {
  /**
   * The model whose output ends at this point — the model that declined at this hop.
   * When the declining hop is the requested model, its `model` echoes the top-level
   * `model` string the caller sent (alias or canonical); when the declining hop is a
   * fallback model, its `model` is that model's canonical id.
   */
  from: BetaFallbackInfo;

  /**
   * The fallback model producing the content that follows this block. Its `model` is
   * always the canonical id.
   */
  to: BetaFallbackInfo;

  /**
   * What caused the `from` model to hand over at this hop.
   */
  trigger: BetaFallbackRefusalTrigger;

  type: 'fallback';
}

/**
 * A `fallback` block echoed back from a prior response.
 *
 * Accepted in `messages[].content` and not rendered into the prompt; not validated
 * against the request's `fallbacks` chain or top-level `model`.
 *
 * Echo the assistant turn back verbatim, including this block in its original
 * position. The block marks the boundary between content produced before and after
 * a fallback hop, and the server relies on that boundary to validate the turn:
 * when thinking runs flank the boundary, omitting the block merges them into one
 * span the server cannot validate (the request is rejected), and moving it into
 * the middle of a single run is likewise rejected; between non-thinking blocks the
 * block's placement has no validation effect.
 */
export interface BetaFallbackBlockParam {
  /**
   * Identifies one hop of a fallback transition.
   */
  from: BetaFallbackInfoParam;

  /**
   * Identifies one hop of a fallback transition.
   */
  to: BetaFallbackInfoParam;

  type: 'fallback';

  /**
   * The response block's `trigger`, echoed verbatim. Accepted and ignored by the
   * server; any object or `null` is allowed.
   */
  trigger?: unknown;
}

/**
 * Identifies one hop of a fallback transition.
 */
export interface BetaFallbackInfo {
  /**
   * The model that will complete your prompt.
   *
   * See [models](https://docs.anthropic.com/en/docs/models-overview) for additional
   * details and options.
   */
  model: MessagesAPI.Model;
}

/**
 * Identifies one hop of a fallback transition.
 */
export interface BetaFallbackInfoParam {
  /**
   * The model that will complete your prompt.
   *
   * See [models](https://docs.anthropic.com/en/docs/models-overview) for additional
   * details and options.
   */
  model: MessagesAPI.Model;
}

/**
 * Token usage for the fallback-model attempt of a server-side fallback request.
 *
 * Produced in place of a `message` entry for whichever hop served the response. A
 * declined hop produces the existing `message` entry. Whether a fallback model
 * served the response is signalled by the presence of this entry in
 * `usage.iterations`.
 */
export interface BetaFallbackMessageIterationUsage {
  /**
   * Breakdown of cached tokens by TTL
   */
  cache_creation: BetaCacheCreation | null;

  /**
   * The number of input tokens used to create the cache entry.
   */
  cache_creation_input_tokens: number;

  /**
   * The number of input tokens read from the cache.
   */
  cache_read_input_tokens: number;

  /**
   * The number of input tokens which were used.
   */
  input_tokens: number;

  /**
   * The model that will complete your prompt.
   *
   * See [models](https://docs.anthropic.com/en/docs/models-overview) for additional
   * details and options.
   */
  model: MessagesAPI.Model;

  /**
   * The number of output tokens which were used.
   */
  output_tokens: number;

  /**
   * Usage for the fallback-model attempt that served the response
   */
  type: 'fallback_message';
}

/**
 * One entry in the `fallbacks` chain on a `/v1/messages` request.
 *
 * `model` is required. The override fields (`max_tokens`, `thinking`,
 * `output_config`, and `speed`) set the corresponding parameter for this attempt
 * only and are validated as if the request were made to `model`. Any other key is
 * rejected at parse time.
 */
export interface BetaFallbackParam {
  /**
   * The model that will complete your prompt.
   *
   * See [models](https://docs.anthropic.com/en/docs/models-overview) for additional
   * details and options.
   */
  model: MessagesAPI.Model;

  max_tokens?: number | null;

  output_config?: BetaOutputConfig | null;

  /**
   * Inference speed mode. `fast` provides significantly faster output token
   * generation at premium pricing. Not all models support `fast`; invalid
   * combinations are rejected at create time.
   */
  speed?: 'standard' | 'fast' | null;

  thinking?: BetaThinkingConfigEnabled | BetaThinkingConfigDisabled | BetaThinkingConfigAdaptive | null;

  [k: string]: unknown;
}

/**
 * The `from` model declined for policy reasons.
 */
export interface BetaFallbackRefusalTrigger {
  /**
   * The policy category that triggered a refusal.
   *
   * - `cyber` - The request could enable cyber harm, such as malware or exploit
   *   development. Benign cybersecurity work can also trigger this category.
   * - `bio` - The request could enable biological harm, such as dangerous lab
   *   methods. Beneficial life sciences work can also trigger this category.
   * - `frontier_llm` - The request could assist the development of competing AI
   *   models, which is restricted under
   *   [Anthropic's commercial terms](https://www.anthropic.com/legal/commercial-terms).
   *   Benign machine learning work can also trigger this category.
   * - `reasoning_extraction` - The request asks the model to reproduce its internal
   *   reasoning in the response text. To get reasoning in a structured form instead,
   *   use
   *   [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking).
   */
  category: 'cyber' | 'bio' | 'frontier_llm' | 'reasoning_extraction' | null;

  type: 'refusal';
}

export interface BetaFileDocumentSource {
  file_id: string;

  type: 'file';
}

export interface BetaFileImageSource {
  file_id: string;

  type: 'file';
}

export interface BetaImageBlockParam {
  source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource;

  type: 'image';

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;
}

export interface BetaInputJSONDelta {
  partial_json: string;

  type: 'input_json_delta';
}

export interface BetaInputTokensClearAtLeast {
  type: 'input_tokens';

  value: number;
}

export interface BetaInputTokensTrigger {
  type: 'input_tokens';

  value: number;
}

/**
 * Per-iteration token usage breakdown.
 *
 * Each entry represents one sampling iteration, with its own input/output token
 * counts and cache statistics. This allows you to:
 *
 * - Determine which iterations exceeded long context thresholds (>=200k tokens)
 * - Calculate the true context window size from the last iteration
 * - Understand token accumulation across server-side tool use loops
 */
export type BetaIterationsUsage = Array<
  | BetaMessageIterationUsage
  | BetaCompactionIterationUsage
  | BetaAdvisorMessageIterationUsage
  | BetaFallbackMessageIterationUsage
>;

export interface BetaJSONOutputFormat {
  /**
   * The JSON schema of the format
   */
  schema: { [key: string]: unknown };

  type: 'json_schema';
}

/**
 * Configuration for a specific tool in an MCP toolset.
 */
export interface BetaMCPToolConfig {
  defer_loading?: boolean;

  enabled?: boolean;
}

/**
 * Default configuration for tools in an MCP toolset.
 */
export interface BetaMCPToolDefaultConfig {
  defer_loading?: boolean;

  enabled?: boolean;
}

export interface BetaMCPToolResultBlock {
  content: string | Array<BetaTextBlock>;

  is_error: boolean;

  tool_use_id: string;

  type: 'mcp_tool_result';
}

export interface BetaMCPToolUseBlock {
  id: string;

  input: unknown;

  /**
   * The name of the MCP tool
   */
  name: string;

  /**
   * The name of the MCP server
   */
  server_name: string;

  type: 'mcp_tool_use';
}

export interface BetaMCPToolUseBlockParam {
  id: string;

  input: unknown;

  name: string;

  /**
   * The name of the MCP server
   */
  server_name: string;

  type: 'mcp_tool_use';

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;
}

/**
 * Configu