Messages

Create a Message

client.messages.create(params, options?): Message | Stream<RawMessageStreamEvent>

POST/v1/messages

Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.

Count tokens in a Message

client.messages.countTokens(params, options?): MessageTokensCount

POST/v1/messages/count_tokens

Count the number of tokens in a Message.

Models

interface Base64ImageSource { type: "base64"; data; media_type }

type: "base64"

data: string

formatbyte

media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"

One of the following:

"image/jpeg"

"image/png"

"image/gif"

"image/webp"

interface Base64PDFSource { type: "base64"; data; media_type }

type: "base64"

data: string

formatbyte

media_type: "application/pdf"

interface BashCodeExecutionOutputBlock { type: "bash_code_execution_output"; file_id }

type: "bash_code_execution_output"

defaultbash_code_execution_output

file_id: string

interface BashCodeExecutionOutputBlockParam { type: "bash_code_execution_output"; file_id }

type: "bash_code_execution_output"

file_id: string

interface BashCodeExecutionResultBlock { type: "bash_code_execution_result"; content; return_code; /* 2 more */ }

type: "bash_code_execution_result"

defaultbash_code_execution_result

content: Array<BashCodeExecutionOutputBlock { type: "bash_code_execution_output"; file_id }>

type: "bash_code_execution_output"

defaultbash_code_execution_output

file_id: string

return_code: number

stderr: string

stdout: string

interface BashCodeExecutionResultBlockParam { type: "bash_code_execution_result"; content; return_code; /* 2 more */ }

type: "bash_code_execution_result"

content: Array<BashCodeExecutionOutputBlockParam { type: "bash_code_execution_output"; file_id }>

type: "bash_code_execution_output"

file_id: string

return_code: number

stderr: string

stdout: string

interface BashCodeExecutionToolResultBlock { type: "bash_code_execution_tool_result"; content; tool_use_id }

interface BashCodeExecutionToolResultBlockParam { type: "bash_code_execution_tool_result"; content; tool_use_id; cache_control }

interface BashCodeExecutionToolResultError { type: "bash_code_execution_tool_result_error"; error_code }

type: "bash_code_execution_tool_result_error"

defaultbash_code_execution_tool_result_error

error_code: BashCodeExecutionToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

type BashCodeExecutionToolResultErrorCode = "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

interface BashCodeExecutionToolResultErrorParam { type: "bash_code_execution_tool_result_error"; error_code }

type: "bash_code_execution_tool_result_error"

error_code: BashCodeExecutionToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

type BrowserClickTarget = BrowserCoordinateTarget | BrowserRefTarget

Where to act: either a viewport coordinate or an element reference.

One of the following:

interface BrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

interface BrowserRefTarget { type: "ref"; ref }

An element on the page, identified by a reference from a prior read_page or find result. References are scoped to the tab that produced them and become stale after navigation or a major re-render.

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

interface BrowserCloseTabConfig { defer_loading; enabled }

close_tab's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserCloseTabInput { tab_id }

Close the tab with the given tab_id.

tab_id: string

The tab to close.

interface BrowserCloseTabToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

interface BrowserDoubleClickConfig { defer_loading; enabled }

double_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserDoubleClickInput { target; modifiers; tab_id }

Double left-click at a viewport coordinate or on an element by reference.

interface BrowserDoubleClickToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserFileUploadConfig { defer_loading; enabled }

file_upload's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserFileUploadInput { target; document_ids; paths; tab_id }

Set the value of a file-input element to one or more files. The target must be an element reference; at least one of paths or document_ids is required.

target: BrowserRefTarget { type: "ref"; ref }

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

document_ids?: Array<string> | null

References to files the harness has staged, for deployments where the browser executor cannot read the caller's filesystem.

minItems1

paths?: Array<string> | null

File paths on the browser executor's filesystem.

minItems1

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserFileUploadToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserFindConfig { defer_loading; enabled }

find's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserFindInput { query; tab_id }

Find elements matching a natural-language description (e.g. "search bar", "add to cart button") and return up to 20 matches with element references.

query: string

Natural-language description of the element(s) to find.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserFindToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserFormInputConfig { defer_loading; enabled }

form_input's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserFormInputInput { target; value; tab_id }

Set the value of a form element (input, textarea, select, checkbox). Use a boolean for checkboxes, an option value or text for selects.

target: BrowserRefTarget { type: "ref"; ref }

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

value: BrowserFormInputValue

The value to set.

One of the following:

string

number

boolean

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserFormInputToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

type BrowserFormInputValue = string | number | boolean

One of the following:

string

number

boolean

interface BrowserGetPageTextConfig { defer_loading; enabled }

get_page_text's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserGetPageTextInput { tab_id }

Return the page's visible text content as plain text, prioritizing article content. Suited to articles, documentation, and other text-heavy pages.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserGetPageTextToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserHoldKeyConfig { defer_loading; enabled }

hold_key's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserHoldKeyInput { duration; text; tab_id }

Hold a key or key chord down for a duration, then release it. Uses the same key names and "+" chord syntax as the key action.

duration: number

Seconds to hold the key down (maximum 30).

minimum0

maximum30

text: string

The key or chord to hold.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserHoldKeyToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserHoverConfig { defer_loading; enabled }

hover's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserHoverInput { target; tab_id }

Move the cursor to a coordinate or element without clicking.

target: BrowserClickTarget

Where to act: either a viewport coordinate or an element reference.

One of the following:

interface BrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

interface BrowserRefTarget { type: "ref"; ref }

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserHoverToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserJavascriptExecConfig { defer_loading; enabled }

javascript_exec's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserJavascriptExecInput { text; tab_id }

Execute JavaScript in the page context and return the value of the last expression. The code runs with access to the DOM, window, and page variables. Write the expression you want evaluated — do NOT use return.

text: string

JavaScript to execute in the page context.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserJavascriptExecToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserKeyConfig { defer_loading; enabled }

key's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserKeyInput { text; repeat; tab_id }

Press a key or key chord. Use "+" to combine modifiers with a key (e.g. "ctrl+a", "cmd+shift+p") and space to sequence presses (e.g. "Backspace Backspace Delete"). Common names like "Return", "Tab", "Escape", "BackSpace" are supported.

text: string

The key, chord, or space-separated sequence to press.

repeat?: number | null

Number of times to repeat. Default 1.

minimum1

maximum100

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserKeyToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserLeftClickConfig { defer_loading; enabled }

left_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserLeftClickDragConfig { defer_loading; enabled }

left_click_drag's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserLeftClickDragInput { from; target; tab_id }

Press at from, drag to target, release. Both must be coordinate targets.

interface BrowserLeftClickDragToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserLeftClickInput { target; modifiers; tab_id }

Left-click at a viewport coordinate or on an element by reference.

interface BrowserLeftClickToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserLeftMouseDownConfig { defer_loading; enabled }

left_mouse_down's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserLeftMouseDownInput { target; tab_id }

Press and hold the left mouse button at a viewport coordinate. Pair with left_mouse_up to perform a custom drag.

target: BrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserLeftMouseDownToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserLeftMouseUpConfig { defer_loading; enabled }

left_mouse_up's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserLeftMouseUpInput { target; tab_id }

Release the left mouse button at a viewport coordinate.

target: BrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserLeftMouseUpToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserListTabsConfig { defer_loading; enabled }

list_tabs's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserListTabsInput

