> ## Documentation Index > Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create a Message > Create a Message through the OMA API. OMA forwards the request to the configured model upstream. Optional beta fields depend on that upstream. ## OpenAPI ````yaml /openapi/oma.en.json post /v1/messages openapi: 3.1.0 info: title: OMA API Reference version: 1.0.0 description: Open Managed Agents application API reference. servers: - url: http://localhost:38080 description: Local OMA server security: - omaApiKey: [] - omaBearer: [] paths: /v1/messages: post: summary: Create a Message description: >- Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. The Messages API can be used for either single queries or stateless multi-turn conversations. Learn more about the Messages API in our user guide operationId: beta_messages_post parameters: - name: beta in: query required: true description: Selects the beta API contract for this endpoint. Must be `true`. schema: type: boolean enum: - true - name: anthropic-beta in: header required: false schema: type: string items: type: string description: >- Optional header to specify the beta version(s) you want to use. To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta. title: Anthropic-Beta x-stainless-override-schema: x-stainless-param: betas x-stainless-extend-default: true type: array description: Optional header to specify the beta version(s) you want to use. items: $ref: '#/components/schemas/AnthropicBeta' description: >- Optional header to specify the beta version(s) you want to use. To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta. - name: anthropic-version in: header required: false schema: type: string description: |- The version of the OMA API you want to use. Read more about versioning and our version history here. title: Anthropic-Version description: |- The version of the OMA API you want to use. Read more about versioning and our version history here. - name: anthropic-user-profile-id in: header required: false schema: type: string description: >- The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header. title: Anthropic-User-Profile-Id x-stainless-param: user_profile_id description: >- The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header. requestBody: content: application/json: schema: $ref: '#/components/schemas/BetaCreateMessageParams' required: true responses: '200': description: Message object. content: application/json: schema: $ref: '#/components/schemas/BetaMessage' 4XX: description: |- Error response. See our errors documentation for more details. content: application/json: schema: $ref: '#/components/schemas/BetaErrorResponse' components: schemas: BetaCreateMessageParams: additionalProperties: false example: max_tokens: 1024 messages: - content: Hello, world role: user model: claude-opus-4-6 properties: model: $ref: '#/components/schemas/Model' messages: description: >- Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{"role": "user", "content": "Hello, the model"}] ``` Example with multiple conversational turns: ```json [ {"role": "user", "content": "Hello there."}, {"role": "assistant", "content": "Hi, I'm the model. How can I help you?"}, {"role": "user", "content": "Can you explain LLMs in plain English?"}, ] ``` Example with a partially-filled response from the model: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("}, ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json {"role": "user", "content": "Hello, the model"} ``` ```json {"role": "user", "content": [{"type": "text", "text": "Hello, the model"}]} ``` See input examples. Note that if you want to include a system prompt, you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request. items: $ref: '#/components/schemas/BetaInputMessage' title: Messages type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: >- Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. title: Cache Control container: anyOf: - $ref: '#/components/schemas/BetaContainerParams' - type: string - type: 'null' description: Container identifier for reuse across requests. title: Container context_management: anyOf: - $ref: '#/components/schemas/BetaContextManagementConfig' - type: 'null' description: >- Context management configuration. This allows you to control how the model manages context across multiple requests, such as whether to clear function results or not. diagnostics: anyOf: - $ref: '#/components/schemas/BetaDiagnosticsParam' - type: 'null' description: >- Request-level diagnostics. Supply `previous_message_id` to have the response include `diagnostics.cache_miss_reason` explaining any prompt-cache divergence from that prior request. fallback_credit_token: anyOf: - maxLength: 2048 minLength: 1 type: string - $ref: '#/components/schemas/BetaFallbackCreditTokenParam' - type: 'null' description: >- The `fallback_credit_token` from a prior refusal's `stop_details`. When a preceding request was refused and returned a `fallback_credit_token`, pass that code here on the retry to have the retry's cache-creation tokens for the prefix that was warm on the refused model billed at the cache-read rate. Must be redeemed by the same organization and workspace, with the same request body (optionally extended by one appended `assistant` message whose content is the partial text — with any trailing whitespace stripped from the final text block — and paired server-tool blocks streamed before the refusal; the appended-assistant form is not available for requests with `output_format` set or forced `tool_choice`), on an eligible fallback model, on the same platform, and within 5 minutes of the refusal; a mismatch is a 400. A token minted mid-server-tool-loop whose partial content was continuable may only be redeemed with the appended-assistant form — if an exact-body retry is rejected with a 400 saying the token must be redeemed by continuing the partial response, retry with the appended-assistant form instead. When the appended-assistant form is used on a model that otherwise disallows assistant-turn prefill, this token also authorizes that one prefill. title: Fallback Credit Token fallbacks: anyOf: - items: $ref: '#/components/schemas/BetaFallbackConfigV2' maxItems: 3 minItems: 1 type: array - const: default type: string title: FallbacksDefault x-stainless-variantName: Default - type: 'null' description: >- Opt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order: if the first entry also declines, the second is tried, and so on. The string "default" requests the requested model's server-defined default fallback configuration. title: Fallbacks inference_geo: anyOf: - type: string - type: 'null' description: >- Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. title: Inference Geo max_tokens: description: >- The maximum number of tokens to generate before stopping. Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. Set to `0` to populate the prompt cache without generating a response. Different models have different maximum values for this parameter. See models for details. examples: - 1024 minimum: 0 title: Max Tokens type: integer mcp_servers: description: MCP servers to be utilized in this request items: $ref: '#/components/schemas/BetaRequestMCPServerURLDefinition' maxItems: 20 title: Mcp Servers type: array metadata: $ref: '#/components/schemas/BetaMetadata' description: An object describing metadata about the request. output_config: $ref: '#/components/schemas/BetaOutputConfig' description: >- Configuration options for the model's output, such as the output format. output_format: anyOf: - $ref: '#/components/schemas/BetaJsonOutputFormat' - type: 'null' deprecated: true description: >- Deprecated: Use `output_config.format` instead. See structured outputs A schema to specify the model's output format in responses. This parameter will be removed in a future release. service_tier: description: >- Determines whether to use priority capacity (if available) or standard capacity for this request. OMA offers different levels of service for your API requests. See service-tiers for details. enum: - auto - standard_only title: Service Tier type: string speed: anyOf: - $ref: '#/components/schemas/BetaSpeed' - type: 'null' description: >- The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. stop_sequences: description: >- Custom text sequences that will cause the model to stop generating. Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. items: type: string title: Stop Sequences type: array stream: description: >- Whether to incrementally stream the response using server-sent events. See streaming for details. title: Stream type: boolean example: false system: anyOf: - type: string x-stainless-skip: - go - items: $ref: '#/components/schemas/BetaRequestTextBlock' type: array description: >- System prompt. A system prompt is a way of providing context and instructions to the model, such as specifying a particular goal or role. See our guide to system prompts. examples: - - text: Today's date is 2024-06-01. type: text - Today's date is 2023-01-01. title: System temperature: deprecated: true description: >- Amount of randomness injected into the response. Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. Note that even with `temperature` of `0.0`, the results will not be fully deterministic. examples: - 1 maximum: 1 minimum: 0 title: Temperature type: number x-stainless-deprecation-message: >- Deprecated. Models released after Opus 4.6 do not support setting temperature. A value of 1.0 will be accepted for backwards compatibility; all other values will be rejected with a 400 error. thinking: $ref: '#/components/schemas/BetaThinkingConfigParam' tool_choice: $ref: '#/components/schemas/BetaToolChoice' tools: description: >- Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For server tools, see their individual documentation as each has its own behavior (e.g., the web search tool). Each tool definition includes: * `name`: Name of the tool. * `description`: Optional, but strongly-recommended description of the tool. * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our guide for more details. examples: - description: Get the current weather in a given location input_schema: properties: location: description: The city and state, e.g. San Francisco, CA type: string unit: description: Unit for the output - one of (celsius, fahrenheit) type: string required: - location type: object name: get_weather items: oneOf: - $ref: '#/components/schemas/BetaTool' - $ref: '#/components/schemas/BetaBashTool_20241022' - $ref: '#/components/schemas/BetaBashTool_20250124' - $ref: '#/components/schemas/BetaCodeExecutionTool_20250522' - $ref: '#/components/schemas/BetaCodeExecutionTool_20250825' - $ref: '#/components/schemas/BetaCodeExecutionTool_20260120' - $ref: '#/components/schemas/BetaCodeExecutionTool_20260521' - $ref: '#/components/schemas/BetaComputerUseTool_20241022' - $ref: '#/components/schemas/BetaMemoryTool_20250818' - $ref: '#/components/schemas/BetaComputerUseTool_20250124' - $ref: '#/components/schemas/BetaTextEditor_20241022' - $ref: '#/components/schemas/BetaComputerUseTool_20251124' - $ref: '#/components/schemas/BetaTextEditor_20250124' - $ref: '#/components/schemas/BetaTextEditor_20250429' - $ref: '#/components/schemas/BetaTextEditor_20250728' - $ref: '#/components/schemas/BetaWebSearchTool_20250305' - $ref: '#/components/schemas/BetaWebFetchTool_20250910' - $ref: '#/components/schemas/BetaWebSearchTool_20260209' - $ref: '#/components/schemas/BetaWebFetchTool_20260209' - $ref: '#/components/schemas/BetaWebFetchTool_20260309' - $ref: '#/components/schemas/BetaWebSearchTool_20260318' - $ref: '#/components/schemas/BetaWebFetchTool_20260318' - $ref: '#/components/schemas/BetaAdvisorTool_20260301' - $ref: '#/components/schemas/BetaToolSearchToolBM25_20251119' - $ref: '#/components/schemas/BetaToolSearchToolRegex_20251119' - $ref: '#/components/schemas/BetaMCPToolset' title: Tools type: array top_k: deprecated: true description: >- Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). Recommended for advanced use cases only. examples: - 5 minimum: 0 title: Top K type: integer x-stainless-deprecation-message: >- Deprecated. Models released after Opus 4.6 do not accept top_k; any value will be rejected with a 400 error. top_p: deprecated: true description: >- Use nucleus sampling. In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. Recommended for advanced use cases only. examples: - 0.7 maximum: 1 minimum: 0 title: Top P type: number x-stainless-deprecation-message: >- Deprecated. Models released after Opus 4.6 do not support setting top_p. A value greater than or equal to 0.99 will be accepted for backwards compatibility; all other values will be rejected with a 400 error. required: - model - messages - max_tokens title: CreateMessageParams type: object BetaMessage: examples: - content: - citations: null text: Hi! I am your AI assistant. type: text id: msg_013Zva2CMHLNnXjNJJKqJ2EF model: claude-opus-4-6 role: assistant stop_details: null stop_reason: end_turn stop_sequence: null type: message usage: input_tokens: 2095 output_tokens: 503 properties: id: description: |- Unique object identifier. The format and length of IDs may change over time. examples: - msg_013Zva2CMHLNnXjNJJKqJ2EF title: Id type: string type: const: message default: message description: |- Object type. For Messages, this is always `"message"`. title: Type type: string role: const: assistant default: assistant description: |- Conversational role of the generated message. This will always be `"assistant"`. title: Role type: string content: description: >- Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm the model."}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` examples: - - citations: null text: Hi! I am your AI assistant. type: text items: $ref: '#/components/schemas/BetaContentBlock' title: Content type: array model: $ref: '#/components/schemas/Model' stop_reason: anyOf: - $ref: '#/components/schemas/BetaStopReason' - type: 'null' description: >- The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations * `"model_context_window_exceeded"`: we exceeded the model's context window In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. title: Stop Reason stop_sequence: anyOf: - type: string - type: 'null' default: null description: >- Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. title: Stop Sequence stop_details: anyOf: - $ref: '#/components/schemas/BetaRefusalStopDetails' - type: 'null' default: null description: >- Structured information about why model output stopped. This is `null` when the `stop_reason` has no additional detail to report. usage: $ref: '#/components/schemas/BetaUsage' description: >- Billing and rate-limit usage. OMA's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from the model. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. examples: - input_tokens: 2095 output_tokens: 503 diagnostics: anyOf: - $ref: '#/components/schemas/BetaDiagnostics' - type: 'null' default: null description: >- Request-level diagnostics. Present only when `diagnostics` was supplied on the request; `null` when no prompt-cache divergence was detected. context_management: anyOf: - $ref: '#/components/schemas/BetaResponseContextManagement' - type: 'null' default: null description: >- Context management response. Information about context management strategies applied during the request. container: anyOf: - $ref: '#/components/schemas/BetaContainer' - type: 'null' default: null description: >- Information about the container used in this request. This will be non-null if a container tool (e.g. code execution) was used. required: - id - type - role - content - model - stop_reason - stop_sequence - stop_details - usage - diagnostics - context_management - container title: Message type: object x-stainless-python-custom-imports: - from .beta_content_block import BetaContentBlock as BetaContentBlock BetaErrorResponse: properties: error: discriminator: mapping: api_error: $ref: '#/components/schemas/BetaAPIError' authentication_error: $ref: '#/components/schemas/BetaAuthenticationError' billing_error: $ref: '#/components/schemas/BetaBillingError' invalid_request_error: $ref: '#/components/schemas/BetaInvalidRequestError' not_found_error: $ref: '#/components/schemas/BetaNotFoundError' overloaded_error: $ref: '#/components/schemas/BetaOverloadedError' permission_error: $ref: '#/components/schemas/BetaPermissionError' rate_limit_error: $ref: '#/components/schemas/BetaRateLimitError' timeout_error: $ref: '#/components/schemas/BetaGatewayTimeoutError' propertyName: type oneOf: - $ref: '#/components/schemas/BetaInvalidRequestError' - $ref: '#/components/schemas/BetaAuthenticationError' - $ref: '#/components/schemas/BetaBillingError' - $ref: '#/components/schemas/BetaPermissionError' - $ref: '#/components/schemas/BetaNotFoundError' - $ref: '#/components/schemas/BetaRateLimitError' - $ref: '#/components/schemas/BetaGatewayTimeoutError' - $ref: '#/components/schemas/BetaAPIError' - $ref: '#/components/schemas/BetaOverloadedError' title: Error request_id: anyOf: - type: string - type: 'null' default: null title: Request Id type: const: error default: error title: Type type: string required: - error - request_id - type title: ErrorResponse type: object Model: title: Model description: |- The model that will complete your prompt. See models for additional details and options. anyOf: - type: string - const: claude-sonnet-5 description: High-performance model for coding and agents x-stainless-nominal: false - const: claude-fable-5 description: >- Next generation of intelligence for the hardest knowledge work and coding problems x-stainless-nominal: false - const: claude-mythos-5 description: Most capable model for cybersecurity and biology research x-stainless-nominal: false - const: claude-opus-5 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-8 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-7 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-mythos-preview description: New class of intelligence, strongest in coding and cybersecurity x-stainless-nominal: false deprecated: true x-stainless-deprecation-message: >- Reaches end of life on June 30, 2026. Please migrate to `claude-mythos-5`. - const: claude-opus-4-6 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-sonnet-4-6 description: Best combination of speed and intelligence x-stainless-nominal: false - const: claude-haiku-4-5 description: Fastest model with near-frontier intelligence x-stainless-nominal: false - const: claude-haiku-4-5-20251001 description: Fastest model with near-frontier intelligence x-stainless-nominal: false - const: claude-opus-4-5 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-opus-4-5-20251101 description: Powerful intelligence for long-running agents and coding x-stainless-nominal: false - const: claude-sonnet-4-5 description: High-performance model for agents and coding x-stainless-nominal: false - const: claude-sonnet-4-5-20250929 description: High-performance model for agents and coding x-stainless-nominal: false BetaInputMessage: additionalProperties: false properties: content: anyOf: - type: string x-stainless-skip: - go - cli - items: $ref: '#/components/schemas/BetaInputContentBlock' type: array example: - type: text text: What is a quaternion? title: Content role: enum: - user - assistant - system title: Role type: string required: - content - role title: InputMessage type: object discriminator: propertyName: role BetaCacheControlEphemeral: additionalProperties: false properties: ttl: description: |- 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. enum: - 5m - 1h title: Ttl type: string x-stainless-renameMap: ttl_5m: 5m ttl_1h: 1h type: const: ephemeral title: Type type: string required: - type title: CacheControlEphemeral type: object x-stainless-go-constant-constructor: true BetaContainerParams: additionalProperties: false description: Container parameters with skills to be loaded. properties: id: anyOf: - type: string - type: 'null' description: Container id title: Id skills: anyOf: - items: $ref: '#/components/schemas/BetaSkillParams' maxItems: 8 type: array - type: 'null' description: List of skills to load in the container title: Skills title: ContainerParams type: object BetaContextManagementConfig: additionalProperties: false properties: edits: description: List of context management edits to apply items: discriminator: mapping: clear_thinking_20251015: $ref: '#/components/schemas/BetaClearThinking20251015' clear_tool_uses_20250919: $ref: '#/components/schemas/BetaClearToolUses20250919' compact_20260112: $ref: '#/components/schemas/BetaCompact20260112' propertyName: type oneOf: - $ref: '#/components/schemas/BetaClearToolUses20250919' - $ref: '#/components/schemas/BetaClearThinking20251015' - $ref: '#/components/schemas/BetaCompact20260112' minItems: 0 title: Edits type: array title: ContextManagementConfig type: object BetaDiagnosticsParam: additionalProperties: false description: |- Request-level diagnostics. Currently carries the previous response id for prompt-cache divergence reporting. properties: previous_message_id: anyOf: - maxLength: 256 type: string - type: 'null' description: >- 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. title: Previous Message Id title: DiagnosticsParam type: object BetaFallbackCreditTokenParam: additionalProperties: false description: |- Object form of ``fallback_credit_token``: the token plus a redemption mode. Requires ``anthropic-beta: fallback-credit-2026-07-01``; without that header the field accepts the bare string only. The bare string and the mode-less object are equivalent (both select ``strict``), so wrapping an existing token changes nothing by itself. properties: mode: description: >- How a failing token affects the retry. `strict` (the default, and the bare-string behavior): a failing redemption is a 400 and the retry is not served. `best_effort`: the retry is served either way — a token-layer failure no longer rejects the request; the retry proceeds at normal price and the outcome is reported on the response's `usage.fallback_credit`. Two failures stay hard in both modes: a malformed token, and combining `fallback_credit_token` with `fallbacks`. enum: - strict - best_effort title: Mode type: string token: description: >- The opaque `fallback_credit_token` from a prior refusal's `stop_details` — the same string the bare-string form carries. maxLength: 2048 minLength: 1 title: Token type: string required: - token title: FallbackCreditTokenParam type: object BetaFallbackConfigV2: additionalProperties: true description: |- One entry in the `fallbacks` chain on a `/v1/messages` request. `model` is required. The override fields (`max_tokens`, `thinking`, `output_config`, and `speed`) set the corresponding parameter for this attempt only and are validated as if the request were made to `model`. Any other key is rejected at parse time. properties: max_tokens: anyOf: - type: integer - type: 'null' title: Max Tokens model: $ref: '#/components/schemas/Model' output_config: anyOf: - $ref: '#/components/schemas/BetaOutputConfig' - type: 'null' speed: anyOf: - $ref: '#/components/schemas/BetaSpeed' - type: 'null' thinking: anyOf: - discriminator: mapping: adaptive: $ref: '#/components/schemas/BetaThinkingConfigAdaptive' disabled: $ref: '#/components/schemas/BetaThinkingConfigDisabled' enabled: $ref: '#/components/schemas/BetaThinkingConfigEnabled' propertyName: type oneOf: - $ref: '#/components/schemas/BetaThinkingConfigEnabled' - $ref: '#/components/schemas/BetaThinkingConfigDisabled' - $ref: '#/components/schemas/BetaThinkingConfigAdaptive' - type: 'null' title: Thinking required: - model title: FallbackConfigV2 type: object BetaRequestMCPServerURLDefinition: additionalProperties: false properties: authorization_token: anyOf: - type: string - type: 'null' title: Authorization Token name: title: Name type: string tool_configuration: anyOf: - $ref: '#/components/schemas/BetaRequestMCPServerToolConfiguration' - type: 'null' type: const: url title: Type type: string url: title: Url type: string required: - name - type - url title: RequestMCPServerURLDefinition type: object BetaMetadata: additionalProperties: false properties: user_id: anyOf: - maxLength: 512 type: string - type: 'null' description: >- An external identifier for the user who is associated with the request. This should be a uuid, hash value, or other opaque identifier. OMA may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. examples: - 13803d75-b4b5-4c3e-b2a2-6f21399b021b title: User Id title: Metadata type: object BetaOutputConfig: additionalProperties: false properties: effort: anyOf: - $ref: '#/components/schemas/BetaEffortLevel' - type: 'null' description: >- 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`. format: anyOf: - $ref: '#/components/schemas/BetaJsonOutputFormat' - type: 'null' description: >- A schema to specify the model's output format in responses. See structured outputs task_budget: anyOf: - $ref: '#/components/schemas/BetaTokenTaskBudget' - type: 'null' description: Configuration for token budget tracking across contexts. title: OutputConfig type: object BetaJsonOutputFormat: additionalProperties: false properties: schema: additionalProperties: true description: The JSON schema of the format title: Schema type: object type: const: json_schema title: Type type: string required: - schema - type title: JsonOutputFormat type: object BetaSpeed: type: string description: >- Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. enum: - standard - fast BetaRequestTextBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control citations: anyOf: - items: discriminator: mapping: char_location: $ref: '#/components/schemas/BetaRequestCharLocationCitation' content_block_location: $ref: >- #/components/schemas/BetaRequestContentBlockLocationCitation page_location: $ref: '#/components/schemas/BetaRequestPageLocationCitation' search_result_location: $ref: >- #/components/schemas/BetaRequestSearchResultLocationCitation web_search_result_location: $ref: >- #/components/schemas/BetaRequestWebSearchResultLocationCitation propertyName: type oneOf: - $ref: '#/components/schemas/BetaRequestCharLocationCitation' - $ref: '#/components/schemas/BetaRequestPageLocationCitation' - $ref: >- #/components/schemas/BetaRequestContentBlockLocationCitation - $ref: >- #/components/schemas/BetaRequestWebSearchResultLocationCitation - $ref: >- #/components/schemas/BetaRequestSearchResultLocationCitation type: array - type: 'null' title: Citations text: minLength: 1 title: Text type: string type: const: text title: Type type: string required: - text - type title: RequestTextBlock type: object BetaThinkingConfigParam: description: >- Configuration for enabling the model's extended thinking. When enabled, responses include `thinking` content blocks showing the model's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. See extended thinking for details. discriminator: mapping: adaptive: $ref: '#/components/schemas/BetaThinkingConfigAdaptive' disabled: $ref: '#/components/schemas/BetaThinkingConfigDisabled' enabled: $ref: '#/components/schemas/BetaThinkingConfigEnabled' propertyName: type examples: - type: adaptive oneOf: - $ref: '#/components/schemas/BetaThinkingConfigEnabled' - $ref: '#/components/schemas/BetaThinkingConfigDisabled' - $ref: '#/components/schemas/BetaThinkingConfigAdaptive' title: Thinking BetaToolChoice: description: >- 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. discriminator: mapping: any: $ref: '#/components/schemas/BetaToolChoiceAny' auto: $ref: '#/components/schemas/BetaToolChoiceAuto' none: $ref: '#/components/schemas/BetaToolChoiceNone' tool: $ref: '#/components/schemas/BetaToolChoiceTool' propertyName: type oneOf: - $ref: '#/components/schemas/BetaToolChoiceAuto' - $ref: '#/components/schemas/BetaToolChoiceAny' - $ref: '#/components/schemas/BetaToolChoiceTool' - $ref: '#/components/schemas/BetaToolChoiceNone' title: Tool Choice BetaTool: additionalProperties: false properties: type: anyOf: - type: 'null' - const: custom type: string title: Type description: description: >- Description of what this tool does. Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. examples: - Get the current weather in a given location title: Description type: string name: description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. maxLength: 128 minLength: 1 pattern: ^[a-zA-Z0-9_-]{1,128}$ title: Name type: string input_schema: $ref: '#/components/schemas/BetaInputSchema' description: >- [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. This defines the shape of the `input` that your tool accepts and that the model will produce. examples: - properties: location: description: The city and state, e.g. San Francisco, CA type: string unit: description: Unit for the output - one of (celsius, fahrenheit) type: string required: - location type: object cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean eager_input_streaming: anyOf: - type: boolean - type: 'null' description: >- Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. title: Eager Input Streaming allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array required: - name - input_schema title: Tool type: object BetaBashTool_20241022: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array name: const: bash description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: bash_20241022 title: Type type: string required: - name - type title: BashTool_20241022 type: object BetaBashTool_20250124: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array name: const: bash description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: bash_20250124 title: Type type: string required: - name - type title: BashTool_20250124 type: object BetaCodeExecutionTool_20250522: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean name: const: code_execution description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: code_execution_20250522 title: Type type: string required: - name - type title: CodeExecutionTool_20250522 type: object BetaCodeExecutionTool_20250825: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean name: const: code_execution description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: code_execution_20250825 title: Type type: string required: - name - type title: CodeExecutionTool_20250825 type: object BetaCodeExecutionTool_20260120: additionalProperties: false description: >- Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean name: const: code_execution description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: code_execution_20260120 title: Type type: string required: - name - type title: CodeExecutionTool_20260120 type: object BetaCodeExecutionTool_20260521: additionalProperties: false description: Code execution tool with REPL state persistence. properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean name: const: code_execution description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: code_execution_20260521 title: Type type: string required: - name - type title: CodeExecutionTool_20260521 type: object BetaComputerUseTool_20241022: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean display_height_px: description: The height of the display in pixels. minimum: 1 title: Display Height Px type: integer display_number: anyOf: - minimum: 0 type: integer - type: 'null' description: The X11 display number (e.g. 0, 1) for the display. title: Display Number display_width_px: description: The width of the display in pixels. minimum: 1 title: Display Width Px type: integer input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array name: const: computer description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: computer_20241022 title: Type type: string required: - display_height_px - display_width_px - name - type title: ComputerUseTool_20241022 type: object BetaMemoryTool_20250818: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array name: const: memory description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: memory_20250818 title: Type type: string required: - name - type title: MemoryTool_20250818 type: object BetaComputerUseTool_20250124: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean display_height_px: description: The height of the display in pixels. minimum: 1 title: Display Height Px type: integer display_number: anyOf: - minimum: 0 type: integer - type: 'null' description: The X11 display number (e.g. 0, 1) for the display. title: Display Number display_width_px: description: The width of the display in pixels. minimum: 1 title: Display Width Px type: integer input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array name: const: computer description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: computer_20250124 title: Type type: string required: - display_height_px - display_width_px - name - type title: ComputerUseTool_20250124 type: object BetaTextEditor_20241022: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array name: const: str_replace_editor description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: text_editor_20241022 title: Type type: string required: - name - type title: TextEditor_20241022 type: object BetaComputerUseTool_20251124: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean display_height_px: description: The height of the display in pixels. minimum: 1 title: Display Height Px type: integer display_number: anyOf: - minimum: 0 type: integer - type: 'null' description: The X11 display number (e.g. 0, 1) for the display. title: Display Number display_width_px: description: The width of the display in pixels. minimum: 1 title: Display Width Px type: integer enable_zoom: description: >- Whether to enable an action to take a zoomed-in screenshot of the screen. title: Enable Zoom type: boolean input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array name: const: computer description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: computer_20251124 title: Type type: string required: - display_height_px - display_width_px - name - type title: ComputerUseTool_20251124 type: object BetaTextEditor_20250124: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array name: const: str_replace_editor description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: text_editor_20250124 title: Type type: string required: - name - type title: TextEditor_20250124 type: object BetaTextEditor_20250429: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array name: const: str_replace_based_edit_tool description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: text_editor_20250429 title: Type type: string required: - name - type title: TextEditor_20250429 type: object BetaTextEditor_20250728: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean input_examples: items: additionalProperties: $ref: '#/components/schemas/BetaJsonValue' type: object title: Input Examples type: array max_characters: anyOf: - minimum: 1 type: integer - type: 'null' description: >- Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. title: Max Characters name: const: str_replace_based_edit_tool description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: text_editor_20250728 title: Type type: string required: - name - type title: TextEditor_20250728 type: object BetaWebSearchTool_20250305: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array allowed_domains: anyOf: - items: type: string type: array - type: 'null' description: >- If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. title: Allowed Domains blocked_domains: anyOf: - items: type: string type: array - type: 'null' description: >- If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. title: Blocked Domains cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean max_uses: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: Maximum number of times the tool can be used in the API request. title: Max Uses name: const: web_search description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: web_search_20250305 title: Type type: string user_location: anyOf: - $ref: '#/components/schemas/BetaUserLocation' - type: 'null' description: >- Parameters for the user's location. Used to provide more relevant search results. required: - name - type title: WebSearchTool_20250305 type: object BetaWebFetchTool_20250910: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array allowed_domains: anyOf: - items: type: string type: array - type: 'null' description: List of domains to allow fetching from title: Allowed Domains blocked_domains: anyOf: - items: type: string type: array - type: 'null' description: List of domains to block fetching from title: Blocked Domains cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control citations: anyOf: - $ref: '#/components/schemas/BetaRequestCitationsConfig' - type: 'null' description: >- Citations configuration for fetched documents. Citations are disabled by default. defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean max_content_tokens: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: >- Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. title: Max Content Tokens max_uses: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: Maximum number of times the tool can be used in the API request. title: Max Uses name: const: web_fetch description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: web_fetch_20250910 title: Type type: string required: - name - type title: WebFetchTool_20250910 type: object BetaWebSearchTool_20260209: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array allowed_domains: anyOf: - items: type: string type: array - type: 'null' description: >- If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. title: Allowed Domains blocked_domains: anyOf: - items: type: string type: array - type: 'null' description: >- If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. title: Blocked Domains cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean max_uses: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: Maximum number of times the tool can be used in the API request. title: Max Uses name: const: web_search description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: web_search_20260209 title: Type type: string user_location: anyOf: - $ref: '#/components/schemas/BetaUserLocation' - type: 'null' description: >- Parameters for the user's location. Used to provide more relevant search results. required: - name - type title: WebSearchTool_20260209 type: object BetaWebFetchTool_20260209: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array allowed_domains: anyOf: - items: type: string type: array - type: 'null' description: List of domains to allow fetching from title: Allowed Domains blocked_domains: anyOf: - items: type: string type: array - type: 'null' description: List of domains to block fetching from title: Blocked Domains cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control citations: anyOf: - $ref: '#/components/schemas/BetaRequestCitationsConfig' - type: 'null' description: >- Citations configuration for fetched documents. Citations are disabled by default. defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean max_content_tokens: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: >- Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. title: Max Content Tokens max_uses: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: Maximum number of times the tool can be used in the API request. title: Max Uses name: const: web_fetch description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: web_fetch_20260209 title: Type type: string required: - name - type title: WebFetchTool_20260209 type: object BetaWebFetchTool_20260309: additionalProperties: false description: Web fetch tool with use_cache parameter for bypassing cached content. properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array allowed_domains: anyOf: - items: type: string type: array - type: 'null' description: List of domains to allow fetching from title: Allowed Domains blocked_domains: anyOf: - items: type: string type: array - type: 'null' description: List of domains to block fetching from title: Blocked Domains cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control citations: anyOf: - $ref: '#/components/schemas/BetaRequestCitationsConfig' - type: 'null' description: >- Citations configuration for fetched documents. Citations are disabled by default. defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean max_content_tokens: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: >- Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. title: Max Content Tokens max_uses: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: Maximum number of times the tool can be used in the API request. title: Max Uses name: const: web_fetch description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: web_fetch_20260309 title: Type type: string use_cache: description: >- Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. title: Use Cache type: boolean required: - name - type title: WebFetchTool_20260309 type: object BetaWebSearchTool_20260318: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array allowed_domains: anyOf: - items: type: string type: array - type: 'null' description: >- If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. title: Allowed Domains blocked_domains: anyOf: - items: type: string type: array - type: 'null' description: >- If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. title: Blocked Domains cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean max_uses: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: Maximum number of times the tool can be used in the API request. title: Max Uses name: const: web_search description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string response_inclusion: description: >- How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn. enum: - full - excluded title: Response Inclusion type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: web_search_20260318 title: Type type: string user_location: anyOf: - $ref: '#/components/schemas/BetaUserLocation' - type: 'null' description: >- Parameters for the user's location. Used to provide more relevant search results. required: - name - type title: WebSearchTool_20260318 type: object BetaWebFetchTool_20260318: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array allowed_domains: anyOf: - items: type: string type: array - type: 'null' description: List of domains to allow fetching from title: Allowed Domains blocked_domains: anyOf: - items: type: string type: array - type: 'null' description: List of domains to block fetching from title: Blocked Domains cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control citations: anyOf: - $ref: '#/components/schemas/BetaRequestCitationsConfig' - type: 'null' description: >- Citations configuration for fetched documents. Citations are disabled by default. defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean max_content_tokens: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: >- Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. title: Max Content Tokens max_uses: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: Maximum number of times the tool can be used in the API request. title: Max Uses name: const: web_fetch description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string response_inclusion: description: >- How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn. enum: - full - excluded title: Response Inclusion type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: web_fetch_20260318 title: Type type: string use_cache: description: >- Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. title: Use Cache type: boolean required: - name - type title: WebFetchTool_20260318 type: object BetaAdvisorTool_20260301: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control caching: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: >- Caching for the advisor's own prompt. When set, each advisor call writes a cache entry at the given TTL so subsequent calls in the same conversation read the stable prefix. When omitted, the advisor prompt is not cached. title: Caching defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean max_tokens: anyOf: - minimum: 1024 type: integer - type: 'null' description: >- Bounds the advisor's total output (thinking + text) per call. When the advisor hits this cap, the returned advisor_result or advisor_redacted_result block carries stop_reason='max_tokens', and a truncation note is appended to the advice text the worker model sees (inside the encrypted blob in redacted mode). When set, the server also emits a remaining-tokens budget block in the advisor's prompt so the advisor self-shapes toward the cap. When omitted, the advisor model's default output cap applies and no budget block is emitted. title: Max Tokens max_uses: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: Maximum number of times the tool can be used in the API request. title: Max Uses model: $ref: '#/components/schemas/Model' name: const: advisor description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: const: advisor_20260301 title: Type type: string required: - model - name - type title: AdvisorTool_20260301 type: object BetaToolSearchToolBM25_20251119: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean name: const: tool_search_tool_bm25 description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: enum: - tool_search_tool_bm25_20251119 - tool_search_tool_bm25 title: Type type: string required: - name - type title: ToolSearchToolBM25_20251119 type: object BetaToolSearchToolRegex_20251119: additionalProperties: false properties: allowed_callers: items: $ref: '#/components/schemas/BetaAllowedCaller' title: Allowed Callers type: array cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control defer_loading: description: >- If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. title: Defer Loading type: boolean name: const: tool_search_tool_regex description: >- Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. title: Name type: string strict: description: When true, guarantees schema validation on tool names and inputs title: Strict type: boolean type: enum: - tool_search_tool_regex_20251119 - tool_search_tool_regex title: Type type: string required: - name - type title: ToolSearchToolRegex_20251119 type: object BetaMCPToolset: additionalProperties: false description: |- Configuration for a group of tools from an MCP server. Allows configuring enabled status and defer_loading for all tools from an MCP server, with optional per-tool overrides. properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control configs: anyOf: - additionalProperties: $ref: '#/components/schemas/BetaMCPToolConfig' type: object - type: 'null' description: Configuration overrides for specific tools, keyed by tool name title: Configs default_config: $ref: '#/components/schemas/BetaMCPToolDefaultConfig' description: Default configuration applied to all tools from this server mcp_server_name: description: Name of the MCP server to configure tools for maxLength: 255 minLength: 1 title: Mcp Server Name type: string type: const: mcp_toolset title: Type type: string required: - mcp_server_name - type title: MCPToolset type: object BetaContentBlock: discriminator: mapping: advisor_tool_result: $ref: '#/components/schemas/BetaResponseAdvisorToolResultBlock' bash_code_execution_tool_result: $ref: '#/components/schemas/BetaResponseBashCodeExecutionToolResultBlock' code_execution_tool_result: $ref: '#/components/schemas/BetaResponseCodeExecutionToolResultBlock' compaction: $ref: '#/components/schemas/BetaResponseCompactionBlock' container_upload: $ref: '#/components/schemas/BetaResponseContainerUploadBlock' fallback: $ref: '#/components/schemas/BetaResponseFallbackBlock' mcp_tool_result: $ref: '#/components/schemas/BetaResponseMCPToolResultBlock' mcp_tool_use: $ref: '#/components/schemas/BetaResponseMCPToolUseBlock' redacted_thinking: $ref: '#/components/schemas/BetaResponseRedactedThinkingBlock' server_tool_use: $ref: '#/components/schemas/BetaResponseServerToolUseBlock' text: $ref: '#/components/schemas/BetaResponseTextBlock' text_editor_code_execution_tool_result: $ref: >- #/components/schemas/BetaResponseTextEditorCodeExecutionToolResultBlock thinking: $ref: '#/components/schemas/BetaResponseThinkingBlock' tool_search_tool_result: $ref: '#/components/schemas/BetaResponseToolSearchToolResultBlock' tool_use: $ref: '#/components/schemas/BetaResponseToolUseBlock' web_fetch_tool_result: $ref: '#/components/schemas/BetaResponseWebFetchToolResultBlock' web_search_tool_result: $ref: '#/components/schemas/BetaResponseWebSearchToolResultBlock' propertyName: type oneOf: - $ref: '#/components/schemas/BetaResponseTextBlock' - $ref: '#/components/schemas/BetaResponseThinkingBlock' - $ref: '#/components/schemas/BetaResponseRedactedThinkingBlock' - $ref: '#/components/schemas/BetaResponseToolUseBlock' - $ref: '#/components/schemas/BetaResponseServerToolUseBlock' - $ref: '#/components/schemas/BetaResponseWebSearchToolResultBlock' - $ref: '#/components/schemas/BetaResponseWebFetchToolResultBlock' - $ref: '#/components/schemas/BetaResponseAdvisorToolResultBlock' - $ref: '#/components/schemas/BetaResponseCodeExecutionToolResultBlock' - $ref: '#/components/schemas/BetaResponseBashCodeExecutionToolResultBlock' - $ref: >- #/components/schemas/BetaResponseTextEditorCodeExecutionToolResultBlock - $ref: '#/components/schemas/BetaResponseToolSearchToolResultBlock' - $ref: '#/components/schemas/BetaResponseMCPToolUseBlock' - $ref: '#/components/schemas/BetaResponseMCPToolResultBlock' - $ref: '#/components/schemas/BetaResponseContainerUploadBlock' - $ref: '#/components/schemas/BetaResponseCompactionBlock' - $ref: '#/components/schemas/BetaResponseFallbackBlock' BetaStopReason: enum: - end_turn - max_tokens - stop_sequence - tool_use - pause_turn - compaction - refusal - model_context_window_exceeded type: string BetaRefusalStopDetails: description: Structured information about a refusal. properties: category: anyOf: - $ref: '#/components/schemas/BetaRefusalCategory' - type: 'null' default: null description: |- The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. explanation: anyOf: - type: string - type: 'null' default: null description: >- Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. examples: - >- This request was declined because it conflicts with the usage policy. title: Explanation fallback_credit_token: anyOf: - type: string - type: 'null' default: null description: >- Opaque code that refunds the cache-miss cost when retrying this refused request on the fallback model. Pass it as `fallback_credit_token` on the retry request. Expires 5 minutes after the refusal. The retry is sent either with the same request body (`system`, `messages`, `tools`, and other render-shaping fields), or with the same body plus one appended `assistant` message whose content is the partial text (with any trailing whitespace stripped from the final text block) and paired server-tool blocks from this refusal — which also authorizes that appended turn as an assistant-prefill continuation on models that otherwise disallow prefill. A token minted mid-server-tool-loop whose partial content was continuable may only be redeemed the second way — if a same-body retry is rejected with a 400 saying the token must be redeemed by continuing the partial response, retry the second way instead. Either way: same workspace, same platform; a mismatch is a 400. Resending a token for an already-warm prefix is permitted but yields no additional credit. `null` when the refused model isn't eligible for a fallback credit. examples: - QW50aHJvcGljL0NsYXVkZQ== title: Fallback Credit Token fallback_has_prefill_claim: anyOf: - type: boolean - type: 'null' default: null description: >- Whether the accompanying `fallback_credit_token` may be redeemed with the appended-assistant retry form. Only set when `fallback_credit_token` is present. `true`: retry by resending the same request body plus one appended `assistant` message whose content is this response's `content` with any trailing whitespace stripped from the final text block and unpaired `tool_use` blocks omitted (the same appended-turn shape described on `fallback_credit_token`), with the token attached. `false`: retry by resending the original request body unchanged, with the token attached — the appended-assistant form is not available for this refusal (no continuable partial content, or the request uses `output_format` or a `tool_choice` that forces tool use). One exception: when the request used `output_format` or a forced `tool_choice` and the refusal arrived after server tools (including MCP connector tools) had already executed, the token may not be redeemable by either retry form; if the exact-body retry is then rejected with a 400 saying the token must be redeemed by continuing the partial response, discard the token and retry without it. Advisory: if an appended-assistant retry is rejected with a 400 despite `true`, fall back to resending the original request body with the token. title: Fallback Has Prefill Claim recommended_model: anyOf: - type: string - type: 'null' default: null description: >- The server's suggested retry target for this refusal. Populated when a fallback attempt could not be made (the fallback model's rate limit was exhausted, or it was overloaded); names the fallback model the caller can retry directly. Null otherwise. examples: - claude-sonnet-4-6 title: Recommended Model type: const: refusal default: refusal title: Type type: string required: - category - explanation - fallback_credit_token - fallback_has_prefill_claim - recommended_model - type title: RefusalStopDetails type: object BetaUsage: properties: cache_creation: anyOf: - $ref: '#/components/schemas/BetaCacheCreation' - type: 'null' default: null description: Breakdown of cached tokens by TTL cache_creation_input_tokens: anyOf: - minimum: 0 type: integer - type: 'null' default: null description: The number of input tokens used to create the cache entry. examples: - 2051 title: Cache Creation Input Tokens cache_read_input_tokens: anyOf: - minimum: 0 type: integer - type: 'null' default: null description: The number of input tokens read from the cache. examples: - 2051 title: Cache Read Input Tokens fallback_credit: anyOf: - $ref: '#/components/schemas/BetaFallbackCreditUsage' - type: 'null' default: null description: >- Outcome of the `fallback_credit_token` presented on this request. Present on every response to a non-batch request that carried a `fallback_credit_token`, in either redemption mode; absent otherwise (batch items accept and ignore the token and carry no outcome object). inference_geo: anyOf: - type: string - type: 'null' default: null description: >- The geographic region where inference was performed for this request. examples: - global title: Inference Geo input_tokens: description: The number of input tokens which were used. examples: - 2095 minimum: 0 title: Input Tokens type: integer iterations: $ref: '#/components/schemas/BetaIterationsUsage' output_tokens: description: The number of output tokens which were used. examples: - 503 minimum: 0 title: Output Tokens type: integer output_tokens_details: anyOf: - $ref: '#/components/schemas/BetaOutputTokensDetails' - type: 'null' default: null description: >- Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. server_tool_use: anyOf: - $ref: '#/components/schemas/BetaServerToolUsage' - type: 'null' default: null description: The number of server tool requests. service_tier: anyOf: - enum: - standard - priority - batch type: string - type: 'null' default: null description: If the request used the priority, standard, or batch tier. title: Service Tier speed: anyOf: - $ref: '#/components/schemas/BetaSpeed' - type: 'null' default: null description: The inference speed mode used for this request. required: - cache_creation - cache_creation_input_tokens - cache_read_input_tokens - fallback_credit - inference_geo - input_tokens - iterations - output_tokens - output_tokens_details - server_tool_use - service_tier - speed title: Usage type: object BetaDiagnostics: description: |- Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request. properties: cache_miss_reason: anyOf: - discriminator: mapping: messages_changed: $ref: '#/components/schemas/BetaCacheMissMessagesChanged' model_changed: $ref: '#/components/schemas/BetaCacheMissModelChanged' previous_message_not_found: $ref: '#/components/schemas/BetaCacheMissPreviousMessageNotFound' system_changed: $ref: '#/components/schemas/BetaCacheMissSystemChanged' tools_changed: $ref: '#/components/schemas/BetaCacheMissToolsChanged' unavailable: $ref: '#/components/schemas/BetaCacheMissUnavailable' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheMissModelChanged' - $ref: '#/components/schemas/BetaCacheMissSystemChanged' - $ref: '#/components/schemas/BetaCacheMissToolsChanged' - $ref: '#/components/schemas/BetaCacheMissMessagesChanged' - $ref: '#/components/schemas/BetaCacheMissPreviousMessageNotFound' - $ref: '#/components/schemas/BetaCacheMissUnavailable' - type: 'null' default: null description: >- 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. title: Cache Miss Reason required: - cache_miss_reason title: Diagnostics type: object BetaResponseContextManagement: properties: applied_edits: description: List of context management edits that were applied. items: discriminator: mapping: clear_thinking_20251015: $ref: '#/components/schemas/BetaResponseClearThinking20251015Edit' clear_tool_uses_20250919: $ref: '#/components/schemas/BetaResponseClearToolUses20250919Edit' propertyName: type oneOf: - $ref: '#/components/schemas/BetaResponseClearToolUses20250919Edit' - $ref: '#/components/schemas/BetaResponseClearThinking20251015Edit' title: Applied Edits type: array required: - applied_edits title: ResponseContextManagement type: object BetaContainer: description: >- Information about the container used in the request (for the code execution tool) properties: expires_at: description: The time at which the container will expire. format: date-time title: Expires At type: string id: description: Identifier for the container used in this request examples: - container_011CpZohnwH4vuy7gazohgSP title: Id type: string skills: anyOf: - items: $ref: '#/components/schemas/BetaSkill' type: array - type: 'null' default: null description: Skills loaded in the container title: Skills required: - expires_at - id - skills title: Container type: object BetaAPIError: properties: message: default: Internal server error title: Message type: string type: const: api_error default: api_error title: Type type: string required: - message - type title: APIError type: object BetaAuthenticationError: properties: message: default: Authentication error title: Message type: string type: const: authentication_error default: authentication_error title: Type type: string required: - message - type title: AuthenticationError type: object BetaBillingError: properties: message: default: Billing error title: Message type: string type: const: billing_error default: billing_error title: Type type: string required: - message - type title: BillingError type: object BetaInvalidRequestError: properties: message: default: Invalid request title: Message type: string type: const: invalid_request_error default: invalid_request_error title: Type type: string required: - message - type title: InvalidRequestError type: object BetaNotFoundError: properties: message: default: Not found title: Message type: string type: const: not_found_error default: not_found_error title: Type type: string required: - message - type title: NotFoundError type: object BetaOverloadedError: properties: message: default: Overloaded title: Message type: string type: const: overloaded_error default: overloaded_error title: Type type: string required: - message - type title: OverloadedError type: object BetaPermissionError: properties: message: default: Permission denied title: Message type: string type: const: permission_error default: permission_error title: Type type: string required: - message - type title: PermissionError type: object BetaRateLimitError: properties: message: default: Rate limited title: Message type: string type: const: rate_limit_error default: rate_limit_error title: Type type: string required: - message - type title: RateLimitError type: object BetaGatewayTimeoutError: properties: message: default: Request timeout title: Message type: string type: const: timeout_error default: timeout_error title: Type type: string required: - message - type title: GatewayTimeoutError type: object BetaInputContentBlock: discriminator: mapping: advisor_tool_result: $ref: '#/components/schemas/BetaRequestAdvisorToolResultBlock' bash_code_execution_tool_result: $ref: '#/components/schemas/BetaRequestBashCodeExecutionToolResultBlock' code_execution_tool_result: $ref: '#/components/schemas/BetaRequestCodeExecutionToolResultBlock' compaction: $ref: '#/components/schemas/BetaRequestCompactionBlock' container_upload: $ref: '#/components/schemas/BetaRequestContainerUploadBlock' document: $ref: '#/components/schemas/BetaRequestDocumentBlock' fallback: $ref: '#/components/schemas/BetaRequestFallbackBlock' image: $ref: '#/components/schemas/BetaRequestImageBlock' mcp_tool_result: $ref: '#/components/schemas/BetaRequestMCPToolResultBlock' mcp_tool_use: $ref: '#/components/schemas/BetaRequestMCPToolUseBlock' mid_conv_system: $ref: '#/components/schemas/BetaRequestMidConvSystemBlock' redacted_thinking: $ref: '#/components/schemas/BetaRequestRedactedThinkingBlock' search_result: $ref: '#/components/schemas/BetaRequestSearchResultBlock' server_tool_use: $ref: '#/components/schemas/BetaRequestServerToolUseBlock' text: $ref: '#/components/schemas/BetaRequestTextBlock' text_editor_code_execution_tool_result: $ref: >- #/components/schemas/BetaRequestTextEditorCodeExecutionToolResultBlock thinking: $ref: '#/components/schemas/BetaRequestThinkingBlock' tool_addition: $ref: '#/components/schemas/BetaRequestToolAdditionBlock' tool_removal: $ref: '#/components/schemas/BetaRequestToolRemovalBlock' tool_result: $ref: '#/components/schemas/BetaRequestToolResultBlock' tool_search_tool_result: $ref: '#/components/schemas/BetaRequestToolSearchToolResultBlock' tool_use: $ref: '#/components/schemas/BetaRequestToolUseBlock' web_fetch_tool_result: $ref: '#/components/schemas/BetaRequestWebFetchToolResultBlock' web_search_tool_result: $ref: '#/components/schemas/BetaRequestWebSearchToolResultBlock' propertyName: type oneOf: - $ref: '#/components/schemas/BetaRequestTextBlock' description: Regular text content. - $ref: '#/components/schemas/BetaRequestImageBlock' description: >- Image content specified directly as base64 data or as a reference via a URL. - $ref: '#/components/schemas/BetaRequestDocumentBlock' description: >- Document content, either specified directly as base64 data, as text, or as a reference via a URL. - $ref: '#/components/schemas/BetaRequestSearchResultBlock' description: >- A search result block containing source, title, and content from search operations. - $ref: '#/components/schemas/BetaRequestThinkingBlock' description: A block specifying internal thinking by the model. - $ref: '#/components/schemas/BetaRequestRedactedThinkingBlock' description: A block specifying internal, redacted thinking by the model. - $ref: '#/components/schemas/BetaRequestToolUseBlock' description: A block indicating a tool use by the model. - $ref: '#/components/schemas/BetaRequestToolResultBlock' description: A block specifying the results of a tool use by the model. - $ref: '#/components/schemas/BetaRequestServerToolUseBlock' - $ref: '#/components/schemas/BetaRequestWebSearchToolResultBlock' - $ref: '#/components/schemas/BetaRequestWebFetchToolResultBlock' - $ref: '#/components/schemas/BetaRequestAdvisorToolResultBlock' - $ref: '#/components/schemas/BetaRequestCodeExecutionToolResultBlock' - $ref: '#/components/schemas/BetaRequestBashCodeExecutionToolResultBlock' - $ref: >- #/components/schemas/BetaRequestTextEditorCodeExecutionToolResultBlock - $ref: '#/components/schemas/BetaRequestToolSearchToolResultBlock' - $ref: '#/components/schemas/BetaRequestMCPToolUseBlock' - $ref: '#/components/schemas/BetaRequestMCPToolResultBlock' - $ref: '#/components/schemas/BetaRequestContainerUploadBlock' - $ref: '#/components/schemas/BetaRequestCompactionBlock' - $ref: '#/components/schemas/BetaRequestMidConvSystemBlock' - $ref: '#/components/schemas/BetaRequestToolAdditionBlock' - $ref: '#/components/schemas/BetaRequestToolRemovalBlock' - $ref: '#/components/schemas/BetaRequestFallbackBlock' x-stainless-go-variant-constructor: naming: new_beta_{variant}_block BetaSkillParams: additionalProperties: false description: Specification for a skill to be loaded in a container (request model). properties: skill_id: description: Skill ID examples: - pdf maxLength: 64 minLength: 1 title: Skill Id type: string type: description: >- Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) enum: - anthropic - custom examples: - anthropic title: Type type: string version: description: Skill version or 'latest' for most recent version examples: - latest maxLength: 64 minLength: 1 title: Version type: string required: - skill_id - type title: SkillParams type: object BetaClearThinking20251015: additionalProperties: false properties: keep: anyOf: - discriminator: mapping: all: $ref: '#/components/schemas/BetaAllThinkingTurns' thinking_turns: $ref: '#/components/schemas/BetaThinkingTurns' propertyName: type oneOf: - $ref: '#/components/schemas/BetaThinkingTurns' - $ref: '#/components/schemas/BetaAllThinkingTurns' - const: all type: string x-stainless-naming: csharp: type_name: All description: >- Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. title: Keep type: const: clear_thinking_20251015 title: Type type: string required: - type title: ClearThinking20251015 type: object BetaClearToolUses20250919: additionalProperties: false properties: clear_at_least: anyOf: - $ref: '#/components/schemas/BetaInputTokensClearAtLeast' - type: 'null' description: >- Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed. clear_tool_inputs: anyOf: - type: boolean - items: type: string type: array - type: 'null' description: >- Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) title: Clear Tool Inputs exclude_tools: anyOf: - items: type: string type: array - type: 'null' description: Tool names whose uses are preserved from clearing title: Exclude Tools keep: description: Number of tool uses to retain in the conversation discriminator: mapping: tool_uses: $ref: '#/components/schemas/BetaToolUsesKeep' propertyName: type oneOf: - $ref: '#/components/schemas/BetaToolUsesKeep' title: Keep trigger: description: Condition that triggers the context management strategy discriminator: mapping: input_tokens: $ref: '#/components/schemas/BetaInputTokensTrigger' tool_uses: $ref: '#/components/schemas/BetaToolUsesTrigger' propertyName: type oneOf: - $ref: '#/components/schemas/BetaInputTokensTrigger' - $ref: '#/components/schemas/BetaToolUsesTrigger' title: Trigger type: const: clear_tool_uses_20250919 title: Type type: string required: - type title: ClearToolUses20250919 type: object BetaCompact20260112: additionalProperties: false description: >- Automatically compact older context when reaching the configured trigger threshold. properties: instructions: anyOf: - type: string - type: 'null' description: Additional instructions for summarization. title: Instructions pause_after_compaction: description: >- Whether to pause after compaction and return the compaction block to the user. title: Pause After Compaction type: boolean trigger: anyOf: - $ref: '#/components/schemas/BetaInputTokensTrigger' - type: 'null' description: When to trigger compaction. Defaults to 150000 input tokens. type: const: compact_20260112 title: Type type: string required: - type title: Compact20260112 type: object BetaThinkingConfigAdaptive: additionalProperties: false properties: display: anyOf: - $ref: '#/components/schemas/BetaThinkingDisplayMode' - type: 'null' description: >- 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. Defaults to `summarized`. type: const: adaptive title: Type type: string required: - type title: ThinkingConfigAdaptive type: object BetaThinkingConfigDisabled: additionalProperties: false properties: type: const: disabled title: Type type: string required: - type title: ThinkingConfigDisabled type: object x-stainless-go-constant-constructor: true BetaThinkingConfigEnabled: additionalProperties: false properties: budget_tokens: description: >- Determines how many tokens the model 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. minimum: 1024 title: Budget Tokens type: integer display: anyOf: - $ref: '#/components/schemas/BetaThinkingDisplayMode' - type: 'null' description: >- 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. Defaults to `summarized`. type: const: enabled title: Type type: string required: - budget_tokens - type title: ThinkingConfigEnabled type: object BetaRequestMCPServerToolConfiguration: additionalProperties: false properties: allowed_tools: anyOf: - items: type: string type: array - type: 'null' title: Allowed Tools enabled: anyOf: - type: boolean - type: 'null' title: Enabled title: RequestMCPServerToolConfiguration type: object BetaEffortLevel: description: All possible effort levels. enum: - low - medium - high - xhigh - max title: EffortLevel type: string BetaTokenTaskBudget: additionalProperties: false description: User-configurable total token budget across contexts. properties: remaining: anyOf: - minimum: 0 type: integer - type: 'null' description: >- Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided. minimum: 0 title: Remaining total: description: Total token budget across all contexts in the session. minimum: 1024 title: Total type: integer type: const: tokens description: The budget type. Currently only 'tokens' is supported. title: Type type: string required: - total - type title: TokenTaskBudget type: object BetaRequestCharLocationCitation: additionalProperties: false properties: cited_text: examples: - The grass is green. The sky is blue. title: Cited Text type: string document_index: minimum: 0 title: Document Index type: integer document_title: anyOf: - maxLength: 500 minLength: 1 type: string - type: 'null' title: Document Title end_char_index: title: End Char Index type: integer start_char_index: minimum: 0 title: Start Char Index type: integer type: const: char_location title: Type type: string required: - cited_text - document_index - document_title - end_char_index - start_char_index - type title: RequestCharLocationCitation type: object BetaRequestContentBlockLocationCitation: additionalProperties: false properties: cited_text: description: >- 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. examples: - The grass is green. The sky is blue. title: Cited Text type: string document_index: minimum: 0 title: Document Index type: integer document_title: anyOf: - maxLength: 500 minLength: 1 type: string - type: 'null' title: Document Title end_block_index: description: >- 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`. title: End Block Index type: integer start_block_index: description: >- 0-based index of the first cited block in the source's `content` array. minimum: 0 title: Start Block Index type: integer type: const: content_block_location title: Type type: string required: - cited_text - document_index - document_title - end_block_index - start_block_index - type title: RequestContentBlockLocationCitation type: object BetaRequestPageLocationCitation: additionalProperties: false properties: cited_text: examples: - The grass is green. The sky is blue. title: Cited Text type: string document_index: minimum: 0 title: Document Index type: integer document_title: anyOf: - maxLength: 500 minLength: 1 type: string - type: 'null' title: Document Title end_page_number: title: End Page Number type: integer start_page_number: minimum: 1 title: Start Page Number type: integer type: const: page_location title: Type type: string required: - cited_text - document_index - document_title - end_page_number - start_page_number - type title: RequestPageLocationCitation type: object BetaRequestSearchResultLocationCitation: additionalProperties: false properties: cited_text: description: >- 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. examples: - The grass is green. The sky is blue. title: Cited Text type: string end_block_index: description: >- 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`. title: End Block Index type: integer search_result_index: description: >- 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. minimum: 0 title: Search Result Index type: integer source: title: Source type: string start_block_index: description: >- 0-based index of the first cited block in the source's `content` array. minimum: 0 title: Start Block Index type: integer title: anyOf: - type: string - type: 'null' title: Title type: const: search_result_location title: Type type: string required: - cited_text - end_block_index - search_result_index - source - start_block_index - title - type title: RequestSearchResultLocationCitation type: object BetaRequestWebSearchResultLocationCitation: additionalProperties: false properties: cited_text: examples: - The grass is green. The sky is blue. title: Cited Text type: string encrypted_index: title: Encrypted Index type: string title: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Title type: const: web_search_result_location title: Type type: string url: minLength: 1 title: Url type: string required: - cited_text - encrypted_index - title - type - url title: RequestWebSearchResultLocationCitation type: object BetaToolChoiceAny: additionalProperties: false description: The model will use any available tools. properties: disable_parallel_tool_use: description: >- Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. title: Disable Parallel Tool Use type: boolean type: const: any title: Type type: string required: - type title: ToolChoiceAny type: object BetaToolChoiceAuto: additionalProperties: false description: The model will automatically decide whether to use tools. properties: disable_parallel_tool_use: description: >- Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output at most one tool use. title: Disable Parallel Tool Use type: boolean type: const: auto title: Type type: string required: - type title: ToolChoiceAuto type: object BetaToolChoiceNone: additionalProperties: false description: The model will not be allowed to use tools. properties: type: const: none title: Type type: string required: - type title: ToolChoiceNone type: object x-stainless-go-constant-constructor: true BetaToolChoiceTool: additionalProperties: false description: The model will use the specified tool with `tool_choice.name`. properties: disable_parallel_tool_use: description: >- Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. title: Disable Parallel Tool Use type: boolean name: description: The name of the tool to use. title: Name type: string type: const: tool title: Type type: string required: - name - type title: ToolChoiceTool type: object BetaInputSchema: additionalProperties: true properties: properties: anyOf: - type: object additionalProperties: true - type: 'null' title: Properties required: anyOf: - items: type: string type: array - type: 'null' title: Required type: const: object title: Type type: string required: - type title: InputSchema type: object BetaAllowedCaller: description: |- Specifies who can invoke a tool. Values: direct: The model can call this tool directly. code_execution_20250825: The tool can be called from the code execution environment (v1). code_execution_20260120: The tool can be called from the code execution environment (v2 with persistence). code_execution_20260521: The tool can be called from the code execution environment (v2 with persistence). enum: - direct - code_execution_20250825 - code_execution_20260120 - code_execution_20260521 title: AllowedCaller type: string BetaJsonValue: {} BetaUserLocation: additionalProperties: false properties: city: anyOf: - maxLength: 255 minLength: 1 type: string - type: 'null' description: The city of the user. examples: - New York - Tokyo - Los Angeles title: City country: anyOf: - maxLength: 2 minLength: 2 type: string - type: 'null' description: >- The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. examples: - US - JP - GB title: Country region: anyOf: - maxLength: 255 minLength: 1 type: string - type: 'null' description: The region of the user. examples: - California - Ontario - Wales title: Region timezone: anyOf: - maxLength: 255 minLength: 1 type: string - type: 'null' description: The [IANA timezone](https://nodatime.org/TimeZones) of the user. examples: - America/New_York - Asia/Tokyo - Europe/London title: Timezone type: const: approximate title: Type type: string required: - type title: UserLocation type: object BetaRequestCitationsConfig: additionalProperties: false properties: enabled: title: Enabled type: boolean title: RequestCitationsConfig type: object BetaMCPToolConfig: additionalProperties: false description: Configuration for a specific tool in an MCP toolset. properties: defer_loading: title: Defer Loading type: boolean enabled: title: Enabled type: boolean title: MCPToolConfig type: object BetaMCPToolDefaultConfig: additionalProperties: false description: Default configuration for tools in an MCP toolset. properties: defer_loading: title: Defer Loading type: boolean enabled: title: Enabled type: boolean title: MCPToolDefaultConfig type: object BetaResponseAdvisorToolResultBlock: properties: content: anyOf: - $ref: '#/components/schemas/BetaResponseAdvisorToolResultError' - $ref: '#/components/schemas/BetaResponseAdvisorResultBlock' - $ref: '#/components/schemas/BetaResponseAdvisorRedactedResultBlock' title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: advisor_tool_result default: advisor_tool_result title: Type type: string required: - content - tool_use_id - type title: ResponseAdvisorToolResultBlock type: object BetaResponseBashCodeExecutionToolResultBlock: properties: content: anyOf: - $ref: >- #/components/schemas/BetaResponseBashCodeExecutionToolResultError - $ref: '#/components/schemas/BetaResponseBashCodeExecutionResultBlock' title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: bash_code_execution_tool_result default: bash_code_execution_tool_result title: Type type: string required: - content - tool_use_id - type title: ResponseBashCodeExecutionToolResultBlock type: object BetaResponseCodeExecutionToolResultBlock: properties: content: anyOf: - $ref: '#/components/schemas/BetaResponseCodeExecutionToolResultError' - $ref: '#/components/schemas/BetaResponseCodeExecutionResultBlock' - $ref: >- #/components/schemas/BetaResponseEncryptedCodeExecutionResultBlock title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: code_execution_tool_result default: code_execution_tool_result title: Type type: string required: - content - tool_use_id - type title: ResponseCodeExecutionToolResultBlock type: object BetaResponseCompactionBlock: description: >- A compaction block returned when autocompact is triggered. When content is None, it indicates the compaction failed to produce a valid summary (e.g., malformed output from the model). Clients may round-trip compaction blocks with null content; the server treats them as no-ops. properties: content: anyOf: - type: string - type: 'null' description: Summary of compacted content, or null if compaction failed title: Content encrypted_content: anyOf: - type: string - type: 'null' default: null description: Opaque metadata from prior compaction, to be round-tripped verbatim title: Encrypted Content type: const: compaction default: compaction title: Type type: string required: - content - encrypted_content - type title: ResponseCompactionBlock type: object BetaResponseContainerUploadBlock: description: Response model for a file uploaded to the container. properties: file_id: title: File Id type: string type: const: container_upload default: container_upload title: Type type: string required: - file_id - type title: ResponseContainerUploadBlock type: object BetaResponseFallbackBlock: description: >- Marks the point in `content` where one model's output gives way to the next. One block appears per hop where a preceding model actually ran this turn and declined. A turn where no preceding model ran and declined has no such boundary and carries no block — the signal for whether a fallback model served the response is the presence of a `fallback_message` entry in `usage.iterations`, not this block. The block is treated like a server-tool content block for streaming: it arrives via the standard `content_block_start` / `content_block_stop` pair and carries no deltas. properties: from: $ref: '#/components/schemas/BetaResponseFallbackHopInfo' description: >- The model whose output ends at this point — the model that declined at this hop. When the declining hop is the requested model, its `model` echoes the top-level `model` string the caller sent (alias or canonical); when the declining hop is a fallback model, its `model` is that model's canonical id. to: $ref: '#/components/schemas/BetaResponseFallbackHopInfo' description: >- The fallback model producing the content that follows this block. Its `model` is always the canonical id. trigger: $ref: '#/components/schemas/BetaFallbackRefusalTrigger' description: What caused the `from` model to hand over at this hop. type: const: fallback default: fallback title: Type type: string required: - from - to - trigger - type title: ResponseFallbackBlock type: object BetaResponseMCPToolResultBlock: properties: content: anyOf: - type: string - items: $ref: '#/components/schemas/BetaResponseTextBlock' title: beta_mcp_tool_result_block_content_item type: array title: beta_mcp_tool_result_block_content title: Content is_error: default: false title: Is Error type: boolean tool_use_id: pattern: ^[a-zA-Z0-9_-]+$ title: Tool Use Id type: string type: const: mcp_tool_result default: mcp_tool_result title: Type type: string required: - content - is_error - tool_use_id - type title: ResponseMCPToolResultBlock type: object BetaResponseMCPToolUseBlock: properties: id: pattern: ^[a-zA-Z0-9_-]+$ title: Id type: string input: additionalProperties: true title: Input type: object name: description: The name of the MCP tool title: Name type: string server_name: description: The name of the MCP server title: Server Name type: string type: const: mcp_tool_use default: mcp_tool_use title: Type type: string required: - id - input - name - server_name - type title: ResponseMCPToolUseBlock type: object BetaResponseRedactedThinkingBlock: properties: data: description: >- 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. title: Data type: string type: const: redacted_thinking default: redacted_thinking title: Type type: string required: - data - type title: ResponseRedactedThinkingBlock type: object BetaResponseServerToolUseBlock: properties: caller: discriminator: mapping: code_execution_20250825: $ref: '#/components/schemas/BetaServerToolCaller' code_execution_20260120: $ref: '#/components/schemas/BetaServerToolCaller_20260120' direct: $ref: '#/components/schemas/BetaDirectCaller' propertyName: type oneOf: - $ref: '#/components/schemas/BetaDirectCaller' - $ref: '#/components/schemas/BetaServerToolCaller' - $ref: '#/components/schemas/BetaServerToolCaller_20260120' title: Caller id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Id type: string input: additionalProperties: true title: Input type: object name: enum: - advisor - web_search - web_fetch - code_execution - bash_code_execution - text_editor_code_execution - tool_search_tool_regex - tool_search_tool_bm25 title: Name type: string type: const: server_tool_use default: server_tool_use title: Type type: string required: - id - input - name - type title: ResponseServerToolUseBlock type: object BetaResponseTextBlock: properties: citations: anyOf: - items: discriminator: mapping: char_location: $ref: '#/components/schemas/BetaResponseCharLocationCitation' content_block_location: $ref: >- #/components/schemas/BetaResponseContentBlockLocationCitation page_location: $ref: '#/components/schemas/BetaResponsePageLocationCitation' search_result_location: $ref: >- #/components/schemas/BetaResponseSearchResultLocationCitation web_search_result_location: $ref: >- #/components/schemas/BetaResponseWebSearchResultLocationCitation propertyName: type oneOf: - $ref: '#/components/schemas/BetaResponseCharLocationCitation' - $ref: '#/components/schemas/BetaResponsePageLocationCitation' - $ref: >- #/components/schemas/BetaResponseContentBlockLocationCitation - $ref: >- #/components/schemas/BetaResponseWebSearchResultLocationCitation - $ref: >- #/components/schemas/BetaResponseSearchResultLocationCitation type: array - type: 'null' default: null description: >- Citations supporting the text block. The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`. title: Citations text: maxLength: 5000000 minLength: 0 title: Text type: string type: const: text default: text title: Type type: string required: - citations - text - type title: ResponseTextBlock type: object BetaResponseTextEditorCodeExecutionToolResultBlock: properties: content: anyOf: - $ref: >- #/components/schemas/BetaResponseTextEditorCodeExecutionToolResultError - $ref: >- #/components/schemas/BetaResponseTextEditorCodeExecutionViewResultBlock - $ref: >- #/components/schemas/BetaResponseTextEditorCodeExecutionCreateResultBlock - $ref: >- #/components/schemas/BetaResponseTextEditorCodeExecutionStrReplaceResultBlock title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: text_editor_code_execution_tool_result default: text_editor_code_execution_tool_result title: Type type: string required: - content - tool_use_id - type title: ResponseTextEditorCodeExecutionToolResultBlock type: object BetaResponseThinkingBlock: properties: signature: description: >- A value used to verify that this thinking block was generated by the model 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. title: Signature type: string thinking: description: The text of the model's thinking process for this block. title: Thinking type: string type: const: thinking default: thinking title: Type type: string required: - signature - thinking - type title: ResponseThinkingBlock type: object BetaResponseToolSearchToolResultBlock: properties: content: anyOf: - $ref: '#/components/schemas/BetaResponseToolSearchToolResultError' - $ref: '#/components/schemas/BetaResponseToolSearchToolSearchResultBlock' title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: tool_search_tool_result default: tool_search_tool_result title: Type type: string required: - content - tool_use_id - type title: ResponseToolSearchToolResultBlock type: object BetaResponseToolUseBlock: properties: caller: discriminator: mapping: code_execution_20250825: $ref: '#/components/schemas/BetaServerToolCaller' code_execution_20260120: $ref: '#/components/schemas/BetaServerToolCaller_20260120' direct: $ref: '#/components/schemas/BetaDirectCaller' propertyName: type oneOf: - $ref: '#/components/schemas/BetaDirectCaller' - $ref: '#/components/schemas/BetaServerToolCaller' - $ref: '#/components/schemas/BetaServerToolCaller_20260120' title: Caller id: pattern: ^[a-zA-Z0-9_-]+$ title: Id type: string input: additionalProperties: true title: Input type: object name: minLength: 1 title: Name type: string type: const: tool_use default: tool_use title: Type type: string required: - id - input - name - type title: ResponseToolUseBlock type: object BetaResponseWebFetchToolResultBlock: properties: caller: discriminator: mapping: code_execution_20250825: $ref: '#/components/schemas/BetaServerToolCaller' code_execution_20260120: $ref: '#/components/schemas/BetaServerToolCaller_20260120' direct: $ref: '#/components/schemas/BetaDirectCaller' propertyName: type oneOf: - $ref: '#/components/schemas/BetaDirectCaller' - $ref: '#/components/schemas/BetaServerToolCaller' - $ref: '#/components/schemas/BetaServerToolCaller_20260120' title: Caller content: anyOf: - $ref: '#/components/schemas/BetaResponseWebFetchToolResultError' - $ref: '#/components/schemas/BetaResponseWebFetchResultBlock' title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: web_fetch_tool_result default: web_fetch_tool_result title: Type type: string required: - content - tool_use_id - type title: ResponseWebFetchToolResultBlock type: object BetaResponseWebSearchToolResultBlock: properties: caller: discriminator: mapping: code_execution_20250825: $ref: '#/components/schemas/BetaServerToolCaller' code_execution_20260120: $ref: '#/components/schemas/BetaServerToolCaller_20260120' direct: $ref: '#/components/schemas/BetaDirectCaller' propertyName: type oneOf: - $ref: '#/components/schemas/BetaDirectCaller' - $ref: '#/components/schemas/BetaServerToolCaller' - $ref: '#/components/schemas/BetaServerToolCaller_20260120' title: Caller content: anyOf: - $ref: '#/components/schemas/BetaResponseWebSearchToolResultError' - items: $ref: '#/components/schemas/BetaResponseWebSearchResultBlock' type: array title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: web_search_tool_result default: web_search_tool_result title: Type type: string required: - content - tool_use_id - type title: ResponseWebSearchToolResultBlock type: object BetaRefusalCategory: description: The policy category that triggered a refusal. enum: - cyber - bio - frontier_llm - reasoning_extraction - general_harms title: RefusalCategory type: string x-enum-descriptions: - >- The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category. - >- The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category. - >- The request was classified as assisting the development of competing AI models. Benign machine learning work can also trigger this category. - >- 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. - >- The request could be related to an area that was determined as harmful. Benign work might sometimes trigger this category. BetaCacheCreation: properties: ephemeral_1h_input_tokens: default: 0 description: The number of input tokens used to create the 1 hour cache entry. minimum: 0 title: Ephemeral 1H Input Tokens type: integer ephemeral_5m_input_tokens: default: 0 description: The number of input tokens used to create the 5 minute cache entry. minimum: 0 title: Ephemeral 5M Input Tokens type: integer required: - ephemeral_1h_input_tokens - ephemeral_5m_input_tokens title: CacheCreation type: object BetaFallbackCreditUsage: description: Outcome of the ``fallback_credit_token`` presented on this request. properties: status: description: >- Whether the fallback-credit reprice was applied to this response's billing. A union discriminated on `type`. `redeemed`: the retry is billed as if the conversation had been on the retry model all along — including when the resulting shift is zero because there was nothing to move. `not_applied`: no reprice was applied; the arm's `reason` says why. discriminator: mapping: not_applied: $ref: '#/components/schemas/BetaFallbackCreditNotApplied' redeemed: $ref: '#/components/schemas/BetaFallbackCreditRedeemed' propertyName: type oneOf: - $ref: '#/components/schemas/BetaFallbackCreditRedeemed' - $ref: '#/components/schemas/BetaFallbackCreditNotApplied' title: Status required: - status title: FallbackCreditUsage type: object BetaIterationsUsage: anyOf: - items: discriminator: mapping: advisor_message: $ref: '#/components/schemas/BetaAdvisorMessageIterationUsage' compaction: $ref: '#/components/schemas/BetaCompactionIterationUsage' fallback_message: $ref: '#/components/schemas/BetaFallbackMessageIterationUsage' message: $ref: '#/components/schemas/BetaMessageIterationUsage' propertyName: type oneOf: - $ref: '#/components/schemas/BetaMessageIterationUsage' - $ref: '#/components/schemas/BetaCompactionIterationUsage' - $ref: '#/components/schemas/BetaAdvisorMessageIterationUsage' - $ref: '#/components/schemas/BetaFallbackMessageIterationUsage' x-stainless-naming: java: type_name: BetaIterationsUsageItems csharp: type_name: BetaIterationsUsageItems type: array - type: 'null' default: null description: >- Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops title: Iterations BetaOutputTokensDetails: properties: thinking_tokens: default: 0 description: >- 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. minimum: 0 title: Thinking Tokens type: integer required: - thinking_tokens title: OutputTokensDetails type: object BetaServerToolUsage: properties: web_fetch_requests: default: 0 description: The number of web fetch tool requests. examples: - 2 minimum: 0 title: Web Fetch Requests type: integer web_search_requests: default: 0 description: The number of web search tool requests. examples: - 0 minimum: 0 title: Web Search Requests type: integer required: - web_fetch_requests - web_search_requests title: ServerToolUsage type: object BetaCacheMissMessagesChanged: properties: cache_missed_input_tokens: description: >- Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. title: Cache Missed Input Tokens type: integer type: const: messages_changed default: messages_changed title: Type type: string required: - cache_missed_input_tokens - type title: CacheMissMessagesChanged type: object BetaCacheMissModelChanged: properties: cache_missed_input_tokens: description: >- Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. title: Cache Missed Input Tokens type: integer type: const: model_changed default: model_changed title: Type type: string required: - cache_missed_input_tokens - type title: CacheMissModelChanged type: object BetaCacheMissPreviousMessageNotFound: properties: type: const: previous_message_not_found default: previous_message_not_found title: Type type: string required: - type title: CacheMissPreviousMessageNotFound type: object BetaCacheMissSystemChanged: properties: cache_missed_input_tokens: description: >- Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. title: Cache Missed Input Tokens type: integer type: const: system_changed default: system_changed title: Type type: string required: - cache_missed_input_tokens - type title: CacheMissSystemChanged type: object BetaCacheMissToolsChanged: properties: cache_missed_input_tokens: description: >- Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. title: Cache Missed Input Tokens type: integer type: const: tools_changed default: tools_changed title: Type type: string required: - cache_missed_input_tokens - type title: CacheMissToolsChanged type: object BetaCacheMissUnavailable: properties: type: const: unavailable default: unavailable title: Type type: string required: - type title: CacheMissUnavailable type: object BetaResponseClearThinking20251015Edit: properties: cleared_input_tokens: description: Number of input tokens cleared by this edit. minimum: 0 title: Cleared Input Tokens type: integer cleared_thinking_turns: description: Number of thinking turns that were cleared. minimum: 0 title: Cleared Thinking Turns type: integer type: const: clear_thinking_20251015 default: clear_thinking_20251015 description: The type of context management edit applied. title: Type type: string required: - cleared_input_tokens - cleared_thinking_turns - type title: ResponseClearThinking20251015Edit type: object BetaResponseClearToolUses20250919Edit: properties: cleared_input_tokens: description: Number of input tokens cleared by this edit. minimum: 0 title: Cleared Input Tokens type: integer cleared_tool_uses: description: Number of tool uses that were cleared. minimum: 0 title: Cleared Tool Uses type: integer type: const: clear_tool_uses_20250919 default: clear_tool_uses_20250919 description: The type of context management edit applied. title: Type type: string required: - cleared_input_tokens - cleared_tool_uses - type title: ResponseClearToolUses20250919Edit type: object BetaSkill: description: A skill that was loaded in a container (response model). properties: skill_id: description: Skill ID examples: - pdf maxLength: 64 minLength: 1 title: Skill Id type: string type: description: >- Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) enum: - anthropic - custom examples: - anthropic title: Type type: string version: description: Skill version or 'latest' for most recent version examples: - latest maxLength: 64 minLength: 1 title: Version type: string required: - skill_id - type - version title: Skill type: object BetaRequestAdvisorToolResultBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control content: anyOf: - $ref: '#/components/schemas/BetaRequestAdvisorToolResultError' - $ref: '#/components/schemas/BetaRequestAdvisorResultBlock' - $ref: '#/components/schemas/BetaRequestAdvisorRedactedResultBlock' title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: advisor_tool_result title: Type type: string required: - content - tool_use_id - type title: RequestAdvisorToolResultBlock type: object BetaRequestBashCodeExecutionToolResultBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control content: anyOf: - $ref: '#/components/schemas/BetaRequestBashCodeExecutionToolResultError' - $ref: '#/components/schemas/BetaRequestBashCodeExecutionResultBlock' title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: bash_code_execution_tool_result title: Type type: string required: - content - tool_use_id - type title: RequestBashCodeExecutionToolResultBlock type: object BetaRequestCodeExecutionToolResultBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control content: anyOf: - $ref: '#/components/schemas/BetaRequestCodeExecutionToolResultError' x-stainless-naming: go: variant_constructor: BetaNewCodeExecutionToolRequestError - $ref: '#/components/schemas/BetaRequestCodeExecutionResultBlock' - $ref: >- #/components/schemas/BetaRequestEncryptedCodeExecutionResultBlock title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: code_execution_tool_result title: Type type: string required: - content - tool_use_id - type title: RequestCodeExecutionToolResultBlock type: object BetaRequestCompactionBlock: additionalProperties: false description: >- A compaction block containing summary of previous context. Users should round-trip these blocks from responses to subsequent requests to maintain context across compaction boundaries. When content is None, the block represents a failed compaction. The server treats these as no-ops. Empty string content is not allowed. properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control content: anyOf: - type: string - type: 'null' description: >- Summary of previously compacted content, or null if compaction failed title: Content encrypted_content: anyOf: - type: string - type: 'null' description: Opaque metadata from prior compaction, to be round-tripped verbatim title: Encrypted Content type: const: compaction title: Type type: string required: - type title: RequestCompactionBlock type: object BetaRequestContainerUploadBlock: additionalProperties: false description: >- 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. properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control file_id: title: File Id type: string type: const: container_upload title: Type type: string required: - file_id - type title: RequestContainerUploadBlock type: object BetaRequestDocumentBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control citations: anyOf: - $ref: '#/components/schemas/BetaRequestCitationsConfig' - type: 'null' context: anyOf: - minLength: 1 type: string - type: 'null' title: Context source: discriminator: mapping: base64: $ref: '#/components/schemas/BetaBase64PDFSource' content: $ref: '#/components/schemas/BetaContentBlockSource' file: $ref: '#/components/schemas/BetaFileDocumentSource' text: $ref: '#/components/schemas/BetaPlainTextSource' url: $ref: '#/components/schemas/BetaURLPDFSource' propertyName: type oneOf: - $ref: '#/components/schemas/BetaBase64PDFSource' - $ref: '#/components/schemas/BetaPlainTextSource' - $ref: '#/components/schemas/BetaContentBlockSource' - $ref: '#/components/schemas/BetaURLPDFSource' - $ref: '#/components/schemas/BetaFileDocumentSource' title: Source title: anyOf: - maxLength: 500 minLength: 1 type: string - type: 'null' title: Title type: const: document title: Type type: string required: - source - type title: RequestDocumentBlock type: object BetaRequestFallbackBlock: additionalProperties: false description: |- A `fallback` block echoed back from a prior response. Accepted in `messages[].content` and not rendered into the prompt; not validated against the request's `fallbacks` chain or top-level `model`. Echo the assistant turn back verbatim, including this block in its original position. The block marks the boundary between content produced before and after a fallback hop, and the server relies on that boundary to validate the turn: when thinking runs flank the boundary, omitting the block merges them into one span the server cannot validate (the request is rejected), and moving it into the middle of a single run is likewise rejected; between non-thinking blocks the block's placement has no validation effect. properties: from: $ref: '#/components/schemas/BetaRequestFallbackHopInfo' to: $ref: '#/components/schemas/BetaRequestFallbackHopInfo' trigger: description: >- The response block's `trigger`, echoed verbatim. Accepted and ignored by the server; any object or `null` is allowed. title: Trigger type: const: fallback title: Type type: string required: - from - to - type title: RequestFallbackBlock type: object BetaRequestImageBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control source: discriminator: mapping: base64: $ref: '#/components/schemas/BetaBase64ImageSource' file: $ref: '#/components/schemas/BetaFileImageSource' url: $ref: '#/components/schemas/BetaURLImageSource' propertyName: type oneOf: - $ref: '#/components/schemas/BetaBase64ImageSource' - $ref: '#/components/schemas/BetaURLImageSource' - $ref: '#/components/schemas/BetaFileImageSource' title: Source type: const: image title: Type type: string required: - source - type title: RequestImageBlock type: object BetaRequestMCPToolResultBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control content: anyOf: - type: string - items: $ref: '#/components/schemas/BetaRequestTextBlock' title: beta_mcp_tool_result_block_param_content_item type: array title: beta_mcp_tool_result_block_param_content title: Content is_error: title: Is Error type: boolean tool_use_id: pattern: ^[a-zA-Z0-9_-]+$ title: Tool Use Id type: string type: const: mcp_tool_result title: Type type: string required: - tool_use_id - type title: RequestMCPToolResultBlock type: object BetaRequestMCPToolUseBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control id: pattern: ^[a-zA-Z0-9_-]+$ title: Id type: string input: additionalProperties: true title: Input type: object name: title: Name type: string server_name: description: The name of the MCP server title: Server Name type: string type: const: mcp_tool_use title: Type type: string required: - id - input - name - server_name - type title: RequestMCPToolUseBlock type: object BetaRequestMidConvSystemBlock: additionalProperties: false description: >- System instructions that appear mid-conversation. Use this block to provide or update system-level instructions at a specific point in the conversation, rather than only via the top-level `system` parameter. properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control content: description: System instruction text blocks. items: discriminator: mapping: text: $ref: '#/components/schemas/BetaRequestTextBlock' tool_addition: $ref: '#/components/schemas/BetaRequestToolAdditionBlock' tool_removal: $ref: '#/components/schemas/BetaRequestToolRemovalBlock' propertyName: type oneOf: - $ref: '#/components/schemas/BetaRequestTextBlock' - $ref: '#/components/schemas/BetaRequestToolAdditionBlock' - $ref: '#/components/schemas/BetaRequestToolRemovalBlock' title: Content type: array type: const: mid_conv_system title: Type type: string required: - content - type title: RequestMidConvSystemBlock type: object BetaRequestRedactedThinkingBlock: additionalProperties: false properties: data: description: >- 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. title: Data type: string type: const: redacted_thinking title: Type type: string required: - data - type title: RequestRedactedThinkingBlock type: object BetaRequestSearchResultBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control citations: $ref: '#/components/schemas/BetaRequestCitationsConfig' content: items: $ref: '#/components/schemas/BetaRequestTextBlock' title: Content type: array source: title: Source type: string title: title: Title type: string type: const: search_result title: Type type: string required: - content - source - title - type title: RequestSearchResultBlock type: object BetaRequestServerToolUseBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control caller: discriminator: mapping: code_execution_20250825: $ref: '#/components/schemas/BetaServerToolCaller' code_execution_20260120: $ref: '#/components/schemas/BetaServerToolCaller_20260120' direct: $ref: '#/components/schemas/BetaDirectCaller' propertyName: type oneOf: - $ref: '#/components/schemas/BetaDirectCaller' - $ref: '#/components/schemas/BetaServerToolCaller' - $ref: '#/components/schemas/BetaServerToolCaller_20260120' title: Caller id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Id type: string input: additionalProperties: true title: Input type: object name: enum: - advisor - web_search - web_fetch - code_execution - bash_code_execution - text_editor_code_execution - tool_search_tool_regex - tool_search_tool_bm25 title: Name type: string type: const: server_tool_use title: Type type: string required: - id - input - name - type title: RequestServerToolUseBlock type: object BetaRequestTextEditorCodeExecutionToolResultBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control content: anyOf: - $ref: >- #/components/schemas/BetaRequestTextEditorCodeExecutionToolResultError - $ref: >- #/components/schemas/BetaRequestTextEditorCodeExecutionViewResultBlock - $ref: >- #/components/schemas/BetaRequestTextEditorCodeExecutionCreateResultBlock - $ref: >- #/components/schemas/BetaRequestTextEditorCodeExecutionStrReplaceResultBlock title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: text_editor_code_execution_tool_result title: Type type: string required: - content - tool_use_id - type title: RequestTextEditorCodeExecutionToolResultBlock type: object BetaRequestThinkingBlock: additionalProperties: false properties: signature: description: >- 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 the model. Thinking blocks must be passed back unmodified and in their original order; a modified block results in a 400 `invalid_request_error`. title: Signature type: string thinking: description: The `thinking` text of this block as returned by the API. title: Thinking type: string type: const: thinking title: Type type: string required: - signature - thinking - type title: RequestThinkingBlock type: object BetaRequestToolAdditionBlock: additionalProperties: false description: |- Mid-conversation directive to surface a declared tool. ``tool`` references a tool (or MCP toolset) by name from the request's ``tools``; it is offered to the model from this point in the conversation onward. properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control tool: discriminator: mapping: mcp_tool_reference: $ref: '#/components/schemas/BetaToolChangeMCPToolReference' mcp_toolset_reference: $ref: '#/components/schemas/BetaToolChangeMCPToolsetReference' tool_reference: $ref: '#/components/schemas/BetaToolChangeToolReference' propertyName: type oneOf: - $ref: '#/components/schemas/BetaToolChangeToolReference' - $ref: '#/components/schemas/BetaToolChangeMCPToolReference' - $ref: '#/components/schemas/BetaToolChangeMCPToolsetReference' title: Tool type: const: tool_addition title: Type type: string required: - tool - type title: RequestToolAdditionBlock type: object BetaRequestToolRemovalBlock: additionalProperties: false description: |- Mid-conversation directive to withdraw a tool. ``tool`` references a tool (or MCP toolset) by name from the request's ``tools``; it is no longer offered to the model from this point in the conversation onward. properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control tool: discriminator: mapping: mcp_tool_reference: $ref: '#/components/schemas/BetaToolChangeMCPToolReference' mcp_toolset_reference: $ref: '#/components/schemas/BetaToolChangeMCPToolsetReference' tool_reference: $ref: '#/components/schemas/BetaToolChangeToolReference' propertyName: type oneOf: - $ref: '#/components/schemas/BetaToolChangeToolReference' - $ref: '#/components/schemas/BetaToolChangeMCPToolReference' - $ref: '#/components/schemas/BetaToolChangeMCPToolsetReference' title: Tool type: const: tool_removal title: Type type: string required: - tool - type title: RequestToolRemovalBlock type: object BetaRequestToolResultBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control content: anyOf: - type: string x-stainless-skip: - go - cli - items: discriminator: mapping: document: $ref: '#/components/schemas/BetaRequestDocumentBlock' image: $ref: '#/components/schemas/BetaRequestImageBlock' search_result: $ref: '#/components/schemas/BetaRequestSearchResultBlock' text: $ref: '#/components/schemas/BetaRequestTextBlock' tool_reference: $ref: '#/components/schemas/BetaRequestToolReferenceBlock' propertyName: type oneOf: - $ref: '#/components/schemas/BetaRequestTextBlock' - $ref: '#/components/schemas/BetaRequestImageBlock' - $ref: '#/components/schemas/BetaRequestSearchResultBlock' - $ref: '#/components/schemas/BetaRequestDocumentBlock' - $ref: '#/components/schemas/BetaRequestToolReferenceBlock' title: Block type: array x-stainless-naming: python: type_name: Content ruby: type_name: Content php: type_name: Content title: Content is_error: title: Is Error type: boolean tool_use_id: pattern: ^[a-zA-Z0-9_-]+$ title: Tool Use Id type: string type: const: tool_result title: Type type: string required: - tool_use_id - type title: RequestToolResultBlock type: object BetaRequestToolSearchToolResultBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control content: anyOf: - $ref: '#/components/schemas/BetaRequestToolSearchToolResultError' - $ref: '#/components/schemas/BetaRequestToolSearchToolSearchResultBlock' title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: tool_search_tool_result title: Type type: string required: - content - tool_use_id - type title: RequestToolSearchToolResultBlock type: object BetaRequestToolUseBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control caller: discriminator: mapping: code_execution_20250825: $ref: '#/components/schemas/BetaServerToolCaller' code_execution_20260120: $ref: '#/components/schemas/BetaServerToolCaller_20260120' direct: $ref: '#/components/schemas/BetaDirectCaller' propertyName: type oneOf: - $ref: '#/components/schemas/BetaDirectCaller' - $ref: '#/components/schemas/BetaServerToolCaller' - $ref: '#/components/schemas/BetaServerToolCaller_20260120' title: Caller id: pattern: ^[a-zA-Z0-9_-]+$ title: Id type: string input: additionalProperties: true title: Input type: object name: maxLength: 200 minLength: 1 title: Name type: string type: const: tool_use title: Type type: string required: - id - input - name - type title: RequestToolUseBlock type: object BetaRequestWebFetchToolResultBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control caller: discriminator: mapping: code_execution_20250825: $ref: '#/components/schemas/BetaServerToolCaller' code_execution_20260120: $ref: '#/components/schemas/BetaServerToolCaller_20260120' direct: $ref: '#/components/schemas/BetaDirectCaller' propertyName: type oneOf: - $ref: '#/components/schemas/BetaDirectCaller' - $ref: '#/components/schemas/BetaServerToolCaller' - $ref: '#/components/schemas/BetaServerToolCaller_20260120' title: Caller content: anyOf: - $ref: '#/components/schemas/BetaRequestWebFetchToolResultError' - $ref: '#/components/schemas/BetaRequestWebFetchResultBlock' title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: web_fetch_tool_result title: Type type: string required: - content - tool_use_id - type title: RequestWebFetchToolResultBlock type: object BetaRequestWebSearchToolResultBlock: additionalProperties: false properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control caller: discriminator: mapping: code_execution_20250825: $ref: '#/components/schemas/BetaServerToolCaller' code_execution_20260120: $ref: '#/components/schemas/BetaServerToolCaller_20260120' direct: $ref: '#/components/schemas/BetaDirectCaller' propertyName: type oneOf: - $ref: '#/components/schemas/BetaDirectCaller' - $ref: '#/components/schemas/BetaServerToolCaller' - $ref: '#/components/schemas/BetaServerToolCaller_20260120' title: Caller content: anyOf: - items: $ref: '#/components/schemas/BetaRequestWebSearchResultBlock' type: array title: Result Block - $ref: '#/components/schemas/BetaRequestWebSearchToolResultError' x-stainless-naming: go: variant_constructor: BetaNewWebSearchToolRequestError title: Content tool_use_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Use Id type: string type: const: web_search_tool_result title: Type type: string required: - content - tool_use_id - type title: RequestWebSearchToolResultBlock type: object BetaAllThinkingTurns: additionalProperties: false properties: type: const: all title: Type type: string required: - type title: AllThinkingTurns type: object BetaThinkingTurns: additionalProperties: false properties: type: const: thinking_turns title: Type type: string value: minimum: 1 title: Value type: integer required: - type - value title: ThinkingTurns type: object BetaInputTokensClearAtLeast: additionalProperties: false properties: type: const: input_tokens title: Type type: string value: minimum: 0 title: Value type: integer required: - type - value title: InputTokensClearAtLeast type: object BetaToolUsesKeep: additionalProperties: false properties: type: const: tool_uses title: Type type: string value: minimum: 0 title: Value type: integer required: - type - value title: ToolUsesKeep type: object BetaInputTokensTrigger: additionalProperties: false properties: type: const: input_tokens title: Type type: string value: minimum: 1 title: Value type: integer required: - type - value title: InputTokensTrigger type: object BetaToolUsesTrigger: additionalProperties: false properties: type: const: tool_uses title: Type type: string value: minimum: 1 title: Value type: integer required: - type - value title: ToolUsesTrigger type: object BetaThinkingDisplayMode: enum: - summarized - omitted title: ThinkingDisplayMode type: string BetaResponseAdvisorToolResultError: properties: error_code: $ref: '#/components/schemas/BetaAdvisorToolResultErrorCode' type: const: advisor_tool_result_error default: advisor_tool_result_error title: Type type: string required: - error_code - type title: ResponseAdvisorToolResultError type: object BetaResponseAdvisorResultBlock: properties: stop_reason: anyOf: - type: string - type: 'null' default: null description: >- The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. title: Stop Reason text: title: Text type: string type: const: advisor_result default: advisor_result title: Type type: string required: - stop_reason - text - type title: ResponseAdvisorResultBlock type: object BetaResponseAdvisorRedactedResultBlock: properties: encrypted_content: description: >- Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. title: Encrypted Content type: string stop_reason: anyOf: - type: string - type: 'null' default: null description: >- The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). title: Stop Reason type: const: advisor_redacted_result default: advisor_redacted_result title: Type type: string required: - encrypted_content - stop_reason - type title: ResponseAdvisorRedactedResultBlock type: object BetaResponseBashCodeExecutionToolResultError: properties: error_code: $ref: '#/components/schemas/BetaBashCodeExecutionToolResultErrorCode' type: const: bash_code_execution_tool_result_error default: bash_code_execution_tool_result_error title: Type type: string required: - error_code - type title: ResponseBashCodeExecutionToolResultError type: object BetaResponseBashCodeExecutionResultBlock: properties: content: items: $ref: '#/components/schemas/BetaResponseBashCodeExecutionOutputBlock' title: Content type: array return_code: title: Return Code type: integer stderr: title: Stderr type: string stdout: title: Stdout type: string type: const: bash_code_execution_result default: bash_code_execution_result title: Type type: string required: - content - return_code - stderr - stdout - type title: ResponseBashCodeExecutionResultBlock type: object BetaResponseCodeExecutionToolResultError: properties: error_code: $ref: '#/components/schemas/BetaCodeExecutionToolResultErrorCode' type: const: code_execution_tool_result_error default: code_execution_tool_result_error title: Type type: string required: - error_code - type title: ResponseCodeExecutionToolResultError type: object BetaResponseCodeExecutionResultBlock: properties: content: items: $ref: '#/components/schemas/BetaResponseCodeExecutionOutputBlock' title: Content type: array return_code: title: Return Code type: integer stderr: title: Stderr type: string stdout: title: Stdout type: string type: const: code_execution_result default: code_execution_result title: Type type: string required: - content - return_code - stderr - stdout - type title: ResponseCodeExecutionResultBlock type: object BetaResponseEncryptedCodeExecutionResultBlock: description: >- Code execution result with encrypted stdout for PFC + web_search results. properties: content: items: $ref: '#/components/schemas/BetaResponseCodeExecutionOutputBlock' title: Content type: array encrypted_stdout: title: Encrypted Stdout type: string return_code: title: Return Code type: integer stderr: title: Stderr type: string type: const: encrypted_code_execution_result default: encrypted_code_execution_result title: Type type: string required: - content - encrypted_stdout - return_code - stderr - type title: ResponseEncryptedCodeExecutionResultBlock type: object BetaResponseFallbackHopInfo: description: Identifies one hop of a fallback transition. properties: model: $ref: '#/components/schemas/Model' required: - model title: ResponseFallbackHopInfo type: object BetaFallbackRefusalTrigger: description: The `from` model declined for policy reasons. properties: category: anyOf: - $ref: '#/components/schemas/BetaRefusalCategory' - type: 'null' default: null description: >- The policy category that triggered the `from` model's refusal at this hop. `null` when the refusal doesn't map to a named category. Same vocabulary as `stop_details.category`. x-stainless-naming: csharp: type_name: BetaFallbackRefusalTriggerCategory type: const: refusal default: refusal title: Type type: string required: - category - type title: FallbackRefusalTrigger type: object BetaServerToolCaller: additionalProperties: false description: Tool invocation generated by a server-side tool. properties: tool_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Id type: string type: const: code_execution_20250825 title: Type type: string required: - tool_id - type title: ServerToolCaller type: object BetaServerToolCaller_20260120: additionalProperties: false properties: tool_id: pattern: ^srvtoolu_[a-zA-Z0-9_]+$ title: Tool Id type: string type: const: code_execution_20260120 title: Type type: string required: - tool_id - type title: ServerToolCaller_20260120 type: object BetaDirectCaller: additionalProperties: false description: Tool invocation directly from the model. properties: type: const: direct title: Type type: string required: - type title: DirectCaller type: object BetaResponseCharLocationCitation: properties: cited_text: examples: - The grass is green. The sky is blue. title: Cited Text type: string document_index: minimum: 0 title: Document Index type: integer document_title: anyOf: - type: string - type: 'null' examples: - My Document title: Document Title end_char_index: title: End Char Index type: integer file_id: anyOf: - type: string - type: 'null' default: null examples: - file_011CNha8iCJcU1wXNR6q4V8w title: File Id start_char_index: minimum: 0 title: Start Char Index type: integer type: const: char_location default: char_location title: Type type: string required: - cited_text - document_index - document_title - end_char_index - file_id - start_char_index - type title: ResponseCharLocationCitation type: object BetaResponseContentBlockLocationCitation: properties: cited_text: description: >- 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. examples: - The grass is green. The sky is blue. title: Cited Text type: string document_index: minimum: 0 title: Document Index type: integer document_title: anyOf: - type: string - type: 'null' examples: - My Document title: Document Title end_block_index: description: >- 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`. title: End Block Index type: integer file_id: anyOf: - type: string - type: 'null' default: null examples: - file_011CNha8iCJcU1wXNR6q4V8w title: File Id start_block_index: description: >- 0-based index of the first cited block in the source's `content` array. minimum: 0 title: Start Block Index type: integer type: const: content_block_location default: content_block_location title: Type type: string required: - cited_text - document_index - document_title - end_block_index - file_id - start_block_index - type title: ResponseContentBlockLocationCitation type: object BetaResponsePageLocationCitation: properties: cited_text: examples: - The grass is green. The sky is blue. title: Cited Text type: string document_index: minimum: 0 title: Document Index type: integer document_title: anyOf: - type: string - type: 'null' examples: - My Document title: Document Title end_page_number: title: End Page Number type: integer file_id: anyOf: - type: string - type: 'null' default: null examples: - file_011CNha8iCJcU1wXNR6q4V8w title: File Id start_page_number: minimum: 1 title: Start Page Number type: integer type: const: page_location default: page_location title: Type type: string required: - cited_text - document_index - document_title - end_page_number - file_id - start_page_number - type title: ResponsePageLocationCitation type: object BetaResponseSearchResultLocationCitation: properties: cited_text: description: >- 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. examples: - The grass is green. The sky is blue. title: Cited Text type: string end_block_index: description: >- 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`. title: End Block Index type: integer search_result_index: description: >- 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. minimum: 0 title: Search Result Index type: integer source: title: Source type: string start_block_index: description: >- 0-based index of the first cited block in the source's `content` array. minimum: 0 title: Start Block Index type: integer title: anyOf: - type: string - type: 'null' title: Title type: const: search_result_location default: search_result_location title: Type type: string required: - cited_text - end_block_index - search_result_index - source - start_block_index - title - type title: ResponseSearchResultLocationCitation type: object BetaResponseWebSearchResultLocationCitation: properties: cited_text: examples: - The grass is green. The sky is blue. title: Cited Text type: string encrypted_index: title: Encrypted Index type: string title: anyOf: - maxLength: 512 type: string - type: 'null' title: Title type: const: web_search_result_location default: web_search_result_location title: Type type: string url: title: Url type: string required: - cited_text - encrypted_index - title - type - url title: ResponseWebSearchResultLocationCitation type: object BetaResponseTextEditorCodeExecutionToolResultError: properties: error_code: $ref: '#/components/schemas/BetaTextEditorCodeExecutionToolResultErrorCode' error_message: anyOf: - type: string - type: 'null' default: null title: Error Message type: const: text_editor_code_execution_tool_result_error default: text_editor_code_execution_tool_result_error title: Type type: string required: - error_code - error_message - type title: ResponseTextEditorCodeExecutionToolResultError type: object BetaResponseTextEditorCodeExecutionViewResultBlock: properties: content: title: Content type: string file_type: enum: - text - image - pdf title: File Type type: string num_lines: anyOf: - type: integer - type: 'null' default: null title: Num Lines start_line: anyOf: - type: integer - type: 'null' default: null title: Start Line total_lines: anyOf: - type: integer - type: 'null' default: null title: Total Lines type: const: text_editor_code_execution_view_result default: text_editor_code_execution_view_result title: Type type: string required: - content - file_type - num_lines - start_line - total_lines - type title: ResponseTextEditorCodeExecutionViewResultBlock type: object BetaResponseTextEditorCodeExecutionCreateResultBlock: properties: is_file_update: title: Is File Update type: boolean type: const: text_editor_code_execution_create_result default: text_editor_code_execution_create_result title: Type type: string required: - is_file_update - type title: ResponseTextEditorCodeExecutionCreateResultBlock type: object BetaResponseTextEditorCodeExecutionStrReplaceResultBlock: properties: lines: anyOf: - items: type: string type: array - type: 'null' default: null title: Lines new_lines: anyOf: - type: integer - type: 'null' default: null title: New Lines new_start: anyOf: - type: integer - type: 'null' default: null title: New Start old_lines: anyOf: - type: integer - type: 'null' default: null title: Old Lines old_start: anyOf: - type: integer - type: 'null' default: null title: Old Start type: const: text_editor_code_execution_str_replace_result default: text_editor_code_execution_str_replace_result title: Type type: string required: - lines - new_lines - new_start - old_lines - old_start - type title: ResponseTextEditorCodeExecutionStrReplaceResultBlock type: object BetaResponseToolSearchToolResultError: properties: error_code: $ref: '#/components/schemas/BetaToolSearchToolResultErrorCode' error_message: anyOf: - type: string - type: 'null' default: null title: Error Message type: const: tool_search_tool_result_error default: tool_search_tool_result_error title: Type type: string required: - error_code - error_message - type title: ResponseToolSearchToolResultError type: object BetaResponseToolSearchToolSearchResultBlock: properties: tool_references: items: $ref: '#/components/schemas/BetaResponseToolReferenceBlock' title: Tool References type: array type: const: tool_search_tool_search_result default: tool_search_tool_search_result title: Type type: string required: - tool_references - type title: ResponseToolSearchToolSearchResultBlock type: object BetaResponseWebFetchToolResultError: properties: error_code: $ref: '#/components/schemas/BetaWebFetchToolResultErrorCode' type: const: web_fetch_tool_result_error default: web_fetch_tool_result_error title: Type type: string required: - error_code - type title: ResponseWebFetchToolResultError type: object BetaResponseWebFetchResultBlock: properties: content: $ref: '#/components/schemas/BetaResponseDocumentBlock' retrieved_at: anyOf: - type: string - type: 'null' default: null description: ISO 8601 timestamp when the content was retrieved title: Retrieved At type: const: web_fetch_result default: web_fetch_result title: Type type: string url: description: Fetched content URL title: Url type: string required: - content - retrieved_at - type - url title: ResponseWebFetchResultBlock type: object BetaResponseWebSearchToolResultError: properties: error_code: $ref: '#/components/schemas/BetaWebSearchToolResultErrorCode' type: const: web_search_tool_result_error default: web_search_tool_result_error title: Type type: string required: - error_code - type title: ResponseWebSearchToolResultError type: object BetaResponseWebSearchResultBlock: properties: encrypted_content: title: Encrypted Content type: string page_age: anyOf: - type: string - type: 'null' default: null title: Page Age title: title: Title type: string type: const: web_search_result default: web_search_result title: Type type: string url: title: Url type: string required: - encrypted_content - page_age - title - type - url title: ResponseWebSearchResultBlock type: object BetaFallbackCreditNotApplied: description: No reprice was applied; ``reason`` says why. properties: reason: description: >- Why the reprice was not applied. A closed enum; additions to the redemption-check vocabulary arrive as deliberate schema updates. enum: - body_mismatch - continuation_excluded - continuation_only - expired - invalid_target_model - not_enabled - reprice_unavailable - temporarily_unavailable - variant_fields_present - wrong_organization - wrong_platform - wrong_workspace title: Reason type: string remove_to_redeem: anyOf: - items: type: string type: array - type: 'null' default: null description: >- Request fields to remove before retrying, so the retry can redeem this token. Present exactly when `reason` is `variant_fields_present` — never null, never an empty array; absent otherwise. Fields are named only from your own request, and only after the sealed variant hash matched. A served best-effort retry has already been billed at normal price; nothing redeems retroactively, but a corrected re-send inside the token's five-minute window can still redeem. title: Remove To Redeem type: const: not_applied default: not_applied title: Type type: string required: - reason - type title: FallbackCreditNotApplied type: object BetaFallbackCreditRedeemed: description: |- The reprice was applied: the retry is billed as if the conversation had been on the retry model all along. properties: type: const: redeemed default: redeemed title: Type type: string required: - type title: FallbackCreditRedeemed type: object BetaAdvisorMessageIterationUsage: description: Token usage for an advisor sub-inference iteration. properties: cache_creation: anyOf: - $ref: '#/components/schemas/BetaCacheCreation' - type: 'null' default: null description: Breakdown of cached tokens by TTL cache_creation_input_tokens: default: 0 description: The number of input tokens used to create the cache entry. minimum: 0 title: Cache Creation Input Tokens type: integer cache_read_input_tokens: default: 0 description: The number of input tokens read from the cache. minimum: 0 title: Cache Read Input Tokens type: integer input_tokens: description: The number of input tokens which were used. minimum: 0 title: Input Tokens type: integer model: $ref: '#/components/schemas/Model' output_tokens: description: The number of output tokens which were used. minimum: 0 title: Output Tokens type: integer type: const: advisor_message default: advisor_message description: Usage for an advisor sub-inference iteration title: Type type: string required: - cache_creation - cache_creation_input_tokens - cache_read_input_tokens - input_tokens - model - output_tokens - type title: AdvisorMessageIterationUsage type: object BetaCompactionIterationUsage: description: Token usage for a compaction iteration. properties: cache_creation: anyOf: - $ref: '#/components/schemas/BetaCacheCreation' - type: 'null' default: null description: Breakdown of cached tokens by TTL cache_creation_input_tokens: default: 0 description: The number of input tokens used to create the cache entry. minimum: 0 title: Cache Creation Input Tokens type: integer cache_read_input_tokens: default: 0 description: The number of input tokens read from the cache. minimum: 0 title: Cache Read Input Tokens type: integer input_tokens: description: The number of input tokens which were used. minimum: 0 title: Input Tokens type: integer output_tokens: description: The number of output tokens which were used. minimum: 0 title: Output Tokens type: integer type: const: compaction default: compaction description: Usage for a compaction iteration title: Type type: string required: - cache_creation - cache_creation_input_tokens - cache_read_input_tokens - input_tokens - output_tokens - type title: CompactionIterationUsage type: object BetaFallbackMessageIterationUsage: description: >- Token usage for the fallback-model attempt of a server-side fallback request. Produced in place of a `message` entry for whichever hop served the response. A declined hop produces the existing `message` entry. Whether a fallback model served the response is signalled by the presence of this entry in `usage.iterations`. properties: cache_creation: anyOf: - $ref: '#/components/schemas/BetaCacheCreation' - type: 'null' default: null description: Breakdown of cached tokens by TTL cache_creation_input_tokens: default: 0 description: The number of input tokens used to create the cache entry. minimum: 0 title: Cache Creation Input Tokens type: integer cache_read_input_tokens: default: 0 description: The number of input tokens read from the cache. minimum: 0 title: Cache Read Input Tokens type: integer input_tokens: description: The number of input tokens which were used. minimum: 0 title: Input Tokens type: integer model: $ref: '#/components/schemas/Model' output_tokens: description: The number of output tokens which were used. minimum: 0 title: Output Tokens type: integer type: const: fallback_message default: fallback_message description: Usage for the fallback-model attempt that served the response title: Type type: string required: - cache_creation - cache_creation_input_tokens - cache_read_input_tokens - input_tokens - model - output_tokens - type title: FallbackMessageIterationUsage type: object BetaMessageIterationUsage: description: Token usage for a sampling iteration. properties: cache_creation: anyOf: - $ref: '#/components/schemas/BetaCacheCreation' - type: 'null' default: null description: Breakdown of cached tokens by TTL cache_creation_input_tokens: default: 0 description: The number of input tokens used to create the cache entry. minimum: 0 title: Cache Creation Input Tokens type: integer cache_read_input_tokens: default: 0 description: The number of input tokens read from the cache. minimum: 0 title: Cache Read Input Tokens type: integer input_tokens: description: The number of input tokens which were used. minimum: 0 title: Input Tokens type: integer model: $ref: '#/components/schemas/Model' output_tokens: description: The number of output tokens which were used. minimum: 0 title: Output Tokens type: integer type: const: message default: message description: Usage for a sampling iteration title: Type type: string required: - cache_creation - cache_creation_input_tokens - cache_read_input_tokens - input_tokens - model - output_tokens - type title: MessageIterationUsage type: object BetaRequestAdvisorToolResultError: additionalProperties: false properties: error_code: $ref: '#/components/schemas/BetaAdvisorToolResultErrorCode' type: const: advisor_tool_result_error title: Type type: string required: - error_code - type title: RequestAdvisorToolResultError type: object BetaRequestAdvisorResultBlock: additionalProperties: false properties: stop_reason: anyOf: - type: string - type: 'null' title: Stop Reason text: title: Text type: string type: const: advisor_result title: Type type: string required: - text - type title: RequestAdvisorResultBlock type: object BetaRequestAdvisorRedactedResultBlock: additionalProperties: false properties: encrypted_content: description: >- Opaque blob produced by a prior response; must be round-tripped verbatim. title: Encrypted Content type: string stop_reason: anyOf: - type: string - type: 'null' title: Stop Reason type: const: advisor_redacted_result title: Type type: string required: - encrypted_content - type title: RequestAdvisorRedactedResultBlock type: object BetaRequestBashCodeExecutionToolResultError: additionalProperties: false properties: error_code: $ref: '#/components/schemas/BetaBashCodeExecutionToolResultErrorCode' type: const: bash_code_execution_tool_result_error title: Type type: string required: - error_code - type title: RequestBashCodeExecutionToolResultError type: object BetaRequestBashCodeExecutionResultBlock: additionalProperties: false properties: content: items: $ref: '#/components/schemas/BetaRequestBashCodeExecutionOutputBlock' title: Content type: array return_code: title: Return Code type: integer stderr: title: Stderr type: string stdout: title: Stdout type: string type: const: bash_code_execution_result title: Type type: string required: - content - return_code - stderr - stdout - type title: RequestBashCodeExecutionResultBlock type: object BetaRequestCodeExecutionToolResultError: additionalProperties: false properties: error_code: $ref: '#/components/schemas/BetaCodeExecutionToolResultErrorCode' type: const: code_execution_tool_result_error title: Type type: string required: - error_code - type title: Error type: object BetaRequestCodeExecutionResultBlock: additionalProperties: false properties: content: items: $ref: '#/components/schemas/BetaRequestCodeExecutionOutputBlock' title: Content type: array return_code: title: Return Code type: integer stderr: title: Stderr type: string stdout: title: Stdout type: string type: const: code_execution_result title: Type type: string required: - content - return_code - stderr - stdout - type title: Result Block type: object BetaRequestEncryptedCodeExecutionResultBlock: additionalProperties: false description: >- Code execution result with encrypted stdout for PFC + web_search results. properties: content: items: $ref: '#/components/schemas/BetaRequestCodeExecutionOutputBlock' title: Content type: array encrypted_stdout: title: Encrypted Stdout type: string return_code: title: Return Code type: integer stderr: title: Stderr type: string type: const: encrypted_code_execution_result title: Type type: string required: - content - encrypted_stdout - return_code - stderr - type title: RequestEncryptedCodeExecutionResultBlock type: object BetaBase64PDFSource: additionalProperties: false properties: data: format: byte title: Data type: string media_type: const: application/pdf title: Media Type type: string type: const: base64 title: Type type: string required: - data - media_type - type title: Base64PDFSource type: object BetaContentBlockSource: additionalProperties: false properties: content: anyOf: - type: string - items: discriminator: mapping: image: $ref: '#/components/schemas/BetaRequestImageBlock' text: $ref: '#/components/schemas/BetaRequestTextBlock' propertyName: type oneOf: - $ref: '#/components/schemas/BetaRequestTextBlock' - $ref: '#/components/schemas/BetaRequestImageBlock' title: beta_content_block_source_content_item type: array title: beta_content_block_source_content title: Content type: const: content title: Type type: string required: - content - type title: ContentBlockSource type: object BetaFileDocumentSource: additionalProperties: false properties: file_id: title: File Id type: string type: const: file title: Type type: string required: - file_id - type title: FileDocumentSource type: object BetaPlainTextSource: additionalProperties: false properties: data: title: Data type: string media_type: const: text/plain title: Media Type type: string type: const: text title: Type type: string required: - data - media_type - type title: PlainTextSource type: object BetaURLPDFSource: additionalProperties: false properties: type: const: url title: Type type: string url: title: Url type: string required: - type - url title: URLPDFSource type: object BetaRequestFallbackHopInfo: additionalProperties: false description: Identifies one hop of a fallback transition. properties: model: $ref: '#/components/schemas/Model' required: - model title: RequestFallbackHopInfo type: object BetaBase64ImageSource: additionalProperties: false properties: data: format: byte title: Data type: string media_type: enum: - image/jpeg - image/png - image/gif - image/webp title: Media Type type: string type: const: base64 title: Type type: string required: - data - media_type - type title: Base64ImageSource type: object BetaFileImageSource: additionalProperties: false properties: file_id: title: File Id type: string type: const: file title: Type type: string required: - file_id - type title: FileImageSource type: object BetaURLImageSource: additionalProperties: false properties: type: const: url title: Type type: string url: title: Url type: string required: - type - url title: URLImageSource type: object BetaRequestTextEditorCodeExecutionToolResultError: additionalProperties: false properties: error_code: $ref: '#/components/schemas/BetaTextEditorCodeExecutionToolResultErrorCode' error_message: anyOf: - type: string - type: 'null' title: Error Message type: const: text_editor_code_execution_tool_result_error title: Type type: string required: - error_code - type title: RequestTextEditorCodeExecutionToolResultError type: object BetaRequestTextEditorCodeExecutionViewResultBlock: additionalProperties: false properties: content: title: Content type: string file_type: enum: - text - image - pdf title: File Type type: string num_lines: anyOf: - type: integer - type: 'null' title: Num Lines start_line: anyOf: - type: integer - type: 'null' title: Start Line total_lines: anyOf: - type: integer - type: 'null' title: Total Lines type: const: text_editor_code_execution_view_result title: Type type: string required: - content - file_type - type title: RequestTextEditorCodeExecutionViewResultBlock type: object BetaRequestTextEditorCodeExecutionCreateResultBlock: additionalProperties: false properties: is_file_update: title: Is File Update type: boolean type: const: text_editor_code_execution_create_result title: Type type: string required: - is_file_update - type title: RequestTextEditorCodeExecutionCreateResultBlock type: object BetaRequestTextEditorCodeExecutionStrReplaceResultBlock: additionalProperties: false properties: lines: anyOf: - items: type: string type: array - type: 'null' title: Lines new_lines: anyOf: - type: integer - type: 'null' title: New Lines new_start: anyOf: - type: integer - type: 'null' title: New Start old_lines: anyOf: - type: integer - type: 'null' title: Old Lines old_start: anyOf: - type: integer - type: 'null' title: Old Start type: const: text_editor_code_execution_str_replace_result title: Type type: string required: - type title: RequestTextEditorCodeExecutionStrReplaceResultBlock type: object BetaToolChangeMCPToolReference: additionalProperties: false description: |- Reference to a single MCP tool by its server and remote name — the same ``server_name``/``name`` pair ``mcp_tool_use`` carries. properties: name: title: Name type: string server_name: title: Server Name type: string type: const: mcp_tool_reference title: Type type: string required: - name - server_name - type title: ToolChangeMCPToolReference type: object BetaToolChangeMCPToolsetReference: additionalProperties: false description: Reference to every tool in the named MCP server's toolset. properties: server_name: title: Server Name type: string type: const: mcp_toolset_reference title: Type type: string required: - server_name - type title: ToolChangeMCPToolsetReference type: object BetaToolChangeToolReference: additionalProperties: false description: |- Reference to a single tool the caller declared directly in ``tools[]``. Does not accept the composed ``{server}_{name}`` form the server assigns to MCP-resolved tools — use ``mcp_tool_reference`` or ``mcp_toolset_reference`` for those. properties: name: pattern: ^[a-zA-Z0-9_-]{1,128}$ title: Name type: string type: const: tool_reference title: Type type: string required: - name - type title: ToolChangeToolReference type: object BetaRequestToolReferenceBlock: additionalProperties: false description: Tool reference block that can be included in tool_result content. properties: cache_control: anyOf: - discriminator: mapping: ephemeral: $ref: '#/components/schemas/BetaCacheControlEphemeral' propertyName: type oneOf: - $ref: '#/components/schemas/BetaCacheControlEphemeral' - type: 'null' description: Create a cache control breakpoint at this content block. title: Cache Control tool_name: maxLength: 256 minLength: 1 pattern: ^[a-zA-Z0-9_-]{1,256}$ title: Tool Name type: string type: const: tool_reference title: Type type: string required: - tool_name - type title: RequestToolReferenceBlock type: object BetaRequestToolSearchToolResultError: additionalProperties: false properties: error_code: $ref: '#/components/schemas/BetaToolSearchToolResultErrorCode' error_message: anyOf: - type: string - type: 'null' title: Error Message type: const: tool_search_tool_result_error title: Type type: string required: - error_code - type title: RequestToolSearchToolResultError type: object BetaRequestToolSearchToolSearchResultBlock: additionalProperties: false properties: tool_references: items: $ref: '#/components/schemas/BetaRequestToolReferenceBlock' title: Tool References type: array type: const: tool_search_tool_search_result title: Type type: string required: - tool_references - type title: RequestToolSearchToolSearchResultBlock type: object BetaRequestWebFetchToolResultError: additionalProperties: false properties: error_code: $ref: '#/components/schemas/BetaWebFetchToolResultErrorCode' type: const: web_fetch_tool_result_error title: Type type: string required: - error_code - type title: RequestWebFetchToolResultError type: object BetaRequestWebFetchResultBlock: additionalProperties: false properties: content: $ref: '#/components/schemas/BetaRequestDocumentBlock' retrieved_at: anyOf: - type: string - type: 'null' description: ISO 8601 timestamp when the content was retrieved title: Retrieved At type: const: web_fetch_result title: Type type: string url: description: Fetched content URL title: Url type: string required: - content - type - url title: RequestWebFetchResultBlock type: object BetaRequestWebSearchResultBlock: additionalProperties: false properties: encrypted_content: title: Encrypted Content type: string page_age: anyOf: - type: string - type: 'null' title: Page Age title: title: Title type: string type: const: web_search_result title: Type type: string url: title: Url type: string required: - encrypted_content - title - type - url title: RequestWebSearchResultBlock type: object BetaRequestWebSearchToolResultError: additionalProperties: false properties: error_code: $ref: '#/components/schemas/BetaWebSearchToolResultErrorCode' type: const: web_search_tool_result_error title: Type type: string required: - error_code - type title: Error type: object BetaAdvisorToolResultErrorCode: enum: - max_uses_exceeded - prompt_too_long - too_many_requests - overloaded - unavailable - execution_time_exceeded - model_not_found title: AdvisorToolResultErrorCode type: string BetaBashCodeExecutionToolResultErrorCode: enum: - invalid_tool_input - unavailable - too_many_requests - execution_time_exceeded - output_file_too_large title: BashCodeExecutionToolResultErrorCode type: string BetaResponseBashCodeExecutionOutputBlock: properties: file_id: title: File Id type: string type: const: bash_code_execution_output default: bash_code_execution_output title: Type type: string required: - file_id - type title: ResponseBashCodeExecutionOutputBlock type: object BetaCodeExecutionToolResultErrorCode: enum: - invalid_tool_input - unavailable - too_many_requests - execution_time_exceeded title: CodeExecutionToolResultErrorCode type: string BetaResponseCodeExecutionOutputBlock: properties: file_id: title: File Id type: string type: const: code_execution_output default: code_execution_output title: Type type: string required: - file_id - type title: ResponseCodeExecutionOutputBlock type: object BetaTextEditorCodeExecutionToolResultErrorCode: enum: - invalid_tool_input - unavailable - too_many_requests - execution_time_exceeded - file_not_found title: TextEditorCodeExecutionToolResultErrorCode type: string BetaToolSearchToolResultErrorCode: enum: - invalid_tool_input - unavailable - too_many_requests - execution_time_exceeded title: ToolSearchToolResultErrorCode type: string BetaResponseToolReferenceBlock: properties: tool_name: maxLength: 256 minLength: 1 pattern: ^[a-zA-Z0-9_-]{1,256}$ title: Tool Name type: string type: const: tool_reference default: tool_reference title: Type type: string required: - tool_name - type title: ResponseToolReferenceBlock type: object BetaWebFetchToolResultErrorCode: enum: - 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 title: WebFetchToolResultErrorCode type: string BetaResponseDocumentBlock: properties: citations: anyOf: - $ref: '#/components/schemas/BetaResponseCitationsConfig' - type: 'null' default: null description: Citation configuration for the document source: discriminator: mapping: base64: $ref: '#/components/schemas/BetaBase64PDFSource' text: $ref: '#/components/schemas/BetaPlainTextSource' propertyName: type oneOf: - $ref: '#/components/schemas/BetaBase64PDFSource' - $ref: '#/components/schemas/BetaPlainTextSource' title: Source title: anyOf: - type: string - type: 'null' default: null description: The title of the document title: Title type: const: document default: document title: Type type: string required: - citations - source - title - type title: ResponseDocumentBlock type: object BetaWebSearchToolResultErrorCode: enum: - invalid_tool_input - unavailable - max_uses_exceeded - too_many_requests - query_too_long - request_too_large title: WebSearchToolResultErrorCode type: string BetaRequestBashCodeExecutionOutputBlock: additionalProperties: false properties: file_id: title: File Id type: string type: const: bash_code_execution_output title: Type type: string required: - file_id - type title: RequestBashCodeExecutionOutputBlock type: object BetaRequestCodeExecutionOutputBlock: additionalProperties: false properties: file_id: title: File Id type: string type: const: code_execution_output title: Type type: string required: - file_id - type title: RequestCodeExecutionOutputBlock type: object BetaResponseCitationsConfig: properties: enabled: default: false title: Enabled type: boolean required: - enabled title: ResponseCitationsConfig type: object securitySchemes: omaApiKey: type: apiKey in: header name: X-Api-Key description: OMA workspace API key. x-default: sk-ant-local-default omaBearer: type: http scheme: bearer description: OMA workspace API key sent as a bearer token. ````