@anthropic-ai/sdk
Version:
The official TypeScript library for the Anthropic API
1,441 lines (1,440 loc) • 155 kB
text/typescript
import * as BatchesAPI from "./batches.mjs";
import { APIPromise } from "../../../core/api-promise.mjs";
import { APIResource } from "../../../core/resource.mjs";
import { Stream } from "../../../core/streaming.mjs";
import { RequestOptions } from "../../../internal/request-options.mjs";
import { type ExtractParsedContentFromBetaParams, type ParsedBetaMessage } from "../../../lib/beta-parser.mjs";
import { BetaMessageStream } from "../../../lib/BetaMessageStream.mjs";
import { BetaToolRunner, BetaToolRunnerParams, BetaToolRunnerRequestOptions } from "../../../lib/tools/BetaToolRunner.mjs";
import { ToolError } from "../../../lib/tools/ToolError.mjs";
import * as BetaMessagesAPI from "./messages.mjs";
import * as MessagesAPI from "../../messages/messages.mjs";
import * as BetaAPI from "../beta.mjs";
import { BatchCancelParams, BatchCreateParams, BatchDeleteParams, BatchListParams, BatchResultsParams, BatchRetrieveParams, Batches, BetaDeletedMessageBatch, BetaMessageBatch, BetaMessageBatchCanceledResult, BetaMessageBatchErroredResult, BetaMessageBatchExpiredResult, BetaMessageBatchIndividualResponse, BetaMessageBatchRequestCounts, BetaMessageBatchResult, BetaMessageBatchSucceededResult, BetaMessageBatchesPage } from "./batches.mjs";
export declare class Messages extends APIResource {
batches: BatchesAPI.Batches;
/**
* 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>;
/**
* 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>>>;
/**
* Create a Message stream
*/
stream<Params extends BetaMessageStreamParams>(body: Params, options?: RequestOptions): BetaMessageStream<ExtractParsedContentFromBetaParams<Params>>;
/**
* 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>;
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>;
}
/**
* 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;
}
/**
* Configuration for a group of tools from an MCP server.
*
* Allows configuring enabled status and defer_loading for all tools from an MCP
* server, with optional per-tool overrides.
*/
export interface BetaMCPToolset {
/**
* Name of the MCP server to configure tools for
*/
mcp_server_name: string;
type: 'mcp_toolset';
/**
* Create a cache control breakpoint at this content block.
*/
cache_control?: BetaCacheControlEphemeral | null;
/**
* Configuration overrides for specific tools, keyed by tool name
*/
configs?: {
[key: string]: BetaMCPToolConfig;
} | null;
/**
* Default configuration applied to all tools from this server
*/
default_config?: BetaMCPToolDefaultConfig;
}
export interface BetaMemoryTool20250818 {
/**
* Name of the tool.
*
* This is how the tool will be called by the model and in `tool_use` blocks.
*/
name: 'memory';
type: 'memory_20250818';
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;
input_examples?: Array<{
[key: string]: unknown;
}>;
/**
* When true, guarantees schema validation on tool names and inputs
*/
strict?: boolean;
}
export type BetaMemoryTool20250818Command = BetaMemoryTool20250818ViewCommand | BetaMemoryTool20250818CreateCommand | BetaMemoryTool20250818StrReplaceCommand | BetaMemoryTool20250818InsertCommand | BetaMemoryTool20250818DeleteCommand | BetaMemoryTool20250818RenameCommand;
export interface BetaMemoryTool20250818CreateCommand {
/**
* Command type identifier
*/
command: 'create';
/**
* Content to write to the file
*/
file_text: string;
/**
* Path where the file should be created
*/
path: string;
}
export interface BetaMemoryTool20250818DeleteCommand {
/**
* Command type identifier
*/
command: 'delete';
/**
* Path to the file or directory to delete
*/
path: string;
}
export interface BetaMemoryTool20250818InsertCommand {
/**
* Command type identifier
*/
command: 'insert';
/**
* Line number where text should be inserted
*/
insert_line: number;
/**
* Text to insert at the specified line
*/
insert_text: string;
/**
* Path to the file where text should be inserted
*/
path: string;
}
export interface BetaMemoryTool20250818RenameCommand {
/**
* Command type identifier
*/
command: 'rename';
/**
* New path for the file or directory
*/
new_path: string;
/**
* Current path of the file or directory
*/
old_path: string;
}
export interface BetaMemoryTool20250818StrReplaceCommand {
/**
* Command type identifier
*/
command: 'str_replace';
/**
* Text to replace with
*/
new_str: string;
/**
* Text to search for and replace
*/
old_str: string;
/**
* Path to the file where text should be replaced
*/
path: string;
}
export interface BetaMemoryTool20250818ViewCommand {
/**
* Command type identifier
*/
command: 'view';
/**
* Path to directory or file to view
*/
path: string;
/**
* Optional line range for viewing specific lines
*/
view_range?: Array<number>;
}
export interface BetaMessage {
/**
* Unique object identifier.
*
* The format and length of IDs may change over time.
*/
id: string;
/**
* Information about the container used in the request (for the code execution
* tool)
*/
container: BetaContainer | null;
/**
* Content generated by the model.
*
* This is an array of content blocks, each of which has a `type` that determines
* its shape.
*
* Example:
*
* ```json
* [{ "type": "text", "text": "Hi, I'm Claude." }]
* ```
*
* If the request input `messages` ended with an `assistant` turn, then the
* response `content` will continue directly from that last turn. You can use this
* to constrain the model's output.
*
* For example, if the input `messages` were:
*
* ```json
* [