List all open tabs with each tab's tab_id, title, and URL.

interface BrowserListTabsToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserMiddleClickConfig { defer_loading; enabled }

middle_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserMiddleClickInput { target; modifiers; tab_id }

Middle-click at a viewport coordinate or on an element by reference.

interface BrowserMiddleClickToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserMouseMoveConfig { defer_loading; enabled }

mouse_move's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserMouseMoveInput { target; tab_id }

Move the pointer to a viewport coordinate without clicking.

target: BrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserMouseMoveToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserNavigateConfig { defer_loading; enabled }

navigate's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserNavigateInput { url; tab_id }

Navigate to a URL, or go back/forward/reload in history. The protocol may be omitted (defaults to https://).

url: string

The URL to navigate to, or "back" / "forward" / "reload" for history navigation.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserNavigateToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserNewTabConfig { defer_loading; enabled }

new_tab's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserNewTabInput

Open a new empty tab and return its tab_id.

interface BrowserNewTabToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserReadConsoleConfig { defer_loading; enabled }

read_console's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserReadConsoleInput { tab_id }

Return console output (log entries, errors, warnings) accumulated since the driver attached to the tab and since the last read, one line per entry. An empty result does not mean no traffic for a tab that predates attach.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserReadConsoleToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserReadNetworkConfig { defer_loading; enabled }

read_network's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserReadNetworkInput { tab_id }

Return the network requests (method, URL, status, MIME type, timing) recorded since the driver attached to the tab and since the last read, one line per entry. An empty result does not mean no traffic for a tab that predates attach.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserReadNetworkToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserReadPageConfig { defer_loading; enabled }

read_page's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

type BrowserReadPageFilter = "all" | "interactive"

One of the following:

"all"

"interactive"

interface BrowserReadPageInput { depth; filter; ref; tab_id }

Return a structured accessibility tree of the page (or the subtree rooted at ref), with element references like [ref_7] that can be used as targets on later actions. Output is capped at 50,000 characters — narrow with ref or a smaller depth when exceeded.

depth?: number | null

Maximum tree depth. Default 15.

minimum1

filter?: BrowserReadPageFilter | null

Which elements to include. Omitted: every visible element. "interactive": interactive elements only. "all": additionally includes off-viewport elements.

One of the following:

"all"

"interactive"

ref?: string | null

Element reference to read a subtree from. Omit to read from the page root.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserReadPageToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserRefTarget { type: "ref"; ref }

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

interface BrowserRightClickConfig { defer_loading; enabled }

right_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserRightClickInput { target; modifiers; tab_id }

Right-click at a viewport coordinate or on an element by reference.

interface BrowserRightClickToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserScreenshotConfig { defer_loading; enabled }

screenshot's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserScreenshotInput { tab_id }

Capture the current browser viewport.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserScreenshotToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserScrollConfig { defer_loading; enabled }

scroll's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

type BrowserScrollDirection = "up" | "down" | "left" | "right"

One of the following:

"up"

"down"

"left"

"right"

interface BrowserScrollInput { scroll_direction; target; scroll_amount; tab_id }

Scroll at a viewport position. target must be a coordinate target.

scroll_direction: BrowserScrollDirection

One of the following:

"up"

"down"

"left"

"right"

target: BrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

scroll_amount?: number | null

Scroll-wheel notches (1–10). Default 3.

minimum1

maximum10

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserScrollToConfig { defer_loading; enabled }

scroll_to's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserScrollToInput { target; tab_id }

Scroll an element into view.

target: BrowserRefTarget { type: "ref"; ref }

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserScrollToToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserScrollToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserStateBlockParam { type: "browser_state"; tabs; cache_control; state_changes }

The caller's browser state after a browser toolset member call — the full inventory of open tabs, which tab is active, and any side effects (tabs opened, download state changes) the call produced.

At most one per tool_result, only on a non-error result answering a browser toolset member tool_use. The server renders the model-visible text from it; the model never sees the raw fields.

type BrowserStateChange = BrowserStateChangeTabOpened | BrowserStateChangeDownloadStarted | BrowserStateChangeDownloadCompleted | BrowserStateChangeDownloadFailed

One of the following:

interface BrowserStateChangeDownloadCompleted { type: "download_completed"; download_id; url; /* 2 more */ }

A file download that finished during this call, reported with the same download_id as its download_started — or without a prior download_started, when the download finished during the call that started it (at most one state change per download_id per result).

type: "download_completed"

download_id: string

The caller-assigned identifier for this download, stable across the state changes reporting it.

minLength1

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

url: string

The final post-redirect URL the download was served from.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

path?: string | null

Where the executor saved the file, on the executor's filesystem. Only included when another tool in the same environment can read the file at that path.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

size_bytes?: number | null

The completed download's size.

minimum0

interface BrowserStateChangeDownloadFailed { type: "download_failed"; download_id; url; error }

A file download that failed — or was cancelled — during this call.

type: "download_failed"

download_id: string

The caller-assigned identifier for this download, stable across the state changes reporting it.

minLength1

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

url: string

The final post-redirect URL the download was served from.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

error?: string | null

The failure or cancellation detail, when known.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

interface BrowserStateChangeDownloadStarted { type: "download_started"; download_id; url }

A file download that started during this call.

type: "download_started"

download_id: string

The caller-assigned identifier for this download, stable across the state changes reporting it.

minLength1

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

url: string

The final post-redirect URL the download was served from.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

interface BrowserStateChangeTabOpened { type: "tab_opened"; tab_id }

A tab this call's execution opened that remains open at its end — the creation delta of the tabs inventory, not an event log.

Carries only the tab_id; the tab's title and url live on its tabs entry, which must include the same tab_id. A tab opened during a failed call gets no deferred tab_opened; it simply appears in the next result's tabs inventory.

type: "tab_opened"

tab_id: string

The tab_id of the opened tab, present in tabs.

minLength1

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

interface BrowserStateTabEntry { tab_id; title; url; active }

One open browser tab reported in a browser_state block's tabs inventory.

tab_id is the caller-assigned identifier for the tab; title and url describe the page the tab is currently showing and may be empty strings (a blank tab legitimately has both empty). active marks the tab that is active after this call; whenever tabs is non-empty, exactly one entry is marked.

tab_id: string

The caller-assigned identifier for this tab, unique within the inventory.

minLength1

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

title: string

The title of the page the tab is showing. May be empty.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

url: string

The URL of the page the tab is showing. May be empty.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

active?: boolean

Whether this tab is the active tab after this call. Whenever tabs is non-empty, exactly one entry is marked active: true.

interface BrowserSwitchTabConfig { defer_loading; enabled }

switch_tab's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserSwitchTabInput { tab_id }

Make the tab with the given tab_id the active tab — the tab that actions without a tab_id apply to.

tab_id: string

The tab to switch to.

interface BrowserSwitchTabToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

type BrowserToolUseBlock = BrowserNavigateToolUseBlock | BrowserListTabsToolUseBlock | BrowserNewTabToolUseBlock | 28 more

One of the following:

interface BrowserToolset20260801 { type: "browser_toolset_20260801"; cache_control; configs }

The browser toolset: a single tools[] entry (carrying no name) that declares the browser tool family. The model is served the family's tool with any members disabled via configs removed from its schema.

type: "browser_toolset_20260801"

cache_control?: CacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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 for details.

One of the following:

"5m"

"1h"

configs?: BrowserToolsetConfigs | null

Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent.

interface BrowserToolsetConfigs { type; close_tab; double_click; /* 28 more */ }

Per-member configuration for browser_toolset_20260801: one optional field per member tool, keyed by the member name — the same name the member's tool_use blocks carry. Every member is an accepted key, and a member's defaults apply wherever its key is absent. Unknown keys are rejected: the field set is this toolset version's complete member set.

interface BrowserTripleClickConfig { defer_loading; enabled }

triple_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserTripleClickInput { target; modifiers; tab_id }

Triple left-click at a viewport coordinate or on an element by reference (typically selects a line or paragraph).

interface BrowserTripleClickToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserTypeConfig { defer_loading; enabled }

type's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserTypeInput { text; tab_id }

Type a literal string at the current focus.

text: string

The text to type.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserTypeToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserWaitConfig { defer_loading; enabled }

wait's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserWaitInput { duration; tab_id }

Pause for the given duration.

duration: number

Seconds to wait (maximum 30).

minimum0

maximum30

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserWaitToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface BrowserZoomConfig { defer_loading; enabled }

zoom's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface BrowserZoomInput { region; tab_id }

Return a cropped screenshot of the given viewport region, scaled up for closer inspection — useful for small icons, buttons, or text. Coordinates are in the same viewport-pixel space as a full screenshot.

region: Array<number>

[x0, y0, x1, y1] in viewport pixels.

minItems4

maxItems4

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BrowserZoomToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface CacheControlEphemeral { type: "ephemeral"; ttl }

type: "ephemeral"

ttl?: "5m" | "1h"

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 for details.

One of the following:

"5m"

"1h"

interface CacheCreation { ephemeral_1h_input_tokens; ephemeral_5m_input_tokens }

ephemeral_1h_input_tokens: number

The number of input tokens used to create the 1 hour cache entry.

default0

minimum0

ephemeral_5m_input_tokens: number

The number of input tokens used to create the 5 minute cache entry.

default0

minimum0

interface CacheMissMessagesChanged { type: "messages_changed"; cache_missed_input_tokens }

type: "messages_changed"

defaultmessages_changed

cache_missed_input_tokens: number

Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

interface CacheMissModelChanged { type: "model_changed"; cache_missed_input_tokens }

type: "model_changed"

defaultmodel_changed

cache_missed_input_tokens: number

Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

interface CacheMissPreviousMessageNotFound { type: "previous_message_not_found" }

type: "previous_message_not_found"

defaultprevious_message_not_found

type CacheMissReason = CacheMissModelChanged | CacheMissSystemChanged | CacheMissToolsChanged | 3 more

One of the following:

interface CacheMissSystemChanged { type: "system_changed"; cache_missed_input_tokens }

type: "system_changed"

defaultsystem_changed

cache_missed_input_tokens: number

Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

interface CacheMissToolsChanged { type: "tools_changed"; cache_missed_input_tokens }

type: "tools_changed"

defaulttools_changed

cache_missed_input_tokens: number

Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

interface CacheMissUnavailable { type: "unavailable" }

type: "unavailable"

defaultunavailable

interface CitationCharLocation { type: "char_location"; cited_text; document_index; /* 4 more */ }

type: "char_location"

defaultchar_location

cited_text: string

document_index: number

minimum0

document_title: string | null

end_char_index: number

file_id: string | null

start_char_index: number

minimum0

interface CitationCharLocationParam { type: "char_location"; cited_text; document_index; /* 3 more */ }

type: "char_location"

cited_text: string

document_index: number

minimum0

document_title: string | null

minLength1

maxLength500

end_char_index: number

start_char_index: number

minimum0

interface CitationContentBlockLocation { type: "content_block_location"; cited_text; document_index; /* 4 more */ }

type: "content_block_location"

defaultcontent_block_location

cited_text: string

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.

document_index: number

minimum0

document_title: string | null

end_block_index: number

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.

file_id: string | null

start_block_index: number

0-based index of the first cited block in the source's content array.

minimum0

interface CitationContentBlockLocationParam { type: "content_block_location"; cited_text; document_index; /* 3 more */ }

type: "content_block_location"

cited_text: string

The full text of the cited block range, concatenated.

document_index: number

minimum0

document_title: string | null

minLength1

maxLength500

end_block_index: number

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.

start_block_index: number

0-based index of the first cited block in the source's content array.

minimum0

interface CitationPageLocation { type: "page_location"; cited_text; document_index; /* 4 more */ }

type: "page_location"

defaultpage_location

cited_text: string

document_index: number

minimum0

document_title: string | null

end_page_number: number

file_id: string | null

start_page_number: number

minimum1

interface CitationPageLocationParam { type: "page_location"; cited_text; document_index; /* 3 more */ }

type: "page_location"

cited_text: string

document_index: number

minimum0

document_title: string | null

minLength1

maxLength500

end_page_number: number

start_page_number: number

minimum1

interface CitationSearchResultLocationParam { type: "search_result_location"; cited_text; end_block_index; /* 4 more */ }

type: "search_result_location"

cited_text: string

The full text of the cited block range, concatenated.

end_block_index: number

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.

search_result_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.

minimum0

source: string

start_block_index: number

0-based index of the first cited block in the source's content array.

minimum0

title: string | null

interface CitationWebSearchResultLocationParam { type: "web_search_result_location"; cited_text; encrypted_index; /* 2 more */ }

type: "web_search_result_location"

cited_text: string

encrypted_index: string

title: string | null

minLength1

maxLength512

url: string

minLength1

interface CitationsConfig { enabled }

enabled: boolean

defaultfalse

interface CitationsConfigParam { enabled }

enabled?: boolean

interface CitationsDelta { type: "citations_delta"; citation }

interface CitationsSearchResultLocation { type: "search_result_location"; cited_text; end_block_index; /* 4 more */ }

type: "search_result_location"

defaultsearch_result_location

cited_text: string

The full text of the cited block range, concatenated.

end_block_index: number

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.

search_result_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.

minimum0

source: string

start_block_index: number

0-based index of the first cited block in the source's content array.

minimum0

title: string | null

interface CitationsWebSearchResultLocation { type: "web_search_result_location"; cited_text; encrypted_index; /* 2 more */ }

type: "web_search_result_location"

defaultweb_search_result_location

cited_text: string

encrypted_index: string

title: string | null

maxLength512

url: string

interface CodeExecutionOutputBlock { type: "code_execution_output"; file_id }

type: "code_execution_output"

defaultcode_execution_output

file_id: string

interface CodeExecutionOutputBlockParam { type: "code_execution_output"; file_id }

type: "code_execution_output"

file_id: string

interface CodeExecutionResultBlock { type: "code_execution_result"; content; return_code; /* 2 more */ }

type: "code_execution_result"

defaultcode_execution_result

content: Array<CodeExecutionOutputBlock { type: "code_execution_output"; file_id }>

type: "code_execution_output"

defaultcode_execution_output

file_id: string

return_code: number

stderr: string

stdout: string

interface CodeExecutionResultBlockParam { type: "code_execution_result"; content; return_code; /* 2 more */ }

type: "code_execution_result"

content: Array<CodeExecutionOutputBlockParam { type: "code_execution_output"; file_id }>

type: "code_execution_output"

file_id: string

return_code: number

stderr: string

stdout: string

interface CodeExecutionTool20250522 { type: "code_execution_20250522"; name; allowed_callers; /* 3 more */ }

interface CodeExecutionTool20250825 { type: "code_execution_20250825"; name; allowed_callers; /* 3 more */ }

interface CodeExecutionTool20260120 { type: "code_execution_20260120"; name; allowed_callers; /* 3 more */ }

Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).

interface CodeExecutionTool20260521 { type: "code_execution_20260521"; name; allowed_callers; /* 3 more */ }

Code execution tool with REPL state persistence.

interface CodeExecutionToolResultBlock { type: "code_execution_tool_result"; content; tool_use_id }

type: "code_execution_tool_result"

defaultcode_execution_tool_result

content: CodeExecutionToolResultBlockContent

One of the following:

tool_use_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

type CodeExecutionToolResultBlockContent = CodeExecutionToolResultError | CodeExecutionResultBlock | EncryptedCodeExecutionResultBlock

One of the following:

interface CodeExecutionToolResultBlockParam { type: "code_execution_tool_result"; content; tool_use_id; cache_control }

type: "code_execution_tool_result"

content: CodeExecutionToolResultBlockParamContent

One of the following:

tool_use_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

cache_control?: CacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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 for details.

One of the following:

"5m"

"1h"

type CodeExecutionToolResultBlockParamContent = CodeExecutionToolResultErrorParam | CodeExecutionResultBlockParam | EncryptedCodeExecutionResultBlockParam

One of the following:

interface CodeExecutionToolResultError { type: "code_execution_tool_result_error"; error_code }

type: "code_execution_tool_result_error"

defaultcode_execution_tool_result_error

error_code: CodeExecutionToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

type CodeExecutionToolResultErrorCode = "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

interface CodeExecutionToolResultErrorParam { type: "code_execution_tool_result_error"; error_code }

type: "code_execution_tool_result_error"

error_code: CodeExecutionToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

interface ComputerCursorPositionConfig { defer_loading; enabled }

cursor_position's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerCursorPositionInput

Get the current (x, y) pixel coordinate of the cursor.

interface ComputerCursorPositionToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerDoubleClickConfig { defer_loading; enabled }

double_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerDoubleClickInput { coordinate; text }

Double-click the left mouse button at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted.

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface ComputerDoubleClickToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerHoldKeyConfig { defer_loading; enabled }

hold_key's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerHoldKeyInput { duration; text }

Hold down a key or key-combination for a specified duration. Uses the same key syntax as key.

duration: number

Duration to hold the key, in seconds.

maximum300

text: string

The key or key-combination to hold.

interface ComputerHoldKeyToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerKeyConfig { defer_loading; enabled }

key's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerKeyInput { text; repeat }

Press a key or key-combination on the keyboard. Use "+" to combine modifiers with a key (e.g. "ctrl+s", "alt+Tab", "ctrl+shift+Escape"). Key names are case-insensitive; common names like "Return", "Tab", "Escape", "Up", "Down", "Left", "Right", "Home", "End", "Page_Up", "Page_Down", "Delete", "BackSpace" are supported.

text: string

The key or key-combination to press.

repeat?: number | null

Number of times to repeat the key press. Default is 1.

minimum1

maximum100

interface ComputerKeyToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerLeftClickConfig { defer_loading; enabled }

left_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerLeftClickDragConfig { defer_loading; enabled }

left_click_drag's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerLeftClickDragInput { coordinate; start_coordinate; text }

Click and drag the cursor from start_coordinate to coordinate.

coordinate: Array<number>

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

start_coordinate: Array<number>

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface ComputerLeftClickDragToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerLeftClickInput { coordinate; text }

Click the left mouse button at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted.

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface ComputerLeftClickToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerLeftMouseDownConfig { defer_loading; enabled }

left_mouse_down's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerLeftMouseDownInput

Press and hold the left mouse button at the current cursor position.

interface ComputerLeftMouseDownToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerLeftMouseUpConfig { defer_loading; enabled }

left_mouse_up's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerLeftMouseUpInput

Release the left mouse button.

interface ComputerLeftMouseUpToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerMiddleClickConfig { defer_loading; enabled }

middle_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerMiddleClickInput { coordinate; text }

Click the middle mouse button at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted.

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface ComputerMiddleClickToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerMouseMoveConfig { defer_loading; enabled }

mouse_move's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerMouseMoveInput { coordinate }

Move the cursor to a specified (x, y) pixel coordinate. Use this ONLY to hover without clicking; otherwise use a click action directly.

coordinate: Array<number>

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

interface ComputerMouseMoveToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerRightClickConfig { defer_loading; enabled }

right_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerRightClickInput { coordinate; text }

Click the right mouse button at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted.

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface ComputerRightClickToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerScreenshotConfig { defer_loading; enabled }

screenshot's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerScreenshotInput

Take a screenshot of the screen.

interface ComputerScreenshotToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerScrollConfig { defer_loading; enabled }

scroll's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

type ComputerScrollDirection = "up" | "down" | "left" | "right"

One of the following:

"up"

"down"

"left"

"right"

interface ComputerScrollInput { scroll_amount; scroll_direction; coordinate; text }

Scroll the screen at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted. Do NOT use PageUp/PageDown to scroll.

scroll_amount: number

Number of 'clicks' of the scroll wheel.

scroll_direction: ComputerScrollDirection

One of the following:

"up"

"down"

"left"

"right"

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface ComputerScrollToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

type ComputerToolUseBlock = ComputerKeyToolUseBlock | ComputerHoldKeyToolUseBlock | ComputerTypeToolUseBlock | 14 more

One of the following:

interface ComputerToolset20260801 { type: "computer_toolset_20260801"; cache_control; configs }

The computer toolset: a single tools[] entry (carrying no name) that declares the computer tool family. The model is served the family's tool with any members disabled via configs removed from its schema. Every member is enabled by default, zoom included. The single-tool options display_number and enable_zoom are not fields of a toolset entry — it carries only type, configs, and cache_control; zoom is controlled via configs.zoom.enabled.

type: "computer_toolset_20260801"

cache_control?: CacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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 for details.

One of the following:

"5m"

"1h"

configs?: ComputerToolsetConfigs | null

Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent.

interface ComputerToolsetConfigs { type; cursor_position; double_click; /* 14 more */ }

Per-member configuration for computer_toolset_20260801: one optional field per member tool, keyed by the member name — the same name the member's tool_use blocks carry. Every member is an accepted key, and a member's defaults apply wherever its key is absent. Unknown keys are rejected: the field set is this toolset version's complete member set.

interface ComputerTripleClickConfig { defer_loading; enabled }

triple_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerTripleClickInput { coordinate; text }

Triple-click the left mouse button at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted.

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface ComputerTripleClickToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerTypeConfig { defer_loading; enabled }

type's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerTypeInput { text }

Type a string of text on the keyboard.

text: string

The text to type.

interface ComputerTypeToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerWaitConfig { defer_loading; enabled }

wait's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerWaitInput { duration }

Wait for a specified duration.

duration: number

Duration to wait, in seconds.

maximum300

interface ComputerWaitToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ComputerZoomConfig { defer_loading; enabled }

zoom's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | null

Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.

interface ComputerZoomInput { region }

Take a screenshot of a rectangular region. Region coordinates are in the full-screenshot space (not physical display pixels). The crop is scaled up to fill the image budget so fine details become legible.

region: Array<number>

(x0, y0, x1, y1): The region to capture.

minItems4

maxItems4

interface ComputerZoomToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface Container { id; expires_at; skills }

Information about the container used in the request (for the code execution tool)

id: string

Identifier for the container used in this request

expires_at: string

The time at which the container will expire.

formatdate-time

skills: Array<ContainerSkill> | null

Skills loaded in the container

type: "anthropic" | "custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

One of the following:

"anthropic"

"custom"

skill_id: string

Skill ID

minLength1

maxLength64

version: string

The resolved version: a skill version ID for custom skills.

minLength1

maxLength64

interface ContainerParams { id; skills }

Container parameters with skills to be loaded.

id?: string | null

Container id

skills?: Array<SkillParams> | null

List of skills to load in the container

maxItems20

type: "anthropic" | "custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

One of the following:

"anthropic"

"custom"

skill_id: string

Skill ID

minLength1

maxLength64

version?: string

Skill version or 'latest' for most recent version

minLength1

maxLength64

interface ContainerSkill { type; skill_id; version }

A skill that was loaded in a container (response model).

type: "anthropic" | "custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

One of the following:

"anthropic"

"custom"

skill_id: string

Skill ID

minLength1

maxLength64

version: string

The resolved version: a skill version ID for custom skills.

minLength1

maxLength64

interface ContainerUploadBlock { type: "container_upload"; file_id }

Response model for a file uploaded to the container.

type: "container_upload"

defaultcontainer_upload

file_id: string

interface ContainerUploadBlockParam { type: "container_upload"; file_id; cache_control }

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.

type: "container_upload"

file_id: string

cache_control?: CacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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 for details.

One of the following:

"5m"

"1h"

type ContentBlock = TextBlock | ThinkingBlock | RedactedThinkingBlock | 9 more

One of the following:

type ContentBlockParam = TextBlockParam | ImageBlockParam | DocumentBlockParam | 13 more

One of the following:

interface ContentBlockSource { type: "content"; content }

type: "content"

content: string | Array<ContentBlockSourceContent>

One of the following:

string

Array<ContentBlockSourceContent>

interface TextBlockParam { type: "text"; text; cache_control; citations }

interface ImageBlockParam { type: "image"; source; cache_control; transformations }

type ContentBlockSourceContent = TextBlockParam | ImageBlockParam

One of the following:

interface TextBlockParam { type: "text"; text; cache_control; citations }

interface ImageBlockParam { type: "image"; source; cache_control; transformations }

interface Diagnostics { cache_miss_reason }

Request-level diagnostics: why the prompt cache could not fully reuse the prefix of the request named by diagnostics.previous_message_id.

cache_miss_reason: CacheMissReason | null

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.

One of the following:

interface DiagnosticsParam { previous_message_id }

Request-level diagnostics. Currently carries the previous response id for prompt-cache divergence reporting.

previous_message_id?: string | null

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.

maxLength256

interface DirectCaller { type: "direct" }

Tool invocation directly from the model.

type: "direct"

interface DocumentBlock { type: "document"; citations; source; title }

interface DocumentBlockParam { type: "document"; source; cache_control; /* 3 more */ }

interface EncryptedCodeExecutionResultBlock { type: "encrypted_code_execution_result"; content; encrypted_stdout; /* 2 more */ }

Code execution result with encrypted stdout for PFC + web_search results.

type: "encrypted_code_execution_result"

defaultencrypted_code_execution_result

content: Array<CodeExecutionOutputBlock { type: "code_execution_output"; file_id }>

type: "code_execution_output"

defaultcode_execution_output

file_id: string

encrypted_stdout: string

return_code: number

stderr: string

interface EncryptedCodeExecutionResultBlockParam { type: "encrypted_code_execution_result"; content; encrypted_stdout; /* 2 more */ }

Code execution result with encrypted stdout for PFC + web_search results.

type: "encrypted_code_execution_result"

content: Array<CodeExecutionOutputBlockParam { type: "code_execution_output"; file_id }>

type: "code_execution_output"

file_id: string

encrypted_stdout: string

return_code: number

stderr: string

interface FileDocumentSource { type: "file"; file_id }

type: "file"

file_id: string

interface FileImageSource { type: "file"; file_id }

type: "file"

file_id: string

interface ImageBlockParam { type: "image"; source; cache_control; transformations }

interface ImageTransformationsParam { oversized_image }

Configures the transformations the server applies to this image before the model observes it. Each key names a condition the server transforms images for; its value selects the transformation applied. Omitted keys keep their default behavior, and an empty object is equivalent to omitting the field.

oversized_image?: "downsize" | "error"

What the server does when this image exceeds the model's maximum image size. "downsize" (the default) scales the image down to fit, which changes the dimensions the model observes without telling you. "error" instead rejects the request with a 400 error naming the image's dimensions and the largest dimensions that fit, so you can scale the image deliberately — your image is never silently scaled down.

One of the following:

"downsize"

"error"

interface InputJSONDelta { type: "input_json_delta"; partial_json }

type: "input_json_delta"

defaultinput_json_delta

partial_json: string

interface JSONOutputFormat { type: "json_schema"; schema }

type: "json_schema"

schema: Record<string, unknown>

The JSON schema of the format

interface MemoryTool20250818 { type: "memory_20250818"; name; allowed_callers; /* 4 more */ }

interface Message { type: "message"; id; container; /* 8 more */ }

type MessageCountTokensTool = Tool | ToolBash20250124 | CodeExecutionTool20250522 | 18 more

One of the following:

type MessageCreateParamsContainer = ContainerParams | string | null

Container identifier for reuse across requests.

One of the following:

interface ContainerParams { id; skills }

Container parameters with skills to be loaded.

id?: string | null

Container id

skills?: Array<SkillParams> | null

List of skills to load in the container

maxItems20

type: "anthropic" | "custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

One of the following:

"anthropic"

"custom"

skill_id: string

Skill ID

minLength1

maxLength64

version?: string

Skill version or 'latest' for most recent version

minLength1

maxLength64

string

interface MessageDeltaUsage { cache_creation_input_tokens; cache_read_input_tokens; input_tokens; /* 3 more */ }

interface MessageParam { content; role }

interface MessageTokensCount { input_tokens }

input_tokens: number

The total number of tokens across the provided list of messages, system prompt, and tools.

interface Metadata { user_id }

user_id?: string | null

An external identifier for the user who is associated with the request.

This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.

maxLength512

type Model = "claude-haiku-5-5" | "claude-sonnet-5-5" | "claude-fable-5-1" | 17 more | (string & {})

The model that will complete your prompt.

See models for additional details and options.

One of the following:

interface OutputConfig { effort; format }

effort?: "low" | "medium" | "high" | 2 more | null

How much effort the model should put into its response. Higher effort levels may result in more thorough analysis but take longer.

Valid values are low, medium, high, xhigh, or max.

One of the following:

"low"

"medium"

"high"

"xhigh"

"max"

format?: JSONOutputFormat | null

A schema to specify Claude's output format in responses. See structured outputs

type: "json_schema"

schema: Record<string, unknown>

The JSON schema of the format

interface OutputTokensDetails { thinking_tokens }

thinking_tokens: number

Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens.

Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ output_tokens; output_tokens - thinking_tokens approximates the non-reasoning output.

default0

minimum0

interface PlainTextSource { type: "text"; data; media_type }

type: "text"

data: string

media_type: "text/plain"

type RawContentBlockDelta = TextDelta | InputJSONDelta | CitationsDelta | 2 more

One of the following:

interface RawContentBlockDeltaEvent { type: "content_block_delta"; delta; index }

type: "content_block_delta"

defaultcontent_block_delta

delta: RawContentBlockDelta

One of the following:

index: number

interface RawContentBlockStartEvent { type: "content_block_start"; content_block; index }

interface RawContentBlockStopEvent { type: "content_block_stop"; index }

type: "content_block_stop"

defaultcontent_block_stop

index: number

interface RawMessageDeltaEvent { type: "message_delta"; delta; usage }

interface RawMessageStartEvent { type: "message_start"; message }

type: "message_start"

defaultmessage_start

message: Message { type: "message"; id; container; /* 8 more */ }

interface RawMessageStopEvent { type: "message_stop" }

type: "message_stop"

defaultmessage_stop

type RawMessageStreamEvent = RawMessageStartEvent | RawMessageDeltaEvent | RawMessageStopEvent | 3 more

One of the following:

interface RedactedThinkingBlock { type: "redacted_thinking"; data }

type: "redacted_thinking"

defaultredacted_thinking

data: string

The contents of this redacted thinking block, returned when portions of the model's thinking were safety-redacted. This field is opaque and encrypted, with no readable content.

Pass redacted_thinking blocks back to the API unchanged when continuing a multi-turn conversation.

See extended thinking for details.

interface RedactedThinkingBlockParam { type: "redacted_thinking"; data }

type: "redacted_thinking"

data: string

The data value of this redacted thinking block, exactly as returned by the API in a previous response. Opaque and encrypted; pass it back unchanged.

interface RefusalStopDetails { type: "refusal"; category; explanation }

Structured information about a refusal.

type: "refusal"

defaultrefusal

category: "cyber" | "bio" | "frontier_llm" | 2 more | null

The policy category that triggered the refusal.

null when the refusal doesn't map to a named category.

One of the following:

"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. 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.

"general_harms"

The request could be related to an area that was determined as harmful. Benign work might sometimes trigger this category.

explanation: string | null

Human-readable explanation of the refusal.

This text is not guaranteed to be stable. null when no explanation is available for the category.

interface SearchResultBlockParam { type: "search_result"; content; source; /* 3 more */ }

interface ServerToolCaller { type: "code_execution_20250825"; tool_id }

Tool invocation generated by a server-side tool.

type: "code_execution_20250825"

tool_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

interface ServerToolCaller20260120 { type: "code_execution_20260120"; tool_id }

type: "code_execution_20260120"

tool_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

interface ServerToolUsage { web_fetch_requests; web_search_requests }

web_fetch_requests: number

The number of web fetch tool requests.

default0

minimum0

web_search_requests: number

The number of web search tool requests.

default0

minimum0

interface ServerToolUseBlock { type: "server_tool_use"; id; caller; /* 2 more */ }

interface ServerToolUseBlockParam { type: "server_tool_use"; id; input; /* 3 more */ }

interface SignatureDelta { type: "signature_delta"; signature }

type: "signature_delta"

defaultsignature_delta

signature: string

The signature for this thinking block: an opaque value used to verify that the block was generated by Claude when it is passed back to the API. Delivered in a signature_delta event just before the block's content_block_stop event.

interface SkillParams { type; skill_id; version }

Specification for a skill to be loaded in a container (request model).

type: "anthropic" | "custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

One of the following:

"anthropic"

"custom"

skill_id: string

Skill ID

minLength1

maxLength64

version?: string

Skill version or 'latest' for most recent version

minLength1

maxLength64

type StopReason = "end_turn" | "max_tokens" | "stop_sequence" | 4 more

One of the following:

"end_turn"

"max_tokens"

"stop_sequence"

"tool_use"

"pause_turn"

"refusal"

"model_context_window_exceeded"

interface TextBlock { type: "text"; citations; text }

interface TextBlockParam { type: "text"; text; cache_control; citations }

type TextCitation = CitationCharLocation | CitationPageLocation | CitationContentBlockLocation | 2 more

One of the following:

type TextCitationParam = CitationCharLocationParam | CitationPageLocationParam | CitationContentBlockLocationParam | 2 more

One of the following:

interface TextDelta { type: "text_delta"; text }

type: "text_delta"

defaulttext_delta

text: string

interface TextEditorCodeExecutionCreateResultBlock { type: "text_editor_code_execution_create_result"; is_file_update }

type: "text_editor_code_execution_create_result"

defaulttext_editor_code_execution_create_result

is_file_update: boolean

interface TextEditorCodeExecutionCreateResultBlockParam { type: "text_editor_code_execution_create_result"; is_file_update }

type: "text_editor_code_execution_create_result"

is_file_update: boolean

interface TextEditorCodeExecutionStrReplaceResultBlock { type: "text_editor_code_execution_str_replace_result"; lines; new_lines; /* 3 more */ }

type: "text_editor_code_execution_str_replace_result"

defaulttext_editor_code_execution_str_replace_result

lines: Array<string> | null

new_lines: number | null

new_start: number | null

old_lines: number | null

old_start: number | null

interface TextEditorCodeExecutionStrReplaceResultBlockParam { type: "text_editor_code_execution_str_replace_result"; lines; new_lines; /* 3 more */ }

type: "text_editor_code_execution_str_replace_result"

lines?: Array<string> | null

new_lines?: number | null

new_start?: number | null

old_lines?: number | null

old_start?: number | null

interface TextEditorCodeExecutionToolResultBlock { type: "text_editor_code_execution_tool_result"; content; tool_use_id }

interface TextEditorCodeExecutionToolResultBlockParam { type: "text_editor_code_execution_tool_result"; content; tool_use_id; cache_control }

interface TextEditorCodeExecutionToolResultError { type: "text_editor_code_execution_tool_result_error"; error_code; error_message }

type: "text_editor_code_execution_tool_result_error"

defaulttext_editor_code_execution_tool_result_error

error_code: TextEditorCodeExecutionToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"file_not_found"

error_message: string | null

type TextEditorCodeExecutionToolResultErrorCode = "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"file_not_found"

interface TextEditorCodeExecutionToolResultErrorParam { type: "text_editor_code_execution_tool_result_error"; error_code; error_message }

type: "text_editor_code_execution_tool_result_error"

error_code: TextEditorCodeExecutionToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"file_not_found"

error_message?: string | null

interface TextEditorCodeExecutionViewResultBlock { type: "text_editor_code_execution_view_result"; content; file_type; /* 3 more */ }

type: "text_editor_code_execution_view_result"

defaulttext_editor_code_execution_view_result

content: string

file_type: "text" | "image" | "pdf"

One of the following:

"text"

"image"

"pdf"

num_lines: number | null

start_line: number | null

total_lines: number | null

interface TextEditorCodeExecutionViewResultBlockParam { type: "text_editor_code_execution_view_result"; content; file_type; /* 3 more */ }

type: "text_editor_code_execution_view_result"

content: string

file_type: "text" | "image" | "pdf"

One of the following:

"text"

"image"

"pdf"

num_lines?: number | null

start_line?: number | null

total_lines?: number | null

interface ThinkingBlock { type: "thinking"; signature; thinking }

type: "thinking"

defaultthinking

signature: string

A value used to verify that this thinking block was generated by Claude when it is passed back to the API.

This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact.

See extended thinking for details.

thinking: string

The text of Claude's thinking process for this block.

interface ThinkingBlockParam { type: "thinking"; signature; thinking }

type: "thinking"

signature: string

The signature value of this thinking block, exactly as returned by the API in a previous response. Used to verify that the block was generated by Claude.

Thinking blocks must be passed back unmodified and in their original order; a modified block results in a 400 invalid_request_error.

thinking: string

The thinking text of this block as returned by the API.

interface ThinkingConfigAdaptive { type: "adaptive"; display }

type: "adaptive"

display?: "summarized" | "omitted" | null

Controls how thinking content appears in the response. When set to summarized, thinking is returned normally. When set to omitted, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see Controlling thinking display.

One of the following:

"summarized"

"omitted"

interface ThinkingConfigBetweenTools { type: "between_tools" }

type: "between_tools"

interface ThinkingConfigDisabled { type: "disabled" }

type: "disabled"

interface ThinkingConfigEnabled { type: "enabled"; budget_tokens; display }

type: "enabled"

budget_tokens: number

Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality.

Must be ≥1024 and less than max_tokens.

See extended thinking for details.

minimum1024

display?: "summarized" | "omitted" | null

One of the following:

"summarized"

"omitted"

type ThinkingConfigParam = ThinkingConfigEnabled | ThinkingConfigDisabled | ThinkingConfigBetweenTools | ThinkingConfigAdaptive

Configuration for Claude's thinking.

With {"type": "adaptive"}, Claude decides when and how much to think. With {"type": "enabled"} (manual extended thinking), you set a budget_tokens of at least 1,024. Thinking tokens count toward your max_tokens limit.

Which type values are accepted, and what happens when you omit thinking, depend on the model. See thinking for each model's behavior.

One of the following:

interface ThinkingDelta { type: "thinking_delta"; thinking }

type: "thinking_delta"

defaultthinking_delta

thinking: string

The incremental thinking text for this content block. Concatenate the thinking values of successive thinking_delta events to assemble the block's full thinking value.

interface Tool { type; input_schema; name; /* 7 more */ }

interface ToolBash20250124 { type: "bash_20250124"; name; allowed_callers; /* 4 more */ }

type ToolChoice = ToolChoiceAuto | ToolChoiceAny | ToolChoiceTool | ToolChoiceNone

How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.

One of the following:

interface ToolChoiceAny { type: "any"; disable_parallel_tool_use }

The model will use any available tools.

type: "any"

disable_parallel_tool_use?: boolean

Whether to disable parallel tool use.

Defaults to false. If set to true, the model will output exactly one tool use.

interface ToolChoiceAuto { type: "auto"; disable_parallel_tool_use }

The model will automatically decide whether to use tools.

type: "auto"

disable_parallel_tool_use?: boolean

Whether to disable parallel tool use.

Defaults to false. If set to true, the model will output at most one tool use.

interface ToolChoiceNone { type: "none" }

The model will not be allowed to use tools.

type: "none"

interface ToolChoiceTool { type: "tool"; name; disable_parallel_tool_use }

The model will use the specified tool with tool_choice.name.

type: "tool"

The name of the tool to use.

disable_parallel_tool_use?: boolean

Whether to disable parallel tool use.

Defaults to false. If set to true, the model will output exactly one tool use.

interface ToolReferenceBlock { type: "tool_reference"; tool_name }

type: "tool_reference"

defaulttool_reference

tool_name: string

minLength1

maxLength256

pattern^[a-zA-Z0-9_-]{1,256}$

interface ToolReferenceBlockParam { type: "tool_reference"; tool_name; cache_control }

Tool reference block that can be included in tool_result content.

type: "tool_reference"

tool_name: string

minLength1

maxLength256

pattern^[a-zA-Z0-9_-]{1,256}$

cache_control?: CacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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 for details.

One of the following:

"5m"

"1h"

interface ToolResultBlockParam { type: "tool_result"; tool_use_id; cache_control; /* 3 more */ }

interface ToolSearchToolBm25_20251119 { type; name; allowed_callers; /* 3 more */ }

interface ToolSearchToolRegex20251119 { type; name; allowed_callers; /* 3 more */ }

interface ToolSearchToolResultBlock { type: "tool_search_tool_result"; content; tool_use_id }

interface ToolSearchToolResultBlockParam { type: "tool_search_tool_result"; content; tool_use_id; cache_control }

interface ToolSearchToolResultError { type: "tool_search_tool_result_error"; error_code; error_message }

type: "tool_search_tool_result_error"

defaulttool_search_tool_result_error

error_code: ToolSearchToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

error_message: string | null

type ToolSearchToolResultErrorCode = "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

interface ToolSearchToolResultErrorParam { type: "tool_search_tool_result_error"; error_code; error_message }

type: "tool_search_tool_result_error"

error_code: ToolSearchToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

error_message?: string | null

interface ToolSearchToolSearchResultBlock { type: "tool_search_tool_search_result"; tool_references }

type: "tool_search_tool_search_result"

defaulttool_search_tool_search_result

tool_references: Array<ToolReferenceBlock { type: "tool_reference"; tool_name }>

type: "tool_reference"

defaulttool_reference

tool_name: string

minLength1

maxLength256

pattern^[a-zA-Z0-9_-]{1,256}$

interface ToolSearchToolSearchResultBlockParam { type: "tool_search_tool_search_result"; tool_references }

type: "tool_search_tool_search_result"

tool_references: Array<ToolReferenceBlockParam { type: "tool_reference"; tool_name; cache_control }>

type: "tool_reference"

tool_name: string

minLength1

maxLength256

pattern^[a-zA-Z0-9_-]{1,256}$

cache_control?: CacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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 for details.

One of the following:

"5m"

"1h"

interface ToolTextEditor20250124 { type: "text_editor_20250124"; name; allowed_callers; /* 4 more */ }

interface ToolTextEditor20250429 { type: "text_editor_20250429"; name; allowed_callers; /* 4 more */ }

interface ToolTextEditor20250728 { type: "text_editor_20250728"; name; allowed_callers; /* 5 more */ }

type ToolUnion = Tool | ToolBash20250124 | CodeExecutionTool20250522 | 18 more

One of the following:

interface ToolUseBlock { type: "tool_use"; id; caller; /* 3 more */ }

interface ToolUseBlockParam { type: "tool_use"; id; input; /* 4 more */ }

type ToolUseCaller = DirectCaller | ServerToolCaller | ServerToolCaller20260120

Which party invoked the tool call: the model directly, or a server tool on its behalf.

One of the following:

interface DirectCaller { type: "direct" }

Tool invocation directly from the model.

type: "direct"

interface ServerToolCaller { type: "code_execution_20250825"; tool_id }

Tool invocation generated by a server-side tool.

type: "code_execution_20250825"

tool_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

interface ServerToolCaller20260120 { type: "code_execution_20260120"; tool_id }

type: "code_execution_20260120"

tool_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

type ToolsetToolUseBlock = BrowserToolUseBlock | ComputerToolUseBlock | ToolUseBlock

One of the following:

interface URLImageSource { type: "url"; url }

type: "url"

url: string

interface URLPDFSource { type: "url"; url }

type: "url"

url: string

interface Usage { cache_creation; cache_creation_input_tokens; cache_read_input_tokens; /* 6 more */ }

interface UserLocation { type: "approximate"; city; country; /* 2 more */ }

type: "approximate"

city?: string | null

The city of the user.

minLength1

maxLength255

country?: string | null

The two letter ISO country code of the user.

minLength2

maxLength2

region?: string | null

The region of the user.

minLength1

maxLength255

timezone?: string | null

The IANA timezone of the user.

minLength1

maxLength255

interface WebFetchBlock { type: "web_fetch_result"; content; retrieved_at; url }

type: "web_fetch_result"

defaultweb_fetch_result

content: DocumentBlock { type: "document"; citations; source; title }

retrieved_at: string | null

ISO 8601 timestamp when the content was retrieved

url: string

Fetched content URL

interface WebFetchBlockParam { type: "web_fetch_result"; content; url; retrieved_at }

type: "web_fetch_result"

content: DocumentBlockParam { type: "document"; source; cache_control; /* 3 more */ }

url: string

Fetched content URL

retrieved_at?: string | null

ISO 8601 timestamp when the content was retrieved

interface WebFetchTool20250910 { type: "web_fetch_20250910"; name; allowed_callers; /* 9 more */ }

interface WebFetchTool20260209 { type: "web_fetch_20260209"; name; allowed_callers; /* 9 more */ }

interface WebFetchTool20260309 { type: "web_fetch_20260309"; name; allowed_callers; /* 10 more */ }

Web fetch tool with use_cache parameter for bypassing cached content.

interface WebFetchTool20260318 { type: "web_fetch_20260318"; name; allowed_callers; /* 11 more */ }

interface WebFetchToolResultBlock { type: "web_fetch_tool_result"; caller; content; tool_use_id }

interface WebFetchToolResultBlockParam { type: "web_fetch_tool_result"; content; tool_use_id; /* 2 more */ }

interface WebFetchToolResultErrorBlock { type: "web_fetch_tool_result_error"; error_code }

type: "web_fetch_tool_result_error"

defaultweb_fetch_tool_result_error

error_code: WebFetchToolResultErrorCode

One of the following:

"invalid_tool_input"

"url_too_long"

"url_not_allowed"

"url_not_in_prior_context"

"url_not_accessible"

"unsupported_content_type"

"too_many_requests"

"max_uses_exceeded"

"unavailable"

"content_too_large"

interface WebFetchToolResultErrorBlockParam { type: "web_fetch_tool_result_error"; error_code }

type: "web_fetch_tool_result_error"

error_code: WebFetchToolResultErrorCode

One of the following:

"invalid_tool_input"

"url_too_long"

"url_not_allowed"

"url_not_in_prior_context"

"url_not_accessible"

"unsupported_content_type"

"too_many_requests"

"max_uses_exceeded"

"unavailable"

"content_too_large"

type WebFetchToolResultErrorCode = "invalid_tool_input" | "url_too_long" | "url_not_allowed" | 7 more

One of the following:

"invalid_tool_input"

"url_too_long"

"url_not_allowed"

"url_not_in_prior_context"

"url_not_accessible"

"unsupported_content_type"

"too_many_requests"

"max_uses_exceeded"

"unavailable"

"content_too_large"

interface WebFetchURLSourceAll { type: "all" }

The url_sources variant under which a source contributes in full: every result of the tool filter's source, or all user input.

type: "all"

interface WebFetchURLSourceExcept { type: "except"; tools }

The tool filter variant under which every result but the named tools' contributes.

type: "except"

tools: Array<WebFetchURLSourceToolReference { type: "tool_reference"; name }>

type: "tool_reference"

interface WebFetchURLSourceNone { type: "none" }

The url_sources variant under which a source contributes nothing: no result of the tool filter's source, or no user input.

type: "none"

interface WebFetchURLSourceOnly { type: "only"; tools }

The tool filter variant under which only the named tools' results contribute.

type: "only"

tools: Array<WebFetchURLSourceToolReference { type: "tool_reference"; name }>

type: "tool_reference"

interface WebFetchURLSourceToolReference { type: "tool_reference"; name }

One entry of a tool filter's tools: it must name a tool declared in this request's tools[].

type: "tool_reference"

interface WebFetchURLSources { client_tool_results; server_tool_results; user_input }

Which sources contribute to the set of URLs web fetch may fetch.

Each key is a tagged variant: user_input is all or none; the two tool filters are all, none, only (only the named tools' results) or except (every result but the named tools'). A named tool must be declared in this request's tools[].

interface WebSearchResultBlock { type: "web_search_result"; encrypted_content; page_age; /* 2 more */ }

type: "web_search_result"

defaultweb_search_result

encrypted_content: string

page_age: string | null

title: string

url: string

interface WebSearchResultBlockParam { type: "web_search_result"; encrypted_content; title; /* 2 more */ }

type: "web_search_result"

encrypted_content: string

title: string

url: string

page_age?: string | null

interface WebSearchTool20250305 { type: "web_search_20250305"; name; allowed_callers; /* 7 more */ }

interface WebSearchTool20260209 { type: "web_search_20260209"; name; allowed_callers; /* 7 more */ }

interface WebSearchTool20260318 { type: "web_search_20260318"; name; allowed_callers; /* 8 more */ }

interface WebSearchToolRequestError { type: "web_search_tool_result_error"; error_code }

type: "web_search_tool_result_error"

error_code: WebSearchToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"max_uses_exceeded"

"too_many_requests"

"query_too_long"

"request_too_large"

interface WebSearchToolResultBlock { type: "web_search_tool_result"; caller; content; tool_use_id }

type WebSearchToolResultBlockContent = WebSearchToolResultError | Array<WebSearchResultBlock>

One of the following:

interface WebSearchToolResultBlockParam { type: "web_search_tool_result"; content; tool_use_id; /* 2 more */ }

type WebSearchToolResultBlockParamContent = Array<WebSearchResultBlockParam> | WebSearchToolRequestError

One of the following:

interface WebSearchToolResultError { type: "web_search_tool_result_error"; error_code }

type: "web_search_tool_result_error"

defaultweb_search_tool_result_error

error_code: WebSearchToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"max_uses_exceeded"

"too_many_requests"

"query_too_long"

"request_too_large"

type WebSearchToolResultErrorCode = "invalid_tool_input" | "unavailable" | "max_uses_exceeded" | 3 more

One of the following:

"invalid_tool_input"

"unavailable"

"max_uses_exceeded"

"too_many_requests"

"query_too_long"

"request_too_large"

MessagesBatches

Create a Message Batch

client.messages.batches.create(params, options?): MessageBatch

POST/v1/messages/batches

Send a batch of Message creation requests.

Retrieve a Message Batch

client.messages.batches.retrieve(messageBatchID, params?, options?): MessageBatch

GET/v1/messages/batches/{message_batch_id}

This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the results_url field in the response.

List Message Batches

client.messages.batches.list(params?, options?): Page<MessageBatch>

GET/v1/messages/batches

List all Message Batches within a Workspace. Most recently created batches are returned first.

Cancel a Message Batch

client.messages.batches.cancel(messageBatchID, params?, options?): MessageBatch

POST/v1/messages/batches/{message_batch_id}/cancel

Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a canceling state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation.

Delete a Message Batch

client.messages.batches.delete(messageBatchID, params?, options?): DeletedMessageBatch

DELETE/v1/messages/batches/{message_batch_id}

Retrieve Message Batch results

client.messages.batches.results(messageBatchID, params?, options?): MessageBatchIndividualResponse | Stream<MessageBatchIndividualResponse>

GET/v1/messages/batches/{message_batch_id}/results

Streams the results of a Message Batch as a .jsonl file.

Messages

Models

MessagesBatches

MessagesBatches