# Beta

## Domain Types

### Anthropic Beta

- `enum AnthropicBeta:`

  - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

  - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

  - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

  - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

  - `PDFS_2024_09_25("pdfs-2024-09-25")`

  - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

  - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

  - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

  - `FILES_API_2025_04_14("files-api-2025-04-14")`

  - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

  - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

  - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

  - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

  - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

  - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

  - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

  - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

  - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

  - `SKILLS_2025_10_02("skills-2025-10-02")`

  - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

  - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

  - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

  - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

  - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

  - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

  - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

  - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

  - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Beta API Error

- `class BetaApiError:`

  - `String message`

  - `JsonValue; type "api_error"constant`

    - `API_ERROR("api_error")`

### Beta Authentication Error

- `class BetaAuthenticationError:`

  - `String message`

  - `JsonValue; type "authentication_error"constant`

    - `AUTHENTICATION_ERROR("authentication_error")`

### Beta Billing Error

- `class BetaBillingError:`

  - `String message`

  - `JsonValue; type "billing_error"constant`

    - `BILLING_ERROR("billing_error")`

### Beta Error

- `class BetaError: A class that can be one of several variants.union`

  - `class BetaInvalidRequestError:`

    - `String message`

    - `JsonValue; type "invalid_request_error"constant`

      - `INVALID_REQUEST_ERROR("invalid_request_error")`

  - `class BetaAuthenticationError:`

    - `String message`

    - `JsonValue; type "authentication_error"constant`

      - `AUTHENTICATION_ERROR("authentication_error")`

  - `class BetaBillingError:`

    - `String message`

    - `JsonValue; type "billing_error"constant`

      - `BILLING_ERROR("billing_error")`

  - `class BetaPermissionError:`

    - `String message`

    - `JsonValue; type "permission_error"constant`

      - `PERMISSION_ERROR("permission_error")`

  - `class BetaNotFoundError:`

    - `String message`

    - `JsonValue; type "not_found_error"constant`

      - `NOT_FOUND_ERROR("not_found_error")`

  - `class BetaRateLimitError:`

    - `String message`

    - `JsonValue; type "rate_limit_error"constant`

      - `RATE_LIMIT_ERROR("rate_limit_error")`

  - `class BetaGatewayTimeoutError:`

    - `String message`

    - `JsonValue; type "timeout_error"constant`

      - `TIMEOUT_ERROR("timeout_error")`

  - `class BetaApiError:`

    - `String message`

    - `JsonValue; type "api_error"constant`

      - `API_ERROR("api_error")`

  - `class BetaOverloadedError:`

    - `String message`

    - `JsonValue; type "overloaded_error"constant`

      - `OVERLOADED_ERROR("overloaded_error")`

### Beta Error Response

- `class BetaErrorResponse:`

  - `BetaError error`

    - `class BetaInvalidRequestError:`

      - `String message`

      - `JsonValue; type "invalid_request_error"constant`

        - `INVALID_REQUEST_ERROR("invalid_request_error")`

    - `class BetaAuthenticationError:`

      - `String message`

      - `JsonValue; type "authentication_error"constant`

        - `AUTHENTICATION_ERROR("authentication_error")`

    - `class BetaBillingError:`

      - `String message`

      - `JsonValue; type "billing_error"constant`

        - `BILLING_ERROR("billing_error")`

    - `class BetaPermissionError:`

      - `String message`

      - `JsonValue; type "permission_error"constant`

        - `PERMISSION_ERROR("permission_error")`

    - `class BetaNotFoundError:`

      - `String message`

      - `JsonValue; type "not_found_error"constant`

        - `NOT_FOUND_ERROR("not_found_error")`

    - `class BetaRateLimitError:`

      - `String message`

      - `JsonValue; type "rate_limit_error"constant`

        - `RATE_LIMIT_ERROR("rate_limit_error")`

    - `class BetaGatewayTimeoutError:`

      - `String message`

      - `JsonValue; type "timeout_error"constant`

        - `TIMEOUT_ERROR("timeout_error")`

    - `class BetaApiError:`

      - `String message`

      - `JsonValue; type "api_error"constant`

        - `API_ERROR("api_error")`

    - `class BetaOverloadedError:`

      - `String message`

      - `JsonValue; type "overloaded_error"constant`

        - `OVERLOADED_ERROR("overloaded_error")`

  - `Optional<String> requestId`

  - `JsonValue; type "error"constant`

    - `ERROR("error")`

### Beta Gateway Timeout Error

- `class BetaGatewayTimeoutError:`

  - `String message`

  - `JsonValue; type "timeout_error"constant`

    - `TIMEOUT_ERROR("timeout_error")`

### Beta Invalid Request Error

- `class BetaInvalidRequestError:`

  - `String message`

  - `JsonValue; type "invalid_request_error"constant`

    - `INVALID_REQUEST_ERROR("invalid_request_error")`

### Beta Not Found Error

- `class BetaNotFoundError:`

  - `String message`

  - `JsonValue; type "not_found_error"constant`

    - `NOT_FOUND_ERROR("not_found_error")`

### Beta Overloaded Error

- `class BetaOverloadedError:`

  - `String message`

  - `JsonValue; type "overloaded_error"constant`

    - `OVERLOADED_ERROR("overloaded_error")`

### Beta Permission Error

- `class BetaPermissionError:`

  - `String message`

  - `JsonValue; type "permission_error"constant`

    - `PERMISSION_ERROR("permission_error")`

### Beta Rate Limit Error

- `class BetaRateLimitError:`

  - `String message`

  - `JsonValue; type "rate_limit_error"constant`

    - `RATE_LIMIT_ERROR("rate_limit_error")`

# Models

## List Models

`ModelListPage beta().models().list(ModelListParamsparams = ModelListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/models`

List available models.

The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first.

### Parameters

- `ModelListParams params`

  - `Optional<String> afterId`

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

  - `Optional<String> beforeId`

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

  - `Optional<Long> limit`

    Number of items to return per page.

    Defaults to `20`. Ranges from `1` to `1000`.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaModelInfo:`

  - `String id`

    Unique model identifier.

  - `Optional<List<String>> allowedFallbackModels`

    Model IDs this model accepts as `fallbacks[i].model` on the Messages API. An empty list means the `fallbacks` parameter is not supported for this model as primary.

  - `Optional<BetaModelCapabilities> capabilities`

    Model capability information.

    - `BetaCapabilitySupport batch`

      Whether the model supports the Batch API.

      - `boolean supported`

        Whether this capability is supported by the model.

    - `BetaCapabilitySupport citations`

      Whether the model supports citation generation.

    - `BetaCapabilitySupport codeExecution`

      Whether the model supports code execution tools.

    - `BetaContextManagementCapability contextManagement`

      Context management support and available strategies.

      - `Optional<BetaCapabilitySupport> clearThinking20251015`

        Indicates whether a capability is supported.

      - `Optional<BetaCapabilitySupport> clearToolUses20250919`

        Indicates whether a capability is supported.

      - `Optional<BetaCapabilitySupport> compact20260112`

        Indicates whether a capability is supported.

      - `boolean supported`

        Whether this capability is supported by the model.

    - `BetaEffortCapability effort`

      Effort (reasoning_effort) support and available levels.

      - `BetaCapabilitySupport high`

        Whether the model supports high effort level.

      - `BetaCapabilitySupport low`

        Whether the model supports low effort level.

      - `BetaCapabilitySupport max`

        Whether the model supports max effort level.

      - `BetaCapabilitySupport medium`

        Whether the model supports medium effort level.

      - `boolean supported`

        Whether this capability is supported by the model.

      - `Optional<BetaCapabilitySupport> xhigh`

        Indicates whether a capability is supported.

    - `BetaCapabilitySupport imageInput`

      Whether the model accepts image content blocks.

    - `BetaCapabilitySupport pdfInput`

      Whether the model accepts PDF content blocks.

    - `BetaCapabilitySupport structuredOutputs`

      Whether the model supports structured output / JSON mode / strict tool schemas.

    - `BetaThinkingCapability thinking`

      Thinking capability and supported type configurations.

      - `boolean supported`

        Whether this capability is supported by the model.

      - `BetaThinkingTypes types`

        Supported thinking type configurations.

        - `BetaCapabilitySupport adaptive`

          Whether the model supports thinking with type 'adaptive' (auto).

        - `BetaCapabilitySupport enabled`

          Whether the model supports thinking with type 'enabled'.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.

  - `String displayName`

    A human-readable name for the model.

  - `Optional<Long> maxInputTokens`

    Maximum input context window size in tokens for this model.

  - `Optional<Long> maxTokens`

    Maximum value for the `max_tokens` parameter when using this model.

  - `JsonValue; type "model"constant`

    Object type.

    For Models, this is always `"model"`.

    - `MODEL("model")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.models.ModelListPage;
import com.anthropic.models.beta.models.ModelListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        ModelListPage page = client.beta().models().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "claude-opus-4-6",
      "allowed_fallback_models": [
        "string"
      ],
      "capabilities": {
        "batch": {
          "supported": true
        },
        "citations": {
          "supported": true
        },
        "code_execution": {
          "supported": true
        },
        "context_management": {
          "clear_thinking_20251015": {
            "supported": true
          },
          "clear_tool_uses_20250919": {
            "supported": true
          },
          "compact_20260112": {
            "supported": true
          },
          "supported": true
        },
        "effort": {
          "high": {
            "supported": true
          },
          "low": {
            "supported": true
          },
          "max": {
            "supported": true
          },
          "medium": {
            "supported": true
          },
          "supported": true,
          "xhigh": {
            "supported": true
          }
        },
        "image_input": {
          "supported": true
        },
        "pdf_input": {
          "supported": true
        },
        "structured_outputs": {
          "supported": true
        },
        "thinking": {
          "supported": true,
          "types": {
            "adaptive": {
              "supported": true
            },
            "enabled": {
              "supported": true
            }
          }
        }
      },
      "created_at": "2026-02-04T00:00:00Z",
      "display_name": "Claude Opus 4.6",
      "max_input_tokens": 0,
      "max_tokens": 0,
      "type": "model"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id"
}
```

## Get a Model

`BetaModelInfo beta().models().retrieve(ModelRetrieveParamsparams = ModelRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/models/{model_id}`

Get a specific model.

The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID.

### Parameters

- `ModelRetrieveParams params`

  - `Optional<String> modelId`

    Model identifier or alias.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaModelInfo:`

  - `String id`

    Unique model identifier.

  - `Optional<List<String>> allowedFallbackModels`

    Model IDs this model accepts as `fallbacks[i].model` on the Messages API. An empty list means the `fallbacks` parameter is not supported for this model as primary.

  - `Optional<BetaModelCapabilities> capabilities`

    Model capability information.

    - `BetaCapabilitySupport batch`

      Whether the model supports the Batch API.

      - `boolean supported`

        Whether this capability is supported by the model.

    - `BetaCapabilitySupport citations`

      Whether the model supports citation generation.

    - `BetaCapabilitySupport codeExecution`

      Whether the model supports code execution tools.

    - `BetaContextManagementCapability contextManagement`

      Context management support and available strategies.

      - `Optional<BetaCapabilitySupport> clearThinking20251015`

        Indicates whether a capability is supported.

      - `Optional<BetaCapabilitySupport> clearToolUses20250919`

        Indicates whether a capability is supported.

      - `Optional<BetaCapabilitySupport> compact20260112`

        Indicates whether a capability is supported.

      - `boolean supported`

        Whether this capability is supported by the model.

    - `BetaEffortCapability effort`

      Effort (reasoning_effort) support and available levels.

      - `BetaCapabilitySupport high`

        Whether the model supports high effort level.

      - `BetaCapabilitySupport low`

        Whether the model supports low effort level.

      - `BetaCapabilitySupport max`

        Whether the model supports max effort level.

      - `BetaCapabilitySupport medium`

        Whether the model supports medium effort level.

      - `boolean supported`

        Whether this capability is supported by the model.

      - `Optional<BetaCapabilitySupport> xhigh`

        Indicates whether a capability is supported.

    - `BetaCapabilitySupport imageInput`

      Whether the model accepts image content blocks.

    - `BetaCapabilitySupport pdfInput`

      Whether the model accepts PDF content blocks.

    - `BetaCapabilitySupport structuredOutputs`

      Whether the model supports structured output / JSON mode / strict tool schemas.

    - `BetaThinkingCapability thinking`

      Thinking capability and supported type configurations.

      - `boolean supported`

        Whether this capability is supported by the model.

      - `BetaThinkingTypes types`

        Supported thinking type configurations.

        - `BetaCapabilitySupport adaptive`

          Whether the model supports thinking with type 'adaptive' (auto).

        - `BetaCapabilitySupport enabled`

          Whether the model supports thinking with type 'enabled'.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.

  - `String displayName`

    A human-readable name for the model.

  - `Optional<Long> maxInputTokens`

    Maximum input context window size in tokens for this model.

  - `Optional<Long> maxTokens`

    Maximum value for the `max_tokens` parameter when using this model.

  - `JsonValue; type "model"constant`

    Object type.

    For Models, this is always `"model"`.

    - `MODEL("model")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.models.BetaModelInfo;
import com.anthropic.models.beta.models.ModelRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaModelInfo betaModelInfo = client.beta().models().retrieve("model_id");
    }
}
```

#### Response

```json
{
  "id": "claude-opus-4-6",
  "allowed_fallback_models": [
    "string"
  ],
  "capabilities": {
    "batch": {
      "supported": true
    },
    "citations": {
      "supported": true
    },
    "code_execution": {
      "supported": true
    },
    "context_management": {
      "clear_thinking_20251015": {
        "supported": true
      },
      "clear_tool_uses_20250919": {
        "supported": true
      },
      "compact_20260112": {
        "supported": true
      },
      "supported": true
    },
    "effort": {
      "high": {
        "supported": true
      },
      "low": {
        "supported": true
      },
      "max": {
        "supported": true
      },
      "medium": {
        "supported": true
      },
      "supported": true,
      "xhigh": {
        "supported": true
      }
    },
    "image_input": {
      "supported": true
    },
    "pdf_input": {
      "supported": true
    },
    "structured_outputs": {
      "supported": true
    },
    "thinking": {
      "supported": true,
      "types": {
        "adaptive": {
          "supported": true
        },
        "enabled": {
          "supported": true
        }
      }
    }
  },
  "created_at": "2026-02-04T00:00:00Z",
  "display_name": "Claude Opus 4.6",
  "max_input_tokens": 0,
  "max_tokens": 0,
  "type": "model"
}
```

## Domain Types

### Beta Capability Support

- `class BetaCapabilitySupport:`

  Indicates whether a capability is supported.

  - `boolean supported`

    Whether this capability is supported by the model.

### Beta Context Management Capability

- `class BetaContextManagementCapability:`

  Context management capability details.

  - `Optional<BetaCapabilitySupport> clearThinking20251015`

    Indicates whether a capability is supported.

    - `boolean supported`

      Whether this capability is supported by the model.

  - `Optional<BetaCapabilitySupport> clearToolUses20250919`

    Indicates whether a capability is supported.

  - `Optional<BetaCapabilitySupport> compact20260112`

    Indicates whether a capability is supported.

  - `boolean supported`

    Whether this capability is supported by the model.

### Beta Effort Capability

- `class BetaEffortCapability:`

  Effort (reasoning_effort) capability details.

  - `BetaCapabilitySupport high`

    Whether the model supports high effort level.

    - `boolean supported`

      Whether this capability is supported by the model.

  - `BetaCapabilitySupport low`

    Whether the model supports low effort level.

  - `BetaCapabilitySupport max`

    Whether the model supports max effort level.

  - `BetaCapabilitySupport medium`

    Whether the model supports medium effort level.

  - `boolean supported`

    Whether this capability is supported by the model.

  - `Optional<BetaCapabilitySupport> xhigh`

    Indicates whether a capability is supported.

### Beta Model Capabilities

- `class BetaModelCapabilities:`

  Model capability information.

  - `BetaCapabilitySupport batch`

    Whether the model supports the Batch API.

    - `boolean supported`

      Whether this capability is supported by the model.

  - `BetaCapabilitySupport citations`

    Whether the model supports citation generation.

  - `BetaCapabilitySupport codeExecution`

    Whether the model supports code execution tools.

  - `BetaContextManagementCapability contextManagement`

    Context management support and available strategies.

    - `Optional<BetaCapabilitySupport> clearThinking20251015`

      Indicates whether a capability is supported.

    - `Optional<BetaCapabilitySupport> clearToolUses20250919`

      Indicates whether a capability is supported.

    - `Optional<BetaCapabilitySupport> compact20260112`

      Indicates whether a capability is supported.

    - `boolean supported`

      Whether this capability is supported by the model.

  - `BetaEffortCapability effort`

    Effort (reasoning_effort) support and available levels.

    - `BetaCapabilitySupport high`

      Whether the model supports high effort level.

    - `BetaCapabilitySupport low`

      Whether the model supports low effort level.

    - `BetaCapabilitySupport max`

      Whether the model supports max effort level.

    - `BetaCapabilitySupport medium`

      Whether the model supports medium effort level.

    - `boolean supported`

      Whether this capability is supported by the model.

    - `Optional<BetaCapabilitySupport> xhigh`

      Indicates whether a capability is supported.

  - `BetaCapabilitySupport imageInput`

    Whether the model accepts image content blocks.

  - `BetaCapabilitySupport pdfInput`

    Whether the model accepts PDF content blocks.

  - `BetaCapabilitySupport structuredOutputs`

    Whether the model supports structured output / JSON mode / strict tool schemas.

  - `BetaThinkingCapability thinking`

    Thinking capability and supported type configurations.

    - `boolean supported`

      Whether this capability is supported by the model.

    - `BetaThinkingTypes types`

      Supported thinking type configurations.

      - `BetaCapabilitySupport adaptive`

        Whether the model supports thinking with type 'adaptive' (auto).

      - `BetaCapabilitySupport enabled`

        Whether the model supports thinking with type 'enabled'.

### Beta Model Info

- `class BetaModelInfo:`

  - `String id`

    Unique model identifier.

  - `Optional<List<String>> allowedFallbackModels`

    Model IDs this model accepts as `fallbacks[i].model` on the Messages API. An empty list means the `fallbacks` parameter is not supported for this model as primary.

  - `Optional<BetaModelCapabilities> capabilities`

    Model capability information.

    - `BetaCapabilitySupport batch`

      Whether the model supports the Batch API.

      - `boolean supported`

        Whether this capability is supported by the model.

    - `BetaCapabilitySupport citations`

      Whether the model supports citation generation.

    - `BetaCapabilitySupport codeExecution`

      Whether the model supports code execution tools.

    - `BetaContextManagementCapability contextManagement`

      Context management support and available strategies.

      - `Optional<BetaCapabilitySupport> clearThinking20251015`

        Indicates whether a capability is supported.

      - `Optional<BetaCapabilitySupport> clearToolUses20250919`

        Indicates whether a capability is supported.

      - `Optional<BetaCapabilitySupport> compact20260112`

        Indicates whether a capability is supported.

      - `boolean supported`

        Whether this capability is supported by the model.

    - `BetaEffortCapability effort`

      Effort (reasoning_effort) support and available levels.

      - `BetaCapabilitySupport high`

        Whether the model supports high effort level.

      - `BetaCapabilitySupport low`

        Whether the model supports low effort level.

      - `BetaCapabilitySupport max`

        Whether the model supports max effort level.

      - `BetaCapabilitySupport medium`

        Whether the model supports medium effort level.

      - `boolean supported`

        Whether this capability is supported by the model.

      - `Optional<BetaCapabilitySupport> xhigh`

        Indicates whether a capability is supported.

    - `BetaCapabilitySupport imageInput`

      Whether the model accepts image content blocks.

    - `BetaCapabilitySupport pdfInput`

      Whether the model accepts PDF content blocks.

    - `BetaCapabilitySupport structuredOutputs`

      Whether the model supports structured output / JSON mode / strict tool schemas.

    - `BetaThinkingCapability thinking`

      Thinking capability and supported type configurations.

      - `boolean supported`

        Whether this capability is supported by the model.

      - `BetaThinkingTypes types`

        Supported thinking type configurations.

        - `BetaCapabilitySupport adaptive`

          Whether the model supports thinking with type 'adaptive' (auto).

        - `BetaCapabilitySupport enabled`

          Whether the model supports thinking with type 'enabled'.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.

  - `String displayName`

    A human-readable name for the model.

  - `Optional<Long> maxInputTokens`

    Maximum input context window size in tokens for this model.

  - `Optional<Long> maxTokens`

    Maximum value for the `max_tokens` parameter when using this model.

  - `JsonValue; type "model"constant`

    Object type.

    For Models, this is always `"model"`.

    - `MODEL("model")`

### Beta Thinking Capability

- `class BetaThinkingCapability:`

  Thinking capability details.

  - `boolean supported`

    Whether this capability is supported by the model.

  - `BetaThinkingTypes types`

    Supported thinking type configurations.

    - `BetaCapabilitySupport adaptive`

      Whether the model supports thinking with type 'adaptive' (auto).

      - `boolean supported`

        Whether this capability is supported by the model.

    - `BetaCapabilitySupport enabled`

      Whether the model supports thinking with type 'enabled'.

### Beta Thinking Types

- `class BetaThinkingTypes:`

  Supported thinking type configurations.

  - `BetaCapabilitySupport adaptive`

    Whether the model supports thinking with type 'adaptive' (auto).

    - `boolean supported`

      Whether this capability is supported by the model.

  - `BetaCapabilitySupport enabled`

    Whether the model supports thinking with type 'enabled'.

# Messages

## Create a Message

`BetaMessage beta().messages().create(MessageCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/messages`

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

The Messages API can be used for either single queries or stateless multi-turn conversations.

Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup)

### Parameters

- `MessageCreateParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `long maxTokens`

    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](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.

    Different models have different maximum values for this parameter.  See [models](https://docs.claude.com/en/docs/models-overview) for details.

  - `List<BetaMessageParam> messages`

    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, Claude"}]
    ```

    Example with multiple conversational turns:

    ```json
    [
      {"role": "user", "content": "Hello there."},
      {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
      {"role": "user", "content": "Can you explain LLMs in plain English?"},
    ]
    ```

    Example with a partially-filled response from Claude:

    ```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, Claude"}
    ```

    ```json
    {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
    ```

    See [input examples](https://docs.claude.com/en/api/messages-examples).

    Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), 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.

    - `Content content`

      - `String`

      - `List<BetaContentBlockParam>`

        - `class BetaTextBlockParam:`

          - `String text`

          - `JsonValue; type "text"constant`

            - `TEXT("text")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

            - `JsonValue; type "ephemeral"constant`

              - `EPHEMERAL("ephemeral")`

            - `Optional<Ttl> ttl`

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

              - `TTL_5M("5m")`

              - `TTL_1H("1h")`

          - `Optional<List<BetaTextCitationParam>> citations`

            - `class BetaCitationCharLocationParam:`

              - `String citedText`

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endCharIndex`

              - `long startCharIndex`

              - `JsonValue; type "char_location"constant`

                - `CHAR_LOCATION("char_location")`

            - `class BetaCitationPageLocationParam:`

              - `String citedText`

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endPageNumber`

              - `long startPageNumber`

              - `JsonValue; type "page_location"constant`

                - `PAGE_LOCATION("page_location")`

            - `class BetaCitationContentBlockLocationParam:`

              - `String citedText`

                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.

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endBlockIndex`

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

              - `long startBlockIndex`

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

              - `JsonValue; type "content_block_location"constant`

                - `CONTENT_BLOCK_LOCATION("content_block_location")`

            - `class BetaCitationWebSearchResultLocationParam:`

              - `String citedText`

              - `String encryptedIndex`

              - `Optional<String> title`

              - `JsonValue; type "web_search_result_location"constant`

                - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

              - `String url`

            - `class BetaCitationSearchResultLocationParam:`

              - `String citedText`

                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.

              - `long endBlockIndex`

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

              - `long searchResultIndex`

                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.

              - `String source`

              - `long startBlockIndex`

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

              - `Optional<String> title`

              - `JsonValue; type "search_result_location"constant`

                - `SEARCH_RESULT_LOCATION("search_result_location")`

        - `class BetaImageBlockParam:`

          - `Source source`

            - `class BetaBase64ImageSource:`

              - `String data`

              - `MediaType mediaType`

                - `IMAGE_JPEG("image/jpeg")`

                - `IMAGE_PNG("image/png")`

                - `IMAGE_GIF("image/gif")`

                - `IMAGE_WEBP("image/webp")`

              - `JsonValue; type "base64"constant`

                - `BASE64("base64")`

            - `class BetaUrlImageSource:`

              - `JsonValue; type "url"constant`

                - `URL("url")`

              - `String url`

            - `class BetaFileImageSource:`

              - `String fileId`

              - `JsonValue; type "file"constant`

                - `FILE("file")`

          - `JsonValue; type "image"constant`

            - `IMAGE("image")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaRequestDocumentBlock:`

          - `Source source`

            - `class BetaBase64PdfSource:`

              - `String data`

              - `JsonValue; mediaType "application/pdf"constant`

                - `APPLICATION_PDF("application/pdf")`

              - `JsonValue; type "base64"constant`

                - `BASE64("base64")`

            - `class BetaPlainTextSource:`

              - `String data`

              - `JsonValue; mediaType "text/plain"constant`

                - `TEXT_PLAIN("text/plain")`

              - `JsonValue; type "text"constant`

                - `TEXT("text")`

            - `class BetaContentBlockSource:`

              - `Content content`

                - `String`

                - `List<BetaContentBlockSourceContent>`

                  - `class BetaTextBlockParam:`

                  - `class BetaImageBlockParam:`

              - `JsonValue; type "content"constant`

                - `CONTENT("content")`

            - `class BetaUrlPdfSource:`

              - `JsonValue; type "url"constant`

                - `URL("url")`

              - `String url`

            - `class BetaFileDocumentSource:`

              - `String fileId`

              - `JsonValue; type "file"constant`

                - `FILE("file")`

          - `JsonValue; type "document"constant`

            - `DOCUMENT("document")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<BetaCitationsConfigParam> citations`

            - `Optional<Boolean> enabled`

          - `Optional<String> context`

          - `Optional<String> title`

        - `class BetaSearchResultBlockParam:`

          - `List<BetaTextBlockParam> content`

            - `String text`

            - `JsonValue; type "text"constant`

            - `Optional<BetaCacheControlEphemeral> cacheControl`

              Create a cache control breakpoint at this content block.

            - `Optional<List<BetaTextCitationParam>> citations`

          - `String source`

          - `String title`

          - `JsonValue; type "search_result"constant`

            - `SEARCH_RESULT("search_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<BetaCitationsConfigParam> citations`

        - `class BetaThinkingBlockParam:`

          - `String signature`

          - `String thinking`

          - `JsonValue; type "thinking"constant`

            - `THINKING("thinking")`

        - `class BetaRedactedThinkingBlockParam:`

          - `String data`

          - `JsonValue; type "redacted_thinking"constant`

            - `REDACTED_THINKING("redacted_thinking")`

        - `class BetaToolUseBlockParam:`

          - `String id`

          - `Input input`

          - `String name`

          - `JsonValue; type "tool_use"constant`

            - `TOOL_USE("tool_use")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

              - `JsonValue; type "direct"constant`

                - `DIRECT("direct")`

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

              - `String toolId`

              - `JsonValue; type "code_execution_20250825"constant`

                - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `class BetaServerToolCaller20260120:`

              - `String toolId`

              - `JsonValue; type "code_execution_20260120"constant`

                - `CODE_EXECUTION_20260120("code_execution_20260120")`

        - `class BetaToolResultBlockParam:`

          - `String toolUseId`

          - `JsonValue; type "tool_result"constant`

            - `TOOL_RESULT("tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Content> content`

            - `String`

            - `List<Block>`

              - `class BetaTextBlockParam:`

              - `class BetaImageBlockParam:`

              - `class BetaSearchResultBlockParam:`

              - `class BetaRequestDocumentBlock:`

              - `class BetaToolReferenceBlockParam:`

                Tool reference block that can be included in tool_result content.

                - `String toolName`

                - `JsonValue; type "tool_reference"constant`

                  - `TOOL_REFERENCE("tool_reference")`

                - `Optional<BetaCacheControlEphemeral> cacheControl`

                  Create a cache control breakpoint at this content block.

          - `Optional<Boolean> isError`

        - `class BetaServerToolUseBlockParam:`

          - `String id`

          - `Input input`

          - `Name name`

            - `ADVISOR("advisor")`

            - `WEB_SEARCH("web_search")`

            - `WEB_FETCH("web_fetch")`

            - `CODE_EXECUTION("code_execution")`

            - `BASH_CODE_EXECUTION("bash_code_execution")`

            - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

            - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

            - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

          - `JsonValue; type "server_tool_use"constant`

            - `SERVER_TOOL_USE("server_tool_use")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaWebSearchToolResultBlockParam:`

          - `BetaWebSearchToolResultBlockParamContent content`

            - `List<BetaWebSearchResultBlockParam>`

              - `String encryptedContent`

              - `String title`

              - `JsonValue; type "web_search_result"constant`

                - `WEB_SEARCH_RESULT("web_search_result")`

              - `String url`

              - `Optional<String> pageAge`

            - `class BetaWebSearchToolRequestError:`

              - `BetaWebSearchToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `QUERY_TOO_LONG("query_too_long")`

                - `REQUEST_TOO_LARGE("request_too_large")`

              - `JsonValue; type "web_search_tool_result_error"constant`

                - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

          - `String toolUseId`

          - `JsonValue; type "web_search_tool_result"constant`

            - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaWebFetchToolResultBlockParam:`

          - `Content content`

            - `class BetaWebFetchToolResultErrorBlockParam:`

              - `BetaWebFetchToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `URL_TOO_LONG("url_too_long")`

                - `URL_NOT_ALLOWED("url_not_allowed")`

                - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

                - `URL_NOT_ACCESSIBLE("url_not_accessible")`

                - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `UNAVAILABLE("unavailable")`

              - `JsonValue; type "web_fetch_tool_result_error"constant`

                - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

            - `class BetaWebFetchBlockParam:`

              - `BetaRequestDocumentBlock content`

              - `JsonValue; type "web_fetch_result"constant`

                - `WEB_FETCH_RESULT("web_fetch_result")`

              - `String url`

                Fetched content URL

              - `Optional<String> retrievedAt`

                ISO 8601 timestamp when the content was retrieved

          - `String toolUseId`

          - `JsonValue; type "web_fetch_tool_result"constant`

            - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaAdvisorToolResultBlockParam:`

          - `Content content`

            - `class BetaAdvisorToolResultErrorParam:`

              - `ErrorCode errorCode`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `PROMPT_TOO_LONG("prompt_too_long")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `OVERLOADED("overloaded")`

                - `UNAVAILABLE("unavailable")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `MODEL_NOT_FOUND("model_not_found")`

              - `JsonValue; type "advisor_tool_result_error"constant`

                - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

            - `class BetaAdvisorResultBlockParam:`

              - `String text`

              - `JsonValue; type "advisor_result"constant`

                - `ADVISOR_RESULT("advisor_result")`

              - `Optional<String> stopReason`

            - `class BetaAdvisorRedactedResultBlockParam:`

              - `String encryptedContent`

                Opaque blob produced by a prior response; must be round-tripped verbatim.

              - `JsonValue; type "advisor_redacted_result"constant`

                - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

              - `Optional<String> stopReason`

          - `String toolUseId`

          - `JsonValue; type "advisor_tool_result"constant`

            - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaCodeExecutionToolResultBlockParam:`

          - `BetaCodeExecutionToolResultBlockParamContent content`

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

            - `class BetaCodeExecutionToolResultErrorParam:`

              - `BetaCodeExecutionToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `JsonValue; type "code_execution_tool_result_error"constant`

                - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

            - `class BetaCodeExecutionResultBlockParam:`

              - `List<BetaCodeExecutionOutputBlockParam> content`

                - `String fileId`

                - `JsonValue; type "code_execution_output"constant`

                  - `CODE_EXECUTION_OUTPUT("code_execution_output")`

              - `long returnCode`

              - `String stderr`

              - `String stdout`

              - `JsonValue; type "code_execution_result"constant`

                - `CODE_EXECUTION_RESULT("code_execution_result")`

            - `class BetaEncryptedCodeExecutionResultBlockParam:`

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

              - `List<BetaCodeExecutionOutputBlockParam> content`

                - `String fileId`

                - `JsonValue; type "code_execution_output"constant`

              - `String encryptedStdout`

              - `long returnCode`

              - `String stderr`

              - `JsonValue; type "encrypted_code_execution_result"constant`

                - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

          - `String toolUseId`

          - `JsonValue; type "code_execution_tool_result"constant`

            - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaBashCodeExecutionToolResultBlockParam:`

          - `Content content`

            - `class BetaBashCodeExecutionToolResultErrorParam:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

              - `JsonValue; type "bash_code_execution_tool_result_error"constant`

                - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

            - `class BetaBashCodeExecutionResultBlockParam:`

              - `List<BetaBashCodeExecutionOutputBlockParam> content`

                - `String fileId`

                - `JsonValue; type "bash_code_execution_output"constant`

                  - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

              - `long returnCode`

              - `String stderr`

              - `String stdout`

              - `JsonValue; type "bash_code_execution_result"constant`

                - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

          - `String toolUseId`

          - `JsonValue; type "bash_code_execution_tool_result"constant`

            - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaTextEditorCodeExecutionToolResultBlockParam:`

          - `Content content`

            - `class BetaTextEditorCodeExecutionToolResultErrorParam:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `FILE_NOT_FOUND("file_not_found")`

              - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

              - `Optional<String> errorMessage`

            - `class BetaTextEditorCodeExecutionViewResultBlockParam:`

              - `String content`

              - `FileType fileType`

                - `TEXT("text")`

                - `IMAGE("image")`

                - `PDF("pdf")`

              - `JsonValue; type "text_editor_code_execution_view_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

              - `Optional<Long> numLines`

              - `Optional<Long> startLine`

              - `Optional<Long> totalLines`

            - `class BetaTextEditorCodeExecutionCreateResultBlockParam:`

              - `boolean isFileUpdate`

              - `JsonValue; type "text_editor_code_execution_create_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

            - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:`

              - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

              - `Optional<List<String>> lines`

              - `Optional<Long> newLines`

              - `Optional<Long> newStart`

              - `Optional<Long> oldLines`

              - `Optional<Long> oldStart`

          - `String toolUseId`

          - `JsonValue; type "text_editor_code_execution_tool_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaToolSearchToolResultBlockParam:`

          - `Content content`

            - `class BetaToolSearchToolResultErrorParam:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `JsonValue; type "tool_search_tool_result_error"constant`

                - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

              - `Optional<String> errorMessage`

            - `class BetaToolSearchToolSearchResultBlockParam:`

              - `List<BetaToolReferenceBlockParam> toolReferences`

                - `String toolName`

                - `JsonValue; type "tool_reference"constant`

                - `Optional<BetaCacheControlEphemeral> cacheControl`

                  Create a cache control breakpoint at this content block.

              - `JsonValue; type "tool_search_tool_search_result"constant`

                - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

          - `String toolUseId`

          - `JsonValue; type "tool_search_tool_result"constant`

            - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaMcpToolUseBlockParam:`

          - `String id`

          - `Input input`

          - `String name`

          - `String serverName`

            The name of the MCP server

          - `JsonValue; type "mcp_tool_use"constant`

            - `MCP_TOOL_USE("mcp_tool_use")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaRequestMcpToolResultBlockParam:`

          - `String toolUseId`

          - `JsonValue; type "mcp_tool_result"constant`

            - `MCP_TOOL_RESULT("mcp_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Content> content`

            - `String`

            - `List<BetaTextBlockParam>`

              - `String text`

              - `JsonValue; type "text"constant`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<List<BetaTextCitationParam>> citations`

          - `Optional<Boolean> isError`

        - `class BetaContainerUploadBlockParam:`

          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.

          - `String fileId`

          - `JsonValue; type "container_upload"constant`

            - `CONTAINER_UPLOAD("container_upload")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaCompactionBlockParam:`

          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.

          - `JsonValue; type "compaction"constant`

            - `COMPACTION("compaction")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<String> content`

            Summary of previously compacted content, or null if compaction failed

          - `Optional<String> encryptedContent`

            Opaque metadata from prior compaction, to be round-tripped verbatim

        - `class BetaMidConversationSystemBlockParam:`

          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.

          - `List<BetaTextBlockParam> content`

            System instruction text blocks.

            - `String text`

            - `JsonValue; type "text"constant`

            - `Optional<BetaCacheControlEphemeral> cacheControl`

              Create a cache control breakpoint at this content block.

            - `Optional<List<BetaTextCitationParam>> citations`

          - `JsonValue; type "mid_conv_system"constant`

            - `MID_CONV_SYSTEM("mid_conv_system")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaFallbackBlockParam:`

          A `fallback` block echoed back from a prior response.

          Accepted in `messages[].content` and never rendered into the prompt,
          not validated against the request's `fallbacks` chain or top-level
          `model`, and stripped before the sticky-routing cache key is computed.

          Callers should echo the assistant turn verbatim — block included. The
          block's position is load-bearing for thinking verification: the thinking
          runs on either side of a fallback hop carry independently-rooted
          verification hash chains, and this block is the only record of where one
          chain ends and the next begins. When thinking runs flank the boundary,
          omitting the block merges the runs into one contiguous span whose hashes
          cannot verify (the request is rejected), and moving it into the middle of
          a single run splits that run's chain and is likewise rejected; between
          non-thinking blocks the block's placement has no verification effect.

          - `BetaFallbackInfoParam from`

            Identifies one hop of a fallback transition.

            - `Model model`

              The model that will complete your prompt.

              See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

              - `CLAUDE_FABLE_5("claude-fable-5")`

                Next generation of intelligence for the hardest knowledge work and coding problems

              - `CLAUDE_MYTHOS_5("claude-mythos-5")`

                Most capable model for cybersecurity and biology research

              - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

                New class of intelligence, strongest in coding and cybersecurity

              - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

                Best combination of speed and intelligence

              - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

                Fastest model with near-frontier intelligence

              - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

                Fastest model with near-frontier intelligence

              - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

                Premium model combining maximum intelligence with practical performance

              - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

                Premium model combining maximum intelligence with practical performance

              - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

                High-performance model for agents and coding

              - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

                High-performance model for agents and coding

              - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

                Exceptional model for specialized complex tasks

              - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

                Exceptional model for specialized complex tasks

              - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

                Powerful model for complex tasks

              - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

                Powerful model for complex tasks

              - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

                High-performance model with extended thinking

              - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

                High-performance model with extended thinking

              - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

                Fast and cost-effective model

          - `BetaFallbackInfoParam to`

            Identifies one hop of a fallback transition.

          - `JsonValue; type "fallback"constant`

            - `FALLBACK("fallback")`

    - `Role role`

      - `USER("user")`

      - `ASSISTANT("assistant")`

      - `SYSTEM("system")`

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

  - `Optional<Container> container`

    Container identifier for reuse across requests.

    - `class BetaContainerParams:`

      Container parameters with skills to be loaded.

      - `Optional<String> id`

        Container id

      - `Optional<List<BetaSkillParams>> skills`

        List of skills to load in the container

        - `String skillId`

          Skill ID

        - `Type type`

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

          - `ANTHROPIC("anthropic")`

          - `CUSTOM("custom")`

        - `Optional<String> version`

          Skill version or 'latest' for most recent version

    - `String`

  - `Optional<BetaContextManagementConfig> contextManagement`

    Context management configuration.

    This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not.

  - `Optional<BetaDiagnosticsParam> diagnostics`

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

  - `Optional<String> fallbackCreditToken`

    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.

  - `Optional<List<BetaFallbackParam>> fallbacks`

    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.

    - `Model model`

      The model that will complete your prompt.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `Optional<Long> maxTokens`

    - `Optional<BetaOutputConfig> outputConfig`

      - `Optional<Effort> effort`

        All possible effort levels.

        - `LOW("low")`

        - `MEDIUM("medium")`

        - `HIGH("high")`

        - `XHIGH("xhigh")`

        - `MAX("max")`

      - `Optional<BetaJsonOutputFormat> format`

        A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

        - `Schema schema`

          The JSON schema of the format

        - `JsonValue; type "json_schema"constant`

          - `JSON_SCHEMA("json_schema")`

      - `Optional<BetaTokenTaskBudget> taskBudget`

        User-configurable total token budget across contexts.

        - `long total`

          Total token budget across all contexts in the session.

        - `JsonValue; type "tokens"constant`

          The budget type. Currently only 'tokens' is supported.

          - `TOKENS("tokens")`

        - `Optional<Long> remaining`

          Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.

    - `Optional<Speed> speed`

      - `STANDARD("standard")`

      - `FAST("fast")`

    - `Optional<Thinking> thinking`

      - `class BetaThinkingConfigEnabled:`

        - `long budgetTokens`

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

          Must be ≥1024 and less than `max_tokens`.

          See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.

        - `JsonValue; type "enabled"constant`

          - `ENABLED("enabled")`

        - `Optional<Display> display`

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

          - `SUMMARIZED("summarized")`

          - `OMITTED("omitted")`

      - `class BetaThinkingConfigDisabled:`

        - `JsonValue; type "disabled"constant`

          - `DISABLED("disabled")`

      - `class BetaThinkingConfigAdaptive:`

        - `JsonValue; type "adaptive"constant`

          - `ADAPTIVE("adaptive")`

        - `Optional<Display> display`

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

          - `SUMMARIZED("summarized")`

          - `OMITTED("omitted")`

  - `Optional<String> inferenceGeo`

    Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.

  - `Optional<List<BetaRequestMcpServerUrlDefinition>> mcpServers`

    MCP servers to be utilized in this request

    - `String name`

    - `JsonValue; type "url"constant`

      - `URL("url")`

    - `String url`

    - `Optional<String> authorizationToken`

    - `Optional<BetaRequestMcpServerToolConfiguration> toolConfiguration`

      - `Optional<List<String>> allowedTools`

      - `Optional<Boolean> enabled`

  - `Optional<BetaMetadata> metadata`

    An object describing metadata about the request.

  - `Optional<BetaOutputConfig> outputConfig`

    Configuration options for the model's output, such as the output format.

  - `Optional<BetaJsonOutputFormat> outputFormat`

    Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

    A schema to specify Claude's output format in responses. This parameter will be removed in a future release.

  - `Optional<ServiceTier> serviceTier`

    Determines whether to use priority capacity (if available) or standard capacity for this request.

    Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details.

    - `AUTO("auto")`

    - `STANDARD_ONLY("standard_only")`

  - `Optional<Speed> speed`

    The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference.

    - `STANDARD("standard")`

    - `FAST("fast")`

  - `Optional<List<String>> stopSequences`

    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.

  - `Optional<System> system`

    System prompt.

    A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts).

    - `String`

    - `List<BetaTextBlockParam>`

      - `String text`

      - `JsonValue; type "text"constant`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<List<BetaTextCitationParam>> citations`

  - `Optional<Double> temperature`

    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.

  - `Optional<BetaThinkingConfigParam> thinking`

    Configuration for enabling Claude's extended thinking.

    When enabled, responses include `thinking` content blocks showing Claude'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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.

  - `Optional<BetaToolChoice> toolChoice`

    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.

  - `Optional<List<BetaToolUnion>> tools`

    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](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/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](https://docs.claude.com/en/docs/tool-use) for more details.

    - `class BetaTool:`

      - `InputSchema inputSchema`

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

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<String> 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.

      - `Optional<Boolean> eagerInputStreaming`

        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.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

      - `Optional<Type> type`

        - `CUSTOM("custom")`

    - `class BetaToolBash20241022:`

      - `JsonValue; name "bash"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `BASH("bash")`

      - `JsonValue; type "bash_20241022"constant`

        - `BASH_20241022("bash_20241022")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolBash20250124:`

      - `JsonValue; name "bash"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `BASH("bash")`

      - `JsonValue; type "bash_20250124"constant`

        - `BASH_20250124("bash_20250124")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaCodeExecutionTool20250522:`

      - `JsonValue; name "code_execution"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `CODE_EXECUTION("code_execution")`

      - `JsonValue; type "code_execution_20250522"constant`

        - `CODE_EXECUTION_20250522("code_execution_20250522")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaCodeExecutionTool20250825:`

      - `JsonValue; name "code_execution"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `CODE_EXECUTION("code_execution")`

      - `JsonValue; type "code_execution_20250825"constant`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaCodeExecutionTool20260120:`

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

      - `JsonValue; name "code_execution"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `CODE_EXECUTION("code_execution")`

      - `JsonValue; type "code_execution_20260120"constant`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolComputerUse20241022:`

      - `long displayHeightPx`

        The height of the display in pixels.

      - `long displayWidthPx`

        The width of the display in pixels.

      - `JsonValue; name "computer"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `COMPUTER("computer")`

      - `JsonValue; type "computer_20241022"constant`

        - `COMPUTER_20241022("computer_20241022")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> displayNumber`

        The X11 display number (e.g. 0, 1) for the display.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaMemoryTool20250818:`

      - `JsonValue; name "memory"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `MEMORY("memory")`

      - `JsonValue; type "memory_20250818"constant`

        - `MEMORY_20250818("memory_20250818")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolComputerUse20250124:`

      - `long displayHeightPx`

        The height of the display in pixels.

      - `long displayWidthPx`

        The width of the display in pixels.

      - `JsonValue; name "computer"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `COMPUTER("computer")`

      - `JsonValue; type "computer_20250124"constant`

        - `COMPUTER_20250124("computer_20250124")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> displayNumber`

        The X11 display number (e.g. 0, 1) for the display.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolTextEditor20241022:`

      - `JsonValue; name "str_replace_editor"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `STR_REPLACE_EDITOR("str_replace_editor")`

      - `JsonValue; type "text_editor_20241022"constant`

        - `TEXT_EDITOR_20241022("text_editor_20241022")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolComputerUse20251124:`

      - `long displayHeightPx`

        The height of the display in pixels.

      - `long displayWidthPx`

        The width of the display in pixels.

      - `JsonValue; name "computer"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `COMPUTER("computer")`

      - `JsonValue; type "computer_20251124"constant`

        - `COMPUTER_20251124("computer_20251124")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> displayNumber`

        The X11 display number (e.g. 0, 1) for the display.

      - `Optional<Boolean> enableZoom`

        Whether to enable an action to take a zoomed-in screenshot of the screen.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolTextEditor20250124:`

      - `JsonValue; name "str_replace_editor"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `STR_REPLACE_EDITOR("str_replace_editor")`

      - `JsonValue; type "text_editor_20250124"constant`

        - `TEXT_EDITOR_20250124("text_editor_20250124")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolTextEditor20250429:`

      - `JsonValue; name "str_replace_based_edit_tool"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")`

      - `JsonValue; type "text_editor_20250429"constant`

        - `TEXT_EDITOR_20250429("text_editor_20250429")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolTextEditor20250728:`

      - `JsonValue; name "str_replace_based_edit_tool"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")`

      - `JsonValue; type "text_editor_20250728"constant`

        - `TEXT_EDITOR_20250728("text_editor_20250728")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Long> maxCharacters`

        Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaWebSearchTool20250305:`

      - `JsonValue; name "web_search"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `WEB_SEARCH("web_search")`

      - `JsonValue; type "web_search_20250305"constant`

        - `WEB_SEARCH_20250305("web_search_20250305")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<String>> allowedDomains`

        If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.

      - `Optional<List<String>> blockedDomains`

        If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

      - `Optional<BetaUserLocation> userLocation`

        Parameters for the user's location. Used to provide more relevant search results.

        - `JsonValue; type "approximate"constant`

          - `APPROXIMATE("approximate")`

        - `Optional<String> city`

          The city of the user.

        - `Optional<String> country`

          The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.

        - `Optional<String> region`

          The region of the user.

        - `Optional<String> timezone`

          The [IANA timezone](https://nodatime.org/TimeZones) of the user.

    - `class BetaWebFetchTool20250910:`

      - `JsonValue; name "web_fetch"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `WEB_FETCH("web_fetch")`

      - `JsonValue; type "web_fetch_20250910"constant`

        - `WEB_FETCH_20250910("web_fetch_20250910")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<String>> allowedDomains`

        List of domains to allow fetching from

      - `Optional<List<String>> blockedDomains`

        List of domains to block fetching from

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<BetaCitationsConfigParam> citations`

        Citations configuration for fetched documents. Citations are disabled by default.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxContentTokens`

        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.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaWebSearchTool20260209:`

      - `JsonValue; name "web_search"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `WEB_SEARCH("web_search")`

      - `JsonValue; type "web_search_20260209"constant`

        - `WEB_SEARCH_20260209("web_search_20260209")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<String>> allowedDomains`

        If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.

      - `Optional<List<String>> blockedDomains`

        If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

      - `Optional<BetaUserLocation> userLocation`

        Parameters for the user's location. Used to provide more relevant search results.

    - `class BetaWebFetchTool20260209:`

      - `JsonValue; name "web_fetch"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `WEB_FETCH("web_fetch")`

      - `JsonValue; type "web_fetch_20260209"constant`

        - `WEB_FETCH_20260209("web_fetch_20260209")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<String>> allowedDomains`

        List of domains to allow fetching from

      - `Optional<List<String>> blockedDomains`

        List of domains to block fetching from

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<BetaCitationsConfigParam> citations`

        Citations configuration for fetched documents. Citations are disabled by default.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxContentTokens`

        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.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaWebFetchTool20260309:`

      Web fetch tool with use_cache parameter for bypassing cached content.

      - `JsonValue; name "web_fetch"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `WEB_FETCH("web_fetch")`

      - `JsonValue; type "web_fetch_20260309"constant`

        - `WEB_FETCH_20260309("web_fetch_20260309")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<String>> allowedDomains`

        List of domains to allow fetching from

      - `Optional<List<String>> blockedDomains`

        List of domains to block fetching from

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<BetaCitationsConfigParam> citations`

        Citations configuration for fetched documents. Citations are disabled by default.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxContentTokens`

        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.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

      - `Optional<Boolean> useCache`

        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.

    - `class BetaAdvisorTool20260301:`

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `JsonValue; name "advisor"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `ADVISOR("advisor")`

      - `JsonValue; type "advisor_20260301"constant`

        - `ADVISOR_20260301("advisor_20260301")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<BetaCacheControlEphemeral> caching`

        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.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxTokens`

        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.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolSearchToolBm25_20251119:`

      - `JsonValue; name "tool_search_tool_bm25"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

      - `Type type`

        - `TOOL_SEARCH_TOOL_BM25_20251119("tool_search_tool_bm25_20251119")`

        - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolSearchToolRegex20251119:`

      - `JsonValue; name "tool_search_tool_regex"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

      - `Type type`

        - `TOOL_SEARCH_TOOL_REGEX_20251119("tool_search_tool_regex_20251119")`

        - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaMcpToolset:`

      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.

      - `String mcpServerName`

        Name of the MCP server to configure tools for

      - `JsonValue; type "mcp_toolset"constant`

        - `MCP_TOOLSET("mcp_toolset")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Configs> configs`

        Configuration overrides for specific tools, keyed by tool name

        - `Optional<Boolean> deferLoading`

        - `Optional<Boolean> enabled`

      - `Optional<BetaMcpToolDefaultConfig> defaultConfig`

        Default configuration applied to all tools from this server

        - `Optional<Boolean> deferLoading`

        - `Optional<Boolean> enabled`

  - `Optional<Long> topK`

    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.

  - `Optional<Double> topP`

    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.

  - `Optional<String> userProfileId`

    The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization.

### Returns

- `class BetaMessage:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `Optional<BetaContainer> container`

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

    - `String id`

      Identifier for the container used in this request

    - `LocalDateTime expiresAt`

      The time at which the container will expire.

    - `Optional<List<BetaSkill>> skills`

      Skills loaded in the container

      - `String skillId`

        Skill ID

      - `Type type`

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

        - `ANTHROPIC("anthropic")`

        - `CUSTOM("custom")`

      - `String version`

        Skill version or 'latest' for most recent version

  - `List<BetaContentBlock> content`

    Content generated by the model.

    This is an array of content blocks, each of which has a `type` that determines its shape.

    Example:

    ```json
    [{"type": "text", "text": "Hi, I'm Claude."}]
    ```

    If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.

    For example, if the input `messages` were:

    ```json
    [
      {"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)"}]
    ```

    - `class BetaTextBlock:`

      - `Optional<List<BetaTextCitation>> citations`

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

        - `class BetaCitationCharLocation:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endCharIndex`

          - `Optional<String> fileId`

          - `long startCharIndex`

          - `JsonValue; type "char_location"constant`

            - `CHAR_LOCATION("char_location")`

        - `class BetaCitationPageLocation:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endPageNumber`

          - `Optional<String> fileId`

          - `long startPageNumber`

          - `JsonValue; type "page_location"constant`

            - `PAGE_LOCATION("page_location")`

        - `class BetaCitationContentBlockLocation:`

          - `String citedText`

            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.

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endBlockIndex`

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

          - `Optional<String> fileId`

          - `long startBlockIndex`

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

          - `JsonValue; type "content_block_location"constant`

            - `CONTENT_BLOCK_LOCATION("content_block_location")`

        - `class BetaCitationsWebSearchResultLocation:`

          - `String citedText`

          - `String encryptedIndex`

          - `Optional<String> title`

          - `JsonValue; type "web_search_result_location"constant`

            - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

          - `String url`

        - `class BetaCitationSearchResultLocation:`

          - `String citedText`

            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.

          - `long endBlockIndex`

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

          - `long searchResultIndex`

            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.

          - `String source`

          - `long startBlockIndex`

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

          - `Optional<String> title`

          - `JsonValue; type "search_result_location"constant`

            - `SEARCH_RESULT_LOCATION("search_result_location")`

      - `String text`

      - `JsonValue; type "text"constant`

        - `TEXT("text")`

    - `class BetaThinkingBlock:`

      - `String signature`

      - `String thinking`

      - `JsonValue; type "thinking"constant`

        - `THINKING("thinking")`

    - `class BetaRedactedThinkingBlock:`

      - `String data`

      - `JsonValue; type "redacted_thinking"constant`

        - `REDACTED_THINKING("redacted_thinking")`

    - `class BetaToolUseBlock:`

      - `String id`

      - `Input input`

      - `String name`

      - `JsonValue; type "tool_use"constant`

        - `TOOL_USE("tool_use")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

          - `JsonValue; type "direct"constant`

            - `DIRECT("direct")`

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

          - `String toolId`

          - `JsonValue; type "code_execution_20250825"constant`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `class BetaServerToolCaller20260120:`

          - `String toolId`

          - `JsonValue; type "code_execution_20260120"constant`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `class BetaServerToolUseBlock:`

      - `String id`

      - `Input input`

      - `Name name`

        - `ADVISOR("advisor")`

        - `WEB_SEARCH("web_search")`

        - `WEB_FETCH("web_fetch")`

        - `CODE_EXECUTION("code_execution")`

        - `BASH_CODE_EXECUTION("bash_code_execution")`

        - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

        - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

        - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

      - `JsonValue; type "server_tool_use"constant`

        - `SERVER_TOOL_USE("server_tool_use")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

        - `class BetaServerToolCaller20260120:`

    - `class BetaWebSearchToolResultBlock:`

      - `BetaWebSearchToolResultBlockContent content`

        - `class BetaWebSearchToolResultError:`

          - `BetaWebSearchToolResultErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `MAX_USES_EXCEEDED("max_uses_exceeded")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `QUERY_TOO_LONG("query_too_long")`

            - `REQUEST_TOO_LARGE("request_too_large")`

          - `JsonValue; type "web_search_tool_result_error"constant`

            - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

        - `List<BetaWebSearchResultBlock>`

          - `String encryptedContent`

          - `Optional<String> pageAge`

          - `String title`

          - `JsonValue; type "web_search_result"constant`

            - `WEB_SEARCH_RESULT("web_search_result")`

          - `String url`

      - `String toolUseId`

      - `JsonValue; type "web_search_tool_result"constant`

        - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

        - `class BetaServerToolCaller20260120:`

    - `class BetaWebFetchToolResultBlock:`

      - `Content content`

        - `class BetaWebFetchToolResultErrorBlock:`

          - `BetaWebFetchToolResultErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `URL_TOO_LONG("url_too_long")`

            - `URL_NOT_ALLOWED("url_not_allowed")`

            - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

            - `URL_NOT_ACCESSIBLE("url_not_accessible")`

            - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `MAX_USES_EXCEEDED("max_uses_exceeded")`

            - `UNAVAILABLE("unavailable")`

          - `JsonValue; type "web_fetch_tool_result_error"constant`

            - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

        - `class BetaWebFetchBlock:`

          - `BetaDocumentBlock content`

            - `Optional<BetaCitationConfig> citations`

              Citation configuration for the document

              - `boolean enabled`

            - `Source source`

              - `class BetaBase64PdfSource:`

                - `String data`

                - `JsonValue; mediaType "application/pdf"constant`

                  - `APPLICATION_PDF("application/pdf")`

                - `JsonValue; type "base64"constant`

                  - `BASE64("base64")`

              - `class BetaPlainTextSource:`

                - `String data`

                - `JsonValue; mediaType "text/plain"constant`

                  - `TEXT_PLAIN("text/plain")`

                - `JsonValue; type "text"constant`

                  - `TEXT("text")`

            - `Optional<String> title`

              The title of the document

            - `JsonValue; type "document"constant`

              - `DOCUMENT("document")`

          - `Optional<String> retrievedAt`

            ISO 8601 timestamp when the content was retrieved

          - `JsonValue; type "web_fetch_result"constant`

            - `WEB_FETCH_RESULT("web_fetch_result")`

          - `String url`

            Fetched content URL

      - `String toolUseId`

      - `JsonValue; type "web_fetch_tool_result"constant`

        - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

        - `class BetaServerToolCaller20260120:`

    - `class BetaAdvisorToolResultBlock:`

      - `Content content`

        - `class BetaAdvisorToolResultError:`

          - `ErrorCode errorCode`

            - `MAX_USES_EXCEEDED("max_uses_exceeded")`

            - `PROMPT_TOO_LONG("prompt_too_long")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `OVERLOADED("overloaded")`

            - `UNAVAILABLE("unavailable")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `MODEL_NOT_FOUND("model_not_found")`

          - `JsonValue; type "advisor_tool_result_error"constant`

            - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

        - `class BetaAdvisorResultBlock:`

          - `Optional<String> stopReason`

            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.

          - `String text`

          - `JsonValue; type "advisor_result"constant`

            - `ADVISOR_RESULT("advisor_result")`

        - `class BetaAdvisorRedactedResultBlock:`

          - `String encryptedContent`

            Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

          - `Optional<String> stopReason`

            The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

          - `JsonValue; type "advisor_redacted_result"constant`

            - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

      - `String toolUseId`

      - `JsonValue; type "advisor_tool_result"constant`

        - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

    - `class BetaCodeExecutionToolResultBlock:`

      - `BetaCodeExecutionToolResultBlockContent content`

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

        - `class BetaCodeExecutionToolResultError:`

          - `BetaCodeExecutionToolResultErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `JsonValue; type "code_execution_tool_result_error"constant`

            - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

        - `class BetaCodeExecutionResultBlock:`

          - `List<BetaCodeExecutionOutputBlock> content`

            - `String fileId`

            - `JsonValue; type "code_execution_output"constant`

              - `CODE_EXECUTION_OUTPUT("code_execution_output")`

          - `long returnCode`

          - `String stderr`

          - `String stdout`

          - `JsonValue; type "code_execution_result"constant`

            - `CODE_EXECUTION_RESULT("code_execution_result")`

        - `class BetaEncryptedCodeExecutionResultBlock:`

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

          - `List<BetaCodeExecutionOutputBlock> content`

            - `String fileId`

            - `JsonValue; type "code_execution_output"constant`

          - `String encryptedStdout`

          - `long returnCode`

          - `String stderr`

          - `JsonValue; type "encrypted_code_execution_result"constant`

            - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

      - `String toolUseId`

      - `JsonValue; type "code_execution_tool_result"constant`

        - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

    - `class BetaBashCodeExecutionToolResultBlock:`

      - `Content content`

        - `class BetaBashCodeExecutionToolResultError:`

          - `ErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

          - `JsonValue; type "bash_code_execution_tool_result_error"constant`

            - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

        - `class BetaBashCodeExecutionResultBlock:`

          - `List<BetaBashCodeExecutionOutputBlock> content`

            - `String fileId`

            - `JsonValue; type "bash_code_execution_output"constant`

              - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

          - `long returnCode`

          - `String stderr`

          - `String stdout`

          - `JsonValue; type "bash_code_execution_result"constant`

            - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

      - `String toolUseId`

      - `JsonValue; type "bash_code_execution_tool_result"constant`

        - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

    - `class BetaTextEditorCodeExecutionToolResultBlock:`

      - `Content content`

        - `class BetaTextEditorCodeExecutionToolResultError:`

          - `ErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `FILE_NOT_FOUND("file_not_found")`

          - `Optional<String> errorMessage`

          - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

        - `class BetaTextEditorCodeExecutionViewResultBlock:`

          - `String content`

          - `FileType fileType`

            - `TEXT("text")`

            - `IMAGE("image")`

            - `PDF("pdf")`

          - `Optional<Long> numLines`

          - `Optional<Long> startLine`

          - `Optional<Long> totalLines`

          - `JsonValue; type "text_editor_code_execution_view_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

        - `class BetaTextEditorCodeExecutionCreateResultBlock:`

          - `boolean isFileUpdate`

          - `JsonValue; type "text_editor_code_execution_create_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

        - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

          - `Optional<List<String>> lines`

          - `Optional<Long> newLines`

          - `Optional<Long> newStart`

          - `Optional<Long> oldLines`

          - `Optional<Long> oldStart`

          - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

      - `String toolUseId`

      - `JsonValue; type "text_editor_code_execution_tool_result"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

    - `class BetaToolSearchToolResultBlock:`

      - `Content content`

        - `class BetaToolSearchToolResultError:`

          - `ErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `Optional<String> errorMessage`

          - `JsonValue; type "tool_search_tool_result_error"constant`

            - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

        - `class BetaToolSearchToolSearchResultBlock:`

          - `List<BetaToolReferenceBlock> toolReferences`

            - `String toolName`

            - `JsonValue; type "tool_reference"constant`

              - `TOOL_REFERENCE("tool_reference")`

          - `JsonValue; type "tool_search_tool_search_result"constant`

            - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

      - `String toolUseId`

      - `JsonValue; type "tool_search_tool_result"constant`

        - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

    - `class BetaMcpToolUseBlock:`

      - `String id`

      - `Input input`

      - `String name`

        The name of the MCP tool

      - `String serverName`

        The name of the MCP server

      - `JsonValue; type "mcp_tool_use"constant`

        - `MCP_TOOL_USE("mcp_tool_use")`

    - `class BetaMcpToolResultBlock:`

      - `Content content`

        - `String`

        - `List<BetaTextBlock>`

          - `Optional<List<BetaTextCitation>> citations`

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

          - `String text`

          - `JsonValue; type "text"constant`

      - `boolean isError`

      - `String toolUseId`

      - `JsonValue; type "mcp_tool_result"constant`

        - `MCP_TOOL_RESULT("mcp_tool_result")`

    - `class BetaContainerUploadBlock:`

      Response model for a file uploaded to the container.

      - `String fileId`

      - `JsonValue; type "container_upload"constant`

        - `CONTAINER_UPLOAD("container_upload")`

    - `class BetaCompactionBlock:`

      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.

      - `Optional<String> content`

        Summary of compacted content, or null if compaction failed

      - `Optional<String> encryptedContent`

        Opaque metadata from prior compaction, to be round-tripped verbatim

      - `JsonValue; type "compaction"constant`

        - `COMPACTION("compaction")`

    - `class BetaFallbackBlock:`

      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 routed directly by the sticky decision 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.

      - `BetaFallbackInfo from`

        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.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_MYTHOS_5("claude-mythos-5")`

            Most capable model for cybersecurity and biology research

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

            New class of intelligence, strongest in coding and cybersecurity

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

          - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

            Exceptional model for specialized complex tasks

          - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

            Exceptional model for specialized complex tasks

          - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

            Powerful model for complex tasks

          - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

            Powerful model for complex tasks

          - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

            High-performance model with extended thinking

          - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

            High-performance model with extended thinking

          - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

            Fast and cost-effective model

      - `BetaFallbackInfo to`

        The fallback model producing the content that follows this block. Its `model` is always the canonical id.

      - `JsonValue; type "fallback"constant`

        - `FALLBACK("fallback")`

  - `Optional<BetaContextManagementResponse> contextManagement`

    Context management response.

    Information about context management strategies applied during the request.

    - `List<AppliedEdit> appliedEdits`

      List of context management edits that were applied.

      - `class BetaClearToolUses20250919EditResponse:`

        - `long clearedInputTokens`

          Number of input tokens cleared by this edit.

        - `long clearedToolUses`

          Number of tool uses that were cleared.

        - `JsonValue; type "clear_tool_uses_20250919"constant`

          The type of context management edit applied.

          - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

      - `class BetaClearThinking20251015EditResponse:`

        - `long clearedInputTokens`

          Number of input tokens cleared by this edit.

        - `long clearedThinkingTurns`

          Number of thinking turns that were cleared.

        - `JsonValue; type "clear_thinking_20251015"constant`

          The type of context management edit applied.

          - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

  - `Optional<BetaDiagnostics> diagnostics`

    Response envelope for request-level diagnostics. Present (possibly
    null) whenever the caller supplied `diagnostics` on the request.

    - `Optional<CacheMissReason> cacheMissReason`

      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.

      - `class BetaCacheMissModelChanged:`

        - `long cacheMissedInputTokens`

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

        - `JsonValue; type "model_changed"constant`

          - `MODEL_CHANGED("model_changed")`

      - `class BetaCacheMissSystemChanged:`

        - `long cacheMissedInputTokens`

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

        - `JsonValue; type "system_changed"constant`

          - `SYSTEM_CHANGED("system_changed")`

      - `class BetaCacheMissToolsChanged:`

        - `long cacheMissedInputTokens`

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

        - `JsonValue; type "tools_changed"constant`

          - `TOOLS_CHANGED("tools_changed")`

      - `class BetaCacheMissMessagesChanged:`

        - `long cacheMissedInputTokens`

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

        - `JsonValue; type "messages_changed"constant`

          - `MESSAGES_CHANGED("messages_changed")`

      - `class BetaCacheMissPreviousMessageNotFound:`

        - `JsonValue; type "previous_message_not_found"constant`

          - `PREVIOUS_MESSAGE_NOT_FOUND("previous_message_not_found")`

      - `class BetaCacheMissUnavailable:`

        - `JsonValue; type "unavailable"constant`

          - `UNAVAILABLE("unavailable")`

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

  - `JsonValue; role "assistant"constant`

    Conversational role of the generated message.

    This will always be `"assistant"`.

    - `ASSISTANT("assistant")`

  - `Optional<BetaRefusalStopDetails> stopDetails`

    Structured information about a refusal.

    - `Optional<Category> category`

      The policy category that triggered the refusal.

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

      - `CYBER("cyber")`

      - `BIO("bio")`

      - `REASONING_EXTRACTION("reasoning_extraction")`

    - `Optional<String> explanation`

      Human-readable explanation of the refusal.

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

    - `Optional<String> fallbackCreditToken`

      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.

    - `Optional<Boolean> fallbackHasPrefillClaim`

      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.

    - `Optional<String> recommendedModel`

      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.

    - `JsonValue; type "refusal"constant`

      - `REFUSAL("refusal")`

  - `Optional<BetaStopReason> stopReason`

    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

    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.

    - `END_TURN("end_turn")`

    - `MAX_TOKENS("max_tokens")`

    - `STOP_SEQUENCE("stop_sequence")`

    - `TOOL_USE("tool_use")`

    - `PAUSE_TURN("pause_turn")`

    - `COMPACTION("compaction")`

    - `REFUSAL("refusal")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")`

  - `Optional<String> stopSequence`

    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.

  - `JsonValue; type "message"constant`

    Object type.

    For Messages, this is always `"message"`.

    - `MESSAGE("message")`

  - `BetaUsage usage`

    Billing and rate-limit usage.

    Anthropic'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 Claude.

    Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.

    - `Optional<BetaCacheCreation> cacheCreation`

      Breakdown of cached tokens by TTL

      - `long ephemeral1hInputTokens`

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

      - `long ephemeral5mInputTokens`

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

    - `Optional<Long> cacheCreationInputTokens`

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

    - `Optional<Long> cacheReadInputTokens`

      The number of input tokens read from the cache.

    - `Optional<String> inferenceGeo`

      The geographic region where inference was performed for this request.

    - `long inputTokens`

      The number of input tokens which were used.

    - `Optional<List<BetaIterationsUsageItems>> iterations`

      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

      - `class BetaMessageIterationUsage:`

        Token usage for a sampling iteration.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "message"constant`

          Usage for a sampling iteration

          - `MESSAGE("message")`

      - `class BetaCompactionIterationUsage:`

        Token usage for a compaction iteration.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "compaction"constant`

          Usage for a compaction iteration

          - `COMPACTION("compaction")`

      - `class BetaAdvisorMessageIterationUsage:`

        Token usage for an advisor sub-inference iteration.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "advisor_message"constant`

          Usage for an advisor sub-inference iteration

          - `ADVISOR_MESSAGE("advisor_message")`

      - `class BetaFallbackMessageIterationUsage:`

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

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "fallback_message"constant`

          Usage for the fallback-model attempt that served the response

          - `FALLBACK_MESSAGE("fallback_message")`

    - `long outputTokens`

      The number of output tokens which were used.

    - `Optional<BetaOutputTokensDetails> outputTokensDetails`

      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.

      - `long thinkingTokens`

        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.

    - `Optional<BetaServerToolUsage> serverToolUse`

      The number of server tool requests.

      - `long webFetchRequests`

        The number of web fetch tool requests.

      - `long webSearchRequests`

        The number of web search tool requests.

    - `Optional<ServiceTier> serviceTier`

      If the request used the priority, standard, or batch tier.

      - `STANDARD("standard")`

      - `PRIORITY("priority")`

      - `BATCH("batch")`

    - `Optional<Speed> speed`

      The inference speed mode used for this request.

      - `STANDARD("standard")`

      - `FAST("fast")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
            .maxTokens(1024L)
            .addUserMessage("Hello, world")
            .model(Model.CLAUDE_OPUS_4_6)
            .build();
        BetaMessage betaMessage = client.beta().messages().create(params);
    }
}
```

#### Response

```json
{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "container": {
    "id": "id",
    "expires_at": "2019-12-27T18:11:19.117Z",
    "skills": [
      {
        "skill_id": "pdf",
        "type": "anthropic",
        "version": "latest"
      }
    ]
  },
  "content": [
    {
      "citations": [
        {
          "cited_text": "cited_text",
          "document_index": 0,
          "document_title": "document_title",
          "end_char_index": 0,
          "file_id": "file_id",
          "start_char_index": 0,
          "type": "char_location"
        }
      ],
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "context_management": {
    "applied_edits": [
      {
        "cleared_input_tokens": 0,
        "cleared_tool_uses": 0,
        "type": "clear_tool_uses_20250919"
      }
    ]
  },
  "diagnostics": {
    "cache_miss_reason": {
      "cache_missed_input_tokens": 0,
      "type": "model_changed"
    }
  },
  "model": "claude-opus-4-6",
  "role": "assistant",
  "stop_details": {
    "category": "cyber",
    "explanation": "explanation",
    "fallback_credit_token": "fallback_credit_token",
    "fallback_has_prefill_claim": true,
    "recommended_model": "recommended_model",
    "type": "refusal"
  },
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_creation_input_tokens": 2051,
    "cache_read_input_tokens": 2051,
    "inference_geo": "inference_geo",
    "input_tokens": 2095,
    "iterations": [
      {
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 0
        },
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "input_tokens": 0,
        "model": "claude-fable-5",
        "output_tokens": 0,
        "type": "message"
      }
    ],
    "output_tokens": 503,
    "output_tokens_details": {
      "thinking_tokens": 0
    },
    "server_tool_use": {
      "web_fetch_requests": 2,
      "web_search_requests": 0
    },
    "service_tier": "standard",
    "speed": "standard"
  }
}
```

## Count tokens in a Message

`BetaMessageTokensCount beta().messages().countTokens(MessageCountTokensParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/messages/count_tokens`

Count the number of tokens in a Message.

The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it.

Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting)

### Parameters

- `MessageCountTokensParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `List<BetaMessageParam> messages`

    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, Claude"}]
    ```

    Example with multiple conversational turns:

    ```json
    [
      {"role": "user", "content": "Hello there."},
      {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
      {"role": "user", "content": "Can you explain LLMs in plain English?"},
    ]
    ```

    Example with a partially-filled response from Claude:

    ```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, Claude"}
    ```

    ```json
    {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
    ```

    See [input examples](https://docs.claude.com/en/api/messages-examples).

    Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), 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.

    - `Content content`

      - `String`

      - `List<BetaContentBlockParam>`

        - `class BetaTextBlockParam:`

          - `String text`

          - `JsonValue; type "text"constant`

            - `TEXT("text")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

            - `JsonValue; type "ephemeral"constant`

              - `EPHEMERAL("ephemeral")`

            - `Optional<Ttl> ttl`

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

              - `TTL_5M("5m")`

              - `TTL_1H("1h")`

          - `Optional<List<BetaTextCitationParam>> citations`

            - `class BetaCitationCharLocationParam:`

              - `String citedText`

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endCharIndex`

              - `long startCharIndex`

              - `JsonValue; type "char_location"constant`

                - `CHAR_LOCATION("char_location")`

            - `class BetaCitationPageLocationParam:`

              - `String citedText`

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endPageNumber`

              - `long startPageNumber`

              - `JsonValue; type "page_location"constant`

                - `PAGE_LOCATION("page_location")`

            - `class BetaCitationContentBlockLocationParam:`

              - `String citedText`

                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.

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endBlockIndex`

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

              - `long startBlockIndex`

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

              - `JsonValue; type "content_block_location"constant`

                - `CONTENT_BLOCK_LOCATION("content_block_location")`

            - `class BetaCitationWebSearchResultLocationParam:`

              - `String citedText`

              - `String encryptedIndex`

              - `Optional<String> title`

              - `JsonValue; type "web_search_result_location"constant`

                - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

              - `String url`

            - `class BetaCitationSearchResultLocationParam:`

              - `String citedText`

                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.

              - `long endBlockIndex`

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

              - `long searchResultIndex`

                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.

              - `String source`

              - `long startBlockIndex`

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

              - `Optional<String> title`

              - `JsonValue; type "search_result_location"constant`

                - `SEARCH_RESULT_LOCATION("search_result_location")`

        - `class BetaImageBlockParam:`

          - `Source source`

            - `class BetaBase64ImageSource:`

              - `String data`

              - `MediaType mediaType`

                - `IMAGE_JPEG("image/jpeg")`

                - `IMAGE_PNG("image/png")`

                - `IMAGE_GIF("image/gif")`

                - `IMAGE_WEBP("image/webp")`

              - `JsonValue; type "base64"constant`

                - `BASE64("base64")`

            - `class BetaUrlImageSource:`

              - `JsonValue; type "url"constant`

                - `URL("url")`

              - `String url`

            - `class BetaFileImageSource:`

              - `String fileId`

              - `JsonValue; type "file"constant`

                - `FILE("file")`

          - `JsonValue; type "image"constant`

            - `IMAGE("image")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaRequestDocumentBlock:`

          - `Source source`

            - `class BetaBase64PdfSource:`

              - `String data`

              - `JsonValue; mediaType "application/pdf"constant`

                - `APPLICATION_PDF("application/pdf")`

              - `JsonValue; type "base64"constant`

                - `BASE64("base64")`

            - `class BetaPlainTextSource:`

              - `String data`

              - `JsonValue; mediaType "text/plain"constant`

                - `TEXT_PLAIN("text/plain")`

              - `JsonValue; type "text"constant`

                - `TEXT("text")`

            - `class BetaContentBlockSource:`

              - `Content content`

                - `String`

                - `List<BetaContentBlockSourceContent>`

                  - `class BetaTextBlockParam:`

                  - `class BetaImageBlockParam:`

              - `JsonValue; type "content"constant`

                - `CONTENT("content")`

            - `class BetaUrlPdfSource:`

              - `JsonValue; type "url"constant`

                - `URL("url")`

              - `String url`

            - `class BetaFileDocumentSource:`

              - `String fileId`

              - `JsonValue; type "file"constant`

                - `FILE("file")`

          - `JsonValue; type "document"constant`

            - `DOCUMENT("document")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<BetaCitationsConfigParam> citations`

            - `Optional<Boolean> enabled`

          - `Optional<String> context`

          - `Optional<String> title`

        - `class BetaSearchResultBlockParam:`

          - `List<BetaTextBlockParam> content`

            - `String text`

            - `JsonValue; type "text"constant`

            - `Optional<BetaCacheControlEphemeral> cacheControl`

              Create a cache control breakpoint at this content block.

            - `Optional<List<BetaTextCitationParam>> citations`

          - `String source`

          - `String title`

          - `JsonValue; type "search_result"constant`

            - `SEARCH_RESULT("search_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<BetaCitationsConfigParam> citations`

        - `class BetaThinkingBlockParam:`

          - `String signature`

          - `String thinking`

          - `JsonValue; type "thinking"constant`

            - `THINKING("thinking")`

        - `class BetaRedactedThinkingBlockParam:`

          - `String data`

          - `JsonValue; type "redacted_thinking"constant`

            - `REDACTED_THINKING("redacted_thinking")`

        - `class BetaToolUseBlockParam:`

          - `String id`

          - `Input input`

          - `String name`

          - `JsonValue; type "tool_use"constant`

            - `TOOL_USE("tool_use")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

              - `JsonValue; type "direct"constant`

                - `DIRECT("direct")`

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

              - `String toolId`

              - `JsonValue; type "code_execution_20250825"constant`

                - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `class BetaServerToolCaller20260120:`

              - `String toolId`

              - `JsonValue; type "code_execution_20260120"constant`

                - `CODE_EXECUTION_20260120("code_execution_20260120")`

        - `class BetaToolResultBlockParam:`

          - `String toolUseId`

          - `JsonValue; type "tool_result"constant`

            - `TOOL_RESULT("tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Content> content`

            - `String`

            - `List<Block>`

              - `class BetaTextBlockParam:`

              - `class BetaImageBlockParam:`

              - `class BetaSearchResultBlockParam:`

              - `class BetaRequestDocumentBlock:`

              - `class BetaToolReferenceBlockParam:`

                Tool reference block that can be included in tool_result content.

                - `String toolName`

                - `JsonValue; type "tool_reference"constant`

                  - `TOOL_REFERENCE("tool_reference")`

                - `Optional<BetaCacheControlEphemeral> cacheControl`

                  Create a cache control breakpoint at this content block.

          - `Optional<Boolean> isError`

        - `class BetaServerToolUseBlockParam:`

          - `String id`

          - `Input input`

          - `Name name`

            - `ADVISOR("advisor")`

            - `WEB_SEARCH("web_search")`

            - `WEB_FETCH("web_fetch")`

            - `CODE_EXECUTION("code_execution")`

            - `BASH_CODE_EXECUTION("bash_code_execution")`

            - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

            - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

            - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

          - `JsonValue; type "server_tool_use"constant`

            - `SERVER_TOOL_USE("server_tool_use")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaWebSearchToolResultBlockParam:`

          - `BetaWebSearchToolResultBlockParamContent content`

            - `List<BetaWebSearchResultBlockParam>`

              - `String encryptedContent`

              - `String title`

              - `JsonValue; type "web_search_result"constant`

                - `WEB_SEARCH_RESULT("web_search_result")`

              - `String url`

              - `Optional<String> pageAge`

            - `class BetaWebSearchToolRequestError:`

              - `BetaWebSearchToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `QUERY_TOO_LONG("query_too_long")`

                - `REQUEST_TOO_LARGE("request_too_large")`

              - `JsonValue; type "web_search_tool_result_error"constant`

                - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

          - `String toolUseId`

          - `JsonValue; type "web_search_tool_result"constant`

            - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaWebFetchToolResultBlockParam:`

          - `Content content`

            - `class BetaWebFetchToolResultErrorBlockParam:`

              - `BetaWebFetchToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `URL_TOO_LONG("url_too_long")`

                - `URL_NOT_ALLOWED("url_not_allowed")`

                - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

                - `URL_NOT_ACCESSIBLE("url_not_accessible")`

                - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `UNAVAILABLE("unavailable")`

              - `JsonValue; type "web_fetch_tool_result_error"constant`

                - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

            - `class BetaWebFetchBlockParam:`

              - `BetaRequestDocumentBlock content`

              - `JsonValue; type "web_fetch_result"constant`

                - `WEB_FETCH_RESULT("web_fetch_result")`

              - `String url`

                Fetched content URL

              - `Optional<String> retrievedAt`

                ISO 8601 timestamp when the content was retrieved

          - `String toolUseId`

          - `JsonValue; type "web_fetch_tool_result"constant`

            - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaAdvisorToolResultBlockParam:`

          - `Content content`

            - `class BetaAdvisorToolResultErrorParam:`

              - `ErrorCode errorCode`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `PROMPT_TOO_LONG("prompt_too_long")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `OVERLOADED("overloaded")`

                - `UNAVAILABLE("unavailable")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `MODEL_NOT_FOUND("model_not_found")`

              - `JsonValue; type "advisor_tool_result_error"constant`

                - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

            - `class BetaAdvisorResultBlockParam:`

              - `String text`

              - `JsonValue; type "advisor_result"constant`

                - `ADVISOR_RESULT("advisor_result")`

              - `Optional<String> stopReason`

            - `class BetaAdvisorRedactedResultBlockParam:`

              - `String encryptedContent`

                Opaque blob produced by a prior response; must be round-tripped verbatim.

              - `JsonValue; type "advisor_redacted_result"constant`

                - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

              - `Optional<String> stopReason`

          - `String toolUseId`

          - `JsonValue; type "advisor_tool_result"constant`

            - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaCodeExecutionToolResultBlockParam:`

          - `BetaCodeExecutionToolResultBlockParamContent content`

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

            - `class BetaCodeExecutionToolResultErrorParam:`

              - `BetaCodeExecutionToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `JsonValue; type "code_execution_tool_result_error"constant`

                - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

            - `class BetaCodeExecutionResultBlockParam:`

              - `List<BetaCodeExecutionOutputBlockParam> content`

                - `String fileId`

                - `JsonValue; type "code_execution_output"constant`

                  - `CODE_EXECUTION_OUTPUT("code_execution_output")`

              - `long returnCode`

              - `String stderr`

              - `String stdout`

              - `JsonValue; type "code_execution_result"constant`

                - `CODE_EXECUTION_RESULT("code_execution_result")`

            - `class BetaEncryptedCodeExecutionResultBlockParam:`

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

              - `List<BetaCodeExecutionOutputBlockParam> content`

                - `String fileId`

                - `JsonValue; type "code_execution_output"constant`

              - `String encryptedStdout`

              - `long returnCode`

              - `String stderr`

              - `JsonValue; type "encrypted_code_execution_result"constant`

                - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

          - `String toolUseId`

          - `JsonValue; type "code_execution_tool_result"constant`

            - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaBashCodeExecutionToolResultBlockParam:`

          - `Content content`

            - `class BetaBashCodeExecutionToolResultErrorParam:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

              - `JsonValue; type "bash_code_execution_tool_result_error"constant`

                - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

            - `class BetaBashCodeExecutionResultBlockParam:`

              - `List<BetaBashCodeExecutionOutputBlockParam> content`

                - `String fileId`

                - `JsonValue; type "bash_code_execution_output"constant`

                  - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

              - `long returnCode`

              - `String stderr`

              - `String stdout`

              - `JsonValue; type "bash_code_execution_result"constant`

                - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

          - `String toolUseId`

          - `JsonValue; type "bash_code_execution_tool_result"constant`

            - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaTextEditorCodeExecutionToolResultBlockParam:`

          - `Content content`

            - `class BetaTextEditorCodeExecutionToolResultErrorParam:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `FILE_NOT_FOUND("file_not_found")`

              - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

              - `Optional<String> errorMessage`

            - `class BetaTextEditorCodeExecutionViewResultBlockParam:`

              - `String content`

              - `FileType fileType`

                - `TEXT("text")`

                - `IMAGE("image")`

                - `PDF("pdf")`

              - `JsonValue; type "text_editor_code_execution_view_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

              - `Optional<Long> numLines`

              - `Optional<Long> startLine`

              - `Optional<Long> totalLines`

            - `class BetaTextEditorCodeExecutionCreateResultBlockParam:`

              - `boolean isFileUpdate`

              - `JsonValue; type "text_editor_code_execution_create_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

            - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:`

              - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

              - `Optional<List<String>> lines`

              - `Optional<Long> newLines`

              - `Optional<Long> newStart`

              - `Optional<Long> oldLines`

              - `Optional<Long> oldStart`

          - `String toolUseId`

          - `JsonValue; type "text_editor_code_execution_tool_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaToolSearchToolResultBlockParam:`

          - `Content content`

            - `class BetaToolSearchToolResultErrorParam:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `JsonValue; type "tool_search_tool_result_error"constant`

                - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

              - `Optional<String> errorMessage`

            - `class BetaToolSearchToolSearchResultBlockParam:`

              - `List<BetaToolReferenceBlockParam> toolReferences`

                - `String toolName`

                - `JsonValue; type "tool_reference"constant`

                - `Optional<BetaCacheControlEphemeral> cacheControl`

                  Create a cache control breakpoint at this content block.

              - `JsonValue; type "tool_search_tool_search_result"constant`

                - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

          - `String toolUseId`

          - `JsonValue; type "tool_search_tool_result"constant`

            - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaMcpToolUseBlockParam:`

          - `String id`

          - `Input input`

          - `String name`

          - `String serverName`

            The name of the MCP server

          - `JsonValue; type "mcp_tool_use"constant`

            - `MCP_TOOL_USE("mcp_tool_use")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaRequestMcpToolResultBlockParam:`

          - `String toolUseId`

          - `JsonValue; type "mcp_tool_result"constant`

            - `MCP_TOOL_RESULT("mcp_tool_result")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Content> content`

            - `String`

            - `List<BetaTextBlockParam>`

              - `String text`

              - `JsonValue; type "text"constant`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<List<BetaTextCitationParam>> citations`

          - `Optional<Boolean> isError`

        - `class BetaContainerUploadBlockParam:`

          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.

          - `String fileId`

          - `JsonValue; type "container_upload"constant`

            - `CONTAINER_UPLOAD("container_upload")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaCompactionBlockParam:`

          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.

          - `JsonValue; type "compaction"constant`

            - `COMPACTION("compaction")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<String> content`

            Summary of previously compacted content, or null if compaction failed

          - `Optional<String> encryptedContent`

            Opaque metadata from prior compaction, to be round-tripped verbatim

        - `class BetaMidConversationSystemBlockParam:`

          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.

          - `List<BetaTextBlockParam> content`

            System instruction text blocks.

            - `String text`

            - `JsonValue; type "text"constant`

            - `Optional<BetaCacheControlEphemeral> cacheControl`

              Create a cache control breakpoint at this content block.

            - `Optional<List<BetaTextCitationParam>> citations`

          - `JsonValue; type "mid_conv_system"constant`

            - `MID_CONV_SYSTEM("mid_conv_system")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `class BetaFallbackBlockParam:`

          A `fallback` block echoed back from a prior response.

          Accepted in `messages[].content` and never rendered into the prompt,
          not validated against the request's `fallbacks` chain or top-level
          `model`, and stripped before the sticky-routing cache key is computed.

          Callers should echo the assistant turn verbatim — block included. The
          block's position is load-bearing for thinking verification: the thinking
          runs on either side of a fallback hop carry independently-rooted
          verification hash chains, and this block is the only record of where one
          chain ends and the next begins. When thinking runs flank the boundary,
          omitting the block merges the runs into one contiguous span whose hashes
          cannot verify (the request is rejected), and moving it into the middle of
          a single run splits that run's chain and is likewise rejected; between
          non-thinking blocks the block's placement has no verification effect.

          - `BetaFallbackInfoParam from`

            Identifies one hop of a fallback transition.

            - `Model model`

              The model that will complete your prompt.

              See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

              - `CLAUDE_FABLE_5("claude-fable-5")`

                Next generation of intelligence for the hardest knowledge work and coding problems

              - `CLAUDE_MYTHOS_5("claude-mythos-5")`

                Most capable model for cybersecurity and biology research

              - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

                New class of intelligence, strongest in coding and cybersecurity

              - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

                Best combination of speed and intelligence

              - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

                Fastest model with near-frontier intelligence

              - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

                Fastest model with near-frontier intelligence

              - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

                Premium model combining maximum intelligence with practical performance

              - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

                Premium model combining maximum intelligence with practical performance

              - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

                High-performance model for agents and coding

              - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

                High-performance model for agents and coding

              - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

                Exceptional model for specialized complex tasks

              - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

                Exceptional model for specialized complex tasks

              - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

                Powerful model for complex tasks

              - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

                Powerful model for complex tasks

              - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

                High-performance model with extended thinking

              - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

                High-performance model with extended thinking

              - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

                Fast and cost-effective model

          - `BetaFallbackInfoParam to`

            Identifies one hop of a fallback transition.

          - `JsonValue; type "fallback"constant`

            - `FALLBACK("fallback")`

    - `Role role`

      - `USER("user")`

      - `ASSISTANT("assistant")`

      - `SYSTEM("system")`

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

  - `Optional<BetaContextManagementConfig> contextManagement`

    Context management configuration.

    This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not.

  - `Optional<List<BetaRequestMcpServerUrlDefinition>> mcpServers`

    MCP servers to be utilized in this request

    - `String name`

    - `JsonValue; type "url"constant`

      - `URL("url")`

    - `String url`

    - `Optional<String> authorizationToken`

    - `Optional<BetaRequestMcpServerToolConfiguration> toolConfiguration`

      - `Optional<List<String>> allowedTools`

      - `Optional<Boolean> enabled`

  - `Optional<BetaOutputConfig> outputConfig`

    Configuration options for the model's output, such as the output format.

  - `Optional<BetaJsonOutputFormat> outputFormat`

    Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

    A schema to specify Claude's output format in responses. This parameter will be removed in a future release.

  - `Optional<Speed> speed`

    The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference.

    - `STANDARD("standard")`

    - `FAST("fast")`

  - `Optional<System> system`

    System prompt.

    A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts).

    - `String`

    - `List<BetaTextBlockParam>`

      - `String text`

      - `JsonValue; type "text"constant`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<List<BetaTextCitationParam>> citations`

  - `Optional<BetaThinkingConfigParam> thinking`

    Configuration for enabling Claude's extended thinking.

    When enabled, responses include `thinking` content blocks showing Claude'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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.

  - `Optional<BetaToolChoice> toolChoice`

    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.

  - `Optional<List<Tool>> tools`

    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](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/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](https://docs.claude.com/en/docs/tool-use) for more details.

    - `class BetaTool:`

      - `InputSchema inputSchema`

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

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<String> 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.

      - `Optional<Boolean> eagerInputStreaming`

        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.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

      - `Optional<Type> type`

        - `CUSTOM("custom")`

    - `class BetaToolBash20241022:`

      - `JsonValue; name "bash"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `BASH("bash")`

      - `JsonValue; type "bash_20241022"constant`

        - `BASH_20241022("bash_20241022")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolBash20250124:`

      - `JsonValue; name "bash"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `BASH("bash")`

      - `JsonValue; type "bash_20250124"constant`

        - `BASH_20250124("bash_20250124")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaCodeExecutionTool20250522:`

      - `JsonValue; name "code_execution"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `CODE_EXECUTION("code_execution")`

      - `JsonValue; type "code_execution_20250522"constant`

        - `CODE_EXECUTION_20250522("code_execution_20250522")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaCodeExecutionTool20250825:`

      - `JsonValue; name "code_execution"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `CODE_EXECUTION("code_execution")`

      - `JsonValue; type "code_execution_20250825"constant`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaCodeExecutionTool20260120:`

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

      - `JsonValue; name "code_execution"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `CODE_EXECUTION("code_execution")`

      - `JsonValue; type "code_execution_20260120"constant`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolComputerUse20241022:`

      - `long displayHeightPx`

        The height of the display in pixels.

      - `long displayWidthPx`

        The width of the display in pixels.

      - `JsonValue; name "computer"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `COMPUTER("computer")`

      - `JsonValue; type "computer_20241022"constant`

        - `COMPUTER_20241022("computer_20241022")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> displayNumber`

        The X11 display number (e.g. 0, 1) for the display.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaMemoryTool20250818:`

      - `JsonValue; name "memory"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `MEMORY("memory")`

      - `JsonValue; type "memory_20250818"constant`

        - `MEMORY_20250818("memory_20250818")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolComputerUse20250124:`

      - `long displayHeightPx`

        The height of the display in pixels.

      - `long displayWidthPx`

        The width of the display in pixels.

      - `JsonValue; name "computer"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `COMPUTER("computer")`

      - `JsonValue; type "computer_20250124"constant`

        - `COMPUTER_20250124("computer_20250124")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> displayNumber`

        The X11 display number (e.g. 0, 1) for the display.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolTextEditor20241022:`

      - `JsonValue; name "str_replace_editor"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `STR_REPLACE_EDITOR("str_replace_editor")`

      - `JsonValue; type "text_editor_20241022"constant`

        - `TEXT_EDITOR_20241022("text_editor_20241022")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolComputerUse20251124:`

      - `long displayHeightPx`

        The height of the display in pixels.

      - `long displayWidthPx`

        The width of the display in pixels.

      - `JsonValue; name "computer"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `COMPUTER("computer")`

      - `JsonValue; type "computer_20251124"constant`

        - `COMPUTER_20251124("computer_20251124")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> displayNumber`

        The X11 display number (e.g. 0, 1) for the display.

      - `Optional<Boolean> enableZoom`

        Whether to enable an action to take a zoomed-in screenshot of the screen.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolTextEditor20250124:`

      - `JsonValue; name "str_replace_editor"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `STR_REPLACE_EDITOR("str_replace_editor")`

      - `JsonValue; type "text_editor_20250124"constant`

        - `TEXT_EDITOR_20250124("text_editor_20250124")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolTextEditor20250429:`

      - `JsonValue; name "str_replace_based_edit_tool"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")`

      - `JsonValue; type "text_editor_20250429"constant`

        - `TEXT_EDITOR_20250429("text_editor_20250429")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolTextEditor20250728:`

      - `JsonValue; name "str_replace_based_edit_tool"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")`

      - `JsonValue; type "text_editor_20250728"constant`

        - `TEXT_EDITOR_20250728("text_editor_20250728")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<List<InputExample>> inputExamples`

      - `Optional<Long> maxCharacters`

        Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaWebSearchTool20250305:`

      - `JsonValue; name "web_search"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `WEB_SEARCH("web_search")`

      - `JsonValue; type "web_search_20250305"constant`

        - `WEB_SEARCH_20250305("web_search_20250305")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<String>> allowedDomains`

        If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.

      - `Optional<List<String>> blockedDomains`

        If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

      - `Optional<BetaUserLocation> userLocation`

        Parameters for the user's location. Used to provide more relevant search results.

        - `JsonValue; type "approximate"constant`

          - `APPROXIMATE("approximate")`

        - `Optional<String> city`

          The city of the user.

        - `Optional<String> country`

          The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.

        - `Optional<String> region`

          The region of the user.

        - `Optional<String> timezone`

          The [IANA timezone](https://nodatime.org/TimeZones) of the user.

    - `class BetaWebFetchTool20250910:`

      - `JsonValue; name "web_fetch"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `WEB_FETCH("web_fetch")`

      - `JsonValue; type "web_fetch_20250910"constant`

        - `WEB_FETCH_20250910("web_fetch_20250910")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<String>> allowedDomains`

        List of domains to allow fetching from

      - `Optional<List<String>> blockedDomains`

        List of domains to block fetching from

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<BetaCitationsConfigParam> citations`

        Citations configuration for fetched documents. Citations are disabled by default.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxContentTokens`

        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.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaWebSearchTool20260209:`

      - `JsonValue; name "web_search"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `WEB_SEARCH("web_search")`

      - `JsonValue; type "web_search_20260209"constant`

        - `WEB_SEARCH_20260209("web_search_20260209")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<String>> allowedDomains`

        If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.

      - `Optional<List<String>> blockedDomains`

        If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

      - `Optional<BetaUserLocation> userLocation`

        Parameters for the user's location. Used to provide more relevant search results.

    - `class BetaWebFetchTool20260209:`

      - `JsonValue; name "web_fetch"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `WEB_FETCH("web_fetch")`

      - `JsonValue; type "web_fetch_20260209"constant`

        - `WEB_FETCH_20260209("web_fetch_20260209")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<String>> allowedDomains`

        List of domains to allow fetching from

      - `Optional<List<String>> blockedDomains`

        List of domains to block fetching from

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<BetaCitationsConfigParam> citations`

        Citations configuration for fetched documents. Citations are disabled by default.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxContentTokens`

        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.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaWebFetchTool20260309:`

      Web fetch tool with use_cache parameter for bypassing cached content.

      - `JsonValue; name "web_fetch"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `WEB_FETCH("web_fetch")`

      - `JsonValue; type "web_fetch_20260309"constant`

        - `WEB_FETCH_20260309("web_fetch_20260309")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<List<String>> allowedDomains`

        List of domains to allow fetching from

      - `Optional<List<String>> blockedDomains`

        List of domains to block fetching from

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<BetaCitationsConfigParam> citations`

        Citations configuration for fetched documents. Citations are disabled by default.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxContentTokens`

        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.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

      - `Optional<Boolean> useCache`

        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.

    - `class BetaAdvisorTool20260301:`

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `JsonValue; name "advisor"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `ADVISOR("advisor")`

      - `JsonValue; type "advisor_20260301"constant`

        - `ADVISOR_20260301("advisor_20260301")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<BetaCacheControlEphemeral> caching`

        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.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Long> maxTokens`

        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.

      - `Optional<Long> maxUses`

        Maximum number of times the tool can be used in the API request.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolSearchToolBm25_20251119:`

      - `JsonValue; name "tool_search_tool_bm25"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

      - `Type type`

        - `TOOL_SEARCH_TOOL_BM25_20251119("tool_search_tool_bm25_20251119")`

        - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaToolSearchToolRegex20251119:`

      - `JsonValue; name "tool_search_tool_regex"constant`

        Name of the tool.

        This is how the tool will be called by the model and in `tool_use` blocks.

        - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

      - `Type type`

        - `TOOL_SEARCH_TOOL_REGEX_20251119("tool_search_tool_regex_20251119")`

        - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

      - `Optional<List<AllowedCaller>> allowedCallers`

        - `DIRECT("direct")`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Boolean> deferLoading`

        If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

      - `Optional<Boolean> strict`

        When true, guarantees schema validation on tool names and inputs

    - `class BetaMcpToolset:`

      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.

      - `String mcpServerName`

        Name of the MCP server to configure tools for

      - `JsonValue; type "mcp_toolset"constant`

        - `MCP_TOOLSET("mcp_toolset")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<Configs> configs`

        Configuration overrides for specific tools, keyed by tool name

        - `Optional<Boolean> deferLoading`

        - `Optional<Boolean> enabled`

      - `Optional<BetaMcpToolDefaultConfig> defaultConfig`

        Default configuration applied to all tools from this server

        - `Optional<Boolean> deferLoading`

        - `Optional<Boolean> enabled`

### Returns

- `class BetaMessageTokensCount:`

  - `Optional<BetaCountTokensContextManagementResponse> contextManagement`

    Information about context management applied to the message.

    - `long originalInputTokens`

      The original token count before context management was applied

  - `long inputTokens`

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

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.BetaMessageTokensCount;
import com.anthropic.models.beta.messages.MessageCountTokensParams;
import com.anthropic.models.messages.Model;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCountTokensParams params = MessageCountTokensParams.builder()
            .addUserMessage("Hello, world")
            .model(Model.CLAUDE_OPUS_4_6)
            .build();
        BetaMessageTokensCount betaMessageTokensCount = client.beta().messages().countTokens(params);
    }
}
```

#### Response

```json
{
  "context_management": {
    "original_input_tokens": 0
  },
  "input_tokens": 2095
}
```

## Domain Types

### Beta Advisor Message Iteration Usage

- `class BetaAdvisorMessageIterationUsage:`

  Token usage for an advisor sub-inference iteration.

  - `Optional<BetaCacheCreation> cacheCreation`

    Breakdown of cached tokens by TTL

    - `long ephemeral1hInputTokens`

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

    - `long ephemeral5mInputTokens`

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

  - `long cacheCreationInputTokens`

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

  - `long cacheReadInputTokens`

    The number of input tokens read from the cache.

  - `long inputTokens`

    The number of input tokens which were used.

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `CLAUDE_FABLE_5("claude-fable-5")`

      Next generation of intelligence for the hardest knowledge work and coding problems

    - `CLAUDE_MYTHOS_5("claude-mythos-5")`

      Most capable model for cybersecurity and biology research

    - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

      New class of intelligence, strongest in coding and cybersecurity

    - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

      Best combination of speed and intelligence

    - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

      High-performance model for agents and coding

    - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

      High-performance model for agents and coding

    - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

      Powerful model for complex tasks

    - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

      Powerful model for complex tasks

    - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

      High-performance model with extended thinking

    - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

      High-performance model with extended thinking

    - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

      Fast and cost-effective model

  - `long outputTokens`

    The number of output tokens which were used.

  - `JsonValue; type "advisor_message"constant`

    Usage for an advisor sub-inference iteration

    - `ADVISOR_MESSAGE("advisor_message")`

### Beta Advisor Redacted Result Block

- `class BetaAdvisorRedactedResultBlock:`

  - `String encryptedContent`

    Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

  - `Optional<String> stopReason`

    The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

  - `JsonValue; type "advisor_redacted_result"constant`

    - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

### Beta Advisor Redacted Result Block Param

- `class BetaAdvisorRedactedResultBlockParam:`

  - `String encryptedContent`

    Opaque blob produced by a prior response; must be round-tripped verbatim.

  - `JsonValue; type "advisor_redacted_result"constant`

    - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

  - `Optional<String> stopReason`

### Beta Advisor Result Block

- `class BetaAdvisorResultBlock:`

  - `Optional<String> stopReason`

    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.

  - `String text`

  - `JsonValue; type "advisor_result"constant`

    - `ADVISOR_RESULT("advisor_result")`

### Beta Advisor Result Block Param

- `class BetaAdvisorResultBlockParam:`

  - `String text`

  - `JsonValue; type "advisor_result"constant`

    - `ADVISOR_RESULT("advisor_result")`

  - `Optional<String> stopReason`

### Beta Advisor Tool 20260301

- `class BetaAdvisorTool20260301:`

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `CLAUDE_FABLE_5("claude-fable-5")`

      Next generation of intelligence for the hardest knowledge work and coding problems

    - `CLAUDE_MYTHOS_5("claude-mythos-5")`

      Most capable model for cybersecurity and biology research

    - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

      New class of intelligence, strongest in coding and cybersecurity

    - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

      Best combination of speed and intelligence

    - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

      High-performance model for agents and coding

    - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

      High-performance model for agents and coding

    - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

      Powerful model for complex tasks

    - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

      Powerful model for complex tasks

    - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

      High-performance model with extended thinking

    - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

      High-performance model with extended thinking

    - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

      Fast and cost-effective model

  - `JsonValue; name "advisor"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `ADVISOR("advisor")`

  - `JsonValue; type "advisor_20260301"constant`

    - `ADVISOR_20260301("advisor_20260301")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<BetaCacheControlEphemeral> caching`

    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.

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Long> maxTokens`

    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.

  - `Optional<Long> maxUses`

    Maximum number of times the tool can be used in the API request.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Advisor Tool Result Block

- `class BetaAdvisorToolResultBlock:`

  - `Content content`

    - `class BetaAdvisorToolResultError:`

      - `ErrorCode errorCode`

        - `MAX_USES_EXCEEDED("max_uses_exceeded")`

        - `PROMPT_TOO_LONG("prompt_too_long")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `OVERLOADED("overloaded")`

        - `UNAVAILABLE("unavailable")`

        - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

        - `MODEL_NOT_FOUND("model_not_found")`

      - `JsonValue; type "advisor_tool_result_error"constant`

        - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

    - `class BetaAdvisorResultBlock:`

      - `Optional<String> stopReason`

        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.

      - `String text`

      - `JsonValue; type "advisor_result"constant`

        - `ADVISOR_RESULT("advisor_result")`

    - `class BetaAdvisorRedactedResultBlock:`

      - `String encryptedContent`

        Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

      - `Optional<String> stopReason`

        The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

      - `JsonValue; type "advisor_redacted_result"constant`

        - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

  - `String toolUseId`

  - `JsonValue; type "advisor_tool_result"constant`

    - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

### Beta Advisor Tool Result Block Param

- `class BetaAdvisorToolResultBlockParam:`

  - `Content content`

    - `class BetaAdvisorToolResultErrorParam:`

      - `ErrorCode errorCode`

        - `MAX_USES_EXCEEDED("max_uses_exceeded")`

        - `PROMPT_TOO_LONG("prompt_too_long")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `OVERLOADED("overloaded")`

        - `UNAVAILABLE("unavailable")`

        - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

        - `MODEL_NOT_FOUND("model_not_found")`

      - `JsonValue; type "advisor_tool_result_error"constant`

        - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

    - `class BetaAdvisorResultBlockParam:`

      - `String text`

      - `JsonValue; type "advisor_result"constant`

        - `ADVISOR_RESULT("advisor_result")`

      - `Optional<String> stopReason`

    - `class BetaAdvisorRedactedResultBlockParam:`

      - `String encryptedContent`

        Opaque blob produced by a prior response; must be round-tripped verbatim.

      - `JsonValue; type "advisor_redacted_result"constant`

        - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

      - `Optional<String> stopReason`

  - `String toolUseId`

  - `JsonValue; type "advisor_tool_result"constant`

    - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

### Beta Advisor Tool Result Error

- `class BetaAdvisorToolResultError:`

  - `ErrorCode errorCode`

    - `MAX_USES_EXCEEDED("max_uses_exceeded")`

    - `PROMPT_TOO_LONG("prompt_too_long")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `OVERLOADED("overloaded")`

    - `UNAVAILABLE("unavailable")`

    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

    - `MODEL_NOT_FOUND("model_not_found")`

  - `JsonValue; type "advisor_tool_result_error"constant`

    - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

### Beta Advisor Tool Result Error Param

- `class BetaAdvisorToolResultErrorParam:`

  - `ErrorCode errorCode`

    - `MAX_USES_EXCEEDED("max_uses_exceeded")`

    - `PROMPT_TOO_LONG("prompt_too_long")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `OVERLOADED("overloaded")`

    - `UNAVAILABLE("unavailable")`

    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

    - `MODEL_NOT_FOUND("model_not_found")`

  - `JsonValue; type "advisor_tool_result_error"constant`

    - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

### Beta All Thinking Turns

- `class BetaAllThinkingTurns:`

  - `JsonValue; type "all"constant`

    - `ALL("all")`

### Beta Base64 Image Source

- `class BetaBase64ImageSource:`

  - `String data`

  - `MediaType mediaType`

    - `IMAGE_JPEG("image/jpeg")`

    - `IMAGE_PNG("image/png")`

    - `IMAGE_GIF("image/gif")`

    - `IMAGE_WEBP("image/webp")`

  - `JsonValue; type "base64"constant`

    - `BASE64("base64")`

### Beta Base64 PDF Source

- `class BetaBase64PdfSource:`

  - `String data`

  - `JsonValue; mediaType "application/pdf"constant`

    - `APPLICATION_PDF("application/pdf")`

  - `JsonValue; type "base64"constant`

    - `BASE64("base64")`

### Beta Bash Code Execution Output Block

- `class BetaBashCodeExecutionOutputBlock:`

  - `String fileId`

  - `JsonValue; type "bash_code_execution_output"constant`

    - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

### Beta Bash Code Execution Output Block Param

- `class BetaBashCodeExecutionOutputBlockParam:`

  - `String fileId`

  - `JsonValue; type "bash_code_execution_output"constant`

    - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

### Beta Bash Code Execution Result Block

- `class BetaBashCodeExecutionResultBlock:`

  - `List<BetaBashCodeExecutionOutputBlock> content`

    - `String fileId`

    - `JsonValue; type "bash_code_execution_output"constant`

      - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

  - `long returnCode`

  - `String stderr`

  - `String stdout`

  - `JsonValue; type "bash_code_execution_result"constant`

    - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

### Beta Bash Code Execution Result Block Param

- `class BetaBashCodeExecutionResultBlockParam:`

  - `List<BetaBashCodeExecutionOutputBlockParam> content`

    - `String fileId`

    - `JsonValue; type "bash_code_execution_output"constant`

      - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

  - `long returnCode`

  - `String stderr`

  - `String stdout`

  - `JsonValue; type "bash_code_execution_result"constant`

    - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

### Beta Bash Code Execution Tool Result Block

- `class BetaBashCodeExecutionToolResultBlock:`

  - `Content content`

    - `class BetaBashCodeExecutionToolResultError:`

      - `ErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `UNAVAILABLE("unavailable")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

        - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

      - `JsonValue; type "bash_code_execution_tool_result_error"constant`

        - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

    - `class BetaBashCodeExecutionResultBlock:`

      - `List<BetaBashCodeExecutionOutputBlock> content`

        - `String fileId`

        - `JsonValue; type "bash_code_execution_output"constant`

          - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

      - `long returnCode`

      - `String stderr`

      - `String stdout`

      - `JsonValue; type "bash_code_execution_result"constant`

        - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

  - `String toolUseId`

  - `JsonValue; type "bash_code_execution_tool_result"constant`

    - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

### Beta Bash Code Execution Tool Result Block Param

- `class BetaBashCodeExecutionToolResultBlockParam:`

  - `Content content`

    - `class BetaBashCodeExecutionToolResultErrorParam:`

      - `ErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `UNAVAILABLE("unavailable")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

        - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

      - `JsonValue; type "bash_code_execution_tool_result_error"constant`

        - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

    - `class BetaBashCodeExecutionResultBlockParam:`

      - `List<BetaBashCodeExecutionOutputBlockParam> content`

        - `String fileId`

        - `JsonValue; type "bash_code_execution_output"constant`

          - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

      - `long returnCode`

      - `String stderr`

      - `String stdout`

      - `JsonValue; type "bash_code_execution_result"constant`

        - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

  - `String toolUseId`

  - `JsonValue; type "bash_code_execution_tool_result"constant`

    - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

### Beta Bash Code Execution Tool Result Error

- `class BetaBashCodeExecutionToolResultError:`

  - `ErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `UNAVAILABLE("unavailable")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

    - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

  - `JsonValue; type "bash_code_execution_tool_result_error"constant`

    - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

### Beta Bash Code Execution Tool Result Error Param

- `class BetaBashCodeExecutionToolResultErrorParam:`

  - `ErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `UNAVAILABLE("unavailable")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

    - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

  - `JsonValue; type "bash_code_execution_tool_result_error"constant`

    - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

### Beta Cache Control Ephemeral

- `class BetaCacheControlEphemeral:`

  - `JsonValue; type "ephemeral"constant`

    - `EPHEMERAL("ephemeral")`

  - `Optional<Ttl> ttl`

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

    - `TTL_5M("5m")`

    - `TTL_1H("1h")`

### Beta Cache Creation

- `class BetaCacheCreation:`

  - `long ephemeral1hInputTokens`

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

  - `long ephemeral5mInputTokens`

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

### Beta Cache Miss Messages Changed

- `class BetaCacheMissMessagesChanged:`

  - `long cacheMissedInputTokens`

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

  - `JsonValue; type "messages_changed"constant`

    - `MESSAGES_CHANGED("messages_changed")`

### Beta Cache Miss Model Changed

- `class BetaCacheMissModelChanged:`

  - `long cacheMissedInputTokens`

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

  - `JsonValue; type "model_changed"constant`

    - `MODEL_CHANGED("model_changed")`

### Beta Cache Miss Previous Message Not Found

- `class BetaCacheMissPreviousMessageNotFound:`

  - `JsonValue; type "previous_message_not_found"constant`

    - `PREVIOUS_MESSAGE_NOT_FOUND("previous_message_not_found")`

### Beta Cache Miss System Changed

- `class BetaCacheMissSystemChanged:`

  - `long cacheMissedInputTokens`

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

  - `JsonValue; type "system_changed"constant`

    - `SYSTEM_CHANGED("system_changed")`

### Beta Cache Miss Tools Changed

- `class BetaCacheMissToolsChanged:`

  - `long cacheMissedInputTokens`

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

  - `JsonValue; type "tools_changed"constant`

    - `TOOLS_CHANGED("tools_changed")`

### Beta Cache Miss Unavailable

- `class BetaCacheMissUnavailable:`

  - `JsonValue; type "unavailable"constant`

    - `UNAVAILABLE("unavailable")`

### Beta Citation Char Location

- `class BetaCitationCharLocation:`

  - `String citedText`

  - `long documentIndex`

  - `Optional<String> documentTitle`

  - `long endCharIndex`

  - `Optional<String> fileId`

  - `long startCharIndex`

  - `JsonValue; type "char_location"constant`

    - `CHAR_LOCATION("char_location")`

### Beta Citation Char Location Param

- `class BetaCitationCharLocationParam:`

  - `String citedText`

  - `long documentIndex`

  - `Optional<String> documentTitle`

  - `long endCharIndex`

  - `long startCharIndex`

  - `JsonValue; type "char_location"constant`

    - `CHAR_LOCATION("char_location")`

### Beta Citation Config

- `class BetaCitationConfig:`

  - `boolean enabled`

### Beta Citation Content Block Location

- `class BetaCitationContentBlockLocation:`

  - `String citedText`

    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.

  - `long documentIndex`

  - `Optional<String> documentTitle`

  - `long endBlockIndex`

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

  - `Optional<String> fileId`

  - `long startBlockIndex`

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

  - `JsonValue; type "content_block_location"constant`

    - `CONTENT_BLOCK_LOCATION("content_block_location")`

### Beta Citation Content Block Location Param

- `class BetaCitationContentBlockLocationParam:`

  - `String citedText`

    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.

  - `long documentIndex`

  - `Optional<String> documentTitle`

  - `long endBlockIndex`

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

  - `long startBlockIndex`

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

  - `JsonValue; type "content_block_location"constant`

    - `CONTENT_BLOCK_LOCATION("content_block_location")`

### Beta Citation Page Location

- `class BetaCitationPageLocation:`

  - `String citedText`

  - `long documentIndex`

  - `Optional<String> documentTitle`

  - `long endPageNumber`

  - `Optional<String> fileId`

  - `long startPageNumber`

  - `JsonValue; type "page_location"constant`

    - `PAGE_LOCATION("page_location")`

### Beta Citation Page Location Param

- `class BetaCitationPageLocationParam:`

  - `String citedText`

  - `long documentIndex`

  - `Optional<String> documentTitle`

  - `long endPageNumber`

  - `long startPageNumber`

  - `JsonValue; type "page_location"constant`

    - `PAGE_LOCATION("page_location")`

### Beta Citation Search Result Location

- `class BetaCitationSearchResultLocation:`

  - `String citedText`

    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.

  - `long endBlockIndex`

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

  - `long searchResultIndex`

    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.

  - `String source`

  - `long startBlockIndex`

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

  - `Optional<String> title`

  - `JsonValue; type "search_result_location"constant`

    - `SEARCH_RESULT_LOCATION("search_result_location")`

### Beta Citation Search Result Location Param

- `class BetaCitationSearchResultLocationParam:`

  - `String citedText`

    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.

  - `long endBlockIndex`

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

  - `long searchResultIndex`

    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.

  - `String source`

  - `long startBlockIndex`

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

  - `Optional<String> title`

  - `JsonValue; type "search_result_location"constant`

    - `SEARCH_RESULT_LOCATION("search_result_location")`

### Beta Citation Web Search Result Location Param

- `class BetaCitationWebSearchResultLocationParam:`

  - `String citedText`

  - `String encryptedIndex`

  - `Optional<String> title`

  - `JsonValue; type "web_search_result_location"constant`

    - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

  - `String url`

### Beta Citations Config Param

- `class BetaCitationsConfigParam:`

  - `Optional<Boolean> enabled`

### Beta Citations Delta

- `class BetaCitationsDelta:`

  - `Citation citation`

    - `class BetaCitationCharLocation:`

      - `String citedText`

      - `long documentIndex`

      - `Optional<String> documentTitle`

      - `long endCharIndex`

      - `Optional<String> fileId`

      - `long startCharIndex`

      - `JsonValue; type "char_location"constant`

        - `CHAR_LOCATION("char_location")`

    - `class BetaCitationPageLocation:`

      - `String citedText`

      - `long documentIndex`

      - `Optional<String> documentTitle`

      - `long endPageNumber`

      - `Optional<String> fileId`

      - `long startPageNumber`

      - `JsonValue; type "page_location"constant`

        - `PAGE_LOCATION("page_location")`

    - `class BetaCitationContentBlockLocation:`

      - `String citedText`

        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.

      - `long documentIndex`

      - `Optional<String> documentTitle`

      - `long endBlockIndex`

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

      - `Optional<String> fileId`

      - `long startBlockIndex`

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

      - `JsonValue; type "content_block_location"constant`

        - `CONTENT_BLOCK_LOCATION("content_block_location")`

    - `class BetaCitationsWebSearchResultLocation:`

      - `String citedText`

      - `String encryptedIndex`

      - `Optional<String> title`

      - `JsonValue; type "web_search_result_location"constant`

        - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

      - `String url`

    - `class BetaCitationSearchResultLocation:`

      - `String citedText`

        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.

      - `long endBlockIndex`

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

      - `long searchResultIndex`

        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.

      - `String source`

      - `long startBlockIndex`

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

      - `Optional<String> title`

      - `JsonValue; type "search_result_location"constant`

        - `SEARCH_RESULT_LOCATION("search_result_location")`

  - `JsonValue; type "citations_delta"constant`

    - `CITATIONS_DELTA("citations_delta")`

### Beta Citations Web Search Result Location

- `class BetaCitationsWebSearchResultLocation:`

  - `String citedText`

  - `String encryptedIndex`

  - `Optional<String> title`

  - `JsonValue; type "web_search_result_location"constant`

    - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

  - `String url`

### Beta Clear Thinking 20251015 Edit

- `class BetaClearThinking20251015Edit:`

  - `JsonValue; type "clear_thinking_20251015"constant`

    - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

  - `Optional<Keep> keep`

    Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.

    - `class BetaThinkingTurns:`

      - `JsonValue; type "thinking_turns"constant`

        - `THINKING_TURNS("thinking_turns")`

      - `long value`

    - `class BetaAllThinkingTurns:`

      - `JsonValue; type "all"constant`

        - `ALL("all")`

    - `JsonValue;`

      - `ALL("all")`

### Beta Clear Thinking 20251015 Edit Response

- `class BetaClearThinking20251015EditResponse:`

  - `long clearedInputTokens`

    Number of input tokens cleared by this edit.

  - `long clearedThinkingTurns`

    Number of thinking turns that were cleared.

  - `JsonValue; type "clear_thinking_20251015"constant`

    The type of context management edit applied.

    - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

### Beta Clear Tool Uses 20250919 Edit

- `class BetaClearToolUses20250919Edit:`

  - `JsonValue; type "clear_tool_uses_20250919"constant`

    - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

  - `Optional<BetaInputTokensClearAtLeast> clearAtLeast`

    Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed.

    - `JsonValue; type "input_tokens"constant`

      - `INPUT_TOKENS("input_tokens")`

    - `long value`

  - `Optional<ClearToolInputs> clearToolInputs`

    Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)

    - `boolean`

    - `List<String>`

  - `Optional<List<String>> excludeTools`

    Tool names whose uses are preserved from clearing

  - `Optional<BetaToolUsesKeep> keep`

    Number of tool uses to retain in the conversation

    - `JsonValue; type "tool_uses"constant`

      - `TOOL_USES("tool_uses")`

    - `long value`

  - `Optional<Trigger> trigger`

    Condition that triggers the context management strategy

    - `class BetaInputTokensTrigger:`

      - `JsonValue; type "input_tokens"constant`

        - `INPUT_TOKENS("input_tokens")`

      - `long value`

    - `class BetaToolUsesTrigger:`

      - `JsonValue; type "tool_uses"constant`

        - `TOOL_USES("tool_uses")`

      - `long value`

### Beta Clear Tool Uses 20250919 Edit Response

- `class BetaClearToolUses20250919EditResponse:`

  - `long clearedInputTokens`

    Number of input tokens cleared by this edit.

  - `long clearedToolUses`

    Number of tool uses that were cleared.

  - `JsonValue; type "clear_tool_uses_20250919"constant`

    The type of context management edit applied.

    - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

### Beta Code Execution Output Block

- `class BetaCodeExecutionOutputBlock:`

  - `String fileId`

  - `JsonValue; type "code_execution_output"constant`

    - `CODE_EXECUTION_OUTPUT("code_execution_output")`

### Beta Code Execution Output Block Param

- `class BetaCodeExecutionOutputBlockParam:`

  - `String fileId`

  - `JsonValue; type "code_execution_output"constant`

    - `CODE_EXECUTION_OUTPUT("code_execution_output")`

### Beta Code Execution Result Block

- `class BetaCodeExecutionResultBlock:`

  - `List<BetaCodeExecutionOutputBlock> content`

    - `String fileId`

    - `JsonValue; type "code_execution_output"constant`

      - `CODE_EXECUTION_OUTPUT("code_execution_output")`

  - `long returnCode`

  - `String stderr`

  - `String stdout`

  - `JsonValue; type "code_execution_result"constant`

    - `CODE_EXECUTION_RESULT("code_execution_result")`

### Beta Code Execution Result Block Param

- `class BetaCodeExecutionResultBlockParam:`

  - `List<BetaCodeExecutionOutputBlockParam> content`

    - `String fileId`

    - `JsonValue; type "code_execution_output"constant`

      - `CODE_EXECUTION_OUTPUT("code_execution_output")`

  - `long returnCode`

  - `String stderr`

  - `String stdout`

  - `JsonValue; type "code_execution_result"constant`

    - `CODE_EXECUTION_RESULT("code_execution_result")`

### Beta Code Execution Tool 20250522

- `class BetaCodeExecutionTool20250522:`

  - `JsonValue; name "code_execution"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `CODE_EXECUTION("code_execution")`

  - `JsonValue; type "code_execution_20250522"constant`

    - `CODE_EXECUTION_20250522("code_execution_20250522")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Code Execution Tool 20250825

- `class BetaCodeExecutionTool20250825:`

  - `JsonValue; name "code_execution"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `CODE_EXECUTION("code_execution")`

  - `JsonValue; type "code_execution_20250825"constant`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Code Execution Tool 20260120

- `class BetaCodeExecutionTool20260120:`

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

  - `JsonValue; name "code_execution"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `CODE_EXECUTION("code_execution")`

  - `JsonValue; type "code_execution_20260120"constant`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Code Execution Tool Result Block

- `class BetaCodeExecutionToolResultBlock:`

  - `BetaCodeExecutionToolResultBlockContent content`

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

    - `class BetaCodeExecutionToolResultError:`

      - `BetaCodeExecutionToolResultErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `UNAVAILABLE("unavailable")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

      - `JsonValue; type "code_execution_tool_result_error"constant`

        - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

    - `class BetaCodeExecutionResultBlock:`

      - `List<BetaCodeExecutionOutputBlock> content`

        - `String fileId`

        - `JsonValue; type "code_execution_output"constant`

          - `CODE_EXECUTION_OUTPUT("code_execution_output")`

      - `long returnCode`

      - `String stderr`

      - `String stdout`

      - `JsonValue; type "code_execution_result"constant`

        - `CODE_EXECUTION_RESULT("code_execution_result")`

    - `class BetaEncryptedCodeExecutionResultBlock:`

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

      - `List<BetaCodeExecutionOutputBlock> content`

        - `String fileId`

        - `JsonValue; type "code_execution_output"constant`

      - `String encryptedStdout`

      - `long returnCode`

      - `String stderr`

      - `JsonValue; type "encrypted_code_execution_result"constant`

        - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

  - `String toolUseId`

  - `JsonValue; type "code_execution_tool_result"constant`

    - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

### Beta Code Execution Tool Result Block Content

- `class BetaCodeExecutionToolResultBlockContent: A class that can be one of several variants.union`

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

  - `class BetaCodeExecutionToolResultError:`

    - `BetaCodeExecutionToolResultErrorCode errorCode`

      - `INVALID_TOOL_INPUT("invalid_tool_input")`

      - `UNAVAILABLE("unavailable")`

      - `TOO_MANY_REQUESTS("too_many_requests")`

      - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

    - `JsonValue; type "code_execution_tool_result_error"constant`

      - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

  - `class BetaCodeExecutionResultBlock:`

    - `List<BetaCodeExecutionOutputBlock> content`

      - `String fileId`

      - `JsonValue; type "code_execution_output"constant`

        - `CODE_EXECUTION_OUTPUT("code_execution_output")`

    - `long returnCode`

    - `String stderr`

    - `String stdout`

    - `JsonValue; type "code_execution_result"constant`

      - `CODE_EXECUTION_RESULT("code_execution_result")`

  - `class BetaEncryptedCodeExecutionResultBlock:`

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

    - `List<BetaCodeExecutionOutputBlock> content`

      - `String fileId`

      - `JsonValue; type "code_execution_output"constant`

    - `String encryptedStdout`

    - `long returnCode`

    - `String stderr`

    - `JsonValue; type "encrypted_code_execution_result"constant`

      - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

### Beta Code Execution Tool Result Block Param

- `class BetaCodeExecutionToolResultBlockParam:`

  - `BetaCodeExecutionToolResultBlockParamContent content`

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

    - `class BetaCodeExecutionToolResultErrorParam:`

      - `BetaCodeExecutionToolResultErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `UNAVAILABLE("unavailable")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

      - `JsonValue; type "code_execution_tool_result_error"constant`

        - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

    - `class BetaCodeExecutionResultBlockParam:`

      - `List<BetaCodeExecutionOutputBlockParam> content`

        - `String fileId`

        - `JsonValue; type "code_execution_output"constant`

          - `CODE_EXECUTION_OUTPUT("code_execution_output")`

      - `long returnCode`

      - `String stderr`

      - `String stdout`

      - `JsonValue; type "code_execution_result"constant`

        - `CODE_EXECUTION_RESULT("code_execution_result")`

    - `class BetaEncryptedCodeExecutionResultBlockParam:`

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

      - `List<BetaCodeExecutionOutputBlockParam> content`

        - `String fileId`

        - `JsonValue; type "code_execution_output"constant`

      - `String encryptedStdout`

      - `long returnCode`

      - `String stderr`

      - `JsonValue; type "encrypted_code_execution_result"constant`

        - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

  - `String toolUseId`

  - `JsonValue; type "code_execution_tool_result"constant`

    - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

### Beta Code Execution Tool Result Block Param Content

- `class BetaCodeExecutionToolResultBlockParamContent: A class that can be one of several variants.union`

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

  - `class BetaCodeExecutionToolResultErrorParam:`

    - `BetaCodeExecutionToolResultErrorCode errorCode`

      - `INVALID_TOOL_INPUT("invalid_tool_input")`

      - `UNAVAILABLE("unavailable")`

      - `TOO_MANY_REQUESTS("too_many_requests")`

      - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

    - `JsonValue; type "code_execution_tool_result_error"constant`

      - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

  - `class BetaCodeExecutionResultBlockParam:`

    - `List<BetaCodeExecutionOutputBlockParam> content`

      - `String fileId`

      - `JsonValue; type "code_execution_output"constant`

        - `CODE_EXECUTION_OUTPUT("code_execution_output")`

    - `long returnCode`

    - `String stderr`

    - `String stdout`

    - `JsonValue; type "code_execution_result"constant`

      - `CODE_EXECUTION_RESULT("code_execution_result")`

  - `class BetaEncryptedCodeExecutionResultBlockParam:`

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

    - `List<BetaCodeExecutionOutputBlockParam> content`

      - `String fileId`

      - `JsonValue; type "code_execution_output"constant`

    - `String encryptedStdout`

    - `long returnCode`

    - `String stderr`

    - `JsonValue; type "encrypted_code_execution_result"constant`

      - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

### Beta Code Execution Tool Result Error

- `class BetaCodeExecutionToolResultError:`

  - `BetaCodeExecutionToolResultErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `UNAVAILABLE("unavailable")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

  - `JsonValue; type "code_execution_tool_result_error"constant`

    - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

### Beta Code Execution Tool Result Error Code

- `enum BetaCodeExecutionToolResultErrorCode:`

  - `INVALID_TOOL_INPUT("invalid_tool_input")`

  - `UNAVAILABLE("unavailable")`

  - `TOO_MANY_REQUESTS("too_many_requests")`

  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

### Beta Code Execution Tool Result Error Param

- `class BetaCodeExecutionToolResultErrorParam:`

  - `BetaCodeExecutionToolResultErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `UNAVAILABLE("unavailable")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

  - `JsonValue; type "code_execution_tool_result_error"constant`

    - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

### Beta Compact 20260112 Edit

- `class BetaCompact20260112Edit:`

  Automatically compact older context when reaching the configured trigger threshold.

  - `JsonValue; type "compact_20260112"constant`

    - `COMPACT_20260112("compact_20260112")`

  - `Optional<String> instructions`

    Additional instructions for summarization.

  - `Optional<Boolean> pauseAfterCompaction`

    Whether to pause after compaction and return the compaction block to the user.

  - `Optional<BetaInputTokensTrigger> trigger`

    When to trigger compaction. Defaults to 150000 input tokens.

    - `JsonValue; type "input_tokens"constant`

      - `INPUT_TOKENS("input_tokens")`

    - `long value`

### Beta Compaction Block

- `class BetaCompactionBlock:`

  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.

  - `Optional<String> content`

    Summary of compacted content, or null if compaction failed

  - `Optional<String> encryptedContent`

    Opaque metadata from prior compaction, to be round-tripped verbatim

  - `JsonValue; type "compaction"constant`

    - `COMPACTION("compaction")`

### Beta Compaction Block Param

- `class BetaCompactionBlockParam:`

  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.

  - `JsonValue; type "compaction"constant`

    - `COMPACTION("compaction")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<String> content`

    Summary of previously compacted content, or null if compaction failed

  - `Optional<String> encryptedContent`

    Opaque metadata from prior compaction, to be round-tripped verbatim

### Beta Compaction Content Block Delta

- `class BetaCompactionContentBlockDelta:`

  - `Optional<String> content`

  - `Optional<String> encryptedContent`

    Opaque metadata from prior compaction, to be round-tripped verbatim

  - `JsonValue; type "compaction_delta"constant`

    - `COMPACTION_DELTA("compaction_delta")`

### Beta Compaction Iteration Usage

- `class BetaCompactionIterationUsage:`

  Token usage for a compaction iteration.

  - `Optional<BetaCacheCreation> cacheCreation`

    Breakdown of cached tokens by TTL

    - `long ephemeral1hInputTokens`

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

    - `long ephemeral5mInputTokens`

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

  - `long cacheCreationInputTokens`

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

  - `long cacheReadInputTokens`

    The number of input tokens read from the cache.

  - `long inputTokens`

    The number of input tokens which were used.

  - `long outputTokens`

    The number of output tokens which were used.

  - `JsonValue; type "compaction"constant`

    Usage for a compaction iteration

    - `COMPACTION("compaction")`

### Beta Container

- `class BetaContainer:`

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

  - `String id`

    Identifier for the container used in this request

  - `LocalDateTime expiresAt`

    The time at which the container will expire.

  - `Optional<List<BetaSkill>> skills`

    Skills loaded in the container

    - `String skillId`

      Skill ID

    - `Type type`

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

      - `ANTHROPIC("anthropic")`

      - `CUSTOM("custom")`

    - `String version`

      Skill version or 'latest' for most recent version

### Beta Container Params

- `class BetaContainerParams:`

  Container parameters with skills to be loaded.

  - `Optional<String> id`

    Container id

  - `Optional<List<BetaSkillParams>> skills`

    List of skills to load in the container

    - `String skillId`

      Skill ID

    - `Type type`

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

      - `ANTHROPIC("anthropic")`

      - `CUSTOM("custom")`

    - `Optional<String> version`

      Skill version or 'latest' for most recent version

### Beta Container Upload Block

- `class BetaContainerUploadBlock:`

  Response model for a file uploaded to the container.

  - `String fileId`

  - `JsonValue; type "container_upload"constant`

    - `CONTAINER_UPLOAD("container_upload")`

### Beta Container Upload Block Param

- `class BetaContainerUploadBlockParam:`

  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.

  - `String fileId`

  - `JsonValue; type "container_upload"constant`

    - `CONTAINER_UPLOAD("container_upload")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

### Beta Content Block

- `class BetaContentBlock: A class that can be one of several variants.union`

  Response model for a file uploaded to the container.

  - `class BetaTextBlock:`

    - `Optional<List<BetaTextCitation>> citations`

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

      - `class BetaCitationCharLocation:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endCharIndex`

        - `Optional<String> fileId`

        - `long startCharIndex`

        - `JsonValue; type "char_location"constant`

          - `CHAR_LOCATION("char_location")`

      - `class BetaCitationPageLocation:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endPageNumber`

        - `Optional<String> fileId`

        - `long startPageNumber`

        - `JsonValue; type "page_location"constant`

          - `PAGE_LOCATION("page_location")`

      - `class BetaCitationContentBlockLocation:`

        - `String citedText`

          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.

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endBlockIndex`

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

        - `Optional<String> fileId`

        - `long startBlockIndex`

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

        - `JsonValue; type "content_block_location"constant`

          - `CONTENT_BLOCK_LOCATION("content_block_location")`

      - `class BetaCitationsWebSearchResultLocation:`

        - `String citedText`

        - `String encryptedIndex`

        - `Optional<String> title`

        - `JsonValue; type "web_search_result_location"constant`

          - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

        - `String url`

      - `class BetaCitationSearchResultLocation:`

        - `String citedText`

          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.

        - `long endBlockIndex`

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

        - `long searchResultIndex`

          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.

        - `String source`

        - `long startBlockIndex`

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

        - `Optional<String> title`

        - `JsonValue; type "search_result_location"constant`

          - `SEARCH_RESULT_LOCATION("search_result_location")`

    - `String text`

    - `JsonValue; type "text"constant`

      - `TEXT("text")`

  - `class BetaThinkingBlock:`

    - `String signature`

    - `String thinking`

    - `JsonValue; type "thinking"constant`

      - `THINKING("thinking")`

  - `class BetaRedactedThinkingBlock:`

    - `String data`

    - `JsonValue; type "redacted_thinking"constant`

      - `REDACTED_THINKING("redacted_thinking")`

  - `class BetaToolUseBlock:`

    - `String id`

    - `Input input`

    - `String name`

    - `JsonValue; type "tool_use"constant`

      - `TOOL_USE("tool_use")`

    - `Optional<Caller> caller`

      Tool invocation directly from the model.

      - `class BetaDirectCaller:`

        Tool invocation directly from the model.

        - `JsonValue; type "direct"constant`

          - `DIRECT("direct")`

      - `class BetaServerToolCaller:`

        Tool invocation generated by a server-side tool.

        - `String toolId`

        - `JsonValue; type "code_execution_20250825"constant`

          - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `class BetaServerToolCaller20260120:`

        - `String toolId`

        - `JsonValue; type "code_execution_20260120"constant`

          - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `class BetaServerToolUseBlock:`

    - `String id`

    - `Input input`

    - `Name name`

      - `ADVISOR("advisor")`

      - `WEB_SEARCH("web_search")`

      - `WEB_FETCH("web_fetch")`

      - `CODE_EXECUTION("code_execution")`

      - `BASH_CODE_EXECUTION("bash_code_execution")`

      - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

      - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

      - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

    - `JsonValue; type "server_tool_use"constant`

      - `SERVER_TOOL_USE("server_tool_use")`

    - `Optional<Caller> caller`

      Tool invocation directly from the model.

      - `class BetaDirectCaller:`

        Tool invocation directly from the model.

      - `class BetaServerToolCaller:`

        Tool invocation generated by a server-side tool.

      - `class BetaServerToolCaller20260120:`

  - `class BetaWebSearchToolResultBlock:`

    - `BetaWebSearchToolResultBlockContent content`

      - `class BetaWebSearchToolResultError:`

        - `BetaWebSearchToolResultErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `UNAVAILABLE("unavailable")`

          - `MAX_USES_EXCEEDED("max_uses_exceeded")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `QUERY_TOO_LONG("query_too_long")`

          - `REQUEST_TOO_LARGE("request_too_large")`

        - `JsonValue; type "web_search_tool_result_error"constant`

          - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

      - `List<BetaWebSearchResultBlock>`

        - `String encryptedContent`

        - `Optional<String> pageAge`

        - `String title`

        - `JsonValue; type "web_search_result"constant`

          - `WEB_SEARCH_RESULT("web_search_result")`

        - `String url`

    - `String toolUseId`

    - `JsonValue; type "web_search_tool_result"constant`

      - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

    - `Optional<Caller> caller`

      Tool invocation directly from the model.

      - `class BetaDirectCaller:`

        Tool invocation directly from the model.

      - `class BetaServerToolCaller:`

        Tool invocation generated by a server-side tool.

      - `class BetaServerToolCaller20260120:`

  - `class BetaWebFetchToolResultBlock:`

    - `Content content`

      - `class BetaWebFetchToolResultErrorBlock:`

        - `BetaWebFetchToolResultErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `URL_TOO_LONG("url_too_long")`

          - `URL_NOT_ALLOWED("url_not_allowed")`

          - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

          - `URL_NOT_ACCESSIBLE("url_not_accessible")`

          - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `MAX_USES_EXCEEDED("max_uses_exceeded")`

          - `UNAVAILABLE("unavailable")`

        - `JsonValue; type "web_fetch_tool_result_error"constant`

          - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

      - `class BetaWebFetchBlock:`

        - `BetaDocumentBlock content`

          - `Optional<BetaCitationConfig> citations`

            Citation configuration for the document

            - `boolean enabled`

          - `Source source`

            - `class BetaBase64PdfSource:`

              - `String data`

              - `JsonValue; mediaType "application/pdf"constant`

                - `APPLICATION_PDF("application/pdf")`

              - `JsonValue; type "base64"constant`

                - `BASE64("base64")`

            - `class BetaPlainTextSource:`

              - `String data`

              - `JsonValue; mediaType "text/plain"constant`

                - `TEXT_PLAIN("text/plain")`

              - `JsonValue; type "text"constant`

                - `TEXT("text")`

          - `Optional<String> title`

            The title of the document

          - `JsonValue; type "document"constant`

            - `DOCUMENT("document")`

        - `Optional<String> retrievedAt`

          ISO 8601 timestamp when the content was retrieved

        - `JsonValue; type "web_fetch_result"constant`

          - `WEB_FETCH_RESULT("web_fetch_result")`

        - `String url`

          Fetched content URL

    - `String toolUseId`

    - `JsonValue; type "web_fetch_tool_result"constant`

      - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

    - `Optional<Caller> caller`

      Tool invocation directly from the model.

      - `class BetaDirectCaller:`

        Tool invocation directly from the model.

      - `class BetaServerToolCaller:`

        Tool invocation generated by a server-side tool.

      - `class BetaServerToolCaller20260120:`

  - `class BetaAdvisorToolResultBlock:`

    - `Content content`

      - `class BetaAdvisorToolResultError:`

        - `ErrorCode errorCode`

          - `MAX_USES_EXCEEDED("max_uses_exceeded")`

          - `PROMPT_TOO_LONG("prompt_too_long")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `OVERLOADED("overloaded")`

          - `UNAVAILABLE("unavailable")`

          - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `MODEL_NOT_FOUND("model_not_found")`

        - `JsonValue; type "advisor_tool_result_error"constant`

          - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

      - `class BetaAdvisorResultBlock:`

        - `Optional<String> stopReason`

          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.

        - `String text`

        - `JsonValue; type "advisor_result"constant`

          - `ADVISOR_RESULT("advisor_result")`

      - `class BetaAdvisorRedactedResultBlock:`

        - `String encryptedContent`

          Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

        - `Optional<String> stopReason`

          The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

        - `JsonValue; type "advisor_redacted_result"constant`

          - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

    - `String toolUseId`

    - `JsonValue; type "advisor_tool_result"constant`

      - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

  - `class BetaCodeExecutionToolResultBlock:`

    - `BetaCodeExecutionToolResultBlockContent content`

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

      - `class BetaCodeExecutionToolResultError:`

        - `BetaCodeExecutionToolResultErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `UNAVAILABLE("unavailable")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

        - `JsonValue; type "code_execution_tool_result_error"constant`

          - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

      - `class BetaCodeExecutionResultBlock:`

        - `List<BetaCodeExecutionOutputBlock> content`

          - `String fileId`

          - `JsonValue; type "code_execution_output"constant`

            - `CODE_EXECUTION_OUTPUT("code_execution_output")`

        - `long returnCode`

        - `String stderr`

        - `String stdout`

        - `JsonValue; type "code_execution_result"constant`

          - `CODE_EXECUTION_RESULT("code_execution_result")`

      - `class BetaEncryptedCodeExecutionResultBlock:`

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

        - `List<BetaCodeExecutionOutputBlock> content`

          - `String fileId`

          - `JsonValue; type "code_execution_output"constant`

        - `String encryptedStdout`

        - `long returnCode`

        - `String stderr`

        - `JsonValue; type "encrypted_code_execution_result"constant`

          - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

    - `String toolUseId`

    - `JsonValue; type "code_execution_tool_result"constant`

      - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

  - `class BetaBashCodeExecutionToolResultBlock:`

    - `Content content`

      - `class BetaBashCodeExecutionToolResultError:`

        - `ErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `UNAVAILABLE("unavailable")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

        - `JsonValue; type "bash_code_execution_tool_result_error"constant`

          - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

      - `class BetaBashCodeExecutionResultBlock:`

        - `List<BetaBashCodeExecutionOutputBlock> content`

          - `String fileId`

          - `JsonValue; type "bash_code_execution_output"constant`

            - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

        - `long returnCode`

        - `String stderr`

        - `String stdout`

        - `JsonValue; type "bash_code_execution_result"constant`

          - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

    - `String toolUseId`

    - `JsonValue; type "bash_code_execution_tool_result"constant`

      - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

  - `class BetaTextEditorCodeExecutionToolResultBlock:`

    - `Content content`

      - `class BetaTextEditorCodeExecutionToolResultError:`

        - `ErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `UNAVAILABLE("unavailable")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `FILE_NOT_FOUND("file_not_found")`

        - `Optional<String> errorMessage`

        - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

      - `class BetaTextEditorCodeExecutionViewResultBlock:`

        - `String content`

        - `FileType fileType`

          - `TEXT("text")`

          - `IMAGE("image")`

          - `PDF("pdf")`

        - `Optional<Long> numLines`

        - `Optional<Long> startLine`

        - `Optional<Long> totalLines`

        - `JsonValue; type "text_editor_code_execution_view_result"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

      - `class BetaTextEditorCodeExecutionCreateResultBlock:`

        - `boolean isFileUpdate`

        - `JsonValue; type "text_editor_code_execution_create_result"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

      - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

        - `Optional<List<String>> lines`

        - `Optional<Long> newLines`

        - `Optional<Long> newStart`

        - `Optional<Long> oldLines`

        - `Optional<Long> oldStart`

        - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

    - `String toolUseId`

    - `JsonValue; type "text_editor_code_execution_tool_result"constant`

      - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

  - `class BetaToolSearchToolResultBlock:`

    - `Content content`

      - `class BetaToolSearchToolResultError:`

        - `ErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `UNAVAILABLE("unavailable")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

        - `Optional<String> errorMessage`

        - `JsonValue; type "tool_search_tool_result_error"constant`

          - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

      - `class BetaToolSearchToolSearchResultBlock:`

        - `List<BetaToolReferenceBlock> toolReferences`

          - `String toolName`

          - `JsonValue; type "tool_reference"constant`

            - `TOOL_REFERENCE("tool_reference")`

        - `JsonValue; type "tool_search_tool_search_result"constant`

          - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

    - `String toolUseId`

    - `JsonValue; type "tool_search_tool_result"constant`

      - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

  - `class BetaMcpToolUseBlock:`

    - `String id`

    - `Input input`

    - `String name`

      The name of the MCP tool

    - `String serverName`

      The name of the MCP server

    - `JsonValue; type "mcp_tool_use"constant`

      - `MCP_TOOL_USE("mcp_tool_use")`

  - `class BetaMcpToolResultBlock:`

    - `Content content`

      - `String`

      - `List<BetaTextBlock>`

        - `Optional<List<BetaTextCitation>> citations`

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

        - `String text`

        - `JsonValue; type "text"constant`

    - `boolean isError`

    - `String toolUseId`

    - `JsonValue; type "mcp_tool_result"constant`

      - `MCP_TOOL_RESULT("mcp_tool_result")`

  - `class BetaContainerUploadBlock:`

    Response model for a file uploaded to the container.

    - `String fileId`

    - `JsonValue; type "container_upload"constant`

      - `CONTAINER_UPLOAD("container_upload")`

  - `class BetaCompactionBlock:`

    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.

    - `Optional<String> content`

      Summary of compacted content, or null if compaction failed

    - `Optional<String> encryptedContent`

      Opaque metadata from prior compaction, to be round-tripped verbatim

    - `JsonValue; type "compaction"constant`

      - `COMPACTION("compaction")`

  - `class BetaFallbackBlock:`

    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 routed directly by the sticky decision 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.

    - `BetaFallbackInfo from`

      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.

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_MYTHOS_5("claude-mythos-5")`

          Most capable model for cybersecurity and biology research

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

          New class of intelligence, strongest in coding and cybersecurity

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

        - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

          Exceptional model for specialized complex tasks

        - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

          Exceptional model for specialized complex tasks

        - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

          Powerful model for complex tasks

        - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

          Powerful model for complex tasks

        - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

          High-performance model with extended thinking

        - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

          High-performance model with extended thinking

        - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

          Fast and cost-effective model

    - `BetaFallbackInfo to`

      The fallback model producing the content that follows this block. Its `model` is always the canonical id.

    - `JsonValue; type "fallback"constant`

      - `FALLBACK("fallback")`

### Beta Content Block Param

- `class BetaContentBlockParam: A class that can be one of several variants.union`

  Regular text content.

  - `class BetaTextBlockParam:`

    - `String text`

    - `JsonValue; type "text"constant`

      - `TEXT("text")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

      - `JsonValue; type "ephemeral"constant`

        - `EPHEMERAL("ephemeral")`

      - `Optional<Ttl> ttl`

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

        - `TTL_5M("5m")`

        - `TTL_1H("1h")`

    - `Optional<List<BetaTextCitationParam>> citations`

      - `class BetaCitationCharLocationParam:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endCharIndex`

        - `long startCharIndex`

        - `JsonValue; type "char_location"constant`

          - `CHAR_LOCATION("char_location")`

      - `class BetaCitationPageLocationParam:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endPageNumber`

        - `long startPageNumber`

        - `JsonValue; type "page_location"constant`

          - `PAGE_LOCATION("page_location")`

      - `class BetaCitationContentBlockLocationParam:`

        - `String citedText`

          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.

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endBlockIndex`

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

        - `long startBlockIndex`

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

        - `JsonValue; type "content_block_location"constant`

          - `CONTENT_BLOCK_LOCATION("content_block_location")`

      - `class BetaCitationWebSearchResultLocationParam:`

        - `String citedText`

        - `String encryptedIndex`

        - `Optional<String> title`

        - `JsonValue; type "web_search_result_location"constant`

          - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

        - `String url`

      - `class BetaCitationSearchResultLocationParam:`

        - `String citedText`

          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.

        - `long endBlockIndex`

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

        - `long searchResultIndex`

          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.

        - `String source`

        - `long startBlockIndex`

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

        - `Optional<String> title`

        - `JsonValue; type "search_result_location"constant`

          - `SEARCH_RESULT_LOCATION("search_result_location")`

  - `class BetaImageBlockParam:`

    - `Source source`

      - `class BetaBase64ImageSource:`

        - `String data`

        - `MediaType mediaType`

          - `IMAGE_JPEG("image/jpeg")`

          - `IMAGE_PNG("image/png")`

          - `IMAGE_GIF("image/gif")`

          - `IMAGE_WEBP("image/webp")`

        - `JsonValue; type "base64"constant`

          - `BASE64("base64")`

      - `class BetaUrlImageSource:`

        - `JsonValue; type "url"constant`

          - `URL("url")`

        - `String url`

      - `class BetaFileImageSource:`

        - `String fileId`

        - `JsonValue; type "file"constant`

          - `FILE("file")`

    - `JsonValue; type "image"constant`

      - `IMAGE("image")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

  - `class BetaRequestDocumentBlock:`

    - `Source source`

      - `class BetaBase64PdfSource:`

        - `String data`

        - `JsonValue; mediaType "application/pdf"constant`

          - `APPLICATION_PDF("application/pdf")`

        - `JsonValue; type "base64"constant`

          - `BASE64("base64")`

      - `class BetaPlainTextSource:`

        - `String data`

        - `JsonValue; mediaType "text/plain"constant`

          - `TEXT_PLAIN("text/plain")`

        - `JsonValue; type "text"constant`

          - `TEXT("text")`

      - `class BetaContentBlockSource:`

        - `Content content`

          - `String`

          - `List<BetaContentBlockSourceContent>`

            - `class BetaTextBlockParam:`

            - `class BetaImageBlockParam:`

        - `JsonValue; type "content"constant`

          - `CONTENT("content")`

      - `class BetaUrlPdfSource:`

        - `JsonValue; type "url"constant`

          - `URL("url")`

        - `String url`

      - `class BetaFileDocumentSource:`

        - `String fileId`

        - `JsonValue; type "file"constant`

          - `FILE("file")`

    - `JsonValue; type "document"constant`

      - `DOCUMENT("document")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<BetaCitationsConfigParam> citations`

      - `Optional<Boolean> enabled`

    - `Optional<String> context`

    - `Optional<String> title`

  - `class BetaSearchResultBlockParam:`

    - `List<BetaTextBlockParam> content`

      - `String text`

      - `JsonValue; type "text"constant`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<List<BetaTextCitationParam>> citations`

    - `String source`

    - `String title`

    - `JsonValue; type "search_result"constant`

      - `SEARCH_RESULT("search_result")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<BetaCitationsConfigParam> citations`

  - `class BetaThinkingBlockParam:`

    - `String signature`

    - `String thinking`

    - `JsonValue; type "thinking"constant`

      - `THINKING("thinking")`

  - `class BetaRedactedThinkingBlockParam:`

    - `String data`

    - `JsonValue; type "redacted_thinking"constant`

      - `REDACTED_THINKING("redacted_thinking")`

  - `class BetaToolUseBlockParam:`

    - `String id`

    - `Input input`

    - `String name`

    - `JsonValue; type "tool_use"constant`

      - `TOOL_USE("tool_use")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Caller> caller`

      Tool invocation directly from the model.

      - `class BetaDirectCaller:`

        Tool invocation directly from the model.

        - `JsonValue; type "direct"constant`

          - `DIRECT("direct")`

      - `class BetaServerToolCaller:`

        Tool invocation generated by a server-side tool.

        - `String toolId`

        - `JsonValue; type "code_execution_20250825"constant`

          - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `class BetaServerToolCaller20260120:`

        - `String toolId`

        - `JsonValue; type "code_execution_20260120"constant`

          - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `class BetaToolResultBlockParam:`

    - `String toolUseId`

    - `JsonValue; type "tool_result"constant`

      - `TOOL_RESULT("tool_result")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Content> content`

      - `String`

      - `List<Block>`

        - `class BetaTextBlockParam:`

        - `class BetaImageBlockParam:`

        - `class BetaSearchResultBlockParam:`

        - `class BetaRequestDocumentBlock:`

        - `class BetaToolReferenceBlockParam:`

          Tool reference block that can be included in tool_result content.

          - `String toolName`

          - `JsonValue; type "tool_reference"constant`

            - `TOOL_REFERENCE("tool_reference")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

    - `Optional<Boolean> isError`

  - `class BetaServerToolUseBlockParam:`

    - `String id`

    - `Input input`

    - `Name name`

      - `ADVISOR("advisor")`

      - `WEB_SEARCH("web_search")`

      - `WEB_FETCH("web_fetch")`

      - `CODE_EXECUTION("code_execution")`

      - `BASH_CODE_EXECUTION("bash_code_execution")`

      - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

      - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

      - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

    - `JsonValue; type "server_tool_use"constant`

      - `SERVER_TOOL_USE("server_tool_use")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Caller> caller`

      Tool invocation directly from the model.

      - `class BetaDirectCaller:`

        Tool invocation directly from the model.

      - `class BetaServerToolCaller:`

        Tool invocation generated by a server-side tool.

      - `class BetaServerToolCaller20260120:`

  - `class BetaWebSearchToolResultBlockParam:`

    - `BetaWebSearchToolResultBlockParamContent content`

      - `List<BetaWebSearchResultBlockParam>`

        - `String encryptedContent`

        - `String title`

        - `JsonValue; type "web_search_result"constant`

          - `WEB_SEARCH_RESULT("web_search_result")`

        - `String url`

        - `Optional<String> pageAge`

      - `class BetaWebSearchToolRequestError:`

        - `BetaWebSearchToolResultErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `UNAVAILABLE("unavailable")`

          - `MAX_USES_EXCEEDED("max_uses_exceeded")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `QUERY_TOO_LONG("query_too_long")`

          - `REQUEST_TOO_LARGE("request_too_large")`

        - `JsonValue; type "web_search_tool_result_error"constant`

          - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

    - `String toolUseId`

    - `JsonValue; type "web_search_tool_result"constant`

      - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Caller> caller`

      Tool invocation directly from the model.

      - `class BetaDirectCaller:`

        Tool invocation directly from the model.

      - `class BetaServerToolCaller:`

        Tool invocation generated by a server-side tool.

      - `class BetaServerToolCaller20260120:`

  - `class BetaWebFetchToolResultBlockParam:`

    - `Content content`

      - `class BetaWebFetchToolResultErrorBlockParam:`

        - `BetaWebFetchToolResultErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `URL_TOO_LONG("url_too_long")`

          - `URL_NOT_ALLOWED("url_not_allowed")`

          - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

          - `URL_NOT_ACCESSIBLE("url_not_accessible")`

          - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `MAX_USES_EXCEEDED("max_uses_exceeded")`

          - `UNAVAILABLE("unavailable")`

        - `JsonValue; type "web_fetch_tool_result_error"constant`

          - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

      - `class BetaWebFetchBlockParam:`

        - `BetaRequestDocumentBlock content`

        - `JsonValue; type "web_fetch_result"constant`

          - `WEB_FETCH_RESULT("web_fetch_result")`

        - `String url`

          Fetched content URL

        - `Optional<String> retrievedAt`

          ISO 8601 timestamp when the content was retrieved

    - `String toolUseId`

    - `JsonValue; type "web_fetch_tool_result"constant`

      - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Caller> caller`

      Tool invocation directly from the model.

      - `class BetaDirectCaller:`

        Tool invocation directly from the model.

      - `class BetaServerToolCaller:`

        Tool invocation generated by a server-side tool.

      - `class BetaServerToolCaller20260120:`

  - `class BetaAdvisorToolResultBlockParam:`

    - `Content content`

      - `class BetaAdvisorToolResultErrorParam:`

        - `ErrorCode errorCode`

          - `MAX_USES_EXCEEDED("max_uses_exceeded")`

          - `PROMPT_TOO_LONG("prompt_too_long")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `OVERLOADED("overloaded")`

          - `UNAVAILABLE("unavailable")`

          - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `MODEL_NOT_FOUND("model_not_found")`

        - `JsonValue; type "advisor_tool_result_error"constant`

          - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

      - `class BetaAdvisorResultBlockParam:`

        - `String text`

        - `JsonValue; type "advisor_result"constant`

          - `ADVISOR_RESULT("advisor_result")`

        - `Optional<String> stopReason`

      - `class BetaAdvisorRedactedResultBlockParam:`

        - `String encryptedContent`

          Opaque blob produced by a prior response; must be round-tripped verbatim.

        - `JsonValue; type "advisor_redacted_result"constant`

          - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

        - `Optional<String> stopReason`

    - `String toolUseId`

    - `JsonValue; type "advisor_tool_result"constant`

      - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

  - `class BetaCodeExecutionToolResultBlockParam:`

    - `BetaCodeExecutionToolResultBlockParamContent content`

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

      - `class BetaCodeExecutionToolResultErrorParam:`

        - `BetaCodeExecutionToolResultErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `UNAVAILABLE("unavailable")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

        - `JsonValue; type "code_execution_tool_result_error"constant`

          - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

      - `class BetaCodeExecutionResultBlockParam:`

        - `List<BetaCodeExecutionOutputBlockParam> content`

          - `String fileId`

          - `JsonValue; type "code_execution_output"constant`

            - `CODE_EXECUTION_OUTPUT("code_execution_output")`

        - `long returnCode`

        - `String stderr`

        - `String stdout`

        - `JsonValue; type "code_execution_result"constant`

          - `CODE_EXECUTION_RESULT("code_execution_result")`

      - `class BetaEncryptedCodeExecutionResultBlockParam:`

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

        - `List<BetaCodeExecutionOutputBlockParam> content`

          - `String fileId`

          - `JsonValue; type "code_execution_output"constant`

        - `String encryptedStdout`

        - `long returnCode`

        - `String stderr`

        - `JsonValue; type "encrypted_code_execution_result"constant`

          - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

    - `String toolUseId`

    - `JsonValue; type "code_execution_tool_result"constant`

      - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

  - `class BetaBashCodeExecutionToolResultBlockParam:`

    - `Content content`

      - `class BetaBashCodeExecutionToolResultErrorParam:`

        - `ErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `UNAVAILABLE("unavailable")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

        - `JsonValue; type "bash_code_execution_tool_result_error"constant`

          - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

      - `class BetaBashCodeExecutionResultBlockParam:`

        - `List<BetaBashCodeExecutionOutputBlockParam> content`

          - `String fileId`

          - `JsonValue; type "bash_code_execution_output"constant`

            - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

        - `long returnCode`

        - `String stderr`

        - `String stdout`

        - `JsonValue; type "bash_code_execution_result"constant`

          - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

    - `String toolUseId`

    - `JsonValue; type "bash_code_execution_tool_result"constant`

      - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

  - `class BetaTextEditorCodeExecutionToolResultBlockParam:`

    - `Content content`

      - `class BetaTextEditorCodeExecutionToolResultErrorParam:`

        - `ErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `UNAVAILABLE("unavailable")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `FILE_NOT_FOUND("file_not_found")`

        - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

        - `Optional<String> errorMessage`

      - `class BetaTextEditorCodeExecutionViewResultBlockParam:`

        - `String content`

        - `FileType fileType`

          - `TEXT("text")`

          - `IMAGE("image")`

          - `PDF("pdf")`

        - `JsonValue; type "text_editor_code_execution_view_result"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

        - `Optional<Long> numLines`

        - `Optional<Long> startLine`

        - `Optional<Long> totalLines`

      - `class BetaTextEditorCodeExecutionCreateResultBlockParam:`

        - `boolean isFileUpdate`

        - `JsonValue; type "text_editor_code_execution_create_result"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

      - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:`

        - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

        - `Optional<List<String>> lines`

        - `Optional<Long> newLines`

        - `Optional<Long> newStart`

        - `Optional<Long> oldLines`

        - `Optional<Long> oldStart`

    - `String toolUseId`

    - `JsonValue; type "text_editor_code_execution_tool_result"constant`

      - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

  - `class BetaToolSearchToolResultBlockParam:`

    - `Content content`

      - `class BetaToolSearchToolResultErrorParam:`

        - `ErrorCode errorCode`

          - `INVALID_TOOL_INPUT("invalid_tool_input")`

          - `UNAVAILABLE("unavailable")`

          - `TOO_MANY_REQUESTS("too_many_requests")`

          - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

        - `JsonValue; type "tool_search_tool_result_error"constant`

          - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

        - `Optional<String> errorMessage`

      - `class BetaToolSearchToolSearchResultBlockParam:`

        - `List<BetaToolReferenceBlockParam> toolReferences`

          - `String toolName`

          - `JsonValue; type "tool_reference"constant`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

        - `JsonValue; type "tool_search_tool_search_result"constant`

          - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

    - `String toolUseId`

    - `JsonValue; type "tool_search_tool_result"constant`

      - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

  - `class BetaMcpToolUseBlockParam:`

    - `String id`

    - `Input input`

    - `String name`

    - `String serverName`

      The name of the MCP server

    - `JsonValue; type "mcp_tool_use"constant`

      - `MCP_TOOL_USE("mcp_tool_use")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

  - `class BetaRequestMcpToolResultBlockParam:`

    - `String toolUseId`

    - `JsonValue; type "mcp_tool_result"constant`

      - `MCP_TOOL_RESULT("mcp_tool_result")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Content> content`

      - `String`

      - `List<BetaTextBlockParam>`

        - `String text`

        - `JsonValue; type "text"constant`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<List<BetaTextCitationParam>> citations`

    - `Optional<Boolean> isError`

  - `class BetaContainerUploadBlockParam:`

    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.

    - `String fileId`

    - `JsonValue; type "container_upload"constant`

      - `CONTAINER_UPLOAD("container_upload")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

  - `class BetaCompactionBlockParam:`

    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.

    - `JsonValue; type "compaction"constant`

      - `COMPACTION("compaction")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<String> content`

      Summary of previously compacted content, or null if compaction failed

    - `Optional<String> encryptedContent`

      Opaque metadata from prior compaction, to be round-tripped verbatim

  - `class BetaMidConversationSystemBlockParam:`

    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.

    - `List<BetaTextBlockParam> content`

      System instruction text blocks.

      - `String text`

      - `JsonValue; type "text"constant`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<List<BetaTextCitationParam>> citations`

    - `JsonValue; type "mid_conv_system"constant`

      - `MID_CONV_SYSTEM("mid_conv_system")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

  - `class BetaFallbackBlockParam:`

    A `fallback` block echoed back from a prior response.

    Accepted in `messages[].content` and never rendered into the prompt,
    not validated against the request's `fallbacks` chain or top-level
    `model`, and stripped before the sticky-routing cache key is computed.

    Callers should echo the assistant turn verbatim — block included. The
    block's position is load-bearing for thinking verification: the thinking
    runs on either side of a fallback hop carry independently-rooted
    verification hash chains, and this block is the only record of where one
    chain ends and the next begins. When thinking runs flank the boundary,
    omitting the block merges the runs into one contiguous span whose hashes
    cannot verify (the request is rejected), and moving it into the middle of
    a single run splits that run's chain and is likewise rejected; between
    non-thinking blocks the block's placement has no verification effect.

    - `BetaFallbackInfoParam from`

      Identifies one hop of a fallback transition.

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_MYTHOS_5("claude-mythos-5")`

          Most capable model for cybersecurity and biology research

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

          New class of intelligence, strongest in coding and cybersecurity

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

        - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

          Exceptional model for specialized complex tasks

        - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

          Exceptional model for specialized complex tasks

        - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

          Powerful model for complex tasks

        - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

          Powerful model for complex tasks

        - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

          High-performance model with extended thinking

        - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

          High-performance model with extended thinking

        - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

          Fast and cost-effective model

    - `BetaFallbackInfoParam to`

      Identifies one hop of a fallback transition.

    - `JsonValue; type "fallback"constant`

      - `FALLBACK("fallback")`

### Beta Content Block Source

- `class BetaContentBlockSource:`

  - `Content content`

    - `String`

    - `List<BetaContentBlockSourceContent>`

      - `class BetaTextBlockParam:`

        - `String text`

        - `JsonValue; type "text"constant`

          - `TEXT("text")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

          - `JsonValue; type "ephemeral"constant`

            - `EPHEMERAL("ephemeral")`

          - `Optional<Ttl> ttl`

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

            - `TTL_5M("5m")`

            - `TTL_1H("1h")`

        - `Optional<List<BetaTextCitationParam>> citations`

          - `class BetaCitationCharLocationParam:`

            - `String citedText`

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endCharIndex`

            - `long startCharIndex`

            - `JsonValue; type "char_location"constant`

              - `CHAR_LOCATION("char_location")`

          - `class BetaCitationPageLocationParam:`

            - `String citedText`

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endPageNumber`

            - `long startPageNumber`

            - `JsonValue; type "page_location"constant`

              - `PAGE_LOCATION("page_location")`

          - `class BetaCitationContentBlockLocationParam:`

            - `String citedText`

              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.

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endBlockIndex`

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

            - `long startBlockIndex`

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

            - `JsonValue; type "content_block_location"constant`

              - `CONTENT_BLOCK_LOCATION("content_block_location")`

          - `class BetaCitationWebSearchResultLocationParam:`

            - `String citedText`

            - `String encryptedIndex`

            - `Optional<String> title`

            - `JsonValue; type "web_search_result_location"constant`

              - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

            - `String url`

          - `class BetaCitationSearchResultLocationParam:`

            - `String citedText`

              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.

            - `long endBlockIndex`

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

            - `long searchResultIndex`

              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.

            - `String source`

            - `long startBlockIndex`

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

            - `Optional<String> title`

            - `JsonValue; type "search_result_location"constant`

              - `SEARCH_RESULT_LOCATION("search_result_location")`

      - `class BetaImageBlockParam:`

        - `Source source`

          - `class BetaBase64ImageSource:`

            - `String data`

            - `MediaType mediaType`

              - `IMAGE_JPEG("image/jpeg")`

              - `IMAGE_PNG("image/png")`

              - `IMAGE_GIF("image/gif")`

              - `IMAGE_WEBP("image/webp")`

            - `JsonValue; type "base64"constant`

              - `BASE64("base64")`

          - `class BetaUrlImageSource:`

            - `JsonValue; type "url"constant`

              - `URL("url")`

            - `String url`

          - `class BetaFileImageSource:`

            - `String fileId`

            - `JsonValue; type "file"constant`

              - `FILE("file")`

        - `JsonValue; type "image"constant`

          - `IMAGE("image")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

  - `JsonValue; type "content"constant`

    - `CONTENT("content")`

### Beta Content Block Source Content

- `class BetaContentBlockSourceContent: A class that can be one of several variants.union`

  - `class BetaTextBlockParam:`

    - `String text`

    - `JsonValue; type "text"constant`

      - `TEXT("text")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

      - `JsonValue; type "ephemeral"constant`

        - `EPHEMERAL("ephemeral")`

      - `Optional<Ttl> ttl`

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

        - `TTL_5M("5m")`

        - `TTL_1H("1h")`

    - `Optional<List<BetaTextCitationParam>> citations`

      - `class BetaCitationCharLocationParam:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endCharIndex`

        - `long startCharIndex`

        - `JsonValue; type "char_location"constant`

          - `CHAR_LOCATION("char_location")`

      - `class BetaCitationPageLocationParam:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endPageNumber`

        - `long startPageNumber`

        - `JsonValue; type "page_location"constant`

          - `PAGE_LOCATION("page_location")`

      - `class BetaCitationContentBlockLocationParam:`

        - `String citedText`

          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.

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endBlockIndex`

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

        - `long startBlockIndex`

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

        - `JsonValue; type "content_block_location"constant`

          - `CONTENT_BLOCK_LOCATION("content_block_location")`

      - `class BetaCitationWebSearchResultLocationParam:`

        - `String citedText`

        - `String encryptedIndex`

        - `Optional<String> title`

        - `JsonValue; type "web_search_result_location"constant`

          - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

        - `String url`

      - `class BetaCitationSearchResultLocationParam:`

        - `String citedText`

          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.

        - `long endBlockIndex`

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

        - `long searchResultIndex`

          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.

        - `String source`

        - `long startBlockIndex`

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

        - `Optional<String> title`

        - `JsonValue; type "search_result_location"constant`

          - `SEARCH_RESULT_LOCATION("search_result_location")`

  - `class BetaImageBlockParam:`

    - `Source source`

      - `class BetaBase64ImageSource:`

        - `String data`

        - `MediaType mediaType`

          - `IMAGE_JPEG("image/jpeg")`

          - `IMAGE_PNG("image/png")`

          - `IMAGE_GIF("image/gif")`

          - `IMAGE_WEBP("image/webp")`

        - `JsonValue; type "base64"constant`

          - `BASE64("base64")`

      - `class BetaUrlImageSource:`

        - `JsonValue; type "url"constant`

          - `URL("url")`

        - `String url`

      - `class BetaFileImageSource:`

        - `String fileId`

        - `JsonValue; type "file"constant`

          - `FILE("file")`

    - `JsonValue; type "image"constant`

      - `IMAGE("image")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

### Beta Context Management Config

- `class BetaContextManagementConfig:`

  - `Optional<List<Edit>> edits`

    List of context management edits to apply

    - `class BetaClearToolUses20250919Edit:`

      - `JsonValue; type "clear_tool_uses_20250919"constant`

        - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

      - `Optional<BetaInputTokensClearAtLeast> clearAtLeast`

        Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed.

        - `JsonValue; type "input_tokens"constant`

          - `INPUT_TOKENS("input_tokens")`

        - `long value`

      - `Optional<ClearToolInputs> clearToolInputs`

        Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)

        - `boolean`

        - `List<String>`

      - `Optional<List<String>> excludeTools`

        Tool names whose uses are preserved from clearing

      - `Optional<BetaToolUsesKeep> keep`

        Number of tool uses to retain in the conversation

        - `JsonValue; type "tool_uses"constant`

          - `TOOL_USES("tool_uses")`

        - `long value`

      - `Optional<Trigger> trigger`

        Condition that triggers the context management strategy

        - `class BetaInputTokensTrigger:`

          - `JsonValue; type "input_tokens"constant`

            - `INPUT_TOKENS("input_tokens")`

          - `long value`

        - `class BetaToolUsesTrigger:`

          - `JsonValue; type "tool_uses"constant`

            - `TOOL_USES("tool_uses")`

          - `long value`

    - `class BetaClearThinking20251015Edit:`

      - `JsonValue; type "clear_thinking_20251015"constant`

        - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

      - `Optional<Keep> keep`

        Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.

        - `class BetaThinkingTurns:`

          - `JsonValue; type "thinking_turns"constant`

            - `THINKING_TURNS("thinking_turns")`

          - `long value`

        - `class BetaAllThinkingTurns:`

          - `JsonValue; type "all"constant`

            - `ALL("all")`

        - `JsonValue;`

          - `ALL("all")`

    - `class BetaCompact20260112Edit:`

      Automatically compact older context when reaching the configured trigger threshold.

      - `JsonValue; type "compact_20260112"constant`

        - `COMPACT_20260112("compact_20260112")`

      - `Optional<String> instructions`

        Additional instructions for summarization.

      - `Optional<Boolean> pauseAfterCompaction`

        Whether to pause after compaction and return the compaction block to the user.

      - `Optional<BetaInputTokensTrigger> trigger`

        When to trigger compaction. Defaults to 150000 input tokens.

### Beta Context Management Response

- `class BetaContextManagementResponse:`

  - `List<AppliedEdit> appliedEdits`

    List of context management edits that were applied.

    - `class BetaClearToolUses20250919EditResponse:`

      - `long clearedInputTokens`

        Number of input tokens cleared by this edit.

      - `long clearedToolUses`

        Number of tool uses that were cleared.

      - `JsonValue; type "clear_tool_uses_20250919"constant`

        The type of context management edit applied.

        - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

    - `class BetaClearThinking20251015EditResponse:`

      - `long clearedInputTokens`

        Number of input tokens cleared by this edit.

      - `long clearedThinkingTurns`

        Number of thinking turns that were cleared.

      - `JsonValue; type "clear_thinking_20251015"constant`

        The type of context management edit applied.

        - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

### Beta Count Tokens Context Management Response

- `class BetaCountTokensContextManagementResponse:`

  - `long originalInputTokens`

    The original token count before context management was applied

### Beta Diagnostics

- `class BetaDiagnostics:`

  Response envelope for request-level diagnostics. Present (possibly
  null) whenever the caller supplied `diagnostics` on the request.

  - `Optional<CacheMissReason> cacheMissReason`

    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.

    - `class BetaCacheMissModelChanged:`

      - `long cacheMissedInputTokens`

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

      - `JsonValue; type "model_changed"constant`

        - `MODEL_CHANGED("model_changed")`

    - `class BetaCacheMissSystemChanged:`

      - `long cacheMissedInputTokens`

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

      - `JsonValue; type "system_changed"constant`

        - `SYSTEM_CHANGED("system_changed")`

    - `class BetaCacheMissToolsChanged:`

      - `long cacheMissedInputTokens`

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

      - `JsonValue; type "tools_changed"constant`

        - `TOOLS_CHANGED("tools_changed")`

    - `class BetaCacheMissMessagesChanged:`

      - `long cacheMissedInputTokens`

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

      - `JsonValue; type "messages_changed"constant`

        - `MESSAGES_CHANGED("messages_changed")`

    - `class BetaCacheMissPreviousMessageNotFound:`

      - `JsonValue; type "previous_message_not_found"constant`

        - `PREVIOUS_MESSAGE_NOT_FOUND("previous_message_not_found")`

    - `class BetaCacheMissUnavailable:`

      - `JsonValue; type "unavailable"constant`

        - `UNAVAILABLE("unavailable")`

### Beta Diagnostics Param

- `class BetaDiagnosticsParam:`

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

  - `Optional<String> previousMessageId`

    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.

### Beta Direct Caller

- `class BetaDirectCaller:`

  Tool invocation directly from the model.

  - `JsonValue; type "direct"constant`

    - `DIRECT("direct")`

### Beta Document Block

- `class BetaDocumentBlock:`

  - `Optional<BetaCitationConfig> citations`

    Citation configuration for the document

    - `boolean enabled`

  - `Source source`

    - `class BetaBase64PdfSource:`

      - `String data`

      - `JsonValue; mediaType "application/pdf"constant`

        - `APPLICATION_PDF("application/pdf")`

      - `JsonValue; type "base64"constant`

        - `BASE64("base64")`

    - `class BetaPlainTextSource:`

      - `String data`

      - `JsonValue; mediaType "text/plain"constant`

        - `TEXT_PLAIN("text/plain")`

      - `JsonValue; type "text"constant`

        - `TEXT("text")`

  - `Optional<String> title`

    The title of the document

  - `JsonValue; type "document"constant`

    - `DOCUMENT("document")`

### Beta Encrypted Code Execution Result Block

- `class BetaEncryptedCodeExecutionResultBlock:`

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

  - `List<BetaCodeExecutionOutputBlock> content`

    - `String fileId`

    - `JsonValue; type "code_execution_output"constant`

      - `CODE_EXECUTION_OUTPUT("code_execution_output")`

  - `String encryptedStdout`

  - `long returnCode`

  - `String stderr`

  - `JsonValue; type "encrypted_code_execution_result"constant`

    - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

### Beta Encrypted Code Execution Result Block Param

- `class BetaEncryptedCodeExecutionResultBlockParam:`

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

  - `List<BetaCodeExecutionOutputBlockParam> content`

    - `String fileId`

    - `JsonValue; type "code_execution_output"constant`

      - `CODE_EXECUTION_OUTPUT("code_execution_output")`

  - `String encryptedStdout`

  - `long returnCode`

  - `String stderr`

  - `JsonValue; type "encrypted_code_execution_result"constant`

    - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

### Beta Fallback Block

- `class BetaFallbackBlock:`

  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 routed directly by the sticky decision 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.

  - `BetaFallbackInfo from`

    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.

    - `Model model`

      The model that will complete your prompt.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_MYTHOS_5("claude-mythos-5")`

        Most capable model for cybersecurity and biology research

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

        New class of intelligence, strongest in coding and cybersecurity

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

      - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

        Exceptional model for specialized complex tasks

      - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

        Exceptional model for specialized complex tasks

      - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

        Powerful model for complex tasks

      - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

        Powerful model for complex tasks

      - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

        High-performance model with extended thinking

      - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

        High-performance model with extended thinking

      - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

        Fast and cost-effective model

  - `BetaFallbackInfo to`

    The fallback model producing the content that follows this block. Its `model` is always the canonical id.

  - `JsonValue; type "fallback"constant`

    - `FALLBACK("fallback")`

### Beta Fallback Block Param

- `class BetaFallbackBlockParam:`

  A `fallback` block echoed back from a prior response.

  Accepted in `messages[].content` and never rendered into the prompt,
  not validated against the request's `fallbacks` chain or top-level
  `model`, and stripped before the sticky-routing cache key is computed.

  Callers should echo the assistant turn verbatim — block included. The
  block's position is load-bearing for thinking verification: the thinking
  runs on either side of a fallback hop carry independently-rooted
  verification hash chains, and this block is the only record of where one
  chain ends and the next begins. When thinking runs flank the boundary,
  omitting the block merges the runs into one contiguous span whose hashes
  cannot verify (the request is rejected), and moving it into the middle of
  a single run splits that run's chain and is likewise rejected; between
  non-thinking blocks the block's placement has no verification effect.

  - `BetaFallbackInfoParam from`

    Identifies one hop of a fallback transition.

    - `Model model`

      The model that will complete your prompt.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_MYTHOS_5("claude-mythos-5")`

        Most capable model for cybersecurity and biology research

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

        New class of intelligence, strongest in coding and cybersecurity

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

      - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

        Exceptional model for specialized complex tasks

      - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

        Exceptional model for specialized complex tasks

      - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

        Powerful model for complex tasks

      - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

        Powerful model for complex tasks

      - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

        High-performance model with extended thinking

      - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

        High-performance model with extended thinking

      - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

        Fast and cost-effective model

  - `BetaFallbackInfoParam to`

    Identifies one hop of a fallback transition.

  - `JsonValue; type "fallback"constant`

    - `FALLBACK("fallback")`

### Beta Fallback Info

- `class BetaFallbackInfo:`

  Identifies one hop of a fallback transition.

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `CLAUDE_FABLE_5("claude-fable-5")`

      Next generation of intelligence for the hardest knowledge work and coding problems

    - `CLAUDE_MYTHOS_5("claude-mythos-5")`

      Most capable model for cybersecurity and biology research

    - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

      New class of intelligence, strongest in coding and cybersecurity

    - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

      Best combination of speed and intelligence

    - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

      High-performance model for agents and coding

    - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

      High-performance model for agents and coding

    - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

      Powerful model for complex tasks

    - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

      Powerful model for complex tasks

    - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

      High-performance model with extended thinking

    - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

      High-performance model with extended thinking

    - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

      Fast and cost-effective model

### Beta Fallback Info Param

- `class BetaFallbackInfoParam:`

  Identifies one hop of a fallback transition.

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `CLAUDE_FABLE_5("claude-fable-5")`

      Next generation of intelligence for the hardest knowledge work and coding problems

    - `CLAUDE_MYTHOS_5("claude-mythos-5")`

      Most capable model for cybersecurity and biology research

    - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

      New class of intelligence, strongest in coding and cybersecurity

    - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

      Best combination of speed and intelligence

    - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

      High-performance model for agents and coding

    - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

      High-performance model for agents and coding

    - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

      Powerful model for complex tasks

    - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

      Powerful model for complex tasks

    - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

      High-performance model with extended thinking

    - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

      High-performance model with extended thinking

    - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

      Fast and cost-effective model

### Beta Fallback Message Iteration Usage

- `class BetaFallbackMessageIterationUsage:`

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

  - `Optional<BetaCacheCreation> cacheCreation`

    Breakdown of cached tokens by TTL

    - `long ephemeral1hInputTokens`

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

    - `long ephemeral5mInputTokens`

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

  - `long cacheCreationInputTokens`

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

  - `long cacheReadInputTokens`

    The number of input tokens read from the cache.

  - `long inputTokens`

    The number of input tokens which were used.

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `CLAUDE_FABLE_5("claude-fable-5")`

      Next generation of intelligence for the hardest knowledge work and coding problems

    - `CLAUDE_MYTHOS_5("claude-mythos-5")`

      Most capable model for cybersecurity and biology research

    - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

      New class of intelligence, strongest in coding and cybersecurity

    - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

      Best combination of speed and intelligence

    - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

      High-performance model for agents and coding

    - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

      High-performance model for agents and coding

    - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

      Powerful model for complex tasks

    - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

      Powerful model for complex tasks

    - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

      High-performance model with extended thinking

    - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

      High-performance model with extended thinking

    - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

      Fast and cost-effective model

  - `long outputTokens`

    The number of output tokens which were used.

  - `JsonValue; type "fallback_message"constant`

    Usage for the fallback-model attempt that served the response

    - `FALLBACK_MESSAGE("fallback_message")`

### Beta Fallback Param

- `class BetaFallbackParam:`

  One entry in the `fallbacks` chain on a `/v1/messages` request.

  `model` is required. The four override fields (`max_tokens`, `thinking`,
  `output_config`, and `speed`) replace the corresponding top-level field
  for this attempt only and are validated as if the request were made to
  `model`. Any other key is rejected at parse time.

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `CLAUDE_FABLE_5("claude-fable-5")`

      Next generation of intelligence for the hardest knowledge work and coding problems

    - `CLAUDE_MYTHOS_5("claude-mythos-5")`

      Most capable model for cybersecurity and biology research

    - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

      New class of intelligence, strongest in coding and cybersecurity

    - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

      Best combination of speed and intelligence

    - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

      High-performance model for agents and coding

    - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

      High-performance model for agents and coding

    - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

      Powerful model for complex tasks

    - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

      Powerful model for complex tasks

    - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

      High-performance model with extended thinking

    - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

      High-performance model with extended thinking

    - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

      Fast and cost-effective model

  - `Optional<Long> maxTokens`

  - `Optional<BetaOutputConfig> outputConfig`

    - `Optional<Effort> effort`

      All possible effort levels.

      - `LOW("low")`

      - `MEDIUM("medium")`

      - `HIGH("high")`

      - `XHIGH("xhigh")`

      - `MAX("max")`

    - `Optional<BetaJsonOutputFormat> format`

      A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

      - `Schema schema`

        The JSON schema of the format

      - `JsonValue; type "json_schema"constant`

        - `JSON_SCHEMA("json_schema")`

    - `Optional<BetaTokenTaskBudget> taskBudget`

      User-configurable total token budget across contexts.

      - `long total`

        Total token budget across all contexts in the session.

      - `JsonValue; type "tokens"constant`

        The budget type. Currently only 'tokens' is supported.

        - `TOKENS("tokens")`

      - `Optional<Long> remaining`

        Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.

  - `Optional<Speed> speed`

    - `STANDARD("standard")`

    - `FAST("fast")`

  - `Optional<Thinking> thinking`

    - `class BetaThinkingConfigEnabled:`

      - `long budgetTokens`

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

        Must be ≥1024 and less than `max_tokens`.

        See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.

      - `JsonValue; type "enabled"constant`

        - `ENABLED("enabled")`

      - `Optional<Display> display`

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

        - `SUMMARIZED("summarized")`

        - `OMITTED("omitted")`

    - `class BetaThinkingConfigDisabled:`

      - `JsonValue; type "disabled"constant`

        - `DISABLED("disabled")`

    - `class BetaThinkingConfigAdaptive:`

      - `JsonValue; type "adaptive"constant`

        - `ADAPTIVE("adaptive")`

      - `Optional<Display> display`

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

        - `SUMMARIZED("summarized")`

        - `OMITTED("omitted")`

### Beta File Document Source

- `class BetaFileDocumentSource:`

  - `String fileId`

  - `JsonValue; type "file"constant`

    - `FILE("file")`

### Beta File Image Source

- `class BetaFileImageSource:`

  - `String fileId`

  - `JsonValue; type "file"constant`

    - `FILE("file")`

### Beta Image Block Param

- `class BetaImageBlockParam:`

  - `Source source`

    - `class BetaBase64ImageSource:`

      - `String data`

      - `MediaType mediaType`

        - `IMAGE_JPEG("image/jpeg")`

        - `IMAGE_PNG("image/png")`

        - `IMAGE_GIF("image/gif")`

        - `IMAGE_WEBP("image/webp")`

      - `JsonValue; type "base64"constant`

        - `BASE64("base64")`

    - `class BetaUrlImageSource:`

      - `JsonValue; type "url"constant`

        - `URL("url")`

      - `String url`

    - `class BetaFileImageSource:`

      - `String fileId`

      - `JsonValue; type "file"constant`

        - `FILE("file")`

  - `JsonValue; type "image"constant`

    - `IMAGE("image")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

### Beta Input JSON Delta

- `class BetaInputJsonDelta:`

  - `String partialJson`

  - `JsonValue; type "input_json_delta"constant`

    - `INPUT_JSON_DELTA("input_json_delta")`

### Beta Input Tokens Clear At Least

- `class BetaInputTokensClearAtLeast:`

  - `JsonValue; type "input_tokens"constant`

    - `INPUT_TOKENS("input_tokens")`

  - `long value`

### Beta Input Tokens Trigger

- `class BetaInputTokensTrigger:`

  - `JsonValue; type "input_tokens"constant`

    - `INPUT_TOKENS("input_tokens")`

  - `long value`

### Beta JSON Output Format

- `class BetaJsonOutputFormat:`

  - `Schema schema`

    The JSON schema of the format

  - `JsonValue; type "json_schema"constant`

    - `JSON_SCHEMA("json_schema")`

### Beta MCP Tool Config

- `class BetaMcpToolConfig:`

  Configuration for a specific tool in an MCP toolset.

  - `Optional<Boolean> deferLoading`

  - `Optional<Boolean> enabled`

### Beta MCP Tool Default Config

- `class BetaMcpToolDefaultConfig:`

  Default configuration for tools in an MCP toolset.

  - `Optional<Boolean> deferLoading`

  - `Optional<Boolean> enabled`

### Beta MCP Tool Result Block

- `class BetaMcpToolResultBlock:`

  - `Content content`

    - `String`

    - `List<BetaTextBlock>`

      - `Optional<List<BetaTextCitation>> citations`

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

        - `class BetaCitationCharLocation:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endCharIndex`

          - `Optional<String> fileId`

          - `long startCharIndex`

          - `JsonValue; type "char_location"constant`

            - `CHAR_LOCATION("char_location")`

        - `class BetaCitationPageLocation:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endPageNumber`

          - `Optional<String> fileId`

          - `long startPageNumber`

          - `JsonValue; type "page_location"constant`

            - `PAGE_LOCATION("page_location")`

        - `class BetaCitationContentBlockLocation:`

          - `String citedText`

            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.

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endBlockIndex`

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

          - `Optional<String> fileId`

          - `long startBlockIndex`

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

          - `JsonValue; type "content_block_location"constant`

            - `CONTENT_BLOCK_LOCATION("content_block_location")`

        - `class BetaCitationsWebSearchResultLocation:`

          - `String citedText`

          - `String encryptedIndex`

          - `Optional<String> title`

          - `JsonValue; type "web_search_result_location"constant`

            - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

          - `String url`

        - `class BetaCitationSearchResultLocation:`

          - `String citedText`

            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.

          - `long endBlockIndex`

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

          - `long searchResultIndex`

            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.

          - `String source`

          - `long startBlockIndex`

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

          - `Optional<String> title`

          - `JsonValue; type "search_result_location"constant`

            - `SEARCH_RESULT_LOCATION("search_result_location")`

      - `String text`

      - `JsonValue; type "text"constant`

        - `TEXT("text")`

  - `boolean isError`

  - `String toolUseId`

  - `JsonValue; type "mcp_tool_result"constant`

    - `MCP_TOOL_RESULT("mcp_tool_result")`

### Beta MCP Tool Use Block

- `class BetaMcpToolUseBlock:`

  - `String id`

  - `Input input`

  - `String name`

    The name of the MCP tool

  - `String serverName`

    The name of the MCP server

  - `JsonValue; type "mcp_tool_use"constant`

    - `MCP_TOOL_USE("mcp_tool_use")`

### Beta MCP Tool Use Block Param

- `class BetaMcpToolUseBlockParam:`

  - `String id`

  - `Input input`

  - `String name`

  - `String serverName`

    The name of the MCP server

  - `JsonValue; type "mcp_tool_use"constant`

    - `MCP_TOOL_USE("mcp_tool_use")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

### Beta MCP Toolset

- `class BetaMcpToolset:`

  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.

  - `String mcpServerName`

    Name of the MCP server to configure tools for

  - `JsonValue; type "mcp_toolset"constant`

    - `MCP_TOOLSET("mcp_toolset")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Configs> configs`

    Configuration overrides for specific tools, keyed by tool name

    - `Optional<Boolean> deferLoading`

    - `Optional<Boolean> enabled`

  - `Optional<BetaMcpToolDefaultConfig> defaultConfig`

    Default configuration applied to all tools from this server

    - `Optional<Boolean> deferLoading`

    - `Optional<Boolean> enabled`

### Beta Memory Tool 20250818

- `class BetaMemoryTool20250818:`

  - `JsonValue; name "memory"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `MEMORY("memory")`

  - `JsonValue; type "memory_20250818"constant`

    - `MEMORY_20250818("memory_20250818")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Memory Tool 20250818 Command

- `class BetaMemoryTool20250818Command: A class that can be one of several variants.union`

  - `class BetaMemoryTool20250818ViewCommand:`

    - `JsonValue; command "view"constant`

      Command type identifier

      - `VIEW("view")`

    - `String path`

      Path to directory or file to view

    - `Optional<List<Long>> viewRange`

      Optional line range for viewing specific lines

  - `class BetaMemoryTool20250818CreateCommand:`

    - `JsonValue; command "create"constant`

      Command type identifier

      - `CREATE("create")`

    - `String fileText`

      Content to write to the file

    - `String path`

      Path where the file should be created

  - `class BetaMemoryTool20250818StrReplaceCommand:`

    - `JsonValue; command "str_replace"constant`

      Command type identifier

      - `STR_REPLACE("str_replace")`

    - `String newStr`

      Text to replace with

    - `String oldStr`

      Text to search for and replace

    - `String path`

      Path to the file where text should be replaced

  - `class BetaMemoryTool20250818InsertCommand:`

    - `JsonValue; command "insert"constant`

      Command type identifier

      - `INSERT("insert")`

    - `long insertLine`

      Line number where text should be inserted

    - `String insertText`

      Text to insert at the specified line

    - `String path`

      Path to the file where text should be inserted

  - `class BetaMemoryTool20250818DeleteCommand:`

    - `JsonValue; command "delete"constant`

      Command type identifier

      - `DELETE("delete")`

    - `String path`

      Path to the file or directory to delete

  - `class BetaMemoryTool20250818RenameCommand:`

    - `JsonValue; command "rename"constant`

      Command type identifier

      - `RENAME("rename")`

    - `String newPath`

      New path for the file or directory

    - `String oldPath`

      Current path of the file or directory

### Beta Memory Tool 20250818 Create Command

- `class BetaMemoryTool20250818CreateCommand:`

  - `JsonValue; command "create"constant`

    Command type identifier

    - `CREATE("create")`

  - `String fileText`

    Content to write to the file

  - `String path`

    Path where the file should be created

### Beta Memory Tool 20250818 Delete Command

- `class BetaMemoryTool20250818DeleteCommand:`

  - `JsonValue; command "delete"constant`

    Command type identifier

    - `DELETE("delete")`

  - `String path`

    Path to the file or directory to delete

### Beta Memory Tool 20250818 Insert Command

- `class BetaMemoryTool20250818InsertCommand:`

  - `JsonValue; command "insert"constant`

    Command type identifier

    - `INSERT("insert")`

  - `long insertLine`

    Line number where text should be inserted

  - `String insertText`

    Text to insert at the specified line

  - `String path`

    Path to the file where text should be inserted

### Beta Memory Tool 20250818 Rename Command

- `class BetaMemoryTool20250818RenameCommand:`

  - `JsonValue; command "rename"constant`

    Command type identifier

    - `RENAME("rename")`

  - `String newPath`

    New path for the file or directory

  - `String oldPath`

    Current path of the file or directory

### Beta Memory Tool 20250818 Str Replace Command

- `class BetaMemoryTool20250818StrReplaceCommand:`

  - `JsonValue; command "str_replace"constant`

    Command type identifier

    - `STR_REPLACE("str_replace")`

  - `String newStr`

    Text to replace with

  - `String oldStr`

    Text to search for and replace

  - `String path`

    Path to the file where text should be replaced

### Beta Memory Tool 20250818 View Command

- `class BetaMemoryTool20250818ViewCommand:`

  - `JsonValue; command "view"constant`

    Command type identifier

    - `VIEW("view")`

  - `String path`

    Path to directory or file to view

  - `Optional<List<Long>> viewRange`

    Optional line range for viewing specific lines

### Beta Message

- `class BetaMessage:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `Optional<BetaContainer> container`

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

    - `String id`

      Identifier for the container used in this request

    - `LocalDateTime expiresAt`

      The time at which the container will expire.

    - `Optional<List<BetaSkill>> skills`

      Skills loaded in the container

      - `String skillId`

        Skill ID

      - `Type type`

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

        - `ANTHROPIC("anthropic")`

        - `CUSTOM("custom")`

      - `String version`

        Skill version or 'latest' for most recent version

  - `List<BetaContentBlock> content`

    Content generated by the model.

    This is an array of content blocks, each of which has a `type` that determines its shape.

    Example:

    ```json
    [{"type": "text", "text": "Hi, I'm Claude."}]
    ```

    If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.

    For example, if the input `messages` were:

    ```json
    [
      {"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)"}]
    ```

    - `class BetaTextBlock:`

      - `Optional<List<BetaTextCitation>> citations`

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

        - `class BetaCitationCharLocation:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endCharIndex`

          - `Optional<String> fileId`

          - `long startCharIndex`

          - `JsonValue; type "char_location"constant`

            - `CHAR_LOCATION("char_location")`

        - `class BetaCitationPageLocation:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endPageNumber`

          - `Optional<String> fileId`

          - `long startPageNumber`

          - `JsonValue; type "page_location"constant`

            - `PAGE_LOCATION("page_location")`

        - `class BetaCitationContentBlockLocation:`

          - `String citedText`

            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.

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endBlockIndex`

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

          - `Optional<String> fileId`

          - `long startBlockIndex`

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

          - `JsonValue; type "content_block_location"constant`

            - `CONTENT_BLOCK_LOCATION("content_block_location")`

        - `class BetaCitationsWebSearchResultLocation:`

          - `String citedText`

          - `String encryptedIndex`

          - `Optional<String> title`

          - `JsonValue; type "web_search_result_location"constant`

            - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

          - `String url`

        - `class BetaCitationSearchResultLocation:`

          - `String citedText`

            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.

          - `long endBlockIndex`

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

          - `long searchResultIndex`

            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.

          - `String source`

          - `long startBlockIndex`

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

          - `Optional<String> title`

          - `JsonValue; type "search_result_location"constant`

            - `SEARCH_RESULT_LOCATION("search_result_location")`

      - `String text`

      - `JsonValue; type "text"constant`

        - `TEXT("text")`

    - `class BetaThinkingBlock:`

      - `String signature`

      - `String thinking`

      - `JsonValue; type "thinking"constant`

        - `THINKING("thinking")`

    - `class BetaRedactedThinkingBlock:`

      - `String data`

      - `JsonValue; type "redacted_thinking"constant`

        - `REDACTED_THINKING("redacted_thinking")`

    - `class BetaToolUseBlock:`

      - `String id`

      - `Input input`

      - `String name`

      - `JsonValue; type "tool_use"constant`

        - `TOOL_USE("tool_use")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

          - `JsonValue; type "direct"constant`

            - `DIRECT("direct")`

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

          - `String toolId`

          - `JsonValue; type "code_execution_20250825"constant`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `class BetaServerToolCaller20260120:`

          - `String toolId`

          - `JsonValue; type "code_execution_20260120"constant`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `class BetaServerToolUseBlock:`

      - `String id`

      - `Input input`

      - `Name name`

        - `ADVISOR("advisor")`

        - `WEB_SEARCH("web_search")`

        - `WEB_FETCH("web_fetch")`

        - `CODE_EXECUTION("code_execution")`

        - `BASH_CODE_EXECUTION("bash_code_execution")`

        - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

        - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

        - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

      - `JsonValue; type "server_tool_use"constant`

        - `SERVER_TOOL_USE("server_tool_use")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

        - `class BetaServerToolCaller20260120:`

    - `class BetaWebSearchToolResultBlock:`

      - `BetaWebSearchToolResultBlockContent content`

        - `class BetaWebSearchToolResultError:`

          - `BetaWebSearchToolResultErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `MAX_USES_EXCEEDED("max_uses_exceeded")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `QUERY_TOO_LONG("query_too_long")`

            - `REQUEST_TOO_LARGE("request_too_large")`

          - `JsonValue; type "web_search_tool_result_error"constant`

            - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

        - `List<BetaWebSearchResultBlock>`

          - `String encryptedContent`

          - `Optional<String> pageAge`

          - `String title`

          - `JsonValue; type "web_search_result"constant`

            - `WEB_SEARCH_RESULT("web_search_result")`

          - `String url`

      - `String toolUseId`

      - `JsonValue; type "web_search_tool_result"constant`

        - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

        - `class BetaServerToolCaller20260120:`

    - `class BetaWebFetchToolResultBlock:`

      - `Content content`

        - `class BetaWebFetchToolResultErrorBlock:`

          - `BetaWebFetchToolResultErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `URL_TOO_LONG("url_too_long")`

            - `URL_NOT_ALLOWED("url_not_allowed")`

            - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

            - `URL_NOT_ACCESSIBLE("url_not_accessible")`

            - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `MAX_USES_EXCEEDED("max_uses_exceeded")`

            - `UNAVAILABLE("unavailable")`

          - `JsonValue; type "web_fetch_tool_result_error"constant`

            - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

        - `class BetaWebFetchBlock:`

          - `BetaDocumentBlock content`

            - `Optional<BetaCitationConfig> citations`

              Citation configuration for the document

              - `boolean enabled`

            - `Source source`

              - `class BetaBase64PdfSource:`

                - `String data`

                - `JsonValue; mediaType "application/pdf"constant`

                  - `APPLICATION_PDF("application/pdf")`

                - `JsonValue; type "base64"constant`

                  - `BASE64("base64")`

              - `class BetaPlainTextSource:`

                - `String data`

                - `JsonValue; mediaType "text/plain"constant`

                  - `TEXT_PLAIN("text/plain")`

                - `JsonValue; type "text"constant`

                  - `TEXT("text")`

            - `Optional<String> title`

              The title of the document

            - `JsonValue; type "document"constant`

              - `DOCUMENT("document")`

          - `Optional<String> retrievedAt`

            ISO 8601 timestamp when the content was retrieved

          - `JsonValue; type "web_fetch_result"constant`

            - `WEB_FETCH_RESULT("web_fetch_result")`

          - `String url`

            Fetched content URL

      - `String toolUseId`

      - `JsonValue; type "web_fetch_tool_result"constant`

        - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

        - `class BetaServerToolCaller20260120:`

    - `class BetaAdvisorToolResultBlock:`

      - `Content content`

        - `class BetaAdvisorToolResultError:`

          - `ErrorCode errorCode`

            - `MAX_USES_EXCEEDED("max_uses_exceeded")`

            - `PROMPT_TOO_LONG("prompt_too_long")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `OVERLOADED("overloaded")`

            - `UNAVAILABLE("unavailable")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `MODEL_NOT_FOUND("model_not_found")`

          - `JsonValue; type "advisor_tool_result_error"constant`

            - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

        - `class BetaAdvisorResultBlock:`

          - `Optional<String> stopReason`

            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.

          - `String text`

          - `JsonValue; type "advisor_result"constant`

            - `ADVISOR_RESULT("advisor_result")`

        - `class BetaAdvisorRedactedResultBlock:`

          - `String encryptedContent`

            Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

          - `Optional<String> stopReason`

            The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

          - `JsonValue; type "advisor_redacted_result"constant`

            - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

      - `String toolUseId`

      - `JsonValue; type "advisor_tool_result"constant`

        - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

    - `class BetaCodeExecutionToolResultBlock:`

      - `BetaCodeExecutionToolResultBlockContent content`

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

        - `class BetaCodeExecutionToolResultError:`

          - `BetaCodeExecutionToolResultErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `JsonValue; type "code_execution_tool_result_error"constant`

            - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

        - `class BetaCodeExecutionResultBlock:`

          - `List<BetaCodeExecutionOutputBlock> content`

            - `String fileId`

            - `JsonValue; type "code_execution_output"constant`

              - `CODE_EXECUTION_OUTPUT("code_execution_output")`

          - `long returnCode`

          - `String stderr`

          - `String stdout`

          - `JsonValue; type "code_execution_result"constant`

            - `CODE_EXECUTION_RESULT("code_execution_result")`

        - `class BetaEncryptedCodeExecutionResultBlock:`

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

          - `List<BetaCodeExecutionOutputBlock> content`

            - `String fileId`

            - `JsonValue; type "code_execution_output"constant`

          - `String encryptedStdout`

          - `long returnCode`

          - `String stderr`

          - `JsonValue; type "encrypted_code_execution_result"constant`

            - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

      - `String toolUseId`

      - `JsonValue; type "code_execution_tool_result"constant`

        - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

    - `class BetaBashCodeExecutionToolResultBlock:`

      - `Content content`

        - `class BetaBashCodeExecutionToolResultError:`

          - `ErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

          - `JsonValue; type "bash_code_execution_tool_result_error"constant`

            - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

        - `class BetaBashCodeExecutionResultBlock:`

          - `List<BetaBashCodeExecutionOutputBlock> content`

            - `String fileId`

            - `JsonValue; type "bash_code_execution_output"constant`

              - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

          - `long returnCode`

          - `String stderr`

          - `String stdout`

          - `JsonValue; type "bash_code_execution_result"constant`

            - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

      - `String toolUseId`

      - `JsonValue; type "bash_code_execution_tool_result"constant`

        - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

    - `class BetaTextEditorCodeExecutionToolResultBlock:`

      - `Content content`

        - `class BetaTextEditorCodeExecutionToolResultError:`

          - `ErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `FILE_NOT_FOUND("file_not_found")`

          - `Optional<String> errorMessage`

          - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

        - `class BetaTextEditorCodeExecutionViewResultBlock:`

          - `String content`

          - `FileType fileType`

            - `TEXT("text")`

            - `IMAGE("image")`

            - `PDF("pdf")`

          - `Optional<Long> numLines`

          - `Optional<Long> startLine`

          - `Optional<Long> totalLines`

          - `JsonValue; type "text_editor_code_execution_view_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

        - `class BetaTextEditorCodeExecutionCreateResultBlock:`

          - `boolean isFileUpdate`

          - `JsonValue; type "text_editor_code_execution_create_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

        - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

          - `Optional<List<String>> lines`

          - `Optional<Long> newLines`

          - `Optional<Long> newStart`

          - `Optional<Long> oldLines`

          - `Optional<Long> oldStart`

          - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

      - `String toolUseId`

      - `JsonValue; type "text_editor_code_execution_tool_result"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

    - `class BetaToolSearchToolResultBlock:`

      - `Content content`

        - `class BetaToolSearchToolResultError:`

          - `ErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `Optional<String> errorMessage`

          - `JsonValue; type "tool_search_tool_result_error"constant`

            - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

        - `class BetaToolSearchToolSearchResultBlock:`

          - `List<BetaToolReferenceBlock> toolReferences`

            - `String toolName`

            - `JsonValue; type "tool_reference"constant`

              - `TOOL_REFERENCE("tool_reference")`

          - `JsonValue; type "tool_search_tool_search_result"constant`

            - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

      - `String toolUseId`

      - `JsonValue; type "tool_search_tool_result"constant`

        - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

    - `class BetaMcpToolUseBlock:`

      - `String id`

      - `Input input`

      - `String name`

        The name of the MCP tool

      - `String serverName`

        The name of the MCP server

      - `JsonValue; type "mcp_tool_use"constant`

        - `MCP_TOOL_USE("mcp_tool_use")`

    - `class BetaMcpToolResultBlock:`

      - `Content content`

        - `String`

        - `List<BetaTextBlock>`

          - `Optional<List<BetaTextCitation>> citations`

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

          - `String text`

          - `JsonValue; type "text"constant`

      - `boolean isError`

      - `String toolUseId`

      - `JsonValue; type "mcp_tool_result"constant`

        - `MCP_TOOL_RESULT("mcp_tool_result")`

    - `class BetaContainerUploadBlock:`

      Response model for a file uploaded to the container.

      - `String fileId`

      - `JsonValue; type "container_upload"constant`

        - `CONTAINER_UPLOAD("container_upload")`

    - `class BetaCompactionBlock:`

      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.

      - `Optional<String> content`

        Summary of compacted content, or null if compaction failed

      - `Optional<String> encryptedContent`

        Opaque metadata from prior compaction, to be round-tripped verbatim

      - `JsonValue; type "compaction"constant`

        - `COMPACTION("compaction")`

    - `class BetaFallbackBlock:`

      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 routed directly by the sticky decision 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.

      - `BetaFallbackInfo from`

        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.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_MYTHOS_5("claude-mythos-5")`

            Most capable model for cybersecurity and biology research

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

            New class of intelligence, strongest in coding and cybersecurity

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

          - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

            Exceptional model for specialized complex tasks

          - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

            Exceptional model for specialized complex tasks

          - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

            Powerful model for complex tasks

          - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

            Powerful model for complex tasks

          - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

            High-performance model with extended thinking

          - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

            High-performance model with extended thinking

          - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

            Fast and cost-effective model

      - `BetaFallbackInfo to`

        The fallback model producing the content that follows this block. Its `model` is always the canonical id.

      - `JsonValue; type "fallback"constant`

        - `FALLBACK("fallback")`

  - `Optional<BetaContextManagementResponse> contextManagement`

    Context management response.

    Information about context management strategies applied during the request.

    - `List<AppliedEdit> appliedEdits`

      List of context management edits that were applied.

      - `class BetaClearToolUses20250919EditResponse:`

        - `long clearedInputTokens`

          Number of input tokens cleared by this edit.

        - `long clearedToolUses`

          Number of tool uses that were cleared.

        - `JsonValue; type "clear_tool_uses_20250919"constant`

          The type of context management edit applied.

          - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

      - `class BetaClearThinking20251015EditResponse:`

        - `long clearedInputTokens`

          Number of input tokens cleared by this edit.

        - `long clearedThinkingTurns`

          Number of thinking turns that were cleared.

        - `JsonValue; type "clear_thinking_20251015"constant`

          The type of context management edit applied.

          - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

  - `Optional<BetaDiagnostics> diagnostics`

    Response envelope for request-level diagnostics. Present (possibly
    null) whenever the caller supplied `diagnostics` on the request.

    - `Optional<CacheMissReason> cacheMissReason`

      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.

      - `class BetaCacheMissModelChanged:`

        - `long cacheMissedInputTokens`

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

        - `JsonValue; type "model_changed"constant`

          - `MODEL_CHANGED("model_changed")`

      - `class BetaCacheMissSystemChanged:`

        - `long cacheMissedInputTokens`

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

        - `JsonValue; type "system_changed"constant`

          - `SYSTEM_CHANGED("system_changed")`

      - `class BetaCacheMissToolsChanged:`

        - `long cacheMissedInputTokens`

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

        - `JsonValue; type "tools_changed"constant`

          - `TOOLS_CHANGED("tools_changed")`

      - `class BetaCacheMissMessagesChanged:`

        - `long cacheMissedInputTokens`

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

        - `JsonValue; type "messages_changed"constant`

          - `MESSAGES_CHANGED("messages_changed")`

      - `class BetaCacheMissPreviousMessageNotFound:`

        - `JsonValue; type "previous_message_not_found"constant`

          - `PREVIOUS_MESSAGE_NOT_FOUND("previous_message_not_found")`

      - `class BetaCacheMissUnavailable:`

        - `JsonValue; type "unavailable"constant`

          - `UNAVAILABLE("unavailable")`

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

  - `JsonValue; role "assistant"constant`

    Conversational role of the generated message.

    This will always be `"assistant"`.

    - `ASSISTANT("assistant")`

  - `Optional<BetaRefusalStopDetails> stopDetails`

    Structured information about a refusal.

    - `Optional<Category> category`

      The policy category that triggered the refusal.

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

      - `CYBER("cyber")`

      - `BIO("bio")`

      - `REASONING_EXTRACTION("reasoning_extraction")`

    - `Optional<String> explanation`

      Human-readable explanation of the refusal.

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

    - `Optional<String> fallbackCreditToken`

      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.

    - `Optional<Boolean> fallbackHasPrefillClaim`

      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.

    - `Optional<String> recommendedModel`

      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.

    - `JsonValue; type "refusal"constant`

      - `REFUSAL("refusal")`

  - `Optional<BetaStopReason> stopReason`

    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

    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.

    - `END_TURN("end_turn")`

    - `MAX_TOKENS("max_tokens")`

    - `STOP_SEQUENCE("stop_sequence")`

    - `TOOL_USE("tool_use")`

    - `PAUSE_TURN("pause_turn")`

    - `COMPACTION("compaction")`

    - `REFUSAL("refusal")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")`

  - `Optional<String> stopSequence`

    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.

  - `JsonValue; type "message"constant`

    Object type.

    For Messages, this is always `"message"`.

    - `MESSAGE("message")`

  - `BetaUsage usage`

    Billing and rate-limit usage.

    Anthropic'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 Claude.

    Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.

    - `Optional<BetaCacheCreation> cacheCreation`

      Breakdown of cached tokens by TTL

      - `long ephemeral1hInputTokens`

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

      - `long ephemeral5mInputTokens`

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

    - `Optional<Long> cacheCreationInputTokens`

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

    - `Optional<Long> cacheReadInputTokens`

      The number of input tokens read from the cache.

    - `Optional<String> inferenceGeo`

      The geographic region where inference was performed for this request.

    - `long inputTokens`

      The number of input tokens which were used.

    - `Optional<List<BetaIterationsUsageItems>> iterations`

      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

      - `class BetaMessageIterationUsage:`

        Token usage for a sampling iteration.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "message"constant`

          Usage for a sampling iteration

          - `MESSAGE("message")`

      - `class BetaCompactionIterationUsage:`

        Token usage for a compaction iteration.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "compaction"constant`

          Usage for a compaction iteration

          - `COMPACTION("compaction")`

      - `class BetaAdvisorMessageIterationUsage:`

        Token usage for an advisor sub-inference iteration.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "advisor_message"constant`

          Usage for an advisor sub-inference iteration

          - `ADVISOR_MESSAGE("advisor_message")`

      - `class BetaFallbackMessageIterationUsage:`

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

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "fallback_message"constant`

          Usage for the fallback-model attempt that served the response

          - `FALLBACK_MESSAGE("fallback_message")`

    - `long outputTokens`

      The number of output tokens which were used.

    - `Optional<BetaOutputTokensDetails> outputTokensDetails`

      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.

      - `long thinkingTokens`

        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.

    - `Optional<BetaServerToolUsage> serverToolUse`

      The number of server tool requests.

      - `long webFetchRequests`

        The number of web fetch tool requests.

      - `long webSearchRequests`

        The number of web search tool requests.

    - `Optional<ServiceTier> serviceTier`

      If the request used the priority, standard, or batch tier.

      - `STANDARD("standard")`

      - `PRIORITY("priority")`

      - `BATCH("batch")`

    - `Optional<Speed> speed`

      The inference speed mode used for this request.

      - `STANDARD("standard")`

      - `FAST("fast")`

### Beta Message Delta Usage

- `class BetaMessageDeltaUsage:`

  - `Optional<Long> cacheCreationInputTokens`

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

  - `Optional<Long> cacheReadInputTokens`

    The cumulative number of input tokens read from the cache.

  - `Optional<Long> inputTokens`

    The cumulative number of input tokens which were used.

  - `Optional<List<BetaIterationsUsageItems>> iterations`

    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

    - `class BetaMessageIterationUsage:`

      Token usage for a sampling iteration.

      - `Optional<BetaCacheCreation> cacheCreation`

        Breakdown of cached tokens by TTL

        - `long ephemeral1hInputTokens`

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

        - `long ephemeral5mInputTokens`

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

      - `long cacheCreationInputTokens`

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

      - `long cacheReadInputTokens`

        The number of input tokens read from the cache.

      - `long inputTokens`

        The number of input tokens which were used.

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_MYTHOS_5("claude-mythos-5")`

          Most capable model for cybersecurity and biology research

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

          New class of intelligence, strongest in coding and cybersecurity

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

        - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

          Exceptional model for specialized complex tasks

        - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

          Exceptional model for specialized complex tasks

        - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

          Powerful model for complex tasks

        - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

          Powerful model for complex tasks

        - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

          High-performance model with extended thinking

        - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

          High-performance model with extended thinking

        - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

          Fast and cost-effective model

      - `long outputTokens`

        The number of output tokens which were used.

      - `JsonValue; type "message"constant`

        Usage for a sampling iteration

        - `MESSAGE("message")`

    - `class BetaCompactionIterationUsage:`

      Token usage for a compaction iteration.

      - `Optional<BetaCacheCreation> cacheCreation`

        Breakdown of cached tokens by TTL

      - `long cacheCreationInputTokens`

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

      - `long cacheReadInputTokens`

        The number of input tokens read from the cache.

      - `long inputTokens`

        The number of input tokens which were used.

      - `long outputTokens`

        The number of output tokens which were used.

      - `JsonValue; type "compaction"constant`

        Usage for a compaction iteration

        - `COMPACTION("compaction")`

    - `class BetaAdvisorMessageIterationUsage:`

      Token usage for an advisor sub-inference iteration.

      - `Optional<BetaCacheCreation> cacheCreation`

        Breakdown of cached tokens by TTL

      - `long cacheCreationInputTokens`

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

      - `long cacheReadInputTokens`

        The number of input tokens read from the cache.

      - `long inputTokens`

        The number of input tokens which were used.

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `long outputTokens`

        The number of output tokens which were used.

      - `JsonValue; type "advisor_message"constant`

        Usage for an advisor sub-inference iteration

        - `ADVISOR_MESSAGE("advisor_message")`

    - `class BetaFallbackMessageIterationUsage:`

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

      - `Optional<BetaCacheCreation> cacheCreation`

        Breakdown of cached tokens by TTL

      - `long cacheCreationInputTokens`

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

      - `long cacheReadInputTokens`

        The number of input tokens read from the cache.

      - `long inputTokens`

        The number of input tokens which were used.

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `long outputTokens`

        The number of output tokens which were used.

      - `JsonValue; type "fallback_message"constant`

        Usage for the fallback-model attempt that served the response

        - `FALLBACK_MESSAGE("fallback_message")`

  - `long outputTokens`

    The cumulative number of output tokens which were used.

  - `Optional<BetaOutputTokensDetails> outputTokensDetails`

    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.

    - `long thinkingTokens`

      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.

  - `Optional<BetaServerToolUsage> serverToolUse`

    The number of server tool requests.

    - `long webFetchRequests`

      The number of web fetch tool requests.

    - `long webSearchRequests`

      The number of web search tool requests.

### Beta Message Iteration Usage

- `class BetaMessageIterationUsage:`

  Token usage for a sampling iteration.

  - `Optional<BetaCacheCreation> cacheCreation`

    Breakdown of cached tokens by TTL

    - `long ephemeral1hInputTokens`

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

    - `long ephemeral5mInputTokens`

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

  - `long cacheCreationInputTokens`

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

  - `long cacheReadInputTokens`

    The number of input tokens read from the cache.

  - `long inputTokens`

    The number of input tokens which were used.

  - `Model model`

    The model that will complete your prompt.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `CLAUDE_FABLE_5("claude-fable-5")`

      Next generation of intelligence for the hardest knowledge work and coding problems

    - `CLAUDE_MYTHOS_5("claude-mythos-5")`

      Most capable model for cybersecurity and biology research

    - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

      New class of intelligence, strongest in coding and cybersecurity

    - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

      Best combination of speed and intelligence

    - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

      High-performance model for agents and coding

    - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

      High-performance model for agents and coding

    - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

      Exceptional model for specialized complex tasks

    - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

      Powerful model for complex tasks

    - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

      Powerful model for complex tasks

    - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

      High-performance model with extended thinking

    - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

      High-performance model with extended thinking

    - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

      Fast and cost-effective model

  - `long outputTokens`

    The number of output tokens which were used.

  - `JsonValue; type "message"constant`

    Usage for a sampling iteration

    - `MESSAGE("message")`

### Beta Message Param

- `class BetaMessageParam:`

  - `Content content`

    - `String`

    - `List<BetaContentBlockParam>`

      - `class BetaTextBlockParam:`

        - `String text`

        - `JsonValue; type "text"constant`

          - `TEXT("text")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

          - `JsonValue; type "ephemeral"constant`

            - `EPHEMERAL("ephemeral")`

          - `Optional<Ttl> ttl`

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

            - `TTL_5M("5m")`

            - `TTL_1H("1h")`

        - `Optional<List<BetaTextCitationParam>> citations`

          - `class BetaCitationCharLocationParam:`

            - `String citedText`

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endCharIndex`

            - `long startCharIndex`

            - `JsonValue; type "char_location"constant`

              - `CHAR_LOCATION("char_location")`

          - `class BetaCitationPageLocationParam:`

            - `String citedText`

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endPageNumber`

            - `long startPageNumber`

            - `JsonValue; type "page_location"constant`

              - `PAGE_LOCATION("page_location")`

          - `class BetaCitationContentBlockLocationParam:`

            - `String citedText`

              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.

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endBlockIndex`

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

            - `long startBlockIndex`

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

            - `JsonValue; type "content_block_location"constant`

              - `CONTENT_BLOCK_LOCATION("content_block_location")`

          - `class BetaCitationWebSearchResultLocationParam:`

            - `String citedText`

            - `String encryptedIndex`

            - `Optional<String> title`

            - `JsonValue; type "web_search_result_location"constant`

              - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

            - `String url`

          - `class BetaCitationSearchResultLocationParam:`

            - `String citedText`

              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.

            - `long endBlockIndex`

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

            - `long searchResultIndex`

              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.

            - `String source`

            - `long startBlockIndex`

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

            - `Optional<String> title`

            - `JsonValue; type "search_result_location"constant`

              - `SEARCH_RESULT_LOCATION("search_result_location")`

      - `class BetaImageBlockParam:`

        - `Source source`

          - `class BetaBase64ImageSource:`

            - `String data`

            - `MediaType mediaType`

              - `IMAGE_JPEG("image/jpeg")`

              - `IMAGE_PNG("image/png")`

              - `IMAGE_GIF("image/gif")`

              - `IMAGE_WEBP("image/webp")`

            - `JsonValue; type "base64"constant`

              - `BASE64("base64")`

          - `class BetaUrlImageSource:`

            - `JsonValue; type "url"constant`

              - `URL("url")`

            - `String url`

          - `class BetaFileImageSource:`

            - `String fileId`

            - `JsonValue; type "file"constant`

              - `FILE("file")`

        - `JsonValue; type "image"constant`

          - `IMAGE("image")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

      - `class BetaRequestDocumentBlock:`

        - `Source source`

          - `class BetaBase64PdfSource:`

            - `String data`

            - `JsonValue; mediaType "application/pdf"constant`

              - `APPLICATION_PDF("application/pdf")`

            - `JsonValue; type "base64"constant`

              - `BASE64("base64")`

          - `class BetaPlainTextSource:`

            - `String data`

            - `JsonValue; mediaType "text/plain"constant`

              - `TEXT_PLAIN("text/plain")`

            - `JsonValue; type "text"constant`

              - `TEXT("text")`

          - `class BetaContentBlockSource:`

            - `Content content`

              - `String`

              - `List<BetaContentBlockSourceContent>`

                - `class BetaTextBlockParam:`

                - `class BetaImageBlockParam:`

            - `JsonValue; type "content"constant`

              - `CONTENT("content")`

          - `class BetaUrlPdfSource:`

            - `JsonValue; type "url"constant`

              - `URL("url")`

            - `String url`

          - `class BetaFileDocumentSource:`

            - `String fileId`

            - `JsonValue; type "file"constant`

              - `FILE("file")`

        - `JsonValue; type "document"constant`

          - `DOCUMENT("document")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<BetaCitationsConfigParam> citations`

          - `Optional<Boolean> enabled`

        - `Optional<String> context`

        - `Optional<String> title`

      - `class BetaSearchResultBlockParam:`

        - `List<BetaTextBlockParam> content`

          - `String text`

          - `JsonValue; type "text"constant`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<List<BetaTextCitationParam>> citations`

        - `String source`

        - `String title`

        - `JsonValue; type "search_result"constant`

          - `SEARCH_RESULT("search_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<BetaCitationsConfigParam> citations`

      - `class BetaThinkingBlockParam:`

        - `String signature`

        - `String thinking`

        - `JsonValue; type "thinking"constant`

          - `THINKING("thinking")`

      - `class BetaRedactedThinkingBlockParam:`

        - `String data`

        - `JsonValue; type "redacted_thinking"constant`

          - `REDACTED_THINKING("redacted_thinking")`

      - `class BetaToolUseBlockParam:`

        - `String id`

        - `Input input`

        - `String name`

        - `JsonValue; type "tool_use"constant`

          - `TOOL_USE("tool_use")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

            - `JsonValue; type "direct"constant`

              - `DIRECT("direct")`

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

            - `String toolId`

            - `JsonValue; type "code_execution_20250825"constant`

              - `CODE_EXECUTION_20250825("code_execution_20250825")`

          - `class BetaServerToolCaller20260120:`

            - `String toolId`

            - `JsonValue; type "code_execution_20260120"constant`

              - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `class BetaToolResultBlockParam:`

        - `String toolUseId`

        - `JsonValue; type "tool_result"constant`

          - `TOOL_RESULT("tool_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<Content> content`

          - `String`

          - `List<Block>`

            - `class BetaTextBlockParam:`

            - `class BetaImageBlockParam:`

            - `class BetaSearchResultBlockParam:`

            - `class BetaRequestDocumentBlock:`

            - `class BetaToolReferenceBlockParam:`

              Tool reference block that can be included in tool_result content.

              - `String toolName`

              - `JsonValue; type "tool_reference"constant`

                - `TOOL_REFERENCE("tool_reference")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

        - `Optional<Boolean> isError`

      - `class BetaServerToolUseBlockParam:`

        - `String id`

        - `Input input`

        - `Name name`

          - `ADVISOR("advisor")`

          - `WEB_SEARCH("web_search")`

          - `WEB_FETCH("web_fetch")`

          - `CODE_EXECUTION("code_execution")`

          - `BASH_CODE_EXECUTION("bash_code_execution")`

          - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

          - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

          - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

        - `JsonValue; type "server_tool_use"constant`

          - `SERVER_TOOL_USE("server_tool_use")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

          - `class BetaServerToolCaller20260120:`

      - `class BetaWebSearchToolResultBlockParam:`

        - `BetaWebSearchToolResultBlockParamContent content`

          - `List<BetaWebSearchResultBlockParam>`

            - `String encryptedContent`

            - `String title`

            - `JsonValue; type "web_search_result"constant`

              - `WEB_SEARCH_RESULT("web_search_result")`

            - `String url`

            - `Optional<String> pageAge`

          - `class BetaWebSearchToolRequestError:`

            - `BetaWebSearchToolResultErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `MAX_USES_EXCEEDED("max_uses_exceeded")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `QUERY_TOO_LONG("query_too_long")`

              - `REQUEST_TOO_LARGE("request_too_large")`

            - `JsonValue; type "web_search_tool_result_error"constant`

              - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

        - `String toolUseId`

        - `JsonValue; type "web_search_tool_result"constant`

          - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

          - `class BetaServerToolCaller20260120:`

      - `class BetaWebFetchToolResultBlockParam:`

        - `Content content`

          - `class BetaWebFetchToolResultErrorBlockParam:`

            - `BetaWebFetchToolResultErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `URL_TOO_LONG("url_too_long")`

              - `URL_NOT_ALLOWED("url_not_allowed")`

              - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

              - `URL_NOT_ACCESSIBLE("url_not_accessible")`

              - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `MAX_USES_EXCEEDED("max_uses_exceeded")`

              - `UNAVAILABLE("unavailable")`

            - `JsonValue; type "web_fetch_tool_result_error"constant`

              - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

          - `class BetaWebFetchBlockParam:`

            - `BetaRequestDocumentBlock content`

            - `JsonValue; type "web_fetch_result"constant`

              - `WEB_FETCH_RESULT("web_fetch_result")`

            - `String url`

              Fetched content URL

            - `Optional<String> retrievedAt`

              ISO 8601 timestamp when the content was retrieved

        - `String toolUseId`

        - `JsonValue; type "web_fetch_tool_result"constant`

          - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

          - `class BetaServerToolCaller20260120:`

      - `class BetaAdvisorToolResultBlockParam:`

        - `Content content`

          - `class BetaAdvisorToolResultErrorParam:`

            - `ErrorCode errorCode`

              - `MAX_USES_EXCEEDED("max_uses_exceeded")`

              - `PROMPT_TOO_LONG("prompt_too_long")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `OVERLOADED("overloaded")`

              - `UNAVAILABLE("unavailable")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `MODEL_NOT_FOUND("model_not_found")`

            - `JsonValue; type "advisor_tool_result_error"constant`

              - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

          - `class BetaAdvisorResultBlockParam:`

            - `String text`

            - `JsonValue; type "advisor_result"constant`

              - `ADVISOR_RESULT("advisor_result")`

            - `Optional<String> stopReason`

          - `class BetaAdvisorRedactedResultBlockParam:`

            - `String encryptedContent`

              Opaque blob produced by a prior response; must be round-tripped verbatim.

            - `JsonValue; type "advisor_redacted_result"constant`

              - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

            - `Optional<String> stopReason`

        - `String toolUseId`

        - `JsonValue; type "advisor_tool_result"constant`

          - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

      - `class BetaCodeExecutionToolResultBlockParam:`

        - `BetaCodeExecutionToolResultBlockParamContent content`

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

          - `class BetaCodeExecutionToolResultErrorParam:`

            - `BetaCodeExecutionToolResultErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `JsonValue; type "code_execution_tool_result_error"constant`

              - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

          - `class BetaCodeExecutionResultBlockParam:`

            - `List<BetaCodeExecutionOutputBlockParam> content`

              - `String fileId`

              - `JsonValue; type "code_execution_output"constant`

                - `CODE_EXECUTION_OUTPUT("code_execution_output")`

            - `long returnCode`

            - `String stderr`

            - `String stdout`

            - `JsonValue; type "code_execution_result"constant`

              - `CODE_EXECUTION_RESULT("code_execution_result")`

          - `class BetaEncryptedCodeExecutionResultBlockParam:`

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

            - `List<BetaCodeExecutionOutputBlockParam> content`

              - `String fileId`

              - `JsonValue; type "code_execution_output"constant`

            - `String encryptedStdout`

            - `long returnCode`

            - `String stderr`

            - `JsonValue; type "encrypted_code_execution_result"constant`

              - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

        - `String toolUseId`

        - `JsonValue; type "code_execution_tool_result"constant`

          - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

      - `class BetaBashCodeExecutionToolResultBlockParam:`

        - `Content content`

          - `class BetaBashCodeExecutionToolResultErrorParam:`

            - `ErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

            - `JsonValue; type "bash_code_execution_tool_result_error"constant`

              - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

          - `class BetaBashCodeExecutionResultBlockParam:`

            - `List<BetaBashCodeExecutionOutputBlockParam> content`

              - `String fileId`

              - `JsonValue; type "bash_code_execution_output"constant`

                - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

            - `long returnCode`

            - `String stderr`

            - `String stdout`

            - `JsonValue; type "bash_code_execution_result"constant`

              - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

        - `String toolUseId`

        - `JsonValue; type "bash_code_execution_tool_result"constant`

          - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

      - `class BetaTextEditorCodeExecutionToolResultBlockParam:`

        - `Content content`

          - `class BetaTextEditorCodeExecutionToolResultErrorParam:`

            - `ErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `FILE_NOT_FOUND("file_not_found")`

            - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

            - `Optional<String> errorMessage`

          - `class BetaTextEditorCodeExecutionViewResultBlockParam:`

            - `String content`

            - `FileType fileType`

              - `TEXT("text")`

              - `IMAGE("image")`

              - `PDF("pdf")`

            - `JsonValue; type "text_editor_code_execution_view_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

            - `Optional<Long> numLines`

            - `Optional<Long> startLine`

            - `Optional<Long> totalLines`

          - `class BetaTextEditorCodeExecutionCreateResultBlockParam:`

            - `boolean isFileUpdate`

            - `JsonValue; type "text_editor_code_execution_create_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

          - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:`

            - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

            - `Optional<List<String>> lines`

            - `Optional<Long> newLines`

            - `Optional<Long> newStart`

            - `Optional<Long> oldLines`

            - `Optional<Long> oldStart`

        - `String toolUseId`

        - `JsonValue; type "text_editor_code_execution_tool_result"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

      - `class BetaToolSearchToolResultBlockParam:`

        - `Content content`

          - `class BetaToolSearchToolResultErrorParam:`

            - `ErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `JsonValue; type "tool_search_tool_result_error"constant`

              - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

            - `Optional<String> errorMessage`

          - `class BetaToolSearchToolSearchResultBlockParam:`

            - `List<BetaToolReferenceBlockParam> toolReferences`

              - `String toolName`

              - `JsonValue; type "tool_reference"constant`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

            - `JsonValue; type "tool_search_tool_search_result"constant`

              - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

        - `String toolUseId`

        - `JsonValue; type "tool_search_tool_result"constant`

          - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

      - `class BetaMcpToolUseBlockParam:`

        - `String id`

        - `Input input`

        - `String name`

        - `String serverName`

          The name of the MCP server

        - `JsonValue; type "mcp_tool_use"constant`

          - `MCP_TOOL_USE("mcp_tool_use")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

      - `class BetaRequestMcpToolResultBlockParam:`

        - `String toolUseId`

        - `JsonValue; type "mcp_tool_result"constant`

          - `MCP_TOOL_RESULT("mcp_tool_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<Content> content`

          - `String`

          - `List<BetaTextBlockParam>`

            - `String text`

            - `JsonValue; type "text"constant`

            - `Optional<BetaCacheControlEphemeral> cacheControl`

              Create a cache control breakpoint at this content block.

            - `Optional<List<BetaTextCitationParam>> citations`

        - `Optional<Boolean> isError`

      - `class BetaContainerUploadBlockParam:`

        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.

        - `String fileId`

        - `JsonValue; type "container_upload"constant`

          - `CONTAINER_UPLOAD("container_upload")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

      - `class BetaCompactionBlockParam:`

        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.

        - `JsonValue; type "compaction"constant`

          - `COMPACTION("compaction")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<String> content`

          Summary of previously compacted content, or null if compaction failed

        - `Optional<String> encryptedContent`

          Opaque metadata from prior compaction, to be round-tripped verbatim

      - `class BetaMidConversationSystemBlockParam:`

        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.

        - `List<BetaTextBlockParam> content`

          System instruction text blocks.

          - `String text`

          - `JsonValue; type "text"constant`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<List<BetaTextCitationParam>> citations`

        - `JsonValue; type "mid_conv_system"constant`

          - `MID_CONV_SYSTEM("mid_conv_system")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

      - `class BetaFallbackBlockParam:`

        A `fallback` block echoed back from a prior response.

        Accepted in `messages[].content` and never rendered into the prompt,
        not validated against the request's `fallbacks` chain or top-level
        `model`, and stripped before the sticky-routing cache key is computed.

        Callers should echo the assistant turn verbatim — block included. The
        block's position is load-bearing for thinking verification: the thinking
        runs on either side of a fallback hop carry independently-rooted
        verification hash chains, and this block is the only record of where one
        chain ends and the next begins. When thinking runs flank the boundary,
        omitting the block merges the runs into one contiguous span whose hashes
        cannot verify (the request is rejected), and moving it into the middle of
        a single run splits that run's chain and is likewise rejected; between
        non-thinking blocks the block's placement has no verification effect.

        - `BetaFallbackInfoParam from`

          Identifies one hop of a fallback transition.

          - `Model model`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

            - `CLAUDE_FABLE_5("claude-fable-5")`

              Next generation of intelligence for the hardest knowledge work and coding problems

            - `CLAUDE_MYTHOS_5("claude-mythos-5")`

              Most capable model for cybersecurity and biology research

            - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

              Frontier intelligence for long-running agents and coding

            - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

              Frontier intelligence for long-running agents and coding

            - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

              New class of intelligence, strongest in coding and cybersecurity

            - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

              Frontier intelligence for long-running agents and coding

            - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

              Best combination of speed and intelligence

            - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

              Fastest model with near-frontier intelligence

            - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

              Fastest model with near-frontier intelligence

            - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

              Premium model combining maximum intelligence with practical performance

            - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

              Premium model combining maximum intelligence with practical performance

            - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

              High-performance model for agents and coding

            - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

              High-performance model for agents and coding

            - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

              Exceptional model for specialized complex tasks

            - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

              Exceptional model for specialized complex tasks

            - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

              Powerful model for complex tasks

            - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

              Powerful model for complex tasks

            - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

              High-performance model with extended thinking

            - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

              High-performance model with extended thinking

            - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

              Fast and cost-effective model

        - `BetaFallbackInfoParam to`

          Identifies one hop of a fallback transition.

        - `JsonValue; type "fallback"constant`

          - `FALLBACK("fallback")`

  - `Role role`

    - `USER("user")`

    - `ASSISTANT("assistant")`

    - `SYSTEM("system")`

### Beta Message Tokens Count

- `class BetaMessageTokensCount:`

  - `Optional<BetaCountTokensContextManagementResponse> contextManagement`

    Information about context management applied to the message.

    - `long originalInputTokens`

      The original token count before context management was applied

  - `long inputTokens`

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

### Beta Metadata

- `class BetaMetadata:`

  - `Optional<String> userId`

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

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

### Beta Mid Conversation System Block Param

- `class BetaMidConversationSystemBlockParam:`

  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.

  - `List<BetaTextBlockParam> content`

    System instruction text blocks.

    - `String text`

    - `JsonValue; type "text"constant`

      - `TEXT("text")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

      - `JsonValue; type "ephemeral"constant`

        - `EPHEMERAL("ephemeral")`

      - `Optional<Ttl> ttl`

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

        - `TTL_5M("5m")`

        - `TTL_1H("1h")`

    - `Optional<List<BetaTextCitationParam>> citations`

      - `class BetaCitationCharLocationParam:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endCharIndex`

        - `long startCharIndex`

        - `JsonValue; type "char_location"constant`

          - `CHAR_LOCATION("char_location")`

      - `class BetaCitationPageLocationParam:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endPageNumber`

        - `long startPageNumber`

        - `JsonValue; type "page_location"constant`

          - `PAGE_LOCATION("page_location")`

      - `class BetaCitationContentBlockLocationParam:`

        - `String citedText`

          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.

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endBlockIndex`

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

        - `long startBlockIndex`

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

        - `JsonValue; type "content_block_location"constant`

          - `CONTENT_BLOCK_LOCATION("content_block_location")`

      - `class BetaCitationWebSearchResultLocationParam:`

        - `String citedText`

        - `String encryptedIndex`

        - `Optional<String> title`

        - `JsonValue; type "web_search_result_location"constant`

          - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

        - `String url`

      - `class BetaCitationSearchResultLocationParam:`

        - `String citedText`

          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.

        - `long endBlockIndex`

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

        - `long searchResultIndex`

          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.

        - `String source`

        - `long startBlockIndex`

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

        - `Optional<String> title`

        - `JsonValue; type "search_result_location"constant`

          - `SEARCH_RESULT_LOCATION("search_result_location")`

  - `JsonValue; type "mid_conv_system"constant`

    - `MID_CONV_SYSTEM("mid_conv_system")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

### Beta Output Config

- `class BetaOutputConfig:`

  - `Optional<Effort> effort`

    All possible effort levels.

    - `LOW("low")`

    - `MEDIUM("medium")`

    - `HIGH("high")`

    - `XHIGH("xhigh")`

    - `MAX("max")`

  - `Optional<BetaJsonOutputFormat> format`

    A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

    - `Schema schema`

      The JSON schema of the format

    - `JsonValue; type "json_schema"constant`

      - `JSON_SCHEMA("json_schema")`

  - `Optional<BetaTokenTaskBudget> taskBudget`

    User-configurable total token budget across contexts.

    - `long total`

      Total token budget across all contexts in the session.

    - `JsonValue; type "tokens"constant`

      The budget type. Currently only 'tokens' is supported.

      - `TOKENS("tokens")`

    - `Optional<Long> remaining`

      Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.

### Beta Output Tokens Details

- `class BetaOutputTokensDetails:`

  - `long thinkingTokens`

    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.

### Beta Plain Text Source

- `class BetaPlainTextSource:`

  - `String data`

  - `JsonValue; mediaType "text/plain"constant`

    - `TEXT_PLAIN("text/plain")`

  - `JsonValue; type "text"constant`

    - `TEXT("text")`

### Beta Raw Content Block Delta

- `class BetaRawContentBlockDelta: A class that can be one of several variants.union`

  - `class BetaTextDelta:`

    - `String text`

    - `JsonValue; type "text_delta"constant`

      - `TEXT_DELTA("text_delta")`

  - `class BetaInputJsonDelta:`

    - `String partialJson`

    - `JsonValue; type "input_json_delta"constant`

      - `INPUT_JSON_DELTA("input_json_delta")`

  - `class BetaCitationsDelta:`

    - `Citation citation`

      - `class BetaCitationCharLocation:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endCharIndex`

        - `Optional<String> fileId`

        - `long startCharIndex`

        - `JsonValue; type "char_location"constant`

          - `CHAR_LOCATION("char_location")`

      - `class BetaCitationPageLocation:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endPageNumber`

        - `Optional<String> fileId`

        - `long startPageNumber`

        - `JsonValue; type "page_location"constant`

          - `PAGE_LOCATION("page_location")`

      - `class BetaCitationContentBlockLocation:`

        - `String citedText`

          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.

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endBlockIndex`

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

        - `Optional<String> fileId`

        - `long startBlockIndex`

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

        - `JsonValue; type "content_block_location"constant`

          - `CONTENT_BLOCK_LOCATION("content_block_location")`

      - `class BetaCitationsWebSearchResultLocation:`

        - `String citedText`

        - `String encryptedIndex`

        - `Optional<String> title`

        - `JsonValue; type "web_search_result_location"constant`

          - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

        - `String url`

      - `class BetaCitationSearchResultLocation:`

        - `String citedText`

          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.

        - `long endBlockIndex`

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

        - `long searchResultIndex`

          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.

        - `String source`

        - `long startBlockIndex`

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

        - `Optional<String> title`

        - `JsonValue; type "search_result_location"constant`

          - `SEARCH_RESULT_LOCATION("search_result_location")`

    - `JsonValue; type "citations_delta"constant`

      - `CITATIONS_DELTA("citations_delta")`

  - `class BetaThinkingDelta:`

    - `Optional<Long> estimatedTokens`

      Per-frame increment of a coarse, running estimate of the tokens this thinking block has produced so far. Present whenever the `thinking-token-count-2026-05-13` beta is set; `null` unless `thinking.display` resolves to `"omitted"` and a count is due this frame. Sum the increments across `thinking_delta` frames on this block for a progress indicator. Each increment is a non-negative multiple of a fixed quantum and the cadence is rate-limited, so this is a deliberately lossy display hint, not a billable count; `usage.output_tokens` remains authoritative.

    - `String thinking`

    - `JsonValue; type "thinking_delta"constant`

      - `THINKING_DELTA("thinking_delta")`

  - `class BetaSignatureDelta:`

    - `String signature`

    - `JsonValue; type "signature_delta"constant`

      - `SIGNATURE_DELTA("signature_delta")`

  - `class BetaCompactionContentBlockDelta:`

    - `Optional<String> content`

    - `Optional<String> encryptedContent`

      Opaque metadata from prior compaction, to be round-tripped verbatim

    - `JsonValue; type "compaction_delta"constant`

      - `COMPACTION_DELTA("compaction_delta")`

### Beta Raw Content Block Delta Event

- `class BetaRawContentBlockDeltaEvent:`

  - `BetaRawContentBlockDelta delta`

    - `class BetaTextDelta:`

      - `String text`

      - `JsonValue; type "text_delta"constant`

        - `TEXT_DELTA("text_delta")`

    - `class BetaInputJsonDelta:`

      - `String partialJson`

      - `JsonValue; type "input_json_delta"constant`

        - `INPUT_JSON_DELTA("input_json_delta")`

    - `class BetaCitationsDelta:`

      - `Citation citation`

        - `class BetaCitationCharLocation:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endCharIndex`

          - `Optional<String> fileId`

          - `long startCharIndex`

          - `JsonValue; type "char_location"constant`

            - `CHAR_LOCATION("char_location")`

        - `class BetaCitationPageLocation:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endPageNumber`

          - `Optional<String> fileId`

          - `long startPageNumber`

          - `JsonValue; type "page_location"constant`

            - `PAGE_LOCATION("page_location")`

        - `class BetaCitationContentBlockLocation:`

          - `String citedText`

            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.

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endBlockIndex`

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

          - `Optional<String> fileId`

          - `long startBlockIndex`

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

          - `JsonValue; type "content_block_location"constant`

            - `CONTENT_BLOCK_LOCATION("content_block_location")`

        - `class BetaCitationsWebSearchResultLocation:`

          - `String citedText`

          - `String encryptedIndex`

          - `Optional<String> title`

          - `JsonValue; type "web_search_result_location"constant`

            - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

          - `String url`

        - `class BetaCitationSearchResultLocation:`

          - `String citedText`

            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.

          - `long endBlockIndex`

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

          - `long searchResultIndex`

            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.

          - `String source`

          - `long startBlockIndex`

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

          - `Optional<String> title`

          - `JsonValue; type "search_result_location"constant`

            - `SEARCH_RESULT_LOCATION("search_result_location")`

      - `JsonValue; type "citations_delta"constant`

        - `CITATIONS_DELTA("citations_delta")`

    - `class BetaThinkingDelta:`

      - `Optional<Long> estimatedTokens`

        Per-frame increment of a coarse, running estimate of the tokens this thinking block has produced so far. Present whenever the `thinking-token-count-2026-05-13` beta is set; `null` unless `thinking.display` resolves to `"omitted"` and a count is due this frame. Sum the increments across `thinking_delta` frames on this block for a progress indicator. Each increment is a non-negative multiple of a fixed quantum and the cadence is rate-limited, so this is a deliberately lossy display hint, not a billable count; `usage.output_tokens` remains authoritative.

      - `String thinking`

      - `JsonValue; type "thinking_delta"constant`

        - `THINKING_DELTA("thinking_delta")`

    - `class BetaSignatureDelta:`

      - `String signature`

      - `JsonValue; type "signature_delta"constant`

        - `SIGNATURE_DELTA("signature_delta")`

    - `class BetaCompactionContentBlockDelta:`

      - `Optional<String> content`

      - `Optional<String> encryptedContent`

        Opaque metadata from prior compaction, to be round-tripped verbatim

      - `JsonValue; type "compaction_delta"constant`

        - `COMPACTION_DELTA("compaction_delta")`

  - `long index`

  - `JsonValue; type "content_block_delta"constant`

    - `CONTENT_BLOCK_DELTA("content_block_delta")`

### Beta Raw Content Block Start Event

- `class BetaRawContentBlockStartEvent:`

  - `ContentBlock contentBlock`

    Response model for a file uploaded to the container.

    - `class BetaTextBlock:`

      - `Optional<List<BetaTextCitation>> citations`

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

        - `class BetaCitationCharLocation:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endCharIndex`

          - `Optional<String> fileId`

          - `long startCharIndex`

          - `JsonValue; type "char_location"constant`

            - `CHAR_LOCATION("char_location")`

        - `class BetaCitationPageLocation:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endPageNumber`

          - `Optional<String> fileId`

          - `long startPageNumber`

          - `JsonValue; type "page_location"constant`

            - `PAGE_LOCATION("page_location")`

        - `class BetaCitationContentBlockLocation:`

          - `String citedText`

            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.

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endBlockIndex`

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

          - `Optional<String> fileId`

          - `long startBlockIndex`

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

          - `JsonValue; type "content_block_location"constant`

            - `CONTENT_BLOCK_LOCATION("content_block_location")`

        - `class BetaCitationsWebSearchResultLocation:`

          - `String citedText`

          - `String encryptedIndex`

          - `Optional<String> title`

          - `JsonValue; type "web_search_result_location"constant`

            - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

          - `String url`

        - `class BetaCitationSearchResultLocation:`

          - `String citedText`

            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.

          - `long endBlockIndex`

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

          - `long searchResultIndex`

            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.

          - `String source`

          - `long startBlockIndex`

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

          - `Optional<String> title`

          - `JsonValue; type "search_result_location"constant`

            - `SEARCH_RESULT_LOCATION("search_result_location")`

      - `String text`

      - `JsonValue; type "text"constant`

        - `TEXT("text")`

    - `class BetaThinkingBlock:`

      - `String signature`

      - `String thinking`

      - `JsonValue; type "thinking"constant`

        - `THINKING("thinking")`

    - `class BetaRedactedThinkingBlock:`

      - `String data`

      - `JsonValue; type "redacted_thinking"constant`

        - `REDACTED_THINKING("redacted_thinking")`

    - `class BetaToolUseBlock:`

      - `String id`

      - `Input input`

      - `String name`

      - `JsonValue; type "tool_use"constant`

        - `TOOL_USE("tool_use")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

          - `JsonValue; type "direct"constant`

            - `DIRECT("direct")`

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

          - `String toolId`

          - `JsonValue; type "code_execution_20250825"constant`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

        - `class BetaServerToolCaller20260120:`

          - `String toolId`

          - `JsonValue; type "code_execution_20260120"constant`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `class BetaServerToolUseBlock:`

      - `String id`

      - `Input input`

      - `Name name`

        - `ADVISOR("advisor")`

        - `WEB_SEARCH("web_search")`

        - `WEB_FETCH("web_fetch")`

        - `CODE_EXECUTION("code_execution")`

        - `BASH_CODE_EXECUTION("bash_code_execution")`

        - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

        - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

        - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

      - `JsonValue; type "server_tool_use"constant`

        - `SERVER_TOOL_USE("server_tool_use")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

        - `class BetaServerToolCaller20260120:`

    - `class BetaWebSearchToolResultBlock:`

      - `BetaWebSearchToolResultBlockContent content`

        - `class BetaWebSearchToolResultError:`

          - `BetaWebSearchToolResultErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `MAX_USES_EXCEEDED("max_uses_exceeded")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `QUERY_TOO_LONG("query_too_long")`

            - `REQUEST_TOO_LARGE("request_too_large")`

          - `JsonValue; type "web_search_tool_result_error"constant`

            - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

        - `List<BetaWebSearchResultBlock>`

          - `String encryptedContent`

          - `Optional<String> pageAge`

          - `String title`

          - `JsonValue; type "web_search_result"constant`

            - `WEB_SEARCH_RESULT("web_search_result")`

          - `String url`

      - `String toolUseId`

      - `JsonValue; type "web_search_tool_result"constant`

        - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

        - `class BetaServerToolCaller20260120:`

    - `class BetaWebFetchToolResultBlock:`

      - `Content content`

        - `class BetaWebFetchToolResultErrorBlock:`

          - `BetaWebFetchToolResultErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `URL_TOO_LONG("url_too_long")`

            - `URL_NOT_ALLOWED("url_not_allowed")`

            - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

            - `URL_NOT_ACCESSIBLE("url_not_accessible")`

            - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `MAX_USES_EXCEEDED("max_uses_exceeded")`

            - `UNAVAILABLE("unavailable")`

          - `JsonValue; type "web_fetch_tool_result_error"constant`

            - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

        - `class BetaWebFetchBlock:`

          - `BetaDocumentBlock content`

            - `Optional<BetaCitationConfig> citations`

              Citation configuration for the document

              - `boolean enabled`

            - `Source source`

              - `class BetaBase64PdfSource:`

                - `String data`

                - `JsonValue; mediaType "application/pdf"constant`

                  - `APPLICATION_PDF("application/pdf")`

                - `JsonValue; type "base64"constant`

                  - `BASE64("base64")`

              - `class BetaPlainTextSource:`

                - `String data`

                - `JsonValue; mediaType "text/plain"constant`

                  - `TEXT_PLAIN("text/plain")`

                - `JsonValue; type "text"constant`

                  - `TEXT("text")`

            - `Optional<String> title`

              The title of the document

            - `JsonValue; type "document"constant`

              - `DOCUMENT("document")`

          - `Optional<String> retrievedAt`

            ISO 8601 timestamp when the content was retrieved

          - `JsonValue; type "web_fetch_result"constant`

            - `WEB_FETCH_RESULT("web_fetch_result")`

          - `String url`

            Fetched content URL

      - `String toolUseId`

      - `JsonValue; type "web_fetch_tool_result"constant`

        - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

      - `Optional<Caller> caller`

        Tool invocation directly from the model.

        - `class BetaDirectCaller:`

          Tool invocation directly from the model.

        - `class BetaServerToolCaller:`

          Tool invocation generated by a server-side tool.

        - `class BetaServerToolCaller20260120:`

    - `class BetaAdvisorToolResultBlock:`

      - `Content content`

        - `class BetaAdvisorToolResultError:`

          - `ErrorCode errorCode`

            - `MAX_USES_EXCEEDED("max_uses_exceeded")`

            - `PROMPT_TOO_LONG("prompt_too_long")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `OVERLOADED("overloaded")`

            - `UNAVAILABLE("unavailable")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `MODEL_NOT_FOUND("model_not_found")`

          - `JsonValue; type "advisor_tool_result_error"constant`

            - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

        - `class BetaAdvisorResultBlock:`

          - `Optional<String> stopReason`

            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.

          - `String text`

          - `JsonValue; type "advisor_result"constant`

            - `ADVISOR_RESULT("advisor_result")`

        - `class BetaAdvisorRedactedResultBlock:`

          - `String encryptedContent`

            Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

          - `Optional<String> stopReason`

            The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

          - `JsonValue; type "advisor_redacted_result"constant`

            - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

      - `String toolUseId`

      - `JsonValue; type "advisor_tool_result"constant`

        - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

    - `class BetaCodeExecutionToolResultBlock:`

      - `BetaCodeExecutionToolResultBlockContent content`

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

        - `class BetaCodeExecutionToolResultError:`

          - `BetaCodeExecutionToolResultErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `JsonValue; type "code_execution_tool_result_error"constant`

            - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

        - `class BetaCodeExecutionResultBlock:`

          - `List<BetaCodeExecutionOutputBlock> content`

            - `String fileId`

            - `JsonValue; type "code_execution_output"constant`

              - `CODE_EXECUTION_OUTPUT("code_execution_output")`

          - `long returnCode`

          - `String stderr`

          - `String stdout`

          - `JsonValue; type "code_execution_result"constant`

            - `CODE_EXECUTION_RESULT("code_execution_result")`

        - `class BetaEncryptedCodeExecutionResultBlock:`

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

          - `List<BetaCodeExecutionOutputBlock> content`

            - `String fileId`

            - `JsonValue; type "code_execution_output"constant`

          - `String encryptedStdout`

          - `long returnCode`

          - `String stderr`

          - `JsonValue; type "encrypted_code_execution_result"constant`

            - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

      - `String toolUseId`

      - `JsonValue; type "code_execution_tool_result"constant`

        - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

    - `class BetaBashCodeExecutionToolResultBlock:`

      - `Content content`

        - `class BetaBashCodeExecutionToolResultError:`

          - `ErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

          - `JsonValue; type "bash_code_execution_tool_result_error"constant`

            - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

        - `class BetaBashCodeExecutionResultBlock:`

          - `List<BetaBashCodeExecutionOutputBlock> content`

            - `String fileId`

            - `JsonValue; type "bash_code_execution_output"constant`

              - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

          - `long returnCode`

          - `String stderr`

          - `String stdout`

          - `JsonValue; type "bash_code_execution_result"constant`

            - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

      - `String toolUseId`

      - `JsonValue; type "bash_code_execution_tool_result"constant`

        - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

    - `class BetaTextEditorCodeExecutionToolResultBlock:`

      - `Content content`

        - `class BetaTextEditorCodeExecutionToolResultError:`

          - `ErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `FILE_NOT_FOUND("file_not_found")`

          - `Optional<String> errorMessage`

          - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

        - `class BetaTextEditorCodeExecutionViewResultBlock:`

          - `String content`

          - `FileType fileType`

            - `TEXT("text")`

            - `IMAGE("image")`

            - `PDF("pdf")`

          - `Optional<Long> numLines`

          - `Optional<Long> startLine`

          - `Optional<Long> totalLines`

          - `JsonValue; type "text_editor_code_execution_view_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

        - `class BetaTextEditorCodeExecutionCreateResultBlock:`

          - `boolean isFileUpdate`

          - `JsonValue; type "text_editor_code_execution_create_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

        - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

          - `Optional<List<String>> lines`

          - `Optional<Long> newLines`

          - `Optional<Long> newStart`

          - `Optional<Long> oldLines`

          - `Optional<Long> oldStart`

          - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

      - `String toolUseId`

      - `JsonValue; type "text_editor_code_execution_tool_result"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

    - `class BetaToolSearchToolResultBlock:`

      - `Content content`

        - `class BetaToolSearchToolResultError:`

          - `ErrorCode errorCode`

            - `INVALID_TOOL_INPUT("invalid_tool_input")`

            - `UNAVAILABLE("unavailable")`

            - `TOO_MANY_REQUESTS("too_many_requests")`

            - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

          - `Optional<String> errorMessage`

          - `JsonValue; type "tool_search_tool_result_error"constant`

            - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

        - `class BetaToolSearchToolSearchResultBlock:`

          - `List<BetaToolReferenceBlock> toolReferences`

            - `String toolName`

            - `JsonValue; type "tool_reference"constant`

              - `TOOL_REFERENCE("tool_reference")`

          - `JsonValue; type "tool_search_tool_search_result"constant`

            - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

      - `String toolUseId`

      - `JsonValue; type "tool_search_tool_result"constant`

        - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

    - `class BetaMcpToolUseBlock:`

      - `String id`

      - `Input input`

      - `String name`

        The name of the MCP tool

      - `String serverName`

        The name of the MCP server

      - `JsonValue; type "mcp_tool_use"constant`

        - `MCP_TOOL_USE("mcp_tool_use")`

    - `class BetaMcpToolResultBlock:`

      - `Content content`

        - `String`

        - `List<BetaTextBlock>`

          - `Optional<List<BetaTextCitation>> citations`

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

          - `String text`

          - `JsonValue; type "text"constant`

      - `boolean isError`

      - `String toolUseId`

      - `JsonValue; type "mcp_tool_result"constant`

        - `MCP_TOOL_RESULT("mcp_tool_result")`

    - `class BetaContainerUploadBlock:`

      Response model for a file uploaded to the container.

      - `String fileId`

      - `JsonValue; type "container_upload"constant`

        - `CONTAINER_UPLOAD("container_upload")`

    - `class BetaCompactionBlock:`

      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.

      - `Optional<String> content`

        Summary of compacted content, or null if compaction failed

      - `Optional<String> encryptedContent`

        Opaque metadata from prior compaction, to be round-tripped verbatim

      - `JsonValue; type "compaction"constant`

        - `COMPACTION("compaction")`

    - `class BetaFallbackBlock:`

      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 routed directly by the sticky decision 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.

      - `BetaFallbackInfo from`

        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.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_MYTHOS_5("claude-mythos-5")`

            Most capable model for cybersecurity and biology research

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

            New class of intelligence, strongest in coding and cybersecurity

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

          - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

            Exceptional model for specialized complex tasks

          - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

            Exceptional model for specialized complex tasks

          - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

            Powerful model for complex tasks

          - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

            Powerful model for complex tasks

          - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

            High-performance model with extended thinking

          - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

            High-performance model with extended thinking

          - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

            Fast and cost-effective model

      - `BetaFallbackInfo to`

        The fallback model producing the content that follows this block. Its `model` is always the canonical id.

      - `JsonValue; type "fallback"constant`

        - `FALLBACK("fallback")`

  - `long index`

  - `JsonValue; type "content_block_start"constant`

    - `CONTENT_BLOCK_START("content_block_start")`

### Beta Raw Content Block Stop Event

- `class BetaRawContentBlockStopEvent:`

  - `long index`

  - `JsonValue; type "content_block_stop"constant`

    - `CONTENT_BLOCK_STOP("content_block_stop")`

### Beta Raw Message Delta Event

- `class BetaRawMessageDeltaEvent:`

  - `Optional<BetaContextManagementResponse> contextManagement`

    Information about context management strategies applied during the request

    - `List<AppliedEdit> appliedEdits`

      List of context management edits that were applied.

      - `class BetaClearToolUses20250919EditResponse:`

        - `long clearedInputTokens`

          Number of input tokens cleared by this edit.

        - `long clearedToolUses`

          Number of tool uses that were cleared.

        - `JsonValue; type "clear_tool_uses_20250919"constant`

          The type of context management edit applied.

          - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

      - `class BetaClearThinking20251015EditResponse:`

        - `long clearedInputTokens`

          Number of input tokens cleared by this edit.

        - `long clearedThinkingTurns`

          Number of thinking turns that were cleared.

        - `JsonValue; type "clear_thinking_20251015"constant`

          The type of context management edit applied.

          - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

  - `Delta delta`

    - `Optional<BetaContainer> container`

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

      - `String id`

        Identifier for the container used in this request

      - `LocalDateTime expiresAt`

        The time at which the container will expire.

      - `Optional<List<BetaSkill>> skills`

        Skills loaded in the container

        - `String skillId`

          Skill ID

        - `Type type`

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

          - `ANTHROPIC("anthropic")`

          - `CUSTOM("custom")`

        - `String version`

          Skill version or 'latest' for most recent version

    - `Optional<BetaRefusalStopDetails> stopDetails`

      Structured information about a refusal.

      - `Optional<Category> category`

        The policy category that triggered the refusal.

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

        - `CYBER("cyber")`

        - `BIO("bio")`

        - `REASONING_EXTRACTION("reasoning_extraction")`

      - `Optional<String> explanation`

        Human-readable explanation of the refusal.

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

      - `Optional<String> fallbackCreditToken`

        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.

      - `Optional<Boolean> fallbackHasPrefillClaim`

        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.

      - `Optional<String> recommendedModel`

        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.

      - `JsonValue; type "refusal"constant`

        - `REFUSAL("refusal")`

    - `Optional<BetaStopReason> stopReason`

      - `END_TURN("end_turn")`

      - `MAX_TOKENS("max_tokens")`

      - `STOP_SEQUENCE("stop_sequence")`

      - `TOOL_USE("tool_use")`

      - `PAUSE_TURN("pause_turn")`

      - `COMPACTION("compaction")`

      - `REFUSAL("refusal")`

      - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")`

    - `Optional<String> stopSequence`

  - `JsonValue; type "message_delta"constant`

    - `MESSAGE_DELTA("message_delta")`

  - `BetaMessageDeltaUsage usage`

    Billing and rate-limit usage.

    Anthropic'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 Claude.

    Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.

    - `Optional<Long> cacheCreationInputTokens`

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

    - `Optional<Long> cacheReadInputTokens`

      The cumulative number of input tokens read from the cache.

    - `Optional<Long> inputTokens`

      The cumulative number of input tokens which were used.

    - `Optional<List<BetaIterationsUsageItems>> iterations`

      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

      - `class BetaMessageIterationUsage:`

        Token usage for a sampling iteration.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

          - `long ephemeral1hInputTokens`

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

          - `long ephemeral5mInputTokens`

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

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_MYTHOS_5("claude-mythos-5")`

            Most capable model for cybersecurity and biology research

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

            New class of intelligence, strongest in coding and cybersecurity

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

          - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

            Exceptional model for specialized complex tasks

          - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

            Exceptional model for specialized complex tasks

          - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

            Powerful model for complex tasks

          - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

            Powerful model for complex tasks

          - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

            High-performance model with extended thinking

          - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

            High-performance model with extended thinking

          - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

            Fast and cost-effective model

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "message"constant`

          Usage for a sampling iteration

          - `MESSAGE("message")`

      - `class BetaCompactionIterationUsage:`

        Token usage for a compaction iteration.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "compaction"constant`

          Usage for a compaction iteration

          - `COMPACTION("compaction")`

      - `class BetaAdvisorMessageIterationUsage:`

        Token usage for an advisor sub-inference iteration.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "advisor_message"constant`

          Usage for an advisor sub-inference iteration

          - `ADVISOR_MESSAGE("advisor_message")`

      - `class BetaFallbackMessageIterationUsage:`

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

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

        - `long cacheCreationInputTokens`

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

        - `long cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `long outputTokens`

          The number of output tokens which were used.

        - `JsonValue; type "fallback_message"constant`

          Usage for the fallback-model attempt that served the response

          - `FALLBACK_MESSAGE("fallback_message")`

    - `long outputTokens`

      The cumulative number of output tokens which were used.

    - `Optional<BetaOutputTokensDetails> outputTokensDetails`

      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.

      - `long thinkingTokens`

        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.

    - `Optional<BetaServerToolUsage> serverToolUse`

      The number of server tool requests.

      - `long webFetchRequests`

        The number of web fetch tool requests.

      - `long webSearchRequests`

        The number of web search tool requests.

### Beta Raw Message Start Event

- `class BetaRawMessageStartEvent:`

  - `BetaMessage message`

    - `String id`

      Unique object identifier.

      The format and length of IDs may change over time.

    - `Optional<BetaContainer> container`

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

      - `String id`

        Identifier for the container used in this request

      - `LocalDateTime expiresAt`

        The time at which the container will expire.

      - `Optional<List<BetaSkill>> skills`

        Skills loaded in the container

        - `String skillId`

          Skill ID

        - `Type type`

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

          - `ANTHROPIC("anthropic")`

          - `CUSTOM("custom")`

        - `String version`

          Skill version or 'latest' for most recent version

    - `List<BetaContentBlock> content`

      Content generated by the model.

      This is an array of content blocks, each of which has a `type` that determines its shape.

      Example:

      ```json
      [{"type": "text", "text": "Hi, I'm Claude."}]
      ```

      If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.

      For example, if the input `messages` were:

      ```json
      [
        {"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)"}]
      ```

      - `class BetaTextBlock:`

        - `Optional<List<BetaTextCitation>> citations`

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

          - `class BetaCitationCharLocation:`

            - `String citedText`

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endCharIndex`

            - `Optional<String> fileId`

            - `long startCharIndex`

            - `JsonValue; type "char_location"constant`

              - `CHAR_LOCATION("char_location")`

          - `class BetaCitationPageLocation:`

            - `String citedText`

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endPageNumber`

            - `Optional<String> fileId`

            - `long startPageNumber`

            - `JsonValue; type "page_location"constant`

              - `PAGE_LOCATION("page_location")`

          - `class BetaCitationContentBlockLocation:`

            - `String citedText`

              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.

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endBlockIndex`

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

            - `Optional<String> fileId`

            - `long startBlockIndex`

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

            - `JsonValue; type "content_block_location"constant`

              - `CONTENT_BLOCK_LOCATION("content_block_location")`

          - `class BetaCitationsWebSearchResultLocation:`

            - `String citedText`

            - `String encryptedIndex`

            - `Optional<String> title`

            - `JsonValue; type "web_search_result_location"constant`

              - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

            - `String url`

          - `class BetaCitationSearchResultLocation:`

            - `String citedText`

              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.

            - `long endBlockIndex`

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

            - `long searchResultIndex`

              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.

            - `String source`

            - `long startBlockIndex`

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

            - `Optional<String> title`

            - `JsonValue; type "search_result_location"constant`

              - `SEARCH_RESULT_LOCATION("search_result_location")`

        - `String text`

        - `JsonValue; type "text"constant`

          - `TEXT("text")`

      - `class BetaThinkingBlock:`

        - `String signature`

        - `String thinking`

        - `JsonValue; type "thinking"constant`

          - `THINKING("thinking")`

      - `class BetaRedactedThinkingBlock:`

        - `String data`

        - `JsonValue; type "redacted_thinking"constant`

          - `REDACTED_THINKING("redacted_thinking")`

      - `class BetaToolUseBlock:`

        - `String id`

        - `Input input`

        - `String name`

        - `JsonValue; type "tool_use"constant`

          - `TOOL_USE("tool_use")`

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

            - `JsonValue; type "direct"constant`

              - `DIRECT("direct")`

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

            - `String toolId`

            - `JsonValue; type "code_execution_20250825"constant`

              - `CODE_EXECUTION_20250825("code_execution_20250825")`

          - `class BetaServerToolCaller20260120:`

            - `String toolId`

            - `JsonValue; type "code_execution_20260120"constant`

              - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `class BetaServerToolUseBlock:`

        - `String id`

        - `Input input`

        - `Name name`

          - `ADVISOR("advisor")`

          - `WEB_SEARCH("web_search")`

          - `WEB_FETCH("web_fetch")`

          - `CODE_EXECUTION("code_execution")`

          - `BASH_CODE_EXECUTION("bash_code_execution")`

          - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

          - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

          - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

        - `JsonValue; type "server_tool_use"constant`

          - `SERVER_TOOL_USE("server_tool_use")`

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

          - `class BetaServerToolCaller20260120:`

      - `class BetaWebSearchToolResultBlock:`

        - `BetaWebSearchToolResultBlockContent content`

          - `class BetaWebSearchToolResultError:`

            - `BetaWebSearchToolResultErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `MAX_USES_EXCEEDED("max_uses_exceeded")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `QUERY_TOO_LONG("query_too_long")`

              - `REQUEST_TOO_LARGE("request_too_large")`

            - `JsonValue; type "web_search_tool_result_error"constant`

              - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

          - `List<BetaWebSearchResultBlock>`

            - `String encryptedContent`

            - `Optional<String> pageAge`

            - `String title`

            - `JsonValue; type "web_search_result"constant`

              - `WEB_SEARCH_RESULT("web_search_result")`

            - `String url`

        - `String toolUseId`

        - `JsonValue; type "web_search_tool_result"constant`

          - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

          - `class BetaServerToolCaller20260120:`

      - `class BetaWebFetchToolResultBlock:`

        - `Content content`

          - `class BetaWebFetchToolResultErrorBlock:`

            - `BetaWebFetchToolResultErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `URL_TOO_LONG("url_too_long")`

              - `URL_NOT_ALLOWED("url_not_allowed")`

              - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

              - `URL_NOT_ACCESSIBLE("url_not_accessible")`

              - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `MAX_USES_EXCEEDED("max_uses_exceeded")`

              - `UNAVAILABLE("unavailable")`

            - `JsonValue; type "web_fetch_tool_result_error"constant`

              - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

          - `class BetaWebFetchBlock:`

            - `BetaDocumentBlock content`

              - `Optional<BetaCitationConfig> citations`

                Citation configuration for the document

                - `boolean enabled`

              - `Source source`

                - `class BetaBase64PdfSource:`

                  - `String data`

                  - `JsonValue; mediaType "application/pdf"constant`

                    - `APPLICATION_PDF("application/pdf")`

                  - `JsonValue; type "base64"constant`

                    - `BASE64("base64")`

                - `class BetaPlainTextSource:`

                  - `String data`

                  - `JsonValue; mediaType "text/plain"constant`

                    - `TEXT_PLAIN("text/plain")`

                  - `JsonValue; type "text"constant`

                    - `TEXT("text")`

              - `Optional<String> title`

                The title of the document

              - `JsonValue; type "document"constant`

                - `DOCUMENT("document")`

            - `Optional<String> retrievedAt`

              ISO 8601 timestamp when the content was retrieved

            - `JsonValue; type "web_fetch_result"constant`

              - `WEB_FETCH_RESULT("web_fetch_result")`

            - `String url`

              Fetched content URL

        - `String toolUseId`

        - `JsonValue; type "web_fetch_tool_result"constant`

          - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

          - `class BetaServerToolCaller20260120:`

      - `class BetaAdvisorToolResultBlock:`

        - `Content content`

          - `class BetaAdvisorToolResultError:`

            - `ErrorCode errorCode`

              - `MAX_USES_EXCEEDED("max_uses_exceeded")`

              - `PROMPT_TOO_LONG("prompt_too_long")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `OVERLOADED("overloaded")`

              - `UNAVAILABLE("unavailable")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `MODEL_NOT_FOUND("model_not_found")`

            - `JsonValue; type "advisor_tool_result_error"constant`

              - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

          - `class BetaAdvisorResultBlock:`

            - `Optional<String> stopReason`

              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.

            - `String text`

            - `JsonValue; type "advisor_result"constant`

              - `ADVISOR_RESULT("advisor_result")`

          - `class BetaAdvisorRedactedResultBlock:`

            - `String encryptedContent`

              Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

            - `Optional<String> stopReason`

              The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

            - `JsonValue; type "advisor_redacted_result"constant`

              - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

        - `String toolUseId`

        - `JsonValue; type "advisor_tool_result"constant`

          - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

      - `class BetaCodeExecutionToolResultBlock:`

        - `BetaCodeExecutionToolResultBlockContent content`

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

          - `class BetaCodeExecutionToolResultError:`

            - `BetaCodeExecutionToolResultErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `JsonValue; type "code_execution_tool_result_error"constant`

              - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

          - `class BetaCodeExecutionResultBlock:`

            - `List<BetaCodeExecutionOutputBlock> content`

              - `String fileId`

              - `JsonValue; type "code_execution_output"constant`

                - `CODE_EXECUTION_OUTPUT("code_execution_output")`

            - `long returnCode`

            - `String stderr`

            - `String stdout`

            - `JsonValue; type "code_execution_result"constant`

              - `CODE_EXECUTION_RESULT("code_execution_result")`

          - `class BetaEncryptedCodeExecutionResultBlock:`

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

            - `List<BetaCodeExecutionOutputBlock> content`

              - `String fileId`

              - `JsonValue; type "code_execution_output"constant`

            - `String encryptedStdout`

            - `long returnCode`

            - `String stderr`

            - `JsonValue; type "encrypted_code_execution_result"constant`

              - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

        - `String toolUseId`

        - `JsonValue; type "code_execution_tool_result"constant`

          - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

      - `class BetaBashCodeExecutionToolResultBlock:`

        - `Content content`

          - `class BetaBashCodeExecutionToolResultError:`

            - `ErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

            - `JsonValue; type "bash_code_execution_tool_result_error"constant`

              - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

          - `class BetaBashCodeExecutionResultBlock:`

            - `List<BetaBashCodeExecutionOutputBlock> content`

              - `String fileId`

              - `JsonValue; type "bash_code_execution_output"constant`

                - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

            - `long returnCode`

            - `String stderr`

            - `String stdout`

            - `JsonValue; type "bash_code_execution_result"constant`

              - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

        - `String toolUseId`

        - `JsonValue; type "bash_code_execution_tool_result"constant`

          - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

      - `class BetaTextEditorCodeExecutionToolResultBlock:`

        - `Content content`

          - `class BetaTextEditorCodeExecutionToolResultError:`

            - `ErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `FILE_NOT_FOUND("file_not_found")`

            - `Optional<String> errorMessage`

            - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

          - `class BetaTextEditorCodeExecutionViewResultBlock:`

            - `String content`

            - `FileType fileType`

              - `TEXT("text")`

              - `IMAGE("image")`

              - `PDF("pdf")`

            - `Optional<Long> numLines`

            - `Optional<Long> startLine`

            - `Optional<Long> totalLines`

            - `JsonValue; type "text_editor_code_execution_view_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

          - `class BetaTextEditorCodeExecutionCreateResultBlock:`

            - `boolean isFileUpdate`

            - `JsonValue; type "text_editor_code_execution_create_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

          - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

            - `Optional<List<String>> lines`

            - `Optional<Long> newLines`

            - `Optional<Long> newStart`

            - `Optional<Long> oldLines`

            - `Optional<Long> oldStart`

            - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

        - `String toolUseId`

        - `JsonValue; type "text_editor_code_execution_tool_result"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

      - `class BetaToolSearchToolResultBlock:`

        - `Content content`

          - `class BetaToolSearchToolResultError:`

            - `ErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `Optional<String> errorMessage`

            - `JsonValue; type "tool_search_tool_result_error"constant`

              - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

          - `class BetaToolSearchToolSearchResultBlock:`

            - `List<BetaToolReferenceBlock> toolReferences`

              - `String toolName`

              - `JsonValue; type "tool_reference"constant`

                - `TOOL_REFERENCE("tool_reference")`

            - `JsonValue; type "tool_search_tool_search_result"constant`

              - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

        - `String toolUseId`

        - `JsonValue; type "tool_search_tool_result"constant`

          - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

      - `class BetaMcpToolUseBlock:`

        - `String id`

        - `Input input`

        - `String name`

          The name of the MCP tool

        - `String serverName`

          The name of the MCP server

        - `JsonValue; type "mcp_tool_use"constant`

          - `MCP_TOOL_USE("mcp_tool_use")`

      - `class BetaMcpToolResultBlock:`

        - `Content content`

          - `String`

          - `List<BetaTextBlock>`

            - `Optional<List<BetaTextCitation>> citations`

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

            - `String text`

            - `JsonValue; type "text"constant`

        - `boolean isError`

        - `String toolUseId`

        - `JsonValue; type "mcp_tool_result"constant`

          - `MCP_TOOL_RESULT("mcp_tool_result")`

      - `class BetaContainerUploadBlock:`

        Response model for a file uploaded to the container.

        - `String fileId`

        - `JsonValue; type "container_upload"constant`

          - `CONTAINER_UPLOAD("container_upload")`

      - `class BetaCompactionBlock:`

        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.

        - `Optional<String> content`

          Summary of compacted content, or null if compaction failed

        - `Optional<String> encryptedContent`

          Opaque metadata from prior compaction, to be round-tripped verbatim

        - `JsonValue; type "compaction"constant`

          - `COMPACTION("compaction")`

      - `class BetaFallbackBlock:`

        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 routed directly by the sticky decision 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.

        - `BetaFallbackInfo from`

          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.

          - `Model model`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

            - `CLAUDE_FABLE_5("claude-fable-5")`

              Next generation of intelligence for the hardest knowledge work and coding problems

            - `CLAUDE_MYTHOS_5("claude-mythos-5")`

              Most capable model for cybersecurity and biology research

            - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

              Frontier intelligence for long-running agents and coding

            - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

              Frontier intelligence for long-running agents and coding

            - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

              New class of intelligence, strongest in coding and cybersecurity

            - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

              Frontier intelligence for long-running agents and coding

            - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

              Best combination of speed and intelligence

            - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

              Fastest model with near-frontier intelligence

            - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

              Fastest model with near-frontier intelligence

            - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

              Premium model combining maximum intelligence with practical performance

            - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

              Premium model combining maximum intelligence with practical performance

            - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

              High-performance model for agents and coding

            - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

              High-performance model for agents and coding

            - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

              Exceptional model for specialized complex tasks

            - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

              Exceptional model for specialized complex tasks

            - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

              Powerful model for complex tasks

            - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

              Powerful model for complex tasks

            - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

              High-performance model with extended thinking

            - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

              High-performance model with extended thinking

            - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

              Fast and cost-effective model

        - `BetaFallbackInfo to`

          The fallback model producing the content that follows this block. Its `model` is always the canonical id.

        - `JsonValue; type "fallback"constant`

          - `FALLBACK("fallback")`

    - `Optional<BetaContextManagementResponse> contextManagement`

      Context management response.

      Information about context management strategies applied during the request.

      - `List<AppliedEdit> appliedEdits`

        List of context management edits that were applied.

        - `class BetaClearToolUses20250919EditResponse:`

          - `long clearedInputTokens`

            Number of input tokens cleared by this edit.

          - `long clearedToolUses`

            Number of tool uses that were cleared.

          - `JsonValue; type "clear_tool_uses_20250919"constant`

            The type of context management edit applied.

            - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

        - `class BetaClearThinking20251015EditResponse:`

          - `long clearedInputTokens`

            Number of input tokens cleared by this edit.

          - `long clearedThinkingTurns`

            Number of thinking turns that were cleared.

          - `JsonValue; type "clear_thinking_20251015"constant`

            The type of context management edit applied.

            - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

    - `Optional<BetaDiagnostics> diagnostics`

      Response envelope for request-level diagnostics. Present (possibly
      null) whenever the caller supplied `diagnostics` on the request.

      - `Optional<CacheMissReason> cacheMissReason`

        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.

        - `class BetaCacheMissModelChanged:`

          - `long cacheMissedInputTokens`

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

          - `JsonValue; type "model_changed"constant`

            - `MODEL_CHANGED("model_changed")`

        - `class BetaCacheMissSystemChanged:`

          - `long cacheMissedInputTokens`

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

          - `JsonValue; type "system_changed"constant`

            - `SYSTEM_CHANGED("system_changed")`

        - `class BetaCacheMissToolsChanged:`

          - `long cacheMissedInputTokens`

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

          - `JsonValue; type "tools_changed"constant`

            - `TOOLS_CHANGED("tools_changed")`

        - `class BetaCacheMissMessagesChanged:`

          - `long cacheMissedInputTokens`

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

          - `JsonValue; type "messages_changed"constant`

            - `MESSAGES_CHANGED("messages_changed")`

        - `class BetaCacheMissPreviousMessageNotFound:`

          - `JsonValue; type "previous_message_not_found"constant`

            - `PREVIOUS_MESSAGE_NOT_FOUND("previous_message_not_found")`

        - `class BetaCacheMissUnavailable:`

          - `JsonValue; type "unavailable"constant`

            - `UNAVAILABLE("unavailable")`

    - `Model model`

      The model that will complete your prompt.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `JsonValue; role "assistant"constant`

      Conversational role of the generated message.

      This will always be `"assistant"`.

      - `ASSISTANT("assistant")`

    - `Optional<BetaRefusalStopDetails> stopDetails`

      Structured information about a refusal.

      - `Optional<Category> category`

        The policy category that triggered the refusal.

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

        - `CYBER("cyber")`

        - `BIO("bio")`

        - `REASONING_EXTRACTION("reasoning_extraction")`

      - `Optional<String> explanation`

        Human-readable explanation of the refusal.

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

      - `Optional<String> fallbackCreditToken`

        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.

      - `Optional<Boolean> fallbackHasPrefillClaim`

        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.

      - `Optional<String> recommendedModel`

        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.

      - `JsonValue; type "refusal"constant`

        - `REFUSAL("refusal")`

    - `Optional<BetaStopReason> stopReason`

      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

      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.

      - `END_TURN("end_turn")`

      - `MAX_TOKENS("max_tokens")`

      - `STOP_SEQUENCE("stop_sequence")`

      - `TOOL_USE("tool_use")`

      - `PAUSE_TURN("pause_turn")`

      - `COMPACTION("compaction")`

      - `REFUSAL("refusal")`

      - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")`

    - `Optional<String> stopSequence`

      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.

    - `JsonValue; type "message"constant`

      Object type.

      For Messages, this is always `"message"`.

      - `MESSAGE("message")`

    - `BetaUsage usage`

      Billing and rate-limit usage.

      Anthropic'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 Claude.

      Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.

      - `Optional<BetaCacheCreation> cacheCreation`

        Breakdown of cached tokens by TTL

        - `long ephemeral1hInputTokens`

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

        - `long ephemeral5mInputTokens`

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

      - `Optional<Long> cacheCreationInputTokens`

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

      - `Optional<Long> cacheReadInputTokens`

        The number of input tokens read from the cache.

      - `Optional<String> inferenceGeo`

        The geographic region where inference was performed for this request.

      - `long inputTokens`

        The number of input tokens which were used.

      - `Optional<List<BetaIterationsUsageItems>> iterations`

        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

        - `class BetaMessageIterationUsage:`

          Token usage for a sampling iteration.

          - `Optional<BetaCacheCreation> cacheCreation`

            Breakdown of cached tokens by TTL

          - `long cacheCreationInputTokens`

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

          - `long cacheReadInputTokens`

            The number of input tokens read from the cache.

          - `long inputTokens`

            The number of input tokens which were used.

          - `Model model`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `long outputTokens`

            The number of output tokens which were used.

          - `JsonValue; type "message"constant`

            Usage for a sampling iteration

            - `MESSAGE("message")`

        - `class BetaCompactionIterationUsage:`

          Token usage for a compaction iteration.

          - `Optional<BetaCacheCreation> cacheCreation`

            Breakdown of cached tokens by TTL

          - `long cacheCreationInputTokens`

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

          - `long cacheReadInputTokens`

            The number of input tokens read from the cache.

          - `long inputTokens`

            The number of input tokens which were used.

          - `long outputTokens`

            The number of output tokens which were used.

          - `JsonValue; type "compaction"constant`

            Usage for a compaction iteration

            - `COMPACTION("compaction")`

        - `class BetaAdvisorMessageIterationUsage:`

          Token usage for an advisor sub-inference iteration.

          - `Optional<BetaCacheCreation> cacheCreation`

            Breakdown of cached tokens by TTL

          - `long cacheCreationInputTokens`

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

          - `long cacheReadInputTokens`

            The number of input tokens read from the cache.

          - `long inputTokens`

            The number of input tokens which were used.

          - `Model model`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `long outputTokens`

            The number of output tokens which were used.

          - `JsonValue; type "advisor_message"constant`

            Usage for an advisor sub-inference iteration

            - `ADVISOR_MESSAGE("advisor_message")`

        - `class BetaFallbackMessageIterationUsage:`

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

          - `Optional<BetaCacheCreation> cacheCreation`

            Breakdown of cached tokens by TTL

          - `long cacheCreationInputTokens`

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

          - `long cacheReadInputTokens`

            The number of input tokens read from the cache.

          - `long inputTokens`

            The number of input tokens which were used.

          - `Model model`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `long outputTokens`

            The number of output tokens which were used.

          - `JsonValue; type "fallback_message"constant`

            Usage for the fallback-model attempt that served the response

            - `FALLBACK_MESSAGE("fallback_message")`

      - `long outputTokens`

        The number of output tokens which were used.

      - `Optional<BetaOutputTokensDetails> outputTokensDetails`

        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.

        - `long thinkingTokens`

          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.

      - `Optional<BetaServerToolUsage> serverToolUse`

        The number of server tool requests.

        - `long webFetchRequests`

          The number of web fetch tool requests.

        - `long webSearchRequests`

          The number of web search tool requests.

      - `Optional<ServiceTier> serviceTier`

        If the request used the priority, standard, or batch tier.

        - `STANDARD("standard")`

        - `PRIORITY("priority")`

        - `BATCH("batch")`

      - `Optional<Speed> speed`

        The inference speed mode used for this request.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `JsonValue; type "message_start"constant`

    - `MESSAGE_START("message_start")`

### Beta Raw Message Stop Event

- `class BetaRawMessageStopEvent:`

  - `JsonValue; type "message_stop"constant`

    - `MESSAGE_STOP("message_stop")`

### Beta Raw Message Stream Event

- `class BetaRawMessageStreamEvent: A class that can be one of several variants.union`

  - `class BetaRawMessageStartEvent:`

    - `BetaMessage message`

      - `String id`

        Unique object identifier.

        The format and length of IDs may change over time.

      - `Optional<BetaContainer> container`

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

        - `String id`

          Identifier for the container used in this request

        - `LocalDateTime expiresAt`

          The time at which the container will expire.

        - `Optional<List<BetaSkill>> skills`

          Skills loaded in the container

          - `String skillId`

            Skill ID

          - `Type type`

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

            - `ANTHROPIC("anthropic")`

            - `CUSTOM("custom")`

          - `String version`

            Skill version or 'latest' for most recent version

      - `List<BetaContentBlock> content`

        Content generated by the model.

        This is an array of content blocks, each of which has a `type` that determines its shape.

        Example:

        ```json
        [{"type": "text", "text": "Hi, I'm Claude."}]
        ```

        If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.

        For example, if the input `messages` were:

        ```json
        [
          {"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)"}]
        ```

        - `class BetaTextBlock:`

          - `Optional<List<BetaTextCitation>> citations`

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

            - `class BetaCitationCharLocation:`

              - `String citedText`

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endCharIndex`

              - `Optional<String> fileId`

              - `long startCharIndex`

              - `JsonValue; type "char_location"constant`

                - `CHAR_LOCATION("char_location")`

            - `class BetaCitationPageLocation:`

              - `String citedText`

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endPageNumber`

              - `Optional<String> fileId`

              - `long startPageNumber`

              - `JsonValue; type "page_location"constant`

                - `PAGE_LOCATION("page_location")`

            - `class BetaCitationContentBlockLocation:`

              - `String citedText`

                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.

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endBlockIndex`

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

              - `Optional<String> fileId`

              - `long startBlockIndex`

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

              - `JsonValue; type "content_block_location"constant`

                - `CONTENT_BLOCK_LOCATION("content_block_location")`

            - `class BetaCitationsWebSearchResultLocation:`

              - `String citedText`

              - `String encryptedIndex`

              - `Optional<String> title`

              - `JsonValue; type "web_search_result_location"constant`

                - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

              - `String url`

            - `class BetaCitationSearchResultLocation:`

              - `String citedText`

                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.

              - `long endBlockIndex`

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

              - `long searchResultIndex`

                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.

              - `String source`

              - `long startBlockIndex`

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

              - `Optional<String> title`

              - `JsonValue; type "search_result_location"constant`

                - `SEARCH_RESULT_LOCATION("search_result_location")`

          - `String text`

          - `JsonValue; type "text"constant`

            - `TEXT("text")`

        - `class BetaThinkingBlock:`

          - `String signature`

          - `String thinking`

          - `JsonValue; type "thinking"constant`

            - `THINKING("thinking")`

        - `class BetaRedactedThinkingBlock:`

          - `String data`

          - `JsonValue; type "redacted_thinking"constant`

            - `REDACTED_THINKING("redacted_thinking")`

        - `class BetaToolUseBlock:`

          - `String id`

          - `Input input`

          - `String name`

          - `JsonValue; type "tool_use"constant`

            - `TOOL_USE("tool_use")`

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

              - `JsonValue; type "direct"constant`

                - `DIRECT("direct")`

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

              - `String toolId`

              - `JsonValue; type "code_execution_20250825"constant`

                - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `class BetaServerToolCaller20260120:`

              - `String toolId`

              - `JsonValue; type "code_execution_20260120"constant`

                - `CODE_EXECUTION_20260120("code_execution_20260120")`

        - `class BetaServerToolUseBlock:`

          - `String id`

          - `Input input`

          - `Name name`

            - `ADVISOR("advisor")`

            - `WEB_SEARCH("web_search")`

            - `WEB_FETCH("web_fetch")`

            - `CODE_EXECUTION("code_execution")`

            - `BASH_CODE_EXECUTION("bash_code_execution")`

            - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

            - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

            - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

          - `JsonValue; type "server_tool_use"constant`

            - `SERVER_TOOL_USE("server_tool_use")`

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaWebSearchToolResultBlock:`

          - `BetaWebSearchToolResultBlockContent content`

            - `class BetaWebSearchToolResultError:`

              - `BetaWebSearchToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `QUERY_TOO_LONG("query_too_long")`

                - `REQUEST_TOO_LARGE("request_too_large")`

              - `JsonValue; type "web_search_tool_result_error"constant`

                - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

            - `List<BetaWebSearchResultBlock>`

              - `String encryptedContent`

              - `Optional<String> pageAge`

              - `String title`

              - `JsonValue; type "web_search_result"constant`

                - `WEB_SEARCH_RESULT("web_search_result")`

              - `String url`

          - `String toolUseId`

          - `JsonValue; type "web_search_tool_result"constant`

            - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaWebFetchToolResultBlock:`

          - `Content content`

            - `class BetaWebFetchToolResultErrorBlock:`

              - `BetaWebFetchToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `URL_TOO_LONG("url_too_long")`

                - `URL_NOT_ALLOWED("url_not_allowed")`

                - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

                - `URL_NOT_ACCESSIBLE("url_not_accessible")`

                - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `UNAVAILABLE("unavailable")`

              - `JsonValue; type "web_fetch_tool_result_error"constant`

                - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

            - `class BetaWebFetchBlock:`

              - `BetaDocumentBlock content`

                - `Optional<BetaCitationConfig> citations`

                  Citation configuration for the document

                  - `boolean enabled`

                - `Source source`

                  - `class BetaBase64PdfSource:`

                    - `String data`

                    - `JsonValue; mediaType "application/pdf"constant`

                      - `APPLICATION_PDF("application/pdf")`

                    - `JsonValue; type "base64"constant`

                      - `BASE64("base64")`

                  - `class BetaPlainTextSource:`

                    - `String data`

                    - `JsonValue; mediaType "text/plain"constant`

                      - `TEXT_PLAIN("text/plain")`

                    - `JsonValue; type "text"constant`

                      - `TEXT("text")`

                - `Optional<String> title`

                  The title of the document

                - `JsonValue; type "document"constant`

                  - `DOCUMENT("document")`

              - `Optional<String> retrievedAt`

                ISO 8601 timestamp when the content was retrieved

              - `JsonValue; type "web_fetch_result"constant`

                - `WEB_FETCH_RESULT("web_fetch_result")`

              - `String url`

                Fetched content URL

          - `String toolUseId`

          - `JsonValue; type "web_fetch_tool_result"constant`

            - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaAdvisorToolResultBlock:`

          - `Content content`

            - `class BetaAdvisorToolResultError:`

              - `ErrorCode errorCode`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `PROMPT_TOO_LONG("prompt_too_long")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `OVERLOADED("overloaded")`

                - `UNAVAILABLE("unavailable")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `MODEL_NOT_FOUND("model_not_found")`

              - `JsonValue; type "advisor_tool_result_error"constant`

                - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

            - `class BetaAdvisorResultBlock:`

              - `Optional<String> stopReason`

                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.

              - `String text`

              - `JsonValue; type "advisor_result"constant`

                - `ADVISOR_RESULT("advisor_result")`

            - `class BetaAdvisorRedactedResultBlock:`

              - `String encryptedContent`

                Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

              - `Optional<String> stopReason`

                The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

              - `JsonValue; type "advisor_redacted_result"constant`

                - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

          - `String toolUseId`

          - `JsonValue; type "advisor_tool_result"constant`

            - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

        - `class BetaCodeExecutionToolResultBlock:`

          - `BetaCodeExecutionToolResultBlockContent content`

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

            - `class BetaCodeExecutionToolResultError:`

              - `BetaCodeExecutionToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `JsonValue; type "code_execution_tool_result_error"constant`

                - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

            - `class BetaCodeExecutionResultBlock:`

              - `List<BetaCodeExecutionOutputBlock> content`

                - `String fileId`

                - `JsonValue; type "code_execution_output"constant`

                  - `CODE_EXECUTION_OUTPUT("code_execution_output")`

              - `long returnCode`

              - `String stderr`

              - `String stdout`

              - `JsonValue; type "code_execution_result"constant`

                - `CODE_EXECUTION_RESULT("code_execution_result")`

            - `class BetaEncryptedCodeExecutionResultBlock:`

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

              - `List<BetaCodeExecutionOutputBlock> content`

                - `String fileId`

                - `JsonValue; type "code_execution_output"constant`

              - `String encryptedStdout`

              - `long returnCode`

              - `String stderr`

              - `JsonValue; type "encrypted_code_execution_result"constant`

                - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

          - `String toolUseId`

          - `JsonValue; type "code_execution_tool_result"constant`

            - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

        - `class BetaBashCodeExecutionToolResultBlock:`

          - `Content content`

            - `class BetaBashCodeExecutionToolResultError:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

              - `JsonValue; type "bash_code_execution_tool_result_error"constant`

                - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

            - `class BetaBashCodeExecutionResultBlock:`

              - `List<BetaBashCodeExecutionOutputBlock> content`

                - `String fileId`

                - `JsonValue; type "bash_code_execution_output"constant`

                  - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

              - `long returnCode`

              - `String stderr`

              - `String stdout`

              - `JsonValue; type "bash_code_execution_result"constant`

                - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

          - `String toolUseId`

          - `JsonValue; type "bash_code_execution_tool_result"constant`

            - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

        - `class BetaTextEditorCodeExecutionToolResultBlock:`

          - `Content content`

            - `class BetaTextEditorCodeExecutionToolResultError:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `FILE_NOT_FOUND("file_not_found")`

              - `Optional<String> errorMessage`

              - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

            - `class BetaTextEditorCodeExecutionViewResultBlock:`

              - `String content`

              - `FileType fileType`

                - `TEXT("text")`

                - `IMAGE("image")`

                - `PDF("pdf")`

              - `Optional<Long> numLines`

              - `Optional<Long> startLine`

              - `Optional<Long> totalLines`

              - `JsonValue; type "text_editor_code_execution_view_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

            - `class BetaTextEditorCodeExecutionCreateResultBlock:`

              - `boolean isFileUpdate`

              - `JsonValue; type "text_editor_code_execution_create_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

            - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

              - `Optional<List<String>> lines`

              - `Optional<Long> newLines`

              - `Optional<Long> newStart`

              - `Optional<Long> oldLines`

              - `Optional<Long> oldStart`

              - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

          - `String toolUseId`

          - `JsonValue; type "text_editor_code_execution_tool_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

        - `class BetaToolSearchToolResultBlock:`

          - `Content content`

            - `class BetaToolSearchToolResultError:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `Optional<String> errorMessage`

              - `JsonValue; type "tool_search_tool_result_error"constant`

                - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

            - `class BetaToolSearchToolSearchResultBlock:`

              - `List<BetaToolReferenceBlock> toolReferences`

                - `String toolName`

                - `JsonValue; type "tool_reference"constant`

                  - `TOOL_REFERENCE("tool_reference")`

              - `JsonValue; type "tool_search_tool_search_result"constant`

                - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

          - `String toolUseId`

          - `JsonValue; type "tool_search_tool_result"constant`

            - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

        - `class BetaMcpToolUseBlock:`

          - `String id`

          - `Input input`

          - `String name`

            The name of the MCP tool

          - `String serverName`

            The name of the MCP server

          - `JsonValue; type "mcp_tool_use"constant`

            - `MCP_TOOL_USE("mcp_tool_use")`

        - `class BetaMcpToolResultBlock:`

          - `Content content`

            - `String`

            - `List<BetaTextBlock>`

              - `Optional<List<BetaTextCitation>> citations`

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

              - `String text`

              - `JsonValue; type "text"constant`

          - `boolean isError`

          - `String toolUseId`

          - `JsonValue; type "mcp_tool_result"constant`

            - `MCP_TOOL_RESULT("mcp_tool_result")`

        - `class BetaContainerUploadBlock:`

          Response model for a file uploaded to the container.

          - `String fileId`

          - `JsonValue; type "container_upload"constant`

            - `CONTAINER_UPLOAD("container_upload")`

        - `class BetaCompactionBlock:`

          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.

          - `Optional<String> content`

            Summary of compacted content, or null if compaction failed

          - `Optional<String> encryptedContent`

            Opaque metadata from prior compaction, to be round-tripped verbatim

          - `JsonValue; type "compaction"constant`

            - `COMPACTION("compaction")`

        - `class BetaFallbackBlock:`

          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 routed directly by the sticky decision 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.

          - `BetaFallbackInfo from`

            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.

            - `Model model`

              The model that will complete your prompt.

              See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

              - `CLAUDE_FABLE_5("claude-fable-5")`

                Next generation of intelligence for the hardest knowledge work and coding problems

              - `CLAUDE_MYTHOS_5("claude-mythos-5")`

                Most capable model for cybersecurity and biology research

              - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

                New class of intelligence, strongest in coding and cybersecurity

              - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

                Best combination of speed and intelligence

              - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

                Fastest model with near-frontier intelligence

              - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

                Fastest model with near-frontier intelligence

              - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

                Premium model combining maximum intelligence with practical performance

              - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

                Premium model combining maximum intelligence with practical performance

              - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

                High-performance model for agents and coding

              - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

                High-performance model for agents and coding

              - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

                Exceptional model for specialized complex tasks

              - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

                Exceptional model for specialized complex tasks

              - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

                Powerful model for complex tasks

              - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

                Powerful model for complex tasks

              - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

                High-performance model with extended thinking

              - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

                High-performance model with extended thinking

              - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

                Fast and cost-effective model

          - `BetaFallbackInfo to`

            The fallback model producing the content that follows this block. Its `model` is always the canonical id.

          - `JsonValue; type "fallback"constant`

            - `FALLBACK("fallback")`

      - `Optional<BetaContextManagementResponse> contextManagement`

        Context management response.

        Information about context management strategies applied during the request.

        - `List<AppliedEdit> appliedEdits`

          List of context management edits that were applied.

          - `class BetaClearToolUses20250919EditResponse:`

            - `long clearedInputTokens`

              Number of input tokens cleared by this edit.

            - `long clearedToolUses`

              Number of tool uses that were cleared.

            - `JsonValue; type "clear_tool_uses_20250919"constant`

              The type of context management edit applied.

              - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

          - `class BetaClearThinking20251015EditResponse:`

            - `long clearedInputTokens`

              Number of input tokens cleared by this edit.

            - `long clearedThinkingTurns`

              Number of thinking turns that were cleared.

            - `JsonValue; type "clear_thinking_20251015"constant`

              The type of context management edit applied.

              - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

      - `Optional<BetaDiagnostics> diagnostics`

        Response envelope for request-level diagnostics. Present (possibly
        null) whenever the caller supplied `diagnostics` on the request.

        - `Optional<CacheMissReason> cacheMissReason`

          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.

          - `class BetaCacheMissModelChanged:`

            - `long cacheMissedInputTokens`

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

            - `JsonValue; type "model_changed"constant`

              - `MODEL_CHANGED("model_changed")`

          - `class BetaCacheMissSystemChanged:`

            - `long cacheMissedInputTokens`

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

            - `JsonValue; type "system_changed"constant`

              - `SYSTEM_CHANGED("system_changed")`

          - `class BetaCacheMissToolsChanged:`

            - `long cacheMissedInputTokens`

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

            - `JsonValue; type "tools_changed"constant`

              - `TOOLS_CHANGED("tools_changed")`

          - `class BetaCacheMissMessagesChanged:`

            - `long cacheMissedInputTokens`

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

            - `JsonValue; type "messages_changed"constant`

              - `MESSAGES_CHANGED("messages_changed")`

          - `class BetaCacheMissPreviousMessageNotFound:`

            - `JsonValue; type "previous_message_not_found"constant`

              - `PREVIOUS_MESSAGE_NOT_FOUND("previous_message_not_found")`

          - `class BetaCacheMissUnavailable:`

            - `JsonValue; type "unavailable"constant`

              - `UNAVAILABLE("unavailable")`

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `JsonValue; role "assistant"constant`

        Conversational role of the generated message.

        This will always be `"assistant"`.

        - `ASSISTANT("assistant")`

      - `Optional<BetaRefusalStopDetails> stopDetails`

        Structured information about a refusal.

        - `Optional<Category> category`

          The policy category that triggered the refusal.

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

          - `CYBER("cyber")`

          - `BIO("bio")`

          - `REASONING_EXTRACTION("reasoning_extraction")`

        - `Optional<String> explanation`

          Human-readable explanation of the refusal.

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

        - `Optional<String> fallbackCreditToken`

          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.

        - `Optional<Boolean> fallbackHasPrefillClaim`

          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.

        - `Optional<String> recommendedModel`

          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.

        - `JsonValue; type "refusal"constant`

          - `REFUSAL("refusal")`

      - `Optional<BetaStopReason> stopReason`

        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

        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.

        - `END_TURN("end_turn")`

        - `MAX_TOKENS("max_tokens")`

        - `STOP_SEQUENCE("stop_sequence")`

        - `TOOL_USE("tool_use")`

        - `PAUSE_TURN("pause_turn")`

        - `COMPACTION("compaction")`

        - `REFUSAL("refusal")`

        - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")`

      - `Optional<String> stopSequence`

        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.

      - `JsonValue; type "message"constant`

        Object type.

        For Messages, this is always `"message"`.

        - `MESSAGE("message")`

      - `BetaUsage usage`

        Billing and rate-limit usage.

        Anthropic'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 Claude.

        Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

          - `long ephemeral1hInputTokens`

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

          - `long ephemeral5mInputTokens`

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

        - `Optional<Long> cacheCreationInputTokens`

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

        - `Optional<Long> cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `Optional<String> inferenceGeo`

          The geographic region where inference was performed for this request.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Optional<List<BetaIterationsUsageItems>> iterations`

          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

          - `class BetaMessageIterationUsage:`

            Token usage for a sampling iteration.

            - `Optional<BetaCacheCreation> cacheCreation`

              Breakdown of cached tokens by TTL

            - `long cacheCreationInputTokens`

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

            - `long cacheReadInputTokens`

              The number of input tokens read from the cache.

            - `long inputTokens`

              The number of input tokens which were used.

            - `Model model`

              The model that will complete your prompt.

              See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

            - `long outputTokens`

              The number of output tokens which were used.

            - `JsonValue; type "message"constant`

              Usage for a sampling iteration

              - `MESSAGE("message")`

          - `class BetaCompactionIterationUsage:`

            Token usage for a compaction iteration.

            - `Optional<BetaCacheCreation> cacheCreation`

              Breakdown of cached tokens by TTL

            - `long cacheCreationInputTokens`

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

            - `long cacheReadInputTokens`

              The number of input tokens read from the cache.

            - `long inputTokens`

              The number of input tokens which were used.

            - `long outputTokens`

              The number of output tokens which were used.

            - `JsonValue; type "compaction"constant`

              Usage for a compaction iteration

              - `COMPACTION("compaction")`

          - `class BetaAdvisorMessageIterationUsage:`

            Token usage for an advisor sub-inference iteration.

            - `Optional<BetaCacheCreation> cacheCreation`

              Breakdown of cached tokens by TTL

            - `long cacheCreationInputTokens`

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

            - `long cacheReadInputTokens`

              The number of input tokens read from the cache.

            - `long inputTokens`

              The number of input tokens which were used.

            - `Model model`

              The model that will complete your prompt.

              See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

            - `long outputTokens`

              The number of output tokens which were used.

            - `JsonValue; type "advisor_message"constant`

              Usage for an advisor sub-inference iteration

              - `ADVISOR_MESSAGE("advisor_message")`

          - `class BetaFallbackMessageIterationUsage:`

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

            - `Optional<BetaCacheCreation> cacheCreation`

              Breakdown of cached tokens by TTL

            - `long cacheCreationInputTokens`

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

            - `long cacheReadInputTokens`

              The number of input tokens read from the cache.

            - `long inputTokens`

              The number of input tokens which were used.

            - `Model model`

              The model that will complete your prompt.

              See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

            - `long outputTokens`

              The number of output tokens which were used.

            - `JsonValue; type "fallback_message"constant`

              Usage for the fallback-model attempt that served the response

              - `FALLBACK_MESSAGE("fallback_message")`

        - `long outputTokens`

          The number of output tokens which were used.

        - `Optional<BetaOutputTokensDetails> outputTokensDetails`

          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.

          - `long thinkingTokens`

            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.

        - `Optional<BetaServerToolUsage> serverToolUse`

          The number of server tool requests.

          - `long webFetchRequests`

            The number of web fetch tool requests.

          - `long webSearchRequests`

            The number of web search tool requests.

        - `Optional<ServiceTier> serviceTier`

          If the request used the priority, standard, or batch tier.

          - `STANDARD("standard")`

          - `PRIORITY("priority")`

          - `BATCH("batch")`

        - `Optional<Speed> speed`

          The inference speed mode used for this request.

          - `STANDARD("standard")`

          - `FAST("fast")`

    - `JsonValue; type "message_start"constant`

      - `MESSAGE_START("message_start")`

  - `class BetaRawMessageDeltaEvent:`

    - `Optional<BetaContextManagementResponse> contextManagement`

      Information about context management strategies applied during the request

    - `Delta delta`

      - `Optional<BetaContainer> container`

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

      - `Optional<BetaRefusalStopDetails> stopDetails`

        Structured information about a refusal.

      - `Optional<BetaStopReason> stopReason`

      - `Optional<String> stopSequence`

    - `JsonValue; type "message_delta"constant`

      - `MESSAGE_DELTA("message_delta")`

    - `BetaMessageDeltaUsage usage`

      Billing and rate-limit usage.

      Anthropic'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 Claude.

      Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.

      - `Optional<Long> cacheCreationInputTokens`

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

      - `Optional<Long> cacheReadInputTokens`

        The cumulative number of input tokens read from the cache.

      - `Optional<Long> inputTokens`

        The cumulative number of input tokens which were used.

      - `Optional<List<BetaIterationsUsageItems>> iterations`

        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

        - `class BetaMessageIterationUsage:`

          Token usage for a sampling iteration.

        - `class BetaCompactionIterationUsage:`

          Token usage for a compaction iteration.

        - `class BetaAdvisorMessageIterationUsage:`

          Token usage for an advisor sub-inference iteration.

        - `class BetaFallbackMessageIterationUsage:`

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

      - `long outputTokens`

        The cumulative number of output tokens which were used.

      - `Optional<BetaOutputTokensDetails> outputTokensDetails`

        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.

      - `Optional<BetaServerToolUsage> serverToolUse`

        The number of server tool requests.

  - `class BetaRawMessageStopEvent:`

    - `JsonValue; type "message_stop"constant`

      - `MESSAGE_STOP("message_stop")`

  - `class BetaRawContentBlockStartEvent:`

    - `ContentBlock contentBlock`

      Response model for a file uploaded to the container.

      - `class BetaTextBlock:`

      - `class BetaThinkingBlock:`

      - `class BetaRedactedThinkingBlock:`

      - `class BetaToolUseBlock:`

      - `class BetaServerToolUseBlock:`

      - `class BetaWebSearchToolResultBlock:`

      - `class BetaWebFetchToolResultBlock:`

      - `class BetaAdvisorToolResultBlock:`

      - `class BetaCodeExecutionToolResultBlock:`

      - `class BetaBashCodeExecutionToolResultBlock:`

      - `class BetaTextEditorCodeExecutionToolResultBlock:`

      - `class BetaToolSearchToolResultBlock:`

      - `class BetaMcpToolUseBlock:`

      - `class BetaMcpToolResultBlock:`

      - `class BetaContainerUploadBlock:`

        Response model for a file uploaded to the container.

      - `class BetaCompactionBlock:`

        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.

      - `class BetaFallbackBlock:`

        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 routed directly by the sticky decision 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.

    - `long index`

    - `JsonValue; type "content_block_start"constant`

      - `CONTENT_BLOCK_START("content_block_start")`

  - `class BetaRawContentBlockDeltaEvent:`

    - `BetaRawContentBlockDelta delta`

      - `class BetaTextDelta:`

        - `String text`

        - `JsonValue; type "text_delta"constant`

          - `TEXT_DELTA("text_delta")`

      - `class BetaInputJsonDelta:`

        - `String partialJson`

        - `JsonValue; type "input_json_delta"constant`

          - `INPUT_JSON_DELTA("input_json_delta")`

      - `class BetaCitationsDelta:`

        - `Citation citation`

          - `class BetaCitationCharLocation:`

          - `class BetaCitationPageLocation:`

          - `class BetaCitationContentBlockLocation:`

          - `class BetaCitationsWebSearchResultLocation:`

          - `class BetaCitationSearchResultLocation:`

        - `JsonValue; type "citations_delta"constant`

          - `CITATIONS_DELTA("citations_delta")`

      - `class BetaThinkingDelta:`

        - `Optional<Long> estimatedTokens`

          Per-frame increment of a coarse, running estimate of the tokens this thinking block has produced so far. Present whenever the `thinking-token-count-2026-05-13` beta is set; `null` unless `thinking.display` resolves to `"omitted"` and a count is due this frame. Sum the increments across `thinking_delta` frames on this block for a progress indicator. Each increment is a non-negative multiple of a fixed quantum and the cadence is rate-limited, so this is a deliberately lossy display hint, not a billable count; `usage.output_tokens` remains authoritative.

        - `String thinking`

        - `JsonValue; type "thinking_delta"constant`

          - `THINKING_DELTA("thinking_delta")`

      - `class BetaSignatureDelta:`

        - `String signature`

        - `JsonValue; type "signature_delta"constant`

          - `SIGNATURE_DELTA("signature_delta")`

      - `class BetaCompactionContentBlockDelta:`

        - `Optional<String> content`

        - `Optional<String> encryptedContent`

          Opaque metadata from prior compaction, to be round-tripped verbatim

        - `JsonValue; type "compaction_delta"constant`

          - `COMPACTION_DELTA("compaction_delta")`

    - `long index`

    - `JsonValue; type "content_block_delta"constant`

      - `CONTENT_BLOCK_DELTA("content_block_delta")`

  - `class BetaRawContentBlockStopEvent:`

    - `long index`

    - `JsonValue; type "content_block_stop"constant`

      - `CONTENT_BLOCK_STOP("content_block_stop")`

### Beta Redacted Thinking Block

- `class BetaRedactedThinkingBlock:`

  - `String data`

  - `JsonValue; type "redacted_thinking"constant`

    - `REDACTED_THINKING("redacted_thinking")`

### Beta Redacted Thinking Block Param

- `class BetaRedactedThinkingBlockParam:`

  - `String data`

  - `JsonValue; type "redacted_thinking"constant`

    - `REDACTED_THINKING("redacted_thinking")`

### Beta Refusal Stop Details

- `class BetaRefusalStopDetails:`

  Structured information about a refusal.

  - `Optional<Category> category`

    The policy category that triggered the refusal.

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

    - `CYBER("cyber")`

    - `BIO("bio")`

    - `REASONING_EXTRACTION("reasoning_extraction")`

  - `Optional<String> explanation`

    Human-readable explanation of the refusal.

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

  - `Optional<String> fallbackCreditToken`

    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.

  - `Optional<Boolean> fallbackHasPrefillClaim`

    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.

  - `Optional<String> recommendedModel`

    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.

  - `JsonValue; type "refusal"constant`

    - `REFUSAL("refusal")`

### Beta Request Document Block

- `class BetaRequestDocumentBlock:`

  - `Source source`

    - `class BetaBase64PdfSource:`

      - `String data`

      - `JsonValue; mediaType "application/pdf"constant`

        - `APPLICATION_PDF("application/pdf")`

      - `JsonValue; type "base64"constant`

        - `BASE64("base64")`

    - `class BetaPlainTextSource:`

      - `String data`

      - `JsonValue; mediaType "text/plain"constant`

        - `TEXT_PLAIN("text/plain")`

      - `JsonValue; type "text"constant`

        - `TEXT("text")`

    - `class BetaContentBlockSource:`

      - `Content content`

        - `String`

        - `List<BetaContentBlockSourceContent>`

          - `class BetaTextBlockParam:`

            - `String text`

            - `JsonValue; type "text"constant`

              - `TEXT("text")`

            - `Optional<BetaCacheControlEphemeral> cacheControl`

              Create a cache control breakpoint at this content block.

              - `JsonValue; type "ephemeral"constant`

                - `EPHEMERAL("ephemeral")`

              - `Optional<Ttl> ttl`

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

                - `TTL_5M("5m")`

                - `TTL_1H("1h")`

            - `Optional<List<BetaTextCitationParam>> citations`

              - `class BetaCitationCharLocationParam:`

                - `String citedText`

                - `long documentIndex`

                - `Optional<String> documentTitle`

                - `long endCharIndex`

                - `long startCharIndex`

                - `JsonValue; type "char_location"constant`

                  - `CHAR_LOCATION("char_location")`

              - `class BetaCitationPageLocationParam:`

                - `String citedText`

                - `long documentIndex`

                - `Optional<String> documentTitle`

                - `long endPageNumber`

                - `long startPageNumber`

                - `JsonValue; type "page_location"constant`

                  - `PAGE_LOCATION("page_location")`

              - `class BetaCitationContentBlockLocationParam:`

                - `String citedText`

                  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.

                - `long documentIndex`

                - `Optional<String> documentTitle`

                - `long endBlockIndex`

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

                - `long startBlockIndex`

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

                - `JsonValue; type "content_block_location"constant`

                  - `CONTENT_BLOCK_LOCATION("content_block_location")`

              - `class BetaCitationWebSearchResultLocationParam:`

                - `String citedText`

                - `String encryptedIndex`

                - `Optional<String> title`

                - `JsonValue; type "web_search_result_location"constant`

                  - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

                - `String url`

              - `class BetaCitationSearchResultLocationParam:`

                - `String citedText`

                  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.

                - `long endBlockIndex`

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

                - `long searchResultIndex`

                  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.

                - `String source`

                - `long startBlockIndex`

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

                - `Optional<String> title`

                - `JsonValue; type "search_result_location"constant`

                  - `SEARCH_RESULT_LOCATION("search_result_location")`

          - `class BetaImageBlockParam:`

            - `Source source`

              - `class BetaBase64ImageSource:`

                - `String data`

                - `MediaType mediaType`

                  - `IMAGE_JPEG("image/jpeg")`

                  - `IMAGE_PNG("image/png")`

                  - `IMAGE_GIF("image/gif")`

                  - `IMAGE_WEBP("image/webp")`

                - `JsonValue; type "base64"constant`

                  - `BASE64("base64")`

              - `class BetaUrlImageSource:`

                - `JsonValue; type "url"constant`

                  - `URL("url")`

                - `String url`

              - `class BetaFileImageSource:`

                - `String fileId`

                - `JsonValue; type "file"constant`

                  - `FILE("file")`

            - `JsonValue; type "image"constant`

              - `IMAGE("image")`

            - `Optional<BetaCacheControlEphemeral> cacheControl`

              Create a cache control breakpoint at this content block.

      - `JsonValue; type "content"constant`

        - `CONTENT("content")`

    - `class BetaUrlPdfSource:`

      - `JsonValue; type "url"constant`

        - `URL("url")`

      - `String url`

    - `class BetaFileDocumentSource:`

      - `String fileId`

      - `JsonValue; type "file"constant`

        - `FILE("file")`

  - `JsonValue; type "document"constant`

    - `DOCUMENT("document")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

  - `Optional<BetaCitationsConfigParam> citations`

    - `Optional<Boolean> enabled`

  - `Optional<String> context`

  - `Optional<String> title`

### Beta Request MCP Server Tool Configuration

- `class BetaRequestMcpServerToolConfiguration:`

  - `Optional<List<String>> allowedTools`

  - `Optional<Boolean> enabled`

### Beta Request MCP Server URL Definition

- `class BetaRequestMcpServerUrlDefinition:`

  - `String name`

  - `JsonValue; type "url"constant`

    - `URL("url")`

  - `String url`

  - `Optional<String> authorizationToken`

  - `Optional<BetaRequestMcpServerToolConfiguration> toolConfiguration`

    - `Optional<List<String>> allowedTools`

    - `Optional<Boolean> enabled`

### Beta Request MCP Tool Result Block Param

- `class BetaRequestMcpToolResultBlockParam:`

  - `String toolUseId`

  - `JsonValue; type "mcp_tool_result"constant`

    - `MCP_TOOL_RESULT("mcp_tool_result")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Content> content`

    - `String`

    - `List<BetaTextBlockParam>`

      - `String text`

      - `JsonValue; type "text"constant`

        - `TEXT("text")`

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Create a cache control breakpoint at this content block.

      - `Optional<List<BetaTextCitationParam>> citations`

        - `class BetaCitationCharLocationParam:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endCharIndex`

          - `long startCharIndex`

          - `JsonValue; type "char_location"constant`

            - `CHAR_LOCATION("char_location")`

        - `class BetaCitationPageLocationParam:`

          - `String citedText`

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endPageNumber`

          - `long startPageNumber`

          - `JsonValue; type "page_location"constant`

            - `PAGE_LOCATION("page_location")`

        - `class BetaCitationContentBlockLocationParam:`

          - `String citedText`

            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.

          - `long documentIndex`

          - `Optional<String> documentTitle`

          - `long endBlockIndex`

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

          - `long startBlockIndex`

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

          - `JsonValue; type "content_block_location"constant`

            - `CONTENT_BLOCK_LOCATION("content_block_location")`

        - `class BetaCitationWebSearchResultLocationParam:`

          - `String citedText`

          - `String encryptedIndex`

          - `Optional<String> title`

          - `JsonValue; type "web_search_result_location"constant`

            - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

          - `String url`

        - `class BetaCitationSearchResultLocationParam:`

          - `String citedText`

            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.

          - `long endBlockIndex`

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

          - `long searchResultIndex`

            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.

          - `String source`

          - `long startBlockIndex`

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

          - `Optional<String> title`

          - `JsonValue; type "search_result_location"constant`

            - `SEARCH_RESULT_LOCATION("search_result_location")`

  - `Optional<Boolean> isError`

### Beta Search Result Block Param

- `class BetaSearchResultBlockParam:`

  - `List<BetaTextBlockParam> content`

    - `String text`

    - `JsonValue; type "text"constant`

      - `TEXT("text")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

      - `JsonValue; type "ephemeral"constant`

        - `EPHEMERAL("ephemeral")`

      - `Optional<Ttl> ttl`

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

        - `TTL_5M("5m")`

        - `TTL_1H("1h")`

    - `Optional<List<BetaTextCitationParam>> citations`

      - `class BetaCitationCharLocationParam:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endCharIndex`

        - `long startCharIndex`

        - `JsonValue; type "char_location"constant`

          - `CHAR_LOCATION("char_location")`

      - `class BetaCitationPageLocationParam:`

        - `String citedText`

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endPageNumber`

        - `long startPageNumber`

        - `JsonValue; type "page_location"constant`

          - `PAGE_LOCATION("page_location")`

      - `class BetaCitationContentBlockLocationParam:`

        - `String citedText`

          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.

        - `long documentIndex`

        - `Optional<String> documentTitle`

        - `long endBlockIndex`

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

        - `long startBlockIndex`

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

        - `JsonValue; type "content_block_location"constant`

          - `CONTENT_BLOCK_LOCATION("content_block_location")`

      - `class BetaCitationWebSearchResultLocationParam:`

        - `String citedText`

        - `String encryptedIndex`

        - `Optional<String> title`

        - `JsonValue; type "web_search_result_location"constant`

          - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

        - `String url`

      - `class BetaCitationSearchResultLocationParam:`

        - `String citedText`

          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.

        - `long endBlockIndex`

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

        - `long searchResultIndex`

          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.

        - `String source`

        - `long startBlockIndex`

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

        - `Optional<String> title`

        - `JsonValue; type "search_result_location"constant`

          - `SEARCH_RESULT_LOCATION("search_result_location")`

  - `String source`

  - `String title`

  - `JsonValue; type "search_result"constant`

    - `SEARCH_RESULT("search_result")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

  - `Optional<BetaCitationsConfigParam> citations`

    - `Optional<Boolean> enabled`

### Beta Server Tool Caller

- `class BetaServerToolCaller:`

  Tool invocation generated by a server-side tool.

  - `String toolId`

  - `JsonValue; type "code_execution_20250825"constant`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

### Beta Server Tool Caller 20260120

- `class BetaServerToolCaller20260120:`

  - `String toolId`

  - `JsonValue; type "code_execution_20260120"constant`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

### Beta Server Tool Usage

- `class BetaServerToolUsage:`

  - `long webFetchRequests`

    The number of web fetch tool requests.

  - `long webSearchRequests`

    The number of web search tool requests.

### Beta Server Tool Use Block

- `class BetaServerToolUseBlock:`

  - `String id`

  - `Input input`

  - `Name name`

    - `ADVISOR("advisor")`

    - `WEB_SEARCH("web_search")`

    - `WEB_FETCH("web_fetch")`

    - `CODE_EXECUTION("code_execution")`

    - `BASH_CODE_EXECUTION("bash_code_execution")`

    - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

    - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

    - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

  - `JsonValue; type "server_tool_use"constant`

    - `SERVER_TOOL_USE("server_tool_use")`

  - `Optional<Caller> caller`

    Tool invocation directly from the model.

    - `class BetaDirectCaller:`

      Tool invocation directly from the model.

      - `JsonValue; type "direct"constant`

        - `DIRECT("direct")`

    - `class BetaServerToolCaller:`

      Tool invocation generated by a server-side tool.

      - `String toolId`

      - `JsonValue; type "code_execution_20250825"constant`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `class BetaServerToolCaller20260120:`

      - `String toolId`

      - `JsonValue; type "code_execution_20260120"constant`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

### Beta Server Tool Use Block Param

- `class BetaServerToolUseBlockParam:`

  - `String id`

  - `Input input`

  - `Name name`

    - `ADVISOR("advisor")`

    - `WEB_SEARCH("web_search")`

    - `WEB_FETCH("web_fetch")`

    - `CODE_EXECUTION("code_execution")`

    - `BASH_CODE_EXECUTION("bash_code_execution")`

    - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

    - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

    - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

  - `JsonValue; type "server_tool_use"constant`

    - `SERVER_TOOL_USE("server_tool_use")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Caller> caller`

    Tool invocation directly from the model.

    - `class BetaDirectCaller:`

      Tool invocation directly from the model.

      - `JsonValue; type "direct"constant`

        - `DIRECT("direct")`

    - `class BetaServerToolCaller:`

      Tool invocation generated by a server-side tool.

      - `String toolId`

      - `JsonValue; type "code_execution_20250825"constant`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `class BetaServerToolCaller20260120:`

      - `String toolId`

      - `JsonValue; type "code_execution_20260120"constant`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

### Beta Signature Delta

- `class BetaSignatureDelta:`

  - `String signature`

  - `JsonValue; type "signature_delta"constant`

    - `SIGNATURE_DELTA("signature_delta")`

### Beta Skill

- `class BetaSkill:`

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

  - `String skillId`

    Skill ID

  - `Type type`

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

    - `ANTHROPIC("anthropic")`

    - `CUSTOM("custom")`

  - `String version`

    Skill version or 'latest' for most recent version

### Beta Skill Params

- `class BetaSkillParams:`

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

  - `String skillId`

    Skill ID

  - `Type type`

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

    - `ANTHROPIC("anthropic")`

    - `CUSTOM("custom")`

  - `Optional<String> version`

    Skill version or 'latest' for most recent version

### Beta Stop Reason

- `enum BetaStopReason:`

  - `END_TURN("end_turn")`

  - `MAX_TOKENS("max_tokens")`

  - `STOP_SEQUENCE("stop_sequence")`

  - `TOOL_USE("tool_use")`

  - `PAUSE_TURN("pause_turn")`

  - `COMPACTION("compaction")`

  - `REFUSAL("refusal")`

  - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")`

### Beta Text Block

- `class BetaTextBlock:`

  - `Optional<List<BetaTextCitation>> citations`

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

    - `class BetaCitationCharLocation:`

      - `String citedText`

      - `long documentIndex`

      - `Optional<String> documentTitle`

      - `long endCharIndex`

      - `Optional<String> fileId`

      - `long startCharIndex`

      - `JsonValue; type "char_location"constant`

        - `CHAR_LOCATION("char_location")`

    - `class BetaCitationPageLocation:`

      - `String citedText`

      - `long documentIndex`

      - `Optional<String> documentTitle`

      - `long endPageNumber`

      - `Optional<String> fileId`

      - `long startPageNumber`

      - `JsonValue; type "page_location"constant`

        - `PAGE_LOCATION("page_location")`

    - `class BetaCitationContentBlockLocation:`

      - `String citedText`

        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.

      - `long documentIndex`

      - `Optional<String> documentTitle`

      - `long endBlockIndex`

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

      - `Optional<String> fileId`

      - `long startBlockIndex`

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

      - `JsonValue; type "content_block_location"constant`

        - `CONTENT_BLOCK_LOCATION("content_block_location")`

    - `class BetaCitationsWebSearchResultLocation:`

      - `String citedText`

      - `String encryptedIndex`

      - `Optional<String> title`

      - `JsonValue; type "web_search_result_location"constant`

        - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

      - `String url`

    - `class BetaCitationSearchResultLocation:`

      - `String citedText`

        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.

      - `long endBlockIndex`

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

      - `long searchResultIndex`

        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.

      - `String source`

      - `long startBlockIndex`

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

      - `Optional<String> title`

      - `JsonValue; type "search_result_location"constant`

        - `SEARCH_RESULT_LOCATION("search_result_location")`

  - `String text`

  - `JsonValue; type "text"constant`

    - `TEXT("text")`

### Beta Text Block Param

- `class BetaTextBlockParam:`

  - `String text`

  - `JsonValue; type "text"constant`

    - `TEXT("text")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<List<BetaTextCitationParam>> citations`

    - `class BetaCitationCharLocationParam:`

      - `String citedText`

      - `long documentIndex`

      - `Optional<String> documentTitle`

      - `long endCharIndex`

      - `long startCharIndex`

      - `JsonValue; type "char_location"constant`

        - `CHAR_LOCATION("char_location")`

    - `class BetaCitationPageLocationParam:`

      - `String citedText`

      - `long documentIndex`

      - `Optional<String> documentTitle`

      - `long endPageNumber`

      - `long startPageNumber`

      - `JsonValue; type "page_location"constant`

        - `PAGE_LOCATION("page_location")`

    - `class BetaCitationContentBlockLocationParam:`

      - `String citedText`

        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.

      - `long documentIndex`

      - `Optional<String> documentTitle`

      - `long endBlockIndex`

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

      - `long startBlockIndex`

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

      - `JsonValue; type "content_block_location"constant`

        - `CONTENT_BLOCK_LOCATION("content_block_location")`

    - `class BetaCitationWebSearchResultLocationParam:`

      - `String citedText`

      - `String encryptedIndex`

      - `Optional<String> title`

      - `JsonValue; type "web_search_result_location"constant`

        - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

      - `String url`

    - `class BetaCitationSearchResultLocationParam:`

      - `String citedText`

        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.

      - `long endBlockIndex`

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

      - `long searchResultIndex`

        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.

      - `String source`

      - `long startBlockIndex`

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

      - `Optional<String> title`

      - `JsonValue; type "search_result_location"constant`

        - `SEARCH_RESULT_LOCATION("search_result_location")`

### Beta Text Citation

- `class BetaTextCitation: A class that can be one of several variants.union`

  - `class BetaCitationCharLocation:`

    - `String citedText`

    - `long documentIndex`

    - `Optional<String> documentTitle`

    - `long endCharIndex`

    - `Optional<String> fileId`

    - `long startCharIndex`

    - `JsonValue; type "char_location"constant`

      - `CHAR_LOCATION("char_location")`

  - `class BetaCitationPageLocation:`

    - `String citedText`

    - `long documentIndex`

    - `Optional<String> documentTitle`

    - `long endPageNumber`

    - `Optional<String> fileId`

    - `long startPageNumber`

    - `JsonValue; type "page_location"constant`

      - `PAGE_LOCATION("page_location")`

  - `class BetaCitationContentBlockLocation:`

    - `String citedText`

      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.

    - `long documentIndex`

    - `Optional<String> documentTitle`

    - `long endBlockIndex`

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

    - `Optional<String> fileId`

    - `long startBlockIndex`

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

    - `JsonValue; type "content_block_location"constant`

      - `CONTENT_BLOCK_LOCATION("content_block_location")`

  - `class BetaCitationsWebSearchResultLocation:`

    - `String citedText`

    - `String encryptedIndex`

    - `Optional<String> title`

    - `JsonValue; type "web_search_result_location"constant`

      - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

    - `String url`

  - `class BetaCitationSearchResultLocation:`

    - `String citedText`

      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.

    - `long endBlockIndex`

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

    - `long searchResultIndex`

      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.

    - `String source`

    - `long startBlockIndex`

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

    - `Optional<String> title`

    - `JsonValue; type "search_result_location"constant`

      - `SEARCH_RESULT_LOCATION("search_result_location")`

### Beta Text Citation Param

- `class BetaTextCitationParam: A class that can be one of several variants.union`

  - `class BetaCitationCharLocationParam:`

    - `String citedText`

    - `long documentIndex`

    - `Optional<String> documentTitle`

    - `long endCharIndex`

    - `long startCharIndex`

    - `JsonValue; type "char_location"constant`

      - `CHAR_LOCATION("char_location")`

  - `class BetaCitationPageLocationParam:`

    - `String citedText`

    - `long documentIndex`

    - `Optional<String> documentTitle`

    - `long endPageNumber`

    - `long startPageNumber`

    - `JsonValue; type "page_location"constant`

      - `PAGE_LOCATION("page_location")`

  - `class BetaCitationContentBlockLocationParam:`

    - `String citedText`

      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.

    - `long documentIndex`

    - `Optional<String> documentTitle`

    - `long endBlockIndex`

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

    - `long startBlockIndex`

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

    - `JsonValue; type "content_block_location"constant`

      - `CONTENT_BLOCK_LOCATION("content_block_location")`

  - `class BetaCitationWebSearchResultLocationParam:`

    - `String citedText`

    - `String encryptedIndex`

    - `Optional<String> title`

    - `JsonValue; type "web_search_result_location"constant`

      - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

    - `String url`

  - `class BetaCitationSearchResultLocationParam:`

    - `String citedText`

      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.

    - `long endBlockIndex`

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

    - `long searchResultIndex`

      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.

    - `String source`

    - `long startBlockIndex`

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

    - `Optional<String> title`

    - `JsonValue; type "search_result_location"constant`

      - `SEARCH_RESULT_LOCATION("search_result_location")`

### Beta Text Delta

- `class BetaTextDelta:`

  - `String text`

  - `JsonValue; type "text_delta"constant`

    - `TEXT_DELTA("text_delta")`

### Beta Text Editor Code Execution Create Result Block

- `class BetaTextEditorCodeExecutionCreateResultBlock:`

  - `boolean isFileUpdate`

  - `JsonValue; type "text_editor_code_execution_create_result"constant`

    - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

### Beta Text Editor Code Execution Create Result Block Param

- `class BetaTextEditorCodeExecutionCreateResultBlockParam:`

  - `boolean isFileUpdate`

  - `JsonValue; type "text_editor_code_execution_create_result"constant`

    - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

### Beta Text Editor Code Execution Str Replace Result Block

- `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

  - `Optional<List<String>> lines`

  - `Optional<Long> newLines`

  - `Optional<Long> newStart`

  - `Optional<Long> oldLines`

  - `Optional<Long> oldStart`

  - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

    - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

### Beta Text Editor Code Execution Str Replace Result Block Param

- `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:`

  - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

    - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

  - `Optional<List<String>> lines`

  - `Optional<Long> newLines`

  - `Optional<Long> newStart`

  - `Optional<Long> oldLines`

  - `Optional<Long> oldStart`

### Beta Text Editor Code Execution Tool Result Block

- `class BetaTextEditorCodeExecutionToolResultBlock:`

  - `Content content`

    - `class BetaTextEditorCodeExecutionToolResultError:`

      - `ErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `UNAVAILABLE("unavailable")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

        - `FILE_NOT_FOUND("file_not_found")`

      - `Optional<String> errorMessage`

      - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

    - `class BetaTextEditorCodeExecutionViewResultBlock:`

      - `String content`

      - `FileType fileType`

        - `TEXT("text")`

        - `IMAGE("image")`

        - `PDF("pdf")`

      - `Optional<Long> numLines`

      - `Optional<Long> startLine`

      - `Optional<Long> totalLines`

      - `JsonValue; type "text_editor_code_execution_view_result"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

    - `class BetaTextEditorCodeExecutionCreateResultBlock:`

      - `boolean isFileUpdate`

      - `JsonValue; type "text_editor_code_execution_create_result"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

    - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

      - `Optional<List<String>> lines`

      - `Optional<Long> newLines`

      - `Optional<Long> newStart`

      - `Optional<Long> oldLines`

      - `Optional<Long> oldStart`

      - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

  - `String toolUseId`

  - `JsonValue; type "text_editor_code_execution_tool_result"constant`

    - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

### Beta Text Editor Code Execution Tool Result Block Param

- `class BetaTextEditorCodeExecutionToolResultBlockParam:`

  - `Content content`

    - `class BetaTextEditorCodeExecutionToolResultErrorParam:`

      - `ErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `UNAVAILABLE("unavailable")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

        - `FILE_NOT_FOUND("file_not_found")`

      - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

      - `Optional<String> errorMessage`

    - `class BetaTextEditorCodeExecutionViewResultBlockParam:`

      - `String content`

      - `FileType fileType`

        - `TEXT("text")`

        - `IMAGE("image")`

        - `PDF("pdf")`

      - `JsonValue; type "text_editor_code_execution_view_result"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

      - `Optional<Long> numLines`

      - `Optional<Long> startLine`

      - `Optional<Long> totalLines`

    - `class BetaTextEditorCodeExecutionCreateResultBlockParam:`

      - `boolean isFileUpdate`

      - `JsonValue; type "text_editor_code_execution_create_result"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

    - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:`

      - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

        - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

      - `Optional<List<String>> lines`

      - `Optional<Long> newLines`

      - `Optional<Long> newStart`

      - `Optional<Long> oldLines`

      - `Optional<Long> oldStart`

  - `String toolUseId`

  - `JsonValue; type "text_editor_code_execution_tool_result"constant`

    - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

### Beta Text Editor Code Execution Tool Result Error

- `class BetaTextEditorCodeExecutionToolResultError:`

  - `ErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `UNAVAILABLE("unavailable")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

    - `FILE_NOT_FOUND("file_not_found")`

  - `Optional<String> errorMessage`

  - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

    - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

### Beta Text Editor Code Execution Tool Result Error Param

- `class BetaTextEditorCodeExecutionToolResultErrorParam:`

  - `ErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `UNAVAILABLE("unavailable")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

    - `FILE_NOT_FOUND("file_not_found")`

  - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

    - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

  - `Optional<String> errorMessage`

### Beta Text Editor Code Execution View Result Block

- `class BetaTextEditorCodeExecutionViewResultBlock:`

  - `String content`

  - `FileType fileType`

    - `TEXT("text")`

    - `IMAGE("image")`

    - `PDF("pdf")`

  - `Optional<Long> numLines`

  - `Optional<Long> startLine`

  - `Optional<Long> totalLines`

  - `JsonValue; type "text_editor_code_execution_view_result"constant`

    - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

### Beta Text Editor Code Execution View Result Block Param

- `class BetaTextEditorCodeExecutionViewResultBlockParam:`

  - `String content`

  - `FileType fileType`

    - `TEXT("text")`

    - `IMAGE("image")`

    - `PDF("pdf")`

  - `JsonValue; type "text_editor_code_execution_view_result"constant`

    - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

  - `Optional<Long> numLines`

  - `Optional<Long> startLine`

  - `Optional<Long> totalLines`

### Beta Thinking Block

- `class BetaThinkingBlock:`

  - `String signature`

  - `String thinking`

  - `JsonValue; type "thinking"constant`

    - `THINKING("thinking")`

### Beta Thinking Block Param

- `class BetaThinkingBlockParam:`

  - `String signature`

  - `String thinking`

  - `JsonValue; type "thinking"constant`

    - `THINKING("thinking")`

### Beta Thinking Config Adaptive

- `class BetaThinkingConfigAdaptive:`

  - `JsonValue; type "adaptive"constant`

    - `ADAPTIVE("adaptive")`

  - `Optional<Display> display`

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

    - `SUMMARIZED("summarized")`

    - `OMITTED("omitted")`

### Beta Thinking Config Disabled

- `class BetaThinkingConfigDisabled:`

  - `JsonValue; type "disabled"constant`

    - `DISABLED("disabled")`

### Beta Thinking Config Enabled

- `class BetaThinkingConfigEnabled:`

  - `long budgetTokens`

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

    Must be ≥1024 and less than `max_tokens`.

    See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.

  - `JsonValue; type "enabled"constant`

    - `ENABLED("enabled")`

  - `Optional<Display> display`

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

    - `SUMMARIZED("summarized")`

    - `OMITTED("omitted")`

### Beta Thinking Config Param

- `class BetaThinkingConfigParam: A class that can be one of several variants.union`

  Configuration for enabling Claude's extended thinking.

  When enabled, responses include `thinking` content blocks showing Claude'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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.

  - `class BetaThinkingConfigEnabled:`

    - `long budgetTokens`

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

      Must be ≥1024 and less than `max_tokens`.

      See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.

    - `JsonValue; type "enabled"constant`

      - `ENABLED("enabled")`

    - `Optional<Display> display`

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

      - `SUMMARIZED("summarized")`

      - `OMITTED("omitted")`

  - `class BetaThinkingConfigDisabled:`

    - `JsonValue; type "disabled"constant`

      - `DISABLED("disabled")`

  - `class BetaThinkingConfigAdaptive:`

    - `JsonValue; type "adaptive"constant`

      - `ADAPTIVE("adaptive")`

    - `Optional<Display> display`

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

      - `SUMMARIZED("summarized")`

      - `OMITTED("omitted")`

### Beta Thinking Delta

- `class BetaThinkingDelta:`

  - `Optional<Long> estimatedTokens`

    Per-frame increment of a coarse, running estimate of the tokens this thinking block has produced so far. Present whenever the `thinking-token-count-2026-05-13` beta is set; `null` unless `thinking.display` resolves to `"omitted"` and a count is due this frame. Sum the increments across `thinking_delta` frames on this block for a progress indicator. Each increment is a non-negative multiple of a fixed quantum and the cadence is rate-limited, so this is a deliberately lossy display hint, not a billable count; `usage.output_tokens` remains authoritative.

  - `String thinking`

  - `JsonValue; type "thinking_delta"constant`

    - `THINKING_DELTA("thinking_delta")`

### Beta Thinking Turns

- `class BetaThinkingTurns:`

  - `JsonValue; type "thinking_turns"constant`

    - `THINKING_TURNS("thinking_turns")`

  - `long value`

### Beta Token Task Budget

- `class BetaTokenTaskBudget:`

  User-configurable total token budget across contexts.

  - `long total`

    Total token budget across all contexts in the session.

  - `JsonValue; type "tokens"constant`

    The budget type. Currently only 'tokens' is supported.

    - `TOKENS("tokens")`

  - `Optional<Long> remaining`

    Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.

### Beta Tool

- `class BetaTool:`

  - `InputSchema inputSchema`

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

    - `JsonValue; type "object"constant`

      - `OBJECT("object")`

    - `Optional<Properties> properties`

    - `Optional<List<String>> required`

  - `String name`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<String> 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.

  - `Optional<Boolean> eagerInputStreaming`

    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.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

  - `Optional<Type> type`

    - `CUSTOM("custom")`

### Beta Tool Bash 20241022

- `class BetaToolBash20241022:`

  - `JsonValue; name "bash"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `BASH("bash")`

  - `JsonValue; type "bash_20241022"constant`

    - `BASH_20241022("bash_20241022")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Bash 20250124

- `class BetaToolBash20250124:`

  - `JsonValue; name "bash"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `BASH("bash")`

  - `JsonValue; type "bash_20250124"constant`

    - `BASH_20250124("bash_20250124")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Choice

- `class BetaToolChoice: A class that can be one of several variants.union`

  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.

  - `class BetaToolChoiceAuto:`

    The model will automatically decide whether to use tools.

    - `JsonValue; type "auto"constant`

      - `AUTO("auto")`

    - `Optional<Boolean> disableParallelToolUse`

      Whether to disable parallel tool use.

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

  - `class BetaToolChoiceAny:`

    The model will use any available tools.

    - `JsonValue; type "any"constant`

      - `ANY("any")`

    - `Optional<Boolean> disableParallelToolUse`

      Whether to disable parallel tool use.

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

  - `class BetaToolChoiceTool:`

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

    - `String name`

      The name of the tool to use.

    - `JsonValue; type "tool"constant`

      - `TOOL("tool")`

    - `Optional<Boolean> disableParallelToolUse`

      Whether to disable parallel tool use.

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

  - `class BetaToolChoiceNone:`

    The model will not be allowed to use tools.

    - `JsonValue; type "none"constant`

      - `NONE("none")`

### Beta Tool Choice Any

- `class BetaToolChoiceAny:`

  The model will use any available tools.

  - `JsonValue; type "any"constant`

    - `ANY("any")`

  - `Optional<Boolean> disableParallelToolUse`

    Whether to disable parallel tool use.

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

### Beta Tool Choice Auto

- `class BetaToolChoiceAuto:`

  The model will automatically decide whether to use tools.

  - `JsonValue; type "auto"constant`

    - `AUTO("auto")`

  - `Optional<Boolean> disableParallelToolUse`

    Whether to disable parallel tool use.

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

### Beta Tool Choice None

- `class BetaToolChoiceNone:`

  The model will not be allowed to use tools.

  - `JsonValue; type "none"constant`

    - `NONE("none")`

### Beta Tool Choice Tool

- `class BetaToolChoiceTool:`

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

  - `String name`

    The name of the tool to use.

  - `JsonValue; type "tool"constant`

    - `TOOL("tool")`

  - `Optional<Boolean> disableParallelToolUse`

    Whether to disable parallel tool use.

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

### Beta Tool Computer Use 20241022

- `class BetaToolComputerUse20241022:`

  - `long displayHeightPx`

    The height of the display in pixels.

  - `long displayWidthPx`

    The width of the display in pixels.

  - `JsonValue; name "computer"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `COMPUTER("computer")`

  - `JsonValue; type "computer_20241022"constant`

    - `COMPUTER_20241022("computer_20241022")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Long> displayNumber`

    The X11 display number (e.g. 0, 1) for the display.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Computer Use 20250124

- `class BetaToolComputerUse20250124:`

  - `long displayHeightPx`

    The height of the display in pixels.

  - `long displayWidthPx`

    The width of the display in pixels.

  - `JsonValue; name "computer"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `COMPUTER("computer")`

  - `JsonValue; type "computer_20250124"constant`

    - `COMPUTER_20250124("computer_20250124")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Long> displayNumber`

    The X11 display number (e.g. 0, 1) for the display.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Computer Use 20251124

- `class BetaToolComputerUse20251124:`

  - `long displayHeightPx`

    The height of the display in pixels.

  - `long displayWidthPx`

    The width of the display in pixels.

  - `JsonValue; name "computer"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `COMPUTER("computer")`

  - `JsonValue; type "computer_20251124"constant`

    - `COMPUTER_20251124("computer_20251124")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Long> displayNumber`

    The X11 display number (e.g. 0, 1) for the display.

  - `Optional<Boolean> enableZoom`

    Whether to enable an action to take a zoomed-in screenshot of the screen.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Reference Block

- `class BetaToolReferenceBlock:`

  - `String toolName`

  - `JsonValue; type "tool_reference"constant`

    - `TOOL_REFERENCE("tool_reference")`

### Beta Tool Reference Block Param

- `class BetaToolReferenceBlockParam:`

  Tool reference block that can be included in tool_result content.

  - `String toolName`

  - `JsonValue; type "tool_reference"constant`

    - `TOOL_REFERENCE("tool_reference")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

### Beta Tool Result Block Param

- `class BetaToolResultBlockParam:`

  - `String toolUseId`

  - `JsonValue; type "tool_result"constant`

    - `TOOL_RESULT("tool_result")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Content> content`

    - `String`

    - `List<Block>`

      - `class BetaTextBlockParam:`

        - `String text`

        - `JsonValue; type "text"constant`

          - `TEXT("text")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<List<BetaTextCitationParam>> citations`

          - `class BetaCitationCharLocationParam:`

            - `String citedText`

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endCharIndex`

            - `long startCharIndex`

            - `JsonValue; type "char_location"constant`

              - `CHAR_LOCATION("char_location")`

          - `class BetaCitationPageLocationParam:`

            - `String citedText`

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endPageNumber`

            - `long startPageNumber`

            - `JsonValue; type "page_location"constant`

              - `PAGE_LOCATION("page_location")`

          - `class BetaCitationContentBlockLocationParam:`

            - `String citedText`

              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.

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endBlockIndex`

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

            - `long startBlockIndex`

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

            - `JsonValue; type "content_block_location"constant`

              - `CONTENT_BLOCK_LOCATION("content_block_location")`

          - `class BetaCitationWebSearchResultLocationParam:`

            - `String citedText`

            - `String encryptedIndex`

            - `Optional<String> title`

            - `JsonValue; type "web_search_result_location"constant`

              - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

            - `String url`

          - `class BetaCitationSearchResultLocationParam:`

            - `String citedText`

              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.

            - `long endBlockIndex`

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

            - `long searchResultIndex`

              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.

            - `String source`

            - `long startBlockIndex`

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

            - `Optional<String> title`

            - `JsonValue; type "search_result_location"constant`

              - `SEARCH_RESULT_LOCATION("search_result_location")`

      - `class BetaImageBlockParam:`

        - `Source source`

          - `class BetaBase64ImageSource:`

            - `String data`

            - `MediaType mediaType`

              - `IMAGE_JPEG("image/jpeg")`

              - `IMAGE_PNG("image/png")`

              - `IMAGE_GIF("image/gif")`

              - `IMAGE_WEBP("image/webp")`

            - `JsonValue; type "base64"constant`

              - `BASE64("base64")`

          - `class BetaUrlImageSource:`

            - `JsonValue; type "url"constant`

              - `URL("url")`

            - `String url`

          - `class BetaFileImageSource:`

            - `String fileId`

            - `JsonValue; type "file"constant`

              - `FILE("file")`

        - `JsonValue; type "image"constant`

          - `IMAGE("image")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

      - `class BetaSearchResultBlockParam:`

        - `List<BetaTextBlockParam> content`

          - `String text`

          - `JsonValue; type "text"constant`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<List<BetaTextCitationParam>> citations`

        - `String source`

        - `String title`

        - `JsonValue; type "search_result"constant`

          - `SEARCH_RESULT("search_result")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<BetaCitationsConfigParam> citations`

          - `Optional<Boolean> enabled`

      - `class BetaRequestDocumentBlock:`

        - `Source source`

          - `class BetaBase64PdfSource:`

            - `String data`

            - `JsonValue; mediaType "application/pdf"constant`

              - `APPLICATION_PDF("application/pdf")`

            - `JsonValue; type "base64"constant`

              - `BASE64("base64")`

          - `class BetaPlainTextSource:`

            - `String data`

            - `JsonValue; mediaType "text/plain"constant`

              - `TEXT_PLAIN("text/plain")`

            - `JsonValue; type "text"constant`

              - `TEXT("text")`

          - `class BetaContentBlockSource:`

            - `Content content`

              - `String`

              - `List<BetaContentBlockSourceContent>`

                - `class BetaTextBlockParam:`

                - `class BetaImageBlockParam:`

            - `JsonValue; type "content"constant`

              - `CONTENT("content")`

          - `class BetaUrlPdfSource:`

            - `JsonValue; type "url"constant`

              - `URL("url")`

            - `String url`

          - `class BetaFileDocumentSource:`

            - `String fileId`

            - `JsonValue; type "file"constant`

              - `FILE("file")`

        - `JsonValue; type "document"constant`

          - `DOCUMENT("document")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<BetaCitationsConfigParam> citations`

        - `Optional<String> context`

        - `Optional<String> title`

      - `class BetaToolReferenceBlockParam:`

        Tool reference block that can be included in tool_result content.

        - `String toolName`

        - `JsonValue; type "tool_reference"constant`

          - `TOOL_REFERENCE("tool_reference")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

  - `Optional<Boolean> isError`

### Beta Tool Search Tool Bm25 20251119

- `class BetaToolSearchToolBm25_20251119:`

  - `JsonValue; name "tool_search_tool_bm25"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

  - `Type type`

    - `TOOL_SEARCH_TOOL_BM25_20251119("tool_search_tool_bm25_20251119")`

    - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Search Tool Regex 20251119

- `class BetaToolSearchToolRegex20251119:`

  - `JsonValue; name "tool_search_tool_regex"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

  - `Type type`

    - `TOOL_SEARCH_TOOL_REGEX_20251119("tool_search_tool_regex_20251119")`

    - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Search Tool Result Block

- `class BetaToolSearchToolResultBlock:`

  - `Content content`

    - `class BetaToolSearchToolResultError:`

      - `ErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `UNAVAILABLE("unavailable")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

      - `Optional<String> errorMessage`

      - `JsonValue; type "tool_search_tool_result_error"constant`

        - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

    - `class BetaToolSearchToolSearchResultBlock:`

      - `List<BetaToolReferenceBlock> toolReferences`

        - `String toolName`

        - `JsonValue; type "tool_reference"constant`

          - `TOOL_REFERENCE("tool_reference")`

      - `JsonValue; type "tool_search_tool_search_result"constant`

        - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

  - `String toolUseId`

  - `JsonValue; type "tool_search_tool_result"constant`

    - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

### Beta Tool Search Tool Result Block Param

- `class BetaToolSearchToolResultBlockParam:`

  - `Content content`

    - `class BetaToolSearchToolResultErrorParam:`

      - `ErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `UNAVAILABLE("unavailable")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

      - `JsonValue; type "tool_search_tool_result_error"constant`

        - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

      - `Optional<String> errorMessage`

    - `class BetaToolSearchToolSearchResultBlockParam:`

      - `List<BetaToolReferenceBlockParam> toolReferences`

        - `String toolName`

        - `JsonValue; type "tool_reference"constant`

          - `TOOL_REFERENCE("tool_reference")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

          - `JsonValue; type "ephemeral"constant`

            - `EPHEMERAL("ephemeral")`

          - `Optional<Ttl> ttl`

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

            - `TTL_5M("5m")`

            - `TTL_1H("1h")`

      - `JsonValue; type "tool_search_tool_search_result"constant`

        - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

  - `String toolUseId`

  - `JsonValue; type "tool_search_tool_result"constant`

    - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

### Beta Tool Search Tool Result Error

- `class BetaToolSearchToolResultError:`

  - `ErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `UNAVAILABLE("unavailable")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

  - `Optional<String> errorMessage`

  - `JsonValue; type "tool_search_tool_result_error"constant`

    - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

### Beta Tool Search Tool Result Error Param

- `class BetaToolSearchToolResultErrorParam:`

  - `ErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `UNAVAILABLE("unavailable")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

  - `JsonValue; type "tool_search_tool_result_error"constant`

    - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

  - `Optional<String> errorMessage`

### Beta Tool Search Tool Search Result Block

- `class BetaToolSearchToolSearchResultBlock:`

  - `List<BetaToolReferenceBlock> toolReferences`

    - `String toolName`

    - `JsonValue; type "tool_reference"constant`

      - `TOOL_REFERENCE("tool_reference")`

  - `JsonValue; type "tool_search_tool_search_result"constant`

    - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

### Beta Tool Search Tool Search Result Block Param

- `class BetaToolSearchToolSearchResultBlockParam:`

  - `List<BetaToolReferenceBlockParam> toolReferences`

    - `String toolName`

    - `JsonValue; type "tool_reference"constant`

      - `TOOL_REFERENCE("tool_reference")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

      - `JsonValue; type "ephemeral"constant`

        - `EPHEMERAL("ephemeral")`

      - `Optional<Ttl> ttl`

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

        - `TTL_5M("5m")`

        - `TTL_1H("1h")`

  - `JsonValue; type "tool_search_tool_search_result"constant`

    - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

### Beta Tool Text Editor 20241022

- `class BetaToolTextEditor20241022:`

  - `JsonValue; name "str_replace_editor"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `STR_REPLACE_EDITOR("str_replace_editor")`

  - `JsonValue; type "text_editor_20241022"constant`

    - `TEXT_EDITOR_20241022("text_editor_20241022")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Text Editor 20250124

- `class BetaToolTextEditor20250124:`

  - `JsonValue; name "str_replace_editor"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `STR_REPLACE_EDITOR("str_replace_editor")`

  - `JsonValue; type "text_editor_20250124"constant`

    - `TEXT_EDITOR_20250124("text_editor_20250124")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Text Editor 20250429

- `class BetaToolTextEditor20250429:`

  - `JsonValue; name "str_replace_based_edit_tool"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")`

  - `JsonValue; type "text_editor_20250429"constant`

    - `TEXT_EDITOR_20250429("text_editor_20250429")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Text Editor 20250728

- `class BetaToolTextEditor20250728:`

  - `JsonValue; name "str_replace_based_edit_tool"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")`

  - `JsonValue; type "text_editor_20250728"constant`

    - `TEXT_EDITOR_20250728("text_editor_20250728")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<List<InputExample>> inputExamples`

  - `Optional<Long> maxCharacters`

    Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Tool Union

- `class BetaToolUnion: A class that can be one of several variants.union`

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

  - `class BetaTool:`

    - `InputSchema inputSchema`

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

      - `JsonValue; type "object"constant`

        - `OBJECT("object")`

      - `Optional<Properties> properties`

      - `Optional<List<String>> required`

    - `String name`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

      - `JsonValue; type "ephemeral"constant`

        - `EPHEMERAL("ephemeral")`

      - `Optional<Ttl> ttl`

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

        - `TTL_5M("5m")`

        - `TTL_1H("1h")`

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<String> 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.

    - `Optional<Boolean> eagerInputStreaming`

      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.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

    - `Optional<Type> type`

      - `CUSTOM("custom")`

  - `class BetaToolBash20241022:`

    - `JsonValue; name "bash"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `BASH("bash")`

    - `JsonValue; type "bash_20241022"constant`

      - `BASH_20241022("bash_20241022")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaToolBash20250124:`

    - `JsonValue; name "bash"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `BASH("bash")`

    - `JsonValue; type "bash_20250124"constant`

      - `BASH_20250124("bash_20250124")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaCodeExecutionTool20250522:`

    - `JsonValue; name "code_execution"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `CODE_EXECUTION("code_execution")`

    - `JsonValue; type "code_execution_20250522"constant`

      - `CODE_EXECUTION_20250522("code_execution_20250522")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaCodeExecutionTool20250825:`

    - `JsonValue; name "code_execution"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `CODE_EXECUTION("code_execution")`

    - `JsonValue; type "code_execution_20250825"constant`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaCodeExecutionTool20260120:`

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

    - `JsonValue; name "code_execution"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `CODE_EXECUTION("code_execution")`

    - `JsonValue; type "code_execution_20260120"constant`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaToolComputerUse20241022:`

    - `long displayHeightPx`

      The height of the display in pixels.

    - `long displayWidthPx`

      The width of the display in pixels.

    - `JsonValue; name "computer"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `COMPUTER("computer")`

    - `JsonValue; type "computer_20241022"constant`

      - `COMPUTER_20241022("computer_20241022")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Long> displayNumber`

      The X11 display number (e.g. 0, 1) for the display.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaMemoryTool20250818:`

    - `JsonValue; name "memory"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `MEMORY("memory")`

    - `JsonValue; type "memory_20250818"constant`

      - `MEMORY_20250818("memory_20250818")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaToolComputerUse20250124:`

    - `long displayHeightPx`

      The height of the display in pixels.

    - `long displayWidthPx`

      The width of the display in pixels.

    - `JsonValue; name "computer"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `COMPUTER("computer")`

    - `JsonValue; type "computer_20250124"constant`

      - `COMPUTER_20250124("computer_20250124")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Long> displayNumber`

      The X11 display number (e.g. 0, 1) for the display.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaToolTextEditor20241022:`

    - `JsonValue; name "str_replace_editor"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `STR_REPLACE_EDITOR("str_replace_editor")`

    - `JsonValue; type "text_editor_20241022"constant`

      - `TEXT_EDITOR_20241022("text_editor_20241022")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaToolComputerUse20251124:`

    - `long displayHeightPx`

      The height of the display in pixels.

    - `long displayWidthPx`

      The width of the display in pixels.

    - `JsonValue; name "computer"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `COMPUTER("computer")`

    - `JsonValue; type "computer_20251124"constant`

      - `COMPUTER_20251124("computer_20251124")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Long> displayNumber`

      The X11 display number (e.g. 0, 1) for the display.

    - `Optional<Boolean> enableZoom`

      Whether to enable an action to take a zoomed-in screenshot of the screen.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaToolTextEditor20250124:`

    - `JsonValue; name "str_replace_editor"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `STR_REPLACE_EDITOR("str_replace_editor")`

    - `JsonValue; type "text_editor_20250124"constant`

      - `TEXT_EDITOR_20250124("text_editor_20250124")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaToolTextEditor20250429:`

    - `JsonValue; name "str_replace_based_edit_tool"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")`

    - `JsonValue; type "text_editor_20250429"constant`

      - `TEXT_EDITOR_20250429("text_editor_20250429")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaToolTextEditor20250728:`

    - `JsonValue; name "str_replace_based_edit_tool"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")`

    - `JsonValue; type "text_editor_20250728"constant`

      - `TEXT_EDITOR_20250728("text_editor_20250728")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<List<InputExample>> inputExamples`

    - `Optional<Long> maxCharacters`

      Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaWebSearchTool20250305:`

    - `JsonValue; name "web_search"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `WEB_SEARCH("web_search")`

    - `JsonValue; type "web_search_20250305"constant`

      - `WEB_SEARCH_20250305("web_search_20250305")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<List<String>> allowedDomains`

      If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.

    - `Optional<List<String>> blockedDomains`

      If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Long> maxUses`

      Maximum number of times the tool can be used in the API request.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

    - `Optional<BetaUserLocation> userLocation`

      Parameters for the user's location. Used to provide more relevant search results.

      - `JsonValue; type "approximate"constant`

        - `APPROXIMATE("approximate")`

      - `Optional<String> city`

        The city of the user.

      - `Optional<String> country`

        The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.

      - `Optional<String> region`

        The region of the user.

      - `Optional<String> timezone`

        The [IANA timezone](https://nodatime.org/TimeZones) of the user.

  - `class BetaWebFetchTool20250910:`

    - `JsonValue; name "web_fetch"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `WEB_FETCH("web_fetch")`

    - `JsonValue; type "web_fetch_20250910"constant`

      - `WEB_FETCH_20250910("web_fetch_20250910")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<List<String>> allowedDomains`

      List of domains to allow fetching from

    - `Optional<List<String>> blockedDomains`

      List of domains to block fetching from

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<BetaCitationsConfigParam> citations`

      Citations configuration for fetched documents. Citations are disabled by default.

      - `Optional<Boolean> enabled`

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Long> maxContentTokens`

      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.

    - `Optional<Long> maxUses`

      Maximum number of times the tool can be used in the API request.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaWebSearchTool20260209:`

    - `JsonValue; name "web_search"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `WEB_SEARCH("web_search")`

    - `JsonValue; type "web_search_20260209"constant`

      - `WEB_SEARCH_20260209("web_search_20260209")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<List<String>> allowedDomains`

      If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.

    - `Optional<List<String>> blockedDomains`

      If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Long> maxUses`

      Maximum number of times the tool can be used in the API request.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

    - `Optional<BetaUserLocation> userLocation`

      Parameters for the user's location. Used to provide more relevant search results.

  - `class BetaWebFetchTool20260209:`

    - `JsonValue; name "web_fetch"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `WEB_FETCH("web_fetch")`

    - `JsonValue; type "web_fetch_20260209"constant`

      - `WEB_FETCH_20260209("web_fetch_20260209")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<List<String>> allowedDomains`

      List of domains to allow fetching from

    - `Optional<List<String>> blockedDomains`

      List of domains to block fetching from

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<BetaCitationsConfigParam> citations`

      Citations configuration for fetched documents. Citations are disabled by default.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Long> maxContentTokens`

      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.

    - `Optional<Long> maxUses`

      Maximum number of times the tool can be used in the API request.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaWebFetchTool20260309:`

    Web fetch tool with use_cache parameter for bypassing cached content.

    - `JsonValue; name "web_fetch"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `WEB_FETCH("web_fetch")`

    - `JsonValue; type "web_fetch_20260309"constant`

      - `WEB_FETCH_20260309("web_fetch_20260309")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<List<String>> allowedDomains`

      List of domains to allow fetching from

    - `Optional<List<String>> blockedDomains`

      List of domains to block fetching from

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<BetaCitationsConfigParam> citations`

      Citations configuration for fetched documents. Citations are disabled by default.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Long> maxContentTokens`

      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.

    - `Optional<Long> maxUses`

      Maximum number of times the tool can be used in the API request.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

    - `Optional<Boolean> useCache`

      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.

  - `class BetaAdvisorTool20260301:`

    - `Model model`

      The model that will complete your prompt.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_MYTHOS_5("claude-mythos-5")`

        Most capable model for cybersecurity and biology research

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

        New class of intelligence, strongest in coding and cybersecurity

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

      - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

        Exceptional model for specialized complex tasks

      - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

        Exceptional model for specialized complex tasks

      - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

        Powerful model for complex tasks

      - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

        Powerful model for complex tasks

      - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

        High-performance model with extended thinking

      - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

        High-performance model with extended thinking

      - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

        Fast and cost-effective model

    - `JsonValue; name "advisor"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `ADVISOR("advisor")`

    - `JsonValue; type "advisor_20260301"constant`

      - `ADVISOR_20260301("advisor_20260301")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<BetaCacheControlEphemeral> caching`

      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.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Long> maxTokens`

      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.

    - `Optional<Long> maxUses`

      Maximum number of times the tool can be used in the API request.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaToolSearchToolBm25_20251119:`

    - `JsonValue; name "tool_search_tool_bm25"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

    - `Type type`

      - `TOOL_SEARCH_TOOL_BM25_20251119("tool_search_tool_bm25_20251119")`

      - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaToolSearchToolRegex20251119:`

    - `JsonValue; name "tool_search_tool_regex"constant`

      Name of the tool.

      This is how the tool will be called by the model and in `tool_use` blocks.

      - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

    - `Type type`

      - `TOOL_SEARCH_TOOL_REGEX_20251119("tool_search_tool_regex_20251119")`

      - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

    - `Optional<List<AllowedCaller>> allowedCallers`

      - `DIRECT("direct")`

      - `CODE_EXECUTION_20250825("code_execution_20250825")`

      - `CODE_EXECUTION_20260120("code_execution_20260120")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Boolean> deferLoading`

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    - `Optional<Boolean> strict`

      When true, guarantees schema validation on tool names and inputs

  - `class BetaMcpToolset:`

    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.

    - `String mcpServerName`

      Name of the MCP server to configure tools for

    - `JsonValue; type "mcp_toolset"constant`

      - `MCP_TOOLSET("mcp_toolset")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<Configs> configs`

      Configuration overrides for specific tools, keyed by tool name

      - `Optional<Boolean> deferLoading`

      - `Optional<Boolean> enabled`

    - `Optional<BetaMcpToolDefaultConfig> defaultConfig`

      Default configuration applied to all tools from this server

      - `Optional<Boolean> deferLoading`

      - `Optional<Boolean> enabled`

### Beta Tool Use Block

- `class BetaToolUseBlock:`

  - `String id`

  - `Input input`

  - `String name`

  - `JsonValue; type "tool_use"constant`

    - `TOOL_USE("tool_use")`

  - `Optional<Caller> caller`

    Tool invocation directly from the model.

    - `class BetaDirectCaller:`

      Tool invocation directly from the model.

      - `JsonValue; type "direct"constant`

        - `DIRECT("direct")`

    - `class BetaServerToolCaller:`

      Tool invocation generated by a server-side tool.

      - `String toolId`

      - `JsonValue; type "code_execution_20250825"constant`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `class BetaServerToolCaller20260120:`

      - `String toolId`

      - `JsonValue; type "code_execution_20260120"constant`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

### Beta Tool Use Block Param

- `class BetaToolUseBlockParam:`

  - `String id`

  - `Input input`

  - `String name`

  - `JsonValue; type "tool_use"constant`

    - `TOOL_USE("tool_use")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Caller> caller`

    Tool invocation directly from the model.

    - `class BetaDirectCaller:`

      Tool invocation directly from the model.

      - `JsonValue; type "direct"constant`

        - `DIRECT("direct")`

    - `class BetaServerToolCaller:`

      Tool invocation generated by a server-side tool.

      - `String toolId`

      - `JsonValue; type "code_execution_20250825"constant`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `class BetaServerToolCaller20260120:`

      - `String toolId`

      - `JsonValue; type "code_execution_20260120"constant`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

### Beta Tool Uses Keep

- `class BetaToolUsesKeep:`

  - `JsonValue; type "tool_uses"constant`

    - `TOOL_USES("tool_uses")`

  - `long value`

### Beta Tool Uses Trigger

- `class BetaToolUsesTrigger:`

  - `JsonValue; type "tool_uses"constant`

    - `TOOL_USES("tool_uses")`

  - `long value`

### Beta URL Image Source

- `class BetaUrlImageSource:`

  - `JsonValue; type "url"constant`

    - `URL("url")`

  - `String url`

### Beta URL PDF Source

- `class BetaUrlPdfSource:`

  - `JsonValue; type "url"constant`

    - `URL("url")`

  - `String url`

### Beta Usage

- `class BetaUsage:`

  - `Optional<BetaCacheCreation> cacheCreation`

    Breakdown of cached tokens by TTL

    - `long ephemeral1hInputTokens`

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

    - `long ephemeral5mInputTokens`

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

  - `Optional<Long> cacheCreationInputTokens`

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

  - `Optional<Long> cacheReadInputTokens`

    The number of input tokens read from the cache.

  - `Optional<String> inferenceGeo`

    The geographic region where inference was performed for this request.

  - `long inputTokens`

    The number of input tokens which were used.

  - `Optional<List<BetaIterationsUsageItems>> iterations`

    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

    - `class BetaMessageIterationUsage:`

      Token usage for a sampling iteration.

      - `Optional<BetaCacheCreation> cacheCreation`

        Breakdown of cached tokens by TTL

      - `long cacheCreationInputTokens`

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

      - `long cacheReadInputTokens`

        The number of input tokens read from the cache.

      - `long inputTokens`

        The number of input tokens which were used.

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_MYTHOS_5("claude-mythos-5")`

          Most capable model for cybersecurity and biology research

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

          New class of intelligence, strongest in coding and cybersecurity

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

        - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

          Exceptional model for specialized complex tasks

        - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

          Exceptional model for specialized complex tasks

        - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

          Powerful model for complex tasks

        - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

          Powerful model for complex tasks

        - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

          High-performance model with extended thinking

        - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

          High-performance model with extended thinking

        - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

          Fast and cost-effective model

      - `long outputTokens`

        The number of output tokens which were used.

      - `JsonValue; type "message"constant`

        Usage for a sampling iteration

        - `MESSAGE("message")`

    - `class BetaCompactionIterationUsage:`

      Token usage for a compaction iteration.

      - `Optional<BetaCacheCreation> cacheCreation`

        Breakdown of cached tokens by TTL

      - `long cacheCreationInputTokens`

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

      - `long cacheReadInputTokens`

        The number of input tokens read from the cache.

      - `long inputTokens`

        The number of input tokens which were used.

      - `long outputTokens`

        The number of output tokens which were used.

      - `JsonValue; type "compaction"constant`

        Usage for a compaction iteration

        - `COMPACTION("compaction")`

    - `class BetaAdvisorMessageIterationUsage:`

      Token usage for an advisor sub-inference iteration.

      - `Optional<BetaCacheCreation> cacheCreation`

        Breakdown of cached tokens by TTL

      - `long cacheCreationInputTokens`

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

      - `long cacheReadInputTokens`

        The number of input tokens read from the cache.

      - `long inputTokens`

        The number of input tokens which were used.

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `long outputTokens`

        The number of output tokens which were used.

      - `JsonValue; type "advisor_message"constant`

        Usage for an advisor sub-inference iteration

        - `ADVISOR_MESSAGE("advisor_message")`

    - `class BetaFallbackMessageIterationUsage:`

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

      - `Optional<BetaCacheCreation> cacheCreation`

        Breakdown of cached tokens by TTL

      - `long cacheCreationInputTokens`

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

      - `long cacheReadInputTokens`

        The number of input tokens read from the cache.

      - `long inputTokens`

        The number of input tokens which were used.

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `long outputTokens`

        The number of output tokens which were used.

      - `JsonValue; type "fallback_message"constant`

        Usage for the fallback-model attempt that served the response

        - `FALLBACK_MESSAGE("fallback_message")`

  - `long outputTokens`

    The number of output tokens which were used.

  - `Optional<BetaOutputTokensDetails> outputTokensDetails`

    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.

    - `long thinkingTokens`

      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.

  - `Optional<BetaServerToolUsage> serverToolUse`

    The number of server tool requests.

    - `long webFetchRequests`

      The number of web fetch tool requests.

    - `long webSearchRequests`

      The number of web search tool requests.

  - `Optional<ServiceTier> serviceTier`

    If the request used the priority, standard, or batch tier.

    - `STANDARD("standard")`

    - `PRIORITY("priority")`

    - `BATCH("batch")`

  - `Optional<Speed> speed`

    The inference speed mode used for this request.

    - `STANDARD("standard")`

    - `FAST("fast")`

### Beta User Location

- `class BetaUserLocation:`

  - `JsonValue; type "approximate"constant`

    - `APPROXIMATE("approximate")`

  - `Optional<String> city`

    The city of the user.

  - `Optional<String> country`

    The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.

  - `Optional<String> region`

    The region of the user.

  - `Optional<String> timezone`

    The [IANA timezone](https://nodatime.org/TimeZones) of the user.

### Beta Web Fetch Block

- `class BetaWebFetchBlock:`

  - `BetaDocumentBlock content`

    - `Optional<BetaCitationConfig> citations`

      Citation configuration for the document

      - `boolean enabled`

    - `Source source`

      - `class BetaBase64PdfSource:`

        - `String data`

        - `JsonValue; mediaType "application/pdf"constant`

          - `APPLICATION_PDF("application/pdf")`

        - `JsonValue; type "base64"constant`

          - `BASE64("base64")`

      - `class BetaPlainTextSource:`

        - `String data`

        - `JsonValue; mediaType "text/plain"constant`

          - `TEXT_PLAIN("text/plain")`

        - `JsonValue; type "text"constant`

          - `TEXT("text")`

    - `Optional<String> title`

      The title of the document

    - `JsonValue; type "document"constant`

      - `DOCUMENT("document")`

  - `Optional<String> retrievedAt`

    ISO 8601 timestamp when the content was retrieved

  - `JsonValue; type "web_fetch_result"constant`

    - `WEB_FETCH_RESULT("web_fetch_result")`

  - `String url`

    Fetched content URL

### Beta Web Fetch Block Param

- `class BetaWebFetchBlockParam:`

  - `BetaRequestDocumentBlock content`

    - `Source source`

      - `class BetaBase64PdfSource:`

        - `String data`

        - `JsonValue; mediaType "application/pdf"constant`

          - `APPLICATION_PDF("application/pdf")`

        - `JsonValue; type "base64"constant`

          - `BASE64("base64")`

      - `class BetaPlainTextSource:`

        - `String data`

        - `JsonValue; mediaType "text/plain"constant`

          - `TEXT_PLAIN("text/plain")`

        - `JsonValue; type "text"constant`

          - `TEXT("text")`

      - `class BetaContentBlockSource:`

        - `Content content`

          - `String`

          - `List<BetaContentBlockSourceContent>`

            - `class BetaTextBlockParam:`

              - `String text`

              - `JsonValue; type "text"constant`

                - `TEXT("text")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

                - `JsonValue; type "ephemeral"constant`

                  - `EPHEMERAL("ephemeral")`

                - `Optional<Ttl> ttl`

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

                  - `TTL_5M("5m")`

                  - `TTL_1H("1h")`

              - `Optional<List<BetaTextCitationParam>> citations`

                - `class BetaCitationCharLocationParam:`

                  - `String citedText`

                  - `long documentIndex`

                  - `Optional<String> documentTitle`

                  - `long endCharIndex`

                  - `long startCharIndex`

                  - `JsonValue; type "char_location"constant`

                    - `CHAR_LOCATION("char_location")`

                - `class BetaCitationPageLocationParam:`

                  - `String citedText`

                  - `long documentIndex`

                  - `Optional<String> documentTitle`

                  - `long endPageNumber`

                  - `long startPageNumber`

                  - `JsonValue; type "page_location"constant`

                    - `PAGE_LOCATION("page_location")`

                - `class BetaCitationContentBlockLocationParam:`

                  - `String citedText`

                    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.

                  - `long documentIndex`

                  - `Optional<String> documentTitle`

                  - `long endBlockIndex`

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

                  - `long startBlockIndex`

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

                  - `JsonValue; type "content_block_location"constant`

                    - `CONTENT_BLOCK_LOCATION("content_block_location")`

                - `class BetaCitationWebSearchResultLocationParam:`

                  - `String citedText`

                  - `String encryptedIndex`

                  - `Optional<String> title`

                  - `JsonValue; type "web_search_result_location"constant`

                    - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

                  - `String url`

                - `class BetaCitationSearchResultLocationParam:`

                  - `String citedText`

                    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.

                  - `long endBlockIndex`

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

                  - `long searchResultIndex`

                    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.

                  - `String source`

                  - `long startBlockIndex`

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

                  - `Optional<String> title`

                  - `JsonValue; type "search_result_location"constant`

                    - `SEARCH_RESULT_LOCATION("search_result_location")`

            - `class BetaImageBlockParam:`

              - `Source source`

                - `class BetaBase64ImageSource:`

                  - `String data`

                  - `MediaType mediaType`

                    - `IMAGE_JPEG("image/jpeg")`

                    - `IMAGE_PNG("image/png")`

                    - `IMAGE_GIF("image/gif")`

                    - `IMAGE_WEBP("image/webp")`

                  - `JsonValue; type "base64"constant`

                    - `BASE64("base64")`

                - `class BetaUrlImageSource:`

                  - `JsonValue; type "url"constant`

                    - `URL("url")`

                  - `String url`

                - `class BetaFileImageSource:`

                  - `String fileId`

                  - `JsonValue; type "file"constant`

                    - `FILE("file")`

              - `JsonValue; type "image"constant`

                - `IMAGE("image")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

        - `JsonValue; type "content"constant`

          - `CONTENT("content")`

      - `class BetaUrlPdfSource:`

        - `JsonValue; type "url"constant`

          - `URL("url")`

        - `String url`

      - `class BetaFileDocumentSource:`

        - `String fileId`

        - `JsonValue; type "file"constant`

          - `FILE("file")`

    - `JsonValue; type "document"constant`

      - `DOCUMENT("document")`

    - `Optional<BetaCacheControlEphemeral> cacheControl`

      Create a cache control breakpoint at this content block.

    - `Optional<BetaCitationsConfigParam> citations`

      - `Optional<Boolean> enabled`

    - `Optional<String> context`

    - `Optional<String> title`

  - `JsonValue; type "web_fetch_result"constant`

    - `WEB_FETCH_RESULT("web_fetch_result")`

  - `String url`

    Fetched content URL

  - `Optional<String> retrievedAt`

    ISO 8601 timestamp when the content was retrieved

### Beta Web Fetch Tool 20250910

- `class BetaWebFetchTool20250910:`

  - `JsonValue; name "web_fetch"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `WEB_FETCH("web_fetch")`

  - `JsonValue; type "web_fetch_20250910"constant`

    - `WEB_FETCH_20250910("web_fetch_20250910")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<List<String>> allowedDomains`

    List of domains to allow fetching from

  - `Optional<List<String>> blockedDomains`

    List of domains to block fetching from

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<BetaCitationsConfigParam> citations`

    Citations configuration for fetched documents. Citations are disabled by default.

    - `Optional<Boolean> enabled`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Long> maxContentTokens`

    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.

  - `Optional<Long> maxUses`

    Maximum number of times the tool can be used in the API request.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Web Fetch Tool 20260209

- `class BetaWebFetchTool20260209:`

  - `JsonValue; name "web_fetch"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `WEB_FETCH("web_fetch")`

  - `JsonValue; type "web_fetch_20260209"constant`

    - `WEB_FETCH_20260209("web_fetch_20260209")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<List<String>> allowedDomains`

    List of domains to allow fetching from

  - `Optional<List<String>> blockedDomains`

    List of domains to block fetching from

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<BetaCitationsConfigParam> citations`

    Citations configuration for fetched documents. Citations are disabled by default.

    - `Optional<Boolean> enabled`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Long> maxContentTokens`

    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.

  - `Optional<Long> maxUses`

    Maximum number of times the tool can be used in the API request.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

### Beta Web Fetch Tool 20260309

- `class BetaWebFetchTool20260309:`

  Web fetch tool with use_cache parameter for bypassing cached content.

  - `JsonValue; name "web_fetch"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `WEB_FETCH("web_fetch")`

  - `JsonValue; type "web_fetch_20260309"constant`

    - `WEB_FETCH_20260309("web_fetch_20260309")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<List<String>> allowedDomains`

    List of domains to allow fetching from

  - `Optional<List<String>> blockedDomains`

    List of domains to block fetching from

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<BetaCitationsConfigParam> citations`

    Citations configuration for fetched documents. Citations are disabled by default.

    - `Optional<Boolean> enabled`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Long> maxContentTokens`

    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.

  - `Optional<Long> maxUses`

    Maximum number of times the tool can be used in the API request.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

  - `Optional<Boolean> useCache`

    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.

### Beta Web Fetch Tool Result Block

- `class BetaWebFetchToolResultBlock:`

  - `Content content`

    - `class BetaWebFetchToolResultErrorBlock:`

      - `BetaWebFetchToolResultErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `URL_TOO_LONG("url_too_long")`

        - `URL_NOT_ALLOWED("url_not_allowed")`

        - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

        - `URL_NOT_ACCESSIBLE("url_not_accessible")`

        - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `MAX_USES_EXCEEDED("max_uses_exceeded")`

        - `UNAVAILABLE("unavailable")`

      - `JsonValue; type "web_fetch_tool_result_error"constant`

        - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

    - `class BetaWebFetchBlock:`

      - `BetaDocumentBlock content`

        - `Optional<BetaCitationConfig> citations`

          Citation configuration for the document

          - `boolean enabled`

        - `Source source`

          - `class BetaBase64PdfSource:`

            - `String data`

            - `JsonValue; mediaType "application/pdf"constant`

              - `APPLICATION_PDF("application/pdf")`

            - `JsonValue; type "base64"constant`

              - `BASE64("base64")`

          - `class BetaPlainTextSource:`

            - `String data`

            - `JsonValue; mediaType "text/plain"constant`

              - `TEXT_PLAIN("text/plain")`

            - `JsonValue; type "text"constant`

              - `TEXT("text")`

        - `Optional<String> title`

          The title of the document

        - `JsonValue; type "document"constant`

          - `DOCUMENT("document")`

      - `Optional<String> retrievedAt`

        ISO 8601 timestamp when the content was retrieved

      - `JsonValue; type "web_fetch_result"constant`

        - `WEB_FETCH_RESULT("web_fetch_result")`

      - `String url`

        Fetched content URL

  - `String toolUseId`

  - `JsonValue; type "web_fetch_tool_result"constant`

    - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

  - `Optional<Caller> caller`

    Tool invocation directly from the model.

    - `class BetaDirectCaller:`

      Tool invocation directly from the model.

      - `JsonValue; type "direct"constant`

        - `DIRECT("direct")`

    - `class BetaServerToolCaller:`

      Tool invocation generated by a server-side tool.

      - `String toolId`

      - `JsonValue; type "code_execution_20250825"constant`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `class BetaServerToolCaller20260120:`

      - `String toolId`

      - `JsonValue; type "code_execution_20260120"constant`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

### Beta Web Fetch Tool Result Block Param

- `class BetaWebFetchToolResultBlockParam:`

  - `Content content`

    - `class BetaWebFetchToolResultErrorBlockParam:`

      - `BetaWebFetchToolResultErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `URL_TOO_LONG("url_too_long")`

        - `URL_NOT_ALLOWED("url_not_allowed")`

        - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

        - `URL_NOT_ACCESSIBLE("url_not_accessible")`

        - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `MAX_USES_EXCEEDED("max_uses_exceeded")`

        - `UNAVAILABLE("unavailable")`

      - `JsonValue; type "web_fetch_tool_result_error"constant`

        - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

    - `class BetaWebFetchBlockParam:`

      - `BetaRequestDocumentBlock content`

        - `Source source`

          - `class BetaBase64PdfSource:`

            - `String data`

            - `JsonValue; mediaType "application/pdf"constant`

              - `APPLICATION_PDF("application/pdf")`

            - `JsonValue; type "base64"constant`

              - `BASE64("base64")`

          - `class BetaPlainTextSource:`

            - `String data`

            - `JsonValue; mediaType "text/plain"constant`

              - `TEXT_PLAIN("text/plain")`

            - `JsonValue; type "text"constant`

              - `TEXT("text")`

          - `class BetaContentBlockSource:`

            - `Content content`

              - `String`

              - `List<BetaContentBlockSourceContent>`

                - `class BetaTextBlockParam:`

                  - `String text`

                  - `JsonValue; type "text"constant`

                    - `TEXT("text")`

                  - `Optional<BetaCacheControlEphemeral> cacheControl`

                    Create a cache control breakpoint at this content block.

                    - `JsonValue; type "ephemeral"constant`

                      - `EPHEMERAL("ephemeral")`

                    - `Optional<Ttl> ttl`

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

                      - `TTL_5M("5m")`

                      - `TTL_1H("1h")`

                  - `Optional<List<BetaTextCitationParam>> citations`

                    - `class BetaCitationCharLocationParam:`

                      - `String citedText`

                      - `long documentIndex`

                      - `Optional<String> documentTitle`

                      - `long endCharIndex`

                      - `long startCharIndex`

                      - `JsonValue; type "char_location"constant`

                        - `CHAR_LOCATION("char_location")`

                    - `class BetaCitationPageLocationParam:`

                      - `String citedText`

                      - `long documentIndex`

                      - `Optional<String> documentTitle`

                      - `long endPageNumber`

                      - `long startPageNumber`

                      - `JsonValue; type "page_location"constant`

                        - `PAGE_LOCATION("page_location")`

                    - `class BetaCitationContentBlockLocationParam:`

                      - `String citedText`

                        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.

                      - `long documentIndex`

                      - `Optional<String> documentTitle`

                      - `long endBlockIndex`

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

                      - `long startBlockIndex`

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

                      - `JsonValue; type "content_block_location"constant`

                        - `CONTENT_BLOCK_LOCATION("content_block_location")`

                    - `class BetaCitationWebSearchResultLocationParam:`

                      - `String citedText`

                      - `String encryptedIndex`

                      - `Optional<String> title`

                      - `JsonValue; type "web_search_result_location"constant`

                        - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

                      - `String url`

                    - `class BetaCitationSearchResultLocationParam:`

                      - `String citedText`

                        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.

                      - `long endBlockIndex`

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

                      - `long searchResultIndex`

                        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.

                      - `String source`

                      - `long startBlockIndex`

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

                      - `Optional<String> title`

                      - `JsonValue; type "search_result_location"constant`

                        - `SEARCH_RESULT_LOCATION("search_result_location")`

                - `class BetaImageBlockParam:`

                  - `Source source`

                    - `class BetaBase64ImageSource:`

                      - `String data`

                      - `MediaType mediaType`

                        - `IMAGE_JPEG("image/jpeg")`

                        - `IMAGE_PNG("image/png")`

                        - `IMAGE_GIF("image/gif")`

                        - `IMAGE_WEBP("image/webp")`

                      - `JsonValue; type "base64"constant`

                        - `BASE64("base64")`

                    - `class BetaUrlImageSource:`

                      - `JsonValue; type "url"constant`

                        - `URL("url")`

                      - `String url`

                    - `class BetaFileImageSource:`

                      - `String fileId`

                      - `JsonValue; type "file"constant`

                        - `FILE("file")`

                  - `JsonValue; type "image"constant`

                    - `IMAGE("image")`

                  - `Optional<BetaCacheControlEphemeral> cacheControl`

                    Create a cache control breakpoint at this content block.

            - `JsonValue; type "content"constant`

              - `CONTENT("content")`

          - `class BetaUrlPdfSource:`

            - `JsonValue; type "url"constant`

              - `URL("url")`

            - `String url`

          - `class BetaFileDocumentSource:`

            - `String fileId`

            - `JsonValue; type "file"constant`

              - `FILE("file")`

        - `JsonValue; type "document"constant`

          - `DOCUMENT("document")`

        - `Optional<BetaCacheControlEphemeral> cacheControl`

          Create a cache control breakpoint at this content block.

        - `Optional<BetaCitationsConfigParam> citations`

          - `Optional<Boolean> enabled`

        - `Optional<String> context`

        - `Optional<String> title`

      - `JsonValue; type "web_fetch_result"constant`

        - `WEB_FETCH_RESULT("web_fetch_result")`

      - `String url`

        Fetched content URL

      - `Optional<String> retrievedAt`

        ISO 8601 timestamp when the content was retrieved

  - `String toolUseId`

  - `JsonValue; type "web_fetch_tool_result"constant`

    - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

  - `Optional<Caller> caller`

    Tool invocation directly from the model.

    - `class BetaDirectCaller:`

      Tool invocation directly from the model.

      - `JsonValue; type "direct"constant`

        - `DIRECT("direct")`

    - `class BetaServerToolCaller:`

      Tool invocation generated by a server-side tool.

      - `String toolId`

      - `JsonValue; type "code_execution_20250825"constant`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `class BetaServerToolCaller20260120:`

      - `String toolId`

      - `JsonValue; type "code_execution_20260120"constant`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

### Beta Web Fetch Tool Result Error Block

- `class BetaWebFetchToolResultErrorBlock:`

  - `BetaWebFetchToolResultErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `URL_TOO_LONG("url_too_long")`

    - `URL_NOT_ALLOWED("url_not_allowed")`

    - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

    - `URL_NOT_ACCESSIBLE("url_not_accessible")`

    - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `MAX_USES_EXCEEDED("max_uses_exceeded")`

    - `UNAVAILABLE("unavailable")`

  - `JsonValue; type "web_fetch_tool_result_error"constant`

    - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

### Beta Web Fetch Tool Result Error Block Param

- `class BetaWebFetchToolResultErrorBlockParam:`

  - `BetaWebFetchToolResultErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `URL_TOO_LONG("url_too_long")`

    - `URL_NOT_ALLOWED("url_not_allowed")`

    - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

    - `URL_NOT_ACCESSIBLE("url_not_accessible")`

    - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `MAX_USES_EXCEEDED("max_uses_exceeded")`

    - `UNAVAILABLE("unavailable")`

  - `JsonValue; type "web_fetch_tool_result_error"constant`

    - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

### Beta Web Fetch Tool Result Error Code

- `enum BetaWebFetchToolResultErrorCode:`

  - `INVALID_TOOL_INPUT("invalid_tool_input")`

  - `URL_TOO_LONG("url_too_long")`

  - `URL_NOT_ALLOWED("url_not_allowed")`

  - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

  - `URL_NOT_ACCESSIBLE("url_not_accessible")`

  - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

  - `TOO_MANY_REQUESTS("too_many_requests")`

  - `MAX_USES_EXCEEDED("max_uses_exceeded")`

  - `UNAVAILABLE("unavailable")`

### Beta Web Search Result Block

- `class BetaWebSearchResultBlock:`

  - `String encryptedContent`

  - `Optional<String> pageAge`

  - `String title`

  - `JsonValue; type "web_search_result"constant`

    - `WEB_SEARCH_RESULT("web_search_result")`

  - `String url`

### Beta Web Search Result Block Param

- `class BetaWebSearchResultBlockParam:`

  - `String encryptedContent`

  - `String title`

  - `JsonValue; type "web_search_result"constant`

    - `WEB_SEARCH_RESULT("web_search_result")`

  - `String url`

  - `Optional<String> pageAge`

### Beta Web Search Tool 20250305

- `class BetaWebSearchTool20250305:`

  - `JsonValue; name "web_search"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `WEB_SEARCH("web_search")`

  - `JsonValue; type "web_search_20250305"constant`

    - `WEB_SEARCH_20250305("web_search_20250305")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<List<String>> allowedDomains`

    If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.

  - `Optional<List<String>> blockedDomains`

    If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Long> maxUses`

    Maximum number of times the tool can be used in the API request.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

  - `Optional<BetaUserLocation> userLocation`

    Parameters for the user's location. Used to provide more relevant search results.

    - `JsonValue; type "approximate"constant`

      - `APPROXIMATE("approximate")`

    - `Optional<String> city`

      The city of the user.

    - `Optional<String> country`

      The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.

    - `Optional<String> region`

      The region of the user.

    - `Optional<String> timezone`

      The [IANA timezone](https://nodatime.org/TimeZones) of the user.

### Beta Web Search Tool 20260209

- `class BetaWebSearchTool20260209:`

  - `JsonValue; name "web_search"constant`

    Name of the tool.

    This is how the tool will be called by the model and in `tool_use` blocks.

    - `WEB_SEARCH("web_search")`

  - `JsonValue; type "web_search_20260209"constant`

    - `WEB_SEARCH_20260209("web_search_20260209")`

  - `Optional<List<AllowedCaller>> allowedCallers`

    - `DIRECT("direct")`

    - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `CODE_EXECUTION_20260120("code_execution_20260120")`

  - `Optional<List<String>> allowedDomains`

    If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.

  - `Optional<List<String>> blockedDomains`

    If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Boolean> deferLoading`

    If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

  - `Optional<Long> maxUses`

    Maximum number of times the tool can be used in the API request.

  - `Optional<Boolean> strict`

    When true, guarantees schema validation on tool names and inputs

  - `Optional<BetaUserLocation> userLocation`

    Parameters for the user's location. Used to provide more relevant search results.

    - `JsonValue; type "approximate"constant`

      - `APPROXIMATE("approximate")`

    - `Optional<String> city`

      The city of the user.

    - `Optional<String> country`

      The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.

    - `Optional<String> region`

      The region of the user.

    - `Optional<String> timezone`

      The [IANA timezone](https://nodatime.org/TimeZones) of the user.

### Beta Web Search Tool Request Error

- `class BetaWebSearchToolRequestError:`

  - `BetaWebSearchToolResultErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `UNAVAILABLE("unavailable")`

    - `MAX_USES_EXCEEDED("max_uses_exceeded")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `QUERY_TOO_LONG("query_too_long")`

    - `REQUEST_TOO_LARGE("request_too_large")`

  - `JsonValue; type "web_search_tool_result_error"constant`

    - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

### Beta Web Search Tool Result Block

- `class BetaWebSearchToolResultBlock:`

  - `BetaWebSearchToolResultBlockContent content`

    - `class BetaWebSearchToolResultError:`

      - `BetaWebSearchToolResultErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `UNAVAILABLE("unavailable")`

        - `MAX_USES_EXCEEDED("max_uses_exceeded")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `QUERY_TOO_LONG("query_too_long")`

        - `REQUEST_TOO_LARGE("request_too_large")`

      - `JsonValue; type "web_search_tool_result_error"constant`

        - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

    - `List<BetaWebSearchResultBlock>`

      - `String encryptedContent`

      - `Optional<String> pageAge`

      - `String title`

      - `JsonValue; type "web_search_result"constant`

        - `WEB_SEARCH_RESULT("web_search_result")`

      - `String url`

  - `String toolUseId`

  - `JsonValue; type "web_search_tool_result"constant`

    - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

  - `Optional<Caller> caller`

    Tool invocation directly from the model.

    - `class BetaDirectCaller:`

      Tool invocation directly from the model.

      - `JsonValue; type "direct"constant`

        - `DIRECT("direct")`

    - `class BetaServerToolCaller:`

      Tool invocation generated by a server-side tool.

      - `String toolId`

      - `JsonValue; type "code_execution_20250825"constant`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `class BetaServerToolCaller20260120:`

      - `String toolId`

      - `JsonValue; type "code_execution_20260120"constant`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

### Beta Web Search Tool Result Block Content

- `class BetaWebSearchToolResultBlockContent: A class that can be one of several variants.union`

  - `class BetaWebSearchToolResultError:`

    - `BetaWebSearchToolResultErrorCode errorCode`

      - `INVALID_TOOL_INPUT("invalid_tool_input")`

      - `UNAVAILABLE("unavailable")`

      - `MAX_USES_EXCEEDED("max_uses_exceeded")`

      - `TOO_MANY_REQUESTS("too_many_requests")`

      - `QUERY_TOO_LONG("query_too_long")`

      - `REQUEST_TOO_LARGE("request_too_large")`

    - `JsonValue; type "web_search_tool_result_error"constant`

      - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

  - `List<BetaWebSearchResultBlock>`

    - `String encryptedContent`

    - `Optional<String> pageAge`

    - `String title`

    - `JsonValue; type "web_search_result"constant`

      - `WEB_SEARCH_RESULT("web_search_result")`

    - `String url`

### Beta Web Search Tool Result Block Param

- `class BetaWebSearchToolResultBlockParam:`

  - `BetaWebSearchToolResultBlockParamContent content`

    - `List<BetaWebSearchResultBlockParam>`

      - `String encryptedContent`

      - `String title`

      - `JsonValue; type "web_search_result"constant`

        - `WEB_SEARCH_RESULT("web_search_result")`

      - `String url`

      - `Optional<String> pageAge`

    - `class BetaWebSearchToolRequestError:`

      - `BetaWebSearchToolResultErrorCode errorCode`

        - `INVALID_TOOL_INPUT("invalid_tool_input")`

        - `UNAVAILABLE("unavailable")`

        - `MAX_USES_EXCEEDED("max_uses_exceeded")`

        - `TOO_MANY_REQUESTS("too_many_requests")`

        - `QUERY_TOO_LONG("query_too_long")`

        - `REQUEST_TOO_LARGE("request_too_large")`

      - `JsonValue; type "web_search_tool_result_error"constant`

        - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

  - `String toolUseId`

  - `JsonValue; type "web_search_tool_result"constant`

    - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

  - `Optional<BetaCacheControlEphemeral> cacheControl`

    Create a cache control breakpoint at this content block.

    - `JsonValue; type "ephemeral"constant`

      - `EPHEMERAL("ephemeral")`

    - `Optional<Ttl> ttl`

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

      - `TTL_5M("5m")`

      - `TTL_1H("1h")`

  - `Optional<Caller> caller`

    Tool invocation directly from the model.

    - `class BetaDirectCaller:`

      Tool invocation directly from the model.

      - `JsonValue; type "direct"constant`

        - `DIRECT("direct")`

    - `class BetaServerToolCaller:`

      Tool invocation generated by a server-side tool.

      - `String toolId`

      - `JsonValue; type "code_execution_20250825"constant`

        - `CODE_EXECUTION_20250825("code_execution_20250825")`

    - `class BetaServerToolCaller20260120:`

      - `String toolId`

      - `JsonValue; type "code_execution_20260120"constant`

        - `CODE_EXECUTION_20260120("code_execution_20260120")`

### Beta Web Search Tool Result Block Param Content

- `class BetaWebSearchToolResultBlockParamContent: A class that can be one of several variants.union`

  - `List<BetaWebSearchResultBlockParam>`

    - `String encryptedContent`

    - `String title`

    - `JsonValue; type "web_search_result"constant`

      - `WEB_SEARCH_RESULT("web_search_result")`

    - `String url`

    - `Optional<String> pageAge`

  - `class BetaWebSearchToolRequestError:`

    - `BetaWebSearchToolResultErrorCode errorCode`

      - `INVALID_TOOL_INPUT("invalid_tool_input")`

      - `UNAVAILABLE("unavailable")`

      - `MAX_USES_EXCEEDED("max_uses_exceeded")`

      - `TOO_MANY_REQUESTS("too_many_requests")`

      - `QUERY_TOO_LONG("query_too_long")`

      - `REQUEST_TOO_LARGE("request_too_large")`

    - `JsonValue; type "web_search_tool_result_error"constant`

      - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

### Beta Web Search Tool Result Error

- `class BetaWebSearchToolResultError:`

  - `BetaWebSearchToolResultErrorCode errorCode`

    - `INVALID_TOOL_INPUT("invalid_tool_input")`

    - `UNAVAILABLE("unavailable")`

    - `MAX_USES_EXCEEDED("max_uses_exceeded")`

    - `TOO_MANY_REQUESTS("too_many_requests")`

    - `QUERY_TOO_LONG("query_too_long")`

    - `REQUEST_TOO_LARGE("request_too_large")`

  - `JsonValue; type "web_search_tool_result_error"constant`

    - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

### Beta Web Search Tool Result Error Code

- `enum BetaWebSearchToolResultErrorCode:`

  - `INVALID_TOOL_INPUT("invalid_tool_input")`

  - `UNAVAILABLE("unavailable")`

  - `MAX_USES_EXCEEDED("max_uses_exceeded")`

  - `TOO_MANY_REQUESTS("too_many_requests")`

  - `QUERY_TOO_LONG("query_too_long")`

  - `REQUEST_TOO_LARGE("request_too_large")`

# Batches

## Create a Message Batch

`BetaMessageBatch beta().messages().batches().create(BatchCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/messages/batches`

Send a batch of Message creation requests.

The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete.

Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)

### Parameters

- `BatchCreateParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `List<Request> requests`

    List of requests for prompt completion. Each is an individual request to create a Message.

    - `String customId`

      Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.

      Must be unique for each request within the Message Batch.

    - `Params params`

      Messages API creation parameters for the individual request.

      See the [Messages API reference](https://docs.claude.com/en/api/messages) for full documentation on available parameters.

      - `long maxTokens`

        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](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.

        Different models have different maximum values for this parameter.  See [models](https://docs.claude.com/en/docs/models-overview) for details.

      - `List<BetaMessageParam> messages`

        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, Claude"}]
        ```

        Example with multiple conversational turns:

        ```json
        [
          {"role": "user", "content": "Hello there."},
          {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
          {"role": "user", "content": "Can you explain LLMs in plain English?"},
        ]
        ```

        Example with a partially-filled response from Claude:

        ```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, Claude"}
        ```

        ```json
        {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
        ```

        See [input examples](https://docs.claude.com/en/api/messages-examples).

        Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), 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.

        - `Content content`

          - `String`

          - `List<BetaContentBlockParam>`

            - `class BetaTextBlockParam:`

              - `String text`

              - `JsonValue; type "text"constant`

                - `TEXT("text")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

                - `JsonValue; type "ephemeral"constant`

                  - `EPHEMERAL("ephemeral")`

                - `Optional<Ttl> ttl`

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

                  - `TTL_5M("5m")`

                  - `TTL_1H("1h")`

              - `Optional<List<BetaTextCitationParam>> citations`

                - `class BetaCitationCharLocationParam:`

                  - `String citedText`

                  - `long documentIndex`

                  - `Optional<String> documentTitle`

                  - `long endCharIndex`

                  - `long startCharIndex`

                  - `JsonValue; type "char_location"constant`

                    - `CHAR_LOCATION("char_location")`

                - `class BetaCitationPageLocationParam:`

                  - `String citedText`

                  - `long documentIndex`

                  - `Optional<String> documentTitle`

                  - `long endPageNumber`

                  - `long startPageNumber`

                  - `JsonValue; type "page_location"constant`

                    - `PAGE_LOCATION("page_location")`

                - `class BetaCitationContentBlockLocationParam:`

                  - `String citedText`

                    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.

                  - `long documentIndex`

                  - `Optional<String> documentTitle`

                  - `long endBlockIndex`

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

                  - `long startBlockIndex`

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

                  - `JsonValue; type "content_block_location"constant`

                    - `CONTENT_BLOCK_LOCATION("content_block_location")`

                - `class BetaCitationWebSearchResultLocationParam:`

                  - `String citedText`

                  - `String encryptedIndex`

                  - `Optional<String> title`

                  - `JsonValue; type "web_search_result_location"constant`

                    - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

                  - `String url`

                - `class BetaCitationSearchResultLocationParam:`

                  - `String citedText`

                    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.

                  - `long endBlockIndex`

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

                  - `long searchResultIndex`

                    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.

                  - `String source`

                  - `long startBlockIndex`

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

                  - `Optional<String> title`

                  - `JsonValue; type "search_result_location"constant`

                    - `SEARCH_RESULT_LOCATION("search_result_location")`

            - `class BetaImageBlockParam:`

              - `Source source`

                - `class BetaBase64ImageSource:`

                  - `String data`

                  - `MediaType mediaType`

                    - `IMAGE_JPEG("image/jpeg")`

                    - `IMAGE_PNG("image/png")`

                    - `IMAGE_GIF("image/gif")`

                    - `IMAGE_WEBP("image/webp")`

                  - `JsonValue; type "base64"constant`

                    - `BASE64("base64")`

                - `class BetaUrlImageSource:`

                  - `JsonValue; type "url"constant`

                    - `URL("url")`

                  - `String url`

                - `class BetaFileImageSource:`

                  - `String fileId`

                  - `JsonValue; type "file"constant`

                    - `FILE("file")`

              - `JsonValue; type "image"constant`

                - `IMAGE("image")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

            - `class BetaRequestDocumentBlock:`

              - `Source source`

                - `class BetaBase64PdfSource:`

                  - `String data`

                  - `JsonValue; mediaType "application/pdf"constant`

                    - `APPLICATION_PDF("application/pdf")`

                  - `JsonValue; type "base64"constant`

                    - `BASE64("base64")`

                - `class BetaPlainTextSource:`

                  - `String data`

                  - `JsonValue; mediaType "text/plain"constant`

                    - `TEXT_PLAIN("text/plain")`

                  - `JsonValue; type "text"constant`

                    - `TEXT("text")`

                - `class BetaContentBlockSource:`

                  - `Content content`

                    - `String`

                    - `List<BetaContentBlockSourceContent>`

                      - `class BetaTextBlockParam:`

                      - `class BetaImageBlockParam:`

                  - `JsonValue; type "content"constant`

                    - `CONTENT("content")`

                - `class BetaUrlPdfSource:`

                  - `JsonValue; type "url"constant`

                    - `URL("url")`

                  - `String url`

                - `class BetaFileDocumentSource:`

                  - `String fileId`

                  - `JsonValue; type "file"constant`

                    - `FILE("file")`

              - `JsonValue; type "document"constant`

                - `DOCUMENT("document")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<BetaCitationsConfigParam> citations`

                - `Optional<Boolean> enabled`

              - `Optional<String> context`

              - `Optional<String> title`

            - `class BetaSearchResultBlockParam:`

              - `List<BetaTextBlockParam> content`

                - `String text`

                - `JsonValue; type "text"constant`

                - `Optional<BetaCacheControlEphemeral> cacheControl`

                  Create a cache control breakpoint at this content block.

                - `Optional<List<BetaTextCitationParam>> citations`

              - `String source`

              - `String title`

              - `JsonValue; type "search_result"constant`

                - `SEARCH_RESULT("search_result")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<BetaCitationsConfigParam> citations`

            - `class BetaThinkingBlockParam:`

              - `String signature`

              - `String thinking`

              - `JsonValue; type "thinking"constant`

                - `THINKING("thinking")`

            - `class BetaRedactedThinkingBlockParam:`

              - `String data`

              - `JsonValue; type "redacted_thinking"constant`

                - `REDACTED_THINKING("redacted_thinking")`

            - `class BetaToolUseBlockParam:`

              - `String id`

              - `Input input`

              - `String name`

              - `JsonValue; type "tool_use"constant`

                - `TOOL_USE("tool_use")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<Caller> caller`

                Tool invocation directly from the model.

                - `class BetaDirectCaller:`

                  Tool invocation directly from the model.

                  - `JsonValue; type "direct"constant`

                    - `DIRECT("direct")`

                - `class BetaServerToolCaller:`

                  Tool invocation generated by a server-side tool.

                  - `String toolId`

                  - `JsonValue; type "code_execution_20250825"constant`

                    - `CODE_EXECUTION_20250825("code_execution_20250825")`

                - `class BetaServerToolCaller20260120:`

                  - `String toolId`

                  - `JsonValue; type "code_execution_20260120"constant`

                    - `CODE_EXECUTION_20260120("code_execution_20260120")`

            - `class BetaToolResultBlockParam:`

              - `String toolUseId`

              - `JsonValue; type "tool_result"constant`

                - `TOOL_RESULT("tool_result")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<Content> content`

                - `String`

                - `List<Block>`

                  - `class BetaTextBlockParam:`

                  - `class BetaImageBlockParam:`

                  - `class BetaSearchResultBlockParam:`

                  - `class BetaRequestDocumentBlock:`

                  - `class BetaToolReferenceBlockParam:`

                    Tool reference block that can be included in tool_result content.

                    - `String toolName`

                    - `JsonValue; type "tool_reference"constant`

                      - `TOOL_REFERENCE("tool_reference")`

                    - `Optional<BetaCacheControlEphemeral> cacheControl`

                      Create a cache control breakpoint at this content block.

              - `Optional<Boolean> isError`

            - `class BetaServerToolUseBlockParam:`

              - `String id`

              - `Input input`

              - `Name name`

                - `ADVISOR("advisor")`

                - `WEB_SEARCH("web_search")`

                - `WEB_FETCH("web_fetch")`

                - `CODE_EXECUTION("code_execution")`

                - `BASH_CODE_EXECUTION("bash_code_execution")`

                - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

                - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

                - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

              - `JsonValue; type "server_tool_use"constant`

                - `SERVER_TOOL_USE("server_tool_use")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<Caller> caller`

                Tool invocation directly from the model.

                - `class BetaDirectCaller:`

                  Tool invocation directly from the model.

                - `class BetaServerToolCaller:`

                  Tool invocation generated by a server-side tool.

                - `class BetaServerToolCaller20260120:`

            - `class BetaWebSearchToolResultBlockParam:`

              - `BetaWebSearchToolResultBlockParamContent content`

                - `List<BetaWebSearchResultBlockParam>`

                  - `String encryptedContent`

                  - `String title`

                  - `JsonValue; type "web_search_result"constant`

                    - `WEB_SEARCH_RESULT("web_search_result")`

                  - `String url`

                  - `Optional<String> pageAge`

                - `class BetaWebSearchToolRequestError:`

                  - `BetaWebSearchToolResultErrorCode errorCode`

                    - `INVALID_TOOL_INPUT("invalid_tool_input")`

                    - `UNAVAILABLE("unavailable")`

                    - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                    - `TOO_MANY_REQUESTS("too_many_requests")`

                    - `QUERY_TOO_LONG("query_too_long")`

                    - `REQUEST_TOO_LARGE("request_too_large")`

                  - `JsonValue; type "web_search_tool_result_error"constant`

                    - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

              - `String toolUseId`

              - `JsonValue; type "web_search_tool_result"constant`

                - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<Caller> caller`

                Tool invocation directly from the model.

                - `class BetaDirectCaller:`

                  Tool invocation directly from the model.

                - `class BetaServerToolCaller:`

                  Tool invocation generated by a server-side tool.

                - `class BetaServerToolCaller20260120:`

            - `class BetaWebFetchToolResultBlockParam:`

              - `Content content`

                - `class BetaWebFetchToolResultErrorBlockParam:`

                  - `BetaWebFetchToolResultErrorCode errorCode`

                    - `INVALID_TOOL_INPUT("invalid_tool_input")`

                    - `URL_TOO_LONG("url_too_long")`

                    - `URL_NOT_ALLOWED("url_not_allowed")`

                    - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

                    - `URL_NOT_ACCESSIBLE("url_not_accessible")`

                    - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

                    - `TOO_MANY_REQUESTS("too_many_requests")`

                    - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                    - `UNAVAILABLE("unavailable")`

                  - `JsonValue; type "web_fetch_tool_result_error"constant`

                    - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

                - `class BetaWebFetchBlockParam:`

                  - `BetaRequestDocumentBlock content`

                  - `JsonValue; type "web_fetch_result"constant`

                    - `WEB_FETCH_RESULT("web_fetch_result")`

                  - `String url`

                    Fetched content URL

                  - `Optional<String> retrievedAt`

                    ISO 8601 timestamp when the content was retrieved

              - `String toolUseId`

              - `JsonValue; type "web_fetch_tool_result"constant`

                - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<Caller> caller`

                Tool invocation directly from the model.

                - `class BetaDirectCaller:`

                  Tool invocation directly from the model.

                - `class BetaServerToolCaller:`

                  Tool invocation generated by a server-side tool.

                - `class BetaServerToolCaller20260120:`

            - `class BetaAdvisorToolResultBlockParam:`

              - `Content content`

                - `class BetaAdvisorToolResultErrorParam:`

                  - `ErrorCode errorCode`

                    - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                    - `PROMPT_TOO_LONG("prompt_too_long")`

                    - `TOO_MANY_REQUESTS("too_many_requests")`

                    - `OVERLOADED("overloaded")`

                    - `UNAVAILABLE("unavailable")`

                    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                    - `MODEL_NOT_FOUND("model_not_found")`

                  - `JsonValue; type "advisor_tool_result_error"constant`

                    - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

                - `class BetaAdvisorResultBlockParam:`

                  - `String text`

                  - `JsonValue; type "advisor_result"constant`

                    - `ADVISOR_RESULT("advisor_result")`

                  - `Optional<String> stopReason`

                - `class BetaAdvisorRedactedResultBlockParam:`

                  - `String encryptedContent`

                    Opaque blob produced by a prior response; must be round-tripped verbatim.

                  - `JsonValue; type "advisor_redacted_result"constant`

                    - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

                  - `Optional<String> stopReason`

              - `String toolUseId`

              - `JsonValue; type "advisor_tool_result"constant`

                - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

            - `class BetaCodeExecutionToolResultBlockParam:`

              - `BetaCodeExecutionToolResultBlockParamContent content`

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

                - `class BetaCodeExecutionToolResultErrorParam:`

                  - `BetaCodeExecutionToolResultErrorCode errorCode`

                    - `INVALID_TOOL_INPUT("invalid_tool_input")`

                    - `UNAVAILABLE("unavailable")`

                    - `TOO_MANY_REQUESTS("too_many_requests")`

                    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                  - `JsonValue; type "code_execution_tool_result_error"constant`

                    - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

                - `class BetaCodeExecutionResultBlockParam:`

                  - `List<BetaCodeExecutionOutputBlockParam> content`

                    - `String fileId`

                    - `JsonValue; type "code_execution_output"constant`

                      - `CODE_EXECUTION_OUTPUT("code_execution_output")`

                  - `long returnCode`

                  - `String stderr`

                  - `String stdout`

                  - `JsonValue; type "code_execution_result"constant`

                    - `CODE_EXECUTION_RESULT("code_execution_result")`

                - `class BetaEncryptedCodeExecutionResultBlockParam:`

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

                  - `List<BetaCodeExecutionOutputBlockParam> content`

                    - `String fileId`

                    - `JsonValue; type "code_execution_output"constant`

                  - `String encryptedStdout`

                  - `long returnCode`

                  - `String stderr`

                  - `JsonValue; type "encrypted_code_execution_result"constant`

                    - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

              - `String toolUseId`

              - `JsonValue; type "code_execution_tool_result"constant`

                - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

            - `class BetaBashCodeExecutionToolResultBlockParam:`

              - `Content content`

                - `class BetaBashCodeExecutionToolResultErrorParam:`

                  - `ErrorCode errorCode`

                    - `INVALID_TOOL_INPUT("invalid_tool_input")`

                    - `UNAVAILABLE("unavailable")`

                    - `TOO_MANY_REQUESTS("too_many_requests")`

                    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                    - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

                  - `JsonValue; type "bash_code_execution_tool_result_error"constant`

                    - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

                - `class BetaBashCodeExecutionResultBlockParam:`

                  - `List<BetaBashCodeExecutionOutputBlockParam> content`

                    - `String fileId`

                    - `JsonValue; type "bash_code_execution_output"constant`

                      - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

                  - `long returnCode`

                  - `String stderr`

                  - `String stdout`

                  - `JsonValue; type "bash_code_execution_result"constant`

                    - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

              - `String toolUseId`

              - `JsonValue; type "bash_code_execution_tool_result"constant`

                - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

            - `class BetaTextEditorCodeExecutionToolResultBlockParam:`

              - `Content content`

                - `class BetaTextEditorCodeExecutionToolResultErrorParam:`

                  - `ErrorCode errorCode`

                    - `INVALID_TOOL_INPUT("invalid_tool_input")`

                    - `UNAVAILABLE("unavailable")`

                    - `TOO_MANY_REQUESTS("too_many_requests")`

                    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                    - `FILE_NOT_FOUND("file_not_found")`

                  - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

                    - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

                  - `Optional<String> errorMessage`

                - `class BetaTextEditorCodeExecutionViewResultBlockParam:`

                  - `String content`

                  - `FileType fileType`

                    - `TEXT("text")`

                    - `IMAGE("image")`

                    - `PDF("pdf")`

                  - `JsonValue; type "text_editor_code_execution_view_result"constant`

                    - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

                  - `Optional<Long> numLines`

                  - `Optional<Long> startLine`

                  - `Optional<Long> totalLines`

                - `class BetaTextEditorCodeExecutionCreateResultBlockParam:`

                  - `boolean isFileUpdate`

                  - `JsonValue; type "text_editor_code_execution_create_result"constant`

                    - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

                - `class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:`

                  - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

                    - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

                  - `Optional<List<String>> lines`

                  - `Optional<Long> newLines`

                  - `Optional<Long> newStart`

                  - `Optional<Long> oldLines`

                  - `Optional<Long> oldStart`

              - `String toolUseId`

              - `JsonValue; type "text_editor_code_execution_tool_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

            - `class BetaToolSearchToolResultBlockParam:`

              - `Content content`

                - `class BetaToolSearchToolResultErrorParam:`

                  - `ErrorCode errorCode`

                    - `INVALID_TOOL_INPUT("invalid_tool_input")`

                    - `UNAVAILABLE("unavailable")`

                    - `TOO_MANY_REQUESTS("too_many_requests")`

                    - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                  - `JsonValue; type "tool_search_tool_result_error"constant`

                    - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

                  - `Optional<String> errorMessage`

                - `class BetaToolSearchToolSearchResultBlockParam:`

                  - `List<BetaToolReferenceBlockParam> toolReferences`

                    - `String toolName`

                    - `JsonValue; type "tool_reference"constant`

                    - `Optional<BetaCacheControlEphemeral> cacheControl`

                      Create a cache control breakpoint at this content block.

                  - `JsonValue; type "tool_search_tool_search_result"constant`

                    - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

              - `String toolUseId`

              - `JsonValue; type "tool_search_tool_result"constant`

                - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

            - `class BetaMcpToolUseBlockParam:`

              - `String id`

              - `Input input`

              - `String name`

              - `String serverName`

                The name of the MCP server

              - `JsonValue; type "mcp_tool_use"constant`

                - `MCP_TOOL_USE("mcp_tool_use")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

            - `class BetaRequestMcpToolResultBlockParam:`

              - `String toolUseId`

              - `JsonValue; type "mcp_tool_result"constant`

                - `MCP_TOOL_RESULT("mcp_tool_result")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<Content> content`

                - `String`

                - `List<BetaTextBlockParam>`

                  - `String text`

                  - `JsonValue; type "text"constant`

                  - `Optional<BetaCacheControlEphemeral> cacheControl`

                    Create a cache control breakpoint at this content block.

                  - `Optional<List<BetaTextCitationParam>> citations`

              - `Optional<Boolean> isError`

            - `class BetaContainerUploadBlockParam:`

              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.

              - `String fileId`

              - `JsonValue; type "container_upload"constant`

                - `CONTAINER_UPLOAD("container_upload")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

            - `class BetaCompactionBlockParam:`

              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.

              - `JsonValue; type "compaction"constant`

                - `COMPACTION("compaction")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

              - `Optional<String> content`

                Summary of previously compacted content, or null if compaction failed

              - `Optional<String> encryptedContent`

                Opaque metadata from prior compaction, to be round-tripped verbatim

            - `class BetaMidConversationSystemBlockParam:`

              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.

              - `List<BetaTextBlockParam> content`

                System instruction text blocks.

                - `String text`

                - `JsonValue; type "text"constant`

                - `Optional<BetaCacheControlEphemeral> cacheControl`

                  Create a cache control breakpoint at this content block.

                - `Optional<List<BetaTextCitationParam>> citations`

              - `JsonValue; type "mid_conv_system"constant`

                - `MID_CONV_SYSTEM("mid_conv_system")`

              - `Optional<BetaCacheControlEphemeral> cacheControl`

                Create a cache control breakpoint at this content block.

            - `class BetaFallbackBlockParam:`

              A `fallback` block echoed back from a prior response.

              Accepted in `messages[].content` and never rendered into the prompt,
              not validated against the request's `fallbacks` chain or top-level
              `model`, and stripped before the sticky-routing cache key is computed.

              Callers should echo the assistant turn verbatim — block included. The
              block's position is load-bearing for thinking verification: the thinking
              runs on either side of a fallback hop carry independently-rooted
              verification hash chains, and this block is the only record of where one
              chain ends and the next begins. When thinking runs flank the boundary,
              omitting the block merges the runs into one contiguous span whose hashes
              cannot verify (the request is rejected), and moving it into the middle of
              a single run splits that run's chain and is likewise rejected; between
              non-thinking blocks the block's placement has no verification effect.

              - `BetaFallbackInfoParam from`

                Identifies one hop of a fallback transition.

                - `Model model`

                  The model that will complete your prompt.

                  See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

                  - `CLAUDE_FABLE_5("claude-fable-5")`

                    Next generation of intelligence for the hardest knowledge work and coding problems

                  - `CLAUDE_MYTHOS_5("claude-mythos-5")`

                    Most capable model for cybersecurity and biology research

                  - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

                    Frontier intelligence for long-running agents and coding

                  - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

                    Frontier intelligence for long-running agents and coding

                  - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

                    New class of intelligence, strongest in coding and cybersecurity

                  - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

                    Frontier intelligence for long-running agents and coding

                  - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

                    Best combination of speed and intelligence

                  - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

                    Fastest model with near-frontier intelligence

                  - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

                    Fastest model with near-frontier intelligence

                  - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

                    Premium model combining maximum intelligence with practical performance

                  - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

                    Premium model combining maximum intelligence with practical performance

                  - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

                    High-performance model for agents and coding

                  - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

                    High-performance model for agents and coding

                  - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

                    Exceptional model for specialized complex tasks

                  - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

                    Exceptional model for specialized complex tasks

                  - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

                    Powerful model for complex tasks

                  - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

                    Powerful model for complex tasks

                  - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

                    High-performance model with extended thinking

                  - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

                    High-performance model with extended thinking

                  - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

                    Fast and cost-effective model

              - `BetaFallbackInfoParam to`

                Identifies one hop of a fallback transition.

              - `JsonValue; type "fallback"constant`

                - `FALLBACK("fallback")`

        - `Role role`

          - `USER("user")`

          - `ASSISTANT("assistant")`

          - `SYSTEM("system")`

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `Optional<BetaCacheControlEphemeral> cacheControl`

        Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

      - `Optional<Container> container`

        Container identifier for reuse across requests.

        - `class BetaContainerParams:`

          Container parameters with skills to be loaded.

          - `Optional<String> id`

            Container id

          - `Optional<List<BetaSkillParams>> skills`

            List of skills to load in the container

            - `String skillId`

              Skill ID

            - `Type type`

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

              - `ANTHROPIC("anthropic")`

              - `CUSTOM("custom")`

            - `Optional<String> version`

              Skill version or 'latest' for most recent version

        - `String`

      - `Optional<BetaContextManagementConfig> contextManagement`

        Context management configuration.

        This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not.

        - `Optional<List<Edit>> edits`

          List of context management edits to apply

          - `class BetaClearToolUses20250919Edit:`

            - `JsonValue; type "clear_tool_uses_20250919"constant`

              - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

            - `Optional<BetaInputTokensClearAtLeast> clearAtLeast`

              Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed.

              - `JsonValue; type "input_tokens"constant`

                - `INPUT_TOKENS("input_tokens")`

              - `long value`

            - `Optional<ClearToolInputs> clearToolInputs`

              Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)

              - `boolean`

              - `List<String>`

            - `Optional<List<String>> excludeTools`

              Tool names whose uses are preserved from clearing

            - `Optional<BetaToolUsesKeep> keep`

              Number of tool uses to retain in the conversation

              - `JsonValue; type "tool_uses"constant`

                - `TOOL_USES("tool_uses")`

              - `long value`

            - `Optional<Trigger> trigger`

              Condition that triggers the context management strategy

              - `class BetaInputTokensTrigger:`

                - `JsonValue; type "input_tokens"constant`

                  - `INPUT_TOKENS("input_tokens")`

                - `long value`

              - `class BetaToolUsesTrigger:`

                - `JsonValue; type "tool_uses"constant`

                  - `TOOL_USES("tool_uses")`

                - `long value`

          - `class BetaClearThinking20251015Edit:`

            - `JsonValue; type "clear_thinking_20251015"constant`

              - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

            - `Optional<Keep> keep`

              Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.

              - `class BetaThinkingTurns:`

                - `JsonValue; type "thinking_turns"constant`

                  - `THINKING_TURNS("thinking_turns")`

                - `long value`

              - `class BetaAllThinkingTurns:`

                - `JsonValue; type "all"constant`

                  - `ALL("all")`

              - `JsonValue;`

                - `ALL("all")`

          - `class BetaCompact20260112Edit:`

            Automatically compact older context when reaching the configured trigger threshold.

            - `JsonValue; type "compact_20260112"constant`

              - `COMPACT_20260112("compact_20260112")`

            - `Optional<String> instructions`

              Additional instructions for summarization.

            - `Optional<Boolean> pauseAfterCompaction`

              Whether to pause after compaction and return the compaction block to the user.

            - `Optional<BetaInputTokensTrigger> trigger`

              When to trigger compaction. Defaults to 150000 input tokens.

      - `Optional<BetaDiagnosticsParam> diagnostics`

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

        - `Optional<String> previousMessageId`

          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.

      - `Optional<String> fallbackCreditToken`

        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.

      - `Optional<List<BetaFallbackParam>> fallbacks`

        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.

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `Optional<Long> maxTokens`

        - `Optional<BetaOutputConfig> outputConfig`

          - `Optional<Effort> effort`

            All possible effort levels.

            - `LOW("low")`

            - `MEDIUM("medium")`

            - `HIGH("high")`

            - `XHIGH("xhigh")`

            - `MAX("max")`

          - `Optional<BetaJsonOutputFormat> format`

            A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

            - `Schema schema`

              The JSON schema of the format

            - `JsonValue; type "json_schema"constant`

              - `JSON_SCHEMA("json_schema")`

          - `Optional<BetaTokenTaskBudget> taskBudget`

            User-configurable total token budget across contexts.

            - `long total`

              Total token budget across all contexts in the session.

            - `JsonValue; type "tokens"constant`

              The budget type. Currently only 'tokens' is supported.

              - `TOKENS("tokens")`

            - `Optional<Long> remaining`

              Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.

        - `Optional<Speed> speed`

          - `STANDARD("standard")`

          - `FAST("fast")`

        - `Optional<Thinking> thinking`

          - `class BetaThinkingConfigEnabled:`

            - `long budgetTokens`

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

              Must be ≥1024 and less than `max_tokens`.

              See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.

            - `JsonValue; type "enabled"constant`

              - `ENABLED("enabled")`

            - `Optional<Display> display`

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

              - `SUMMARIZED("summarized")`

              - `OMITTED("omitted")`

          - `class BetaThinkingConfigDisabled:`

            - `JsonValue; type "disabled"constant`

              - `DISABLED("disabled")`

          - `class BetaThinkingConfigAdaptive:`

            - `JsonValue; type "adaptive"constant`

              - `ADAPTIVE("adaptive")`

            - `Optional<Display> display`

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

              - `SUMMARIZED("summarized")`

              - `OMITTED("omitted")`

      - `Optional<String> inferenceGeo`

        Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.

      - `Optional<List<BetaRequestMcpServerUrlDefinition>> mcpServers`

        MCP servers to be utilized in this request

        - `String name`

        - `JsonValue; type "url"constant`

          - `URL("url")`

        - `String url`

        - `Optional<String> authorizationToken`

        - `Optional<BetaRequestMcpServerToolConfiguration> toolConfiguration`

          - `Optional<List<String>> allowedTools`

          - `Optional<Boolean> enabled`

      - `Optional<BetaMetadata> metadata`

        An object describing metadata about the request.

        - `Optional<String> userId`

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

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

      - `Optional<BetaOutputConfig> outputConfig`

        Configuration options for the model's output, such as the output format.

      - `Optional<BetaJsonOutputFormat> outputFormat`

        Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

        A schema to specify Claude's output format in responses. This parameter will be removed in a future release.

      - `Optional<ServiceTier> serviceTier`

        Determines whether to use priority capacity (if available) or standard capacity for this request.

        Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details.

        - `AUTO("auto")`

        - `STANDARD_ONLY("standard_only")`

      - `Optional<Speed> speed`

        The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference.

        - `STANDARD("standard")`

        - `FAST("fast")`

      - `Optional<List<String>> stopSequences`

        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.

      - `Optional<Boolean> stream`

        Whether to incrementally stream the response using server-sent events.

        See [streaming](https://docs.claude.com/en/api/messages-streaming) for details.

      - `Optional<System> system`

        System prompt.

        A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts).

        - `String`

        - `List<BetaTextBlockParam>`

          - `String text`

          - `JsonValue; type "text"constant`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<List<BetaTextCitationParam>> citations`

      - `Optional<Double> temperature`

        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.

      - `Optional<BetaThinkingConfigParam> thinking`

        Configuration for enabling Claude's extended thinking.

        When enabled, responses include `thinking` content blocks showing Claude'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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.

        - `class BetaThinkingConfigEnabled:`

        - `class BetaThinkingConfigDisabled:`

        - `class BetaThinkingConfigAdaptive:`

      - `Optional<BetaToolChoice> toolChoice`

        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.

        - `class BetaToolChoiceAuto:`

          The model will automatically decide whether to use tools.

          - `JsonValue; type "auto"constant`

            - `AUTO("auto")`

          - `Optional<Boolean> disableParallelToolUse`

            Whether to disable parallel tool use.

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

        - `class BetaToolChoiceAny:`

          The model will use any available tools.

          - `JsonValue; type "any"constant`

            - `ANY("any")`

          - `Optional<Boolean> disableParallelToolUse`

            Whether to disable parallel tool use.

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

        - `class BetaToolChoiceTool:`

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

          - `String name`

            The name of the tool to use.

          - `JsonValue; type "tool"constant`

            - `TOOL("tool")`

          - `Optional<Boolean> disableParallelToolUse`

            Whether to disable parallel tool use.

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

        - `class BetaToolChoiceNone:`

          The model will not be allowed to use tools.

          - `JsonValue; type "none"constant`

            - `NONE("none")`

      - `Optional<List<BetaToolUnion>> tools`

        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](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/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](https://docs.claude.com/en/docs/tool-use) for more details.

        - `class BetaTool:`

          - `InputSchema inputSchema`

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

            - `JsonValue; type "object"constant`

              - `OBJECT("object")`

            - `Optional<Properties> properties`

            - `Optional<List<String>> required`

          - `String name`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<String> 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.

          - `Optional<Boolean> eagerInputStreaming`

            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.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

          - `Optional<Type> type`

            - `CUSTOM("custom")`

        - `class BetaToolBash20241022:`

          - `JsonValue; name "bash"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `BASH("bash")`

          - `JsonValue; type "bash_20241022"constant`

            - `BASH_20241022("bash_20241022")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaToolBash20250124:`

          - `JsonValue; name "bash"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `BASH("bash")`

          - `JsonValue; type "bash_20250124"constant`

            - `BASH_20250124("bash_20250124")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaCodeExecutionTool20250522:`

          - `JsonValue; name "code_execution"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `CODE_EXECUTION("code_execution")`

          - `JsonValue; type "code_execution_20250522"constant`

            - `CODE_EXECUTION_20250522("code_execution_20250522")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaCodeExecutionTool20250825:`

          - `JsonValue; name "code_execution"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `CODE_EXECUTION("code_execution")`

          - `JsonValue; type "code_execution_20250825"constant`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaCodeExecutionTool20260120:`

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

          - `JsonValue; name "code_execution"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `CODE_EXECUTION("code_execution")`

          - `JsonValue; type "code_execution_20260120"constant`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaToolComputerUse20241022:`

          - `long displayHeightPx`

            The height of the display in pixels.

          - `long displayWidthPx`

            The width of the display in pixels.

          - `JsonValue; name "computer"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `COMPUTER("computer")`

          - `JsonValue; type "computer_20241022"constant`

            - `COMPUTER_20241022("computer_20241022")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Long> displayNumber`

            The X11 display number (e.g. 0, 1) for the display.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaMemoryTool20250818:`

          - `JsonValue; name "memory"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `MEMORY("memory")`

          - `JsonValue; type "memory_20250818"constant`

            - `MEMORY_20250818("memory_20250818")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaToolComputerUse20250124:`

          - `long displayHeightPx`

            The height of the display in pixels.

          - `long displayWidthPx`

            The width of the display in pixels.

          - `JsonValue; name "computer"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `COMPUTER("computer")`

          - `JsonValue; type "computer_20250124"constant`

            - `COMPUTER_20250124("computer_20250124")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Long> displayNumber`

            The X11 display number (e.g. 0, 1) for the display.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaToolTextEditor20241022:`

          - `JsonValue; name "str_replace_editor"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `STR_REPLACE_EDITOR("str_replace_editor")`

          - `JsonValue; type "text_editor_20241022"constant`

            - `TEXT_EDITOR_20241022("text_editor_20241022")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaToolComputerUse20251124:`

          - `long displayHeightPx`

            The height of the display in pixels.

          - `long displayWidthPx`

            The width of the display in pixels.

          - `JsonValue; name "computer"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `COMPUTER("computer")`

          - `JsonValue; type "computer_20251124"constant`

            - `COMPUTER_20251124("computer_20251124")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Long> displayNumber`

            The X11 display number (e.g. 0, 1) for the display.

          - `Optional<Boolean> enableZoom`

            Whether to enable an action to take a zoomed-in screenshot of the screen.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaToolTextEditor20250124:`

          - `JsonValue; name "str_replace_editor"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `STR_REPLACE_EDITOR("str_replace_editor")`

          - `JsonValue; type "text_editor_20250124"constant`

            - `TEXT_EDITOR_20250124("text_editor_20250124")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaToolTextEditor20250429:`

          - `JsonValue; name "str_replace_based_edit_tool"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")`

          - `JsonValue; type "text_editor_20250429"constant`

            - `TEXT_EDITOR_20250429("text_editor_20250429")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaToolTextEditor20250728:`

          - `JsonValue; name "str_replace_based_edit_tool"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `STR_REPLACE_BASED_EDIT_TOOL("str_replace_based_edit_tool")`

          - `JsonValue; type "text_editor_20250728"constant`

            - `TEXT_EDITOR_20250728("text_editor_20250728")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<List<InputExample>> inputExamples`

          - `Optional<Long> maxCharacters`

            Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaWebSearchTool20250305:`

          - `JsonValue; name "web_search"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `WEB_SEARCH("web_search")`

          - `JsonValue; type "web_search_20250305"constant`

            - `WEB_SEARCH_20250305("web_search_20250305")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<List<String>> allowedDomains`

            If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.

          - `Optional<List<String>> blockedDomains`

            If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Long> maxUses`

            Maximum number of times the tool can be used in the API request.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

          - `Optional<BetaUserLocation> userLocation`

            Parameters for the user's location. Used to provide more relevant search results.

            - `JsonValue; type "approximate"constant`

              - `APPROXIMATE("approximate")`

            - `Optional<String> city`

              The city of the user.

            - `Optional<String> country`

              The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user.

            - `Optional<String> region`

              The region of the user.

            - `Optional<String> timezone`

              The [IANA timezone](https://nodatime.org/TimeZones) of the user.

        - `class BetaWebFetchTool20250910:`

          - `JsonValue; name "web_fetch"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `WEB_FETCH("web_fetch")`

          - `JsonValue; type "web_fetch_20250910"constant`

            - `WEB_FETCH_20250910("web_fetch_20250910")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<List<String>> allowedDomains`

            List of domains to allow fetching from

          - `Optional<List<String>> blockedDomains`

            List of domains to block fetching from

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<BetaCitationsConfigParam> citations`

            Citations configuration for fetched documents. Citations are disabled by default.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Long> maxContentTokens`

            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.

          - `Optional<Long> maxUses`

            Maximum number of times the tool can be used in the API request.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaWebSearchTool20260209:`

          - `JsonValue; name "web_search"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `WEB_SEARCH("web_search")`

          - `JsonValue; type "web_search_20260209"constant`

            - `WEB_SEARCH_20260209("web_search_20260209")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<List<String>> allowedDomains`

            If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.

          - `Optional<List<String>> blockedDomains`

            If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Long> maxUses`

            Maximum number of times the tool can be used in the API request.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

          - `Optional<BetaUserLocation> userLocation`

            Parameters for the user's location. Used to provide more relevant search results.

        - `class BetaWebFetchTool20260209:`

          - `JsonValue; name "web_fetch"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `WEB_FETCH("web_fetch")`

          - `JsonValue; type "web_fetch_20260209"constant`

            - `WEB_FETCH_20260209("web_fetch_20260209")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<List<String>> allowedDomains`

            List of domains to allow fetching from

          - `Optional<List<String>> blockedDomains`

            List of domains to block fetching from

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<BetaCitationsConfigParam> citations`

            Citations configuration for fetched documents. Citations are disabled by default.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Long> maxContentTokens`

            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.

          - `Optional<Long> maxUses`

            Maximum number of times the tool can be used in the API request.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaWebFetchTool20260309:`

          Web fetch tool with use_cache parameter for bypassing cached content.

          - `JsonValue; name "web_fetch"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `WEB_FETCH("web_fetch")`

          - `JsonValue; type "web_fetch_20260309"constant`

            - `WEB_FETCH_20260309("web_fetch_20260309")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<List<String>> allowedDomains`

            List of domains to allow fetching from

          - `Optional<List<String>> blockedDomains`

            List of domains to block fetching from

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<BetaCitationsConfigParam> citations`

            Citations configuration for fetched documents. Citations are disabled by default.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Long> maxContentTokens`

            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.

          - `Optional<Long> maxUses`

            Maximum number of times the tool can be used in the API request.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

          - `Optional<Boolean> useCache`

            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.

        - `class BetaAdvisorTool20260301:`

          - `Model model`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `JsonValue; name "advisor"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `ADVISOR("advisor")`

          - `JsonValue; type "advisor_20260301"constant`

            - `ADVISOR_20260301("advisor_20260301")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<BetaCacheControlEphemeral> caching`

            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.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Long> maxTokens`

            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.

          - `Optional<Long> maxUses`

            Maximum number of times the tool can be used in the API request.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaToolSearchToolBm25_20251119:`

          - `JsonValue; name "tool_search_tool_bm25"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

          - `Type type`

            - `TOOL_SEARCH_TOOL_BM25_20251119("tool_search_tool_bm25_20251119")`

            - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaToolSearchToolRegex20251119:`

          - `JsonValue; name "tool_search_tool_regex"constant`

            Name of the tool.

            This is how the tool will be called by the model and in `tool_use` blocks.

            - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

          - `Type type`

            - `TOOL_SEARCH_TOOL_REGEX_20251119("tool_search_tool_regex_20251119")`

            - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

          - `Optional<List<AllowedCaller>> allowedCallers`

            - `DIRECT("direct")`

            - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Boolean> deferLoading`

            If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

          - `Optional<Boolean> strict`

            When true, guarantees schema validation on tool names and inputs

        - `class BetaMcpToolset:`

          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.

          - `String mcpServerName`

            Name of the MCP server to configure tools for

          - `JsonValue; type "mcp_toolset"constant`

            - `MCP_TOOLSET("mcp_toolset")`

          - `Optional<BetaCacheControlEphemeral> cacheControl`

            Create a cache control breakpoint at this content block.

          - `Optional<Configs> configs`

            Configuration overrides for specific tools, keyed by tool name

            - `Optional<Boolean> deferLoading`

            - `Optional<Boolean> enabled`

          - `Optional<BetaMcpToolDefaultConfig> defaultConfig`

            Default configuration applied to all tools from this server

            - `Optional<Boolean> deferLoading`

            - `Optional<Boolean> enabled`

      - `Optional<Long> topK`

        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.

      - `Optional<Double> topP`

        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.

      - `Optional<String> userProfileId`

        The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization.

### Returns

- `class BetaMessageBatch:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `Optional<LocalDateTime> archivedAt`

    RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

  - `Optional<LocalDateTime> cancelInitiatedAt`

    RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing the time at which the Message Batch was created.

  - `Optional<LocalDateTime> endedAt`

    RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

    Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

  - `LocalDateTime expiresAt`

    RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.

  - `ProcessingStatus processingStatus`

    Processing status of the Message Batch.

    - `IN_PROGRESS("in_progress")`

    - `CANCELING("canceling")`

    - `ENDED("ended")`

  - `BetaMessageBatchRequestCounts requestCounts`

    Tallies requests within the Message Batch, categorized by their status.

    Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.

    - `long canceled`

      Number of requests in the Message Batch that have been canceled.

      This is zero until processing of the entire Message Batch has ended.

    - `long errored`

      Number of requests in the Message Batch that encountered an error.

      This is zero until processing of the entire Message Batch has ended.

    - `long expired`

      Number of requests in the Message Batch that have expired.

      This is zero until processing of the entire Message Batch has ended.

    - `long processing`

      Number of requests in the Message Batch that are processing.

    - `long succeeded`

      Number of requests in the Message Batch that have completed successfully.

      This is zero until processing of the entire Message Batch has ended.

  - `Optional<String> resultsUrl`

    URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.

    Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.

  - `JsonValue; type "message_batch"constant`

    Object type.

    For Message Batches, this is always `"message_batch"`.

    - `MESSAGE_BATCH("message_batch")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.batches.BatchCreateParams;
import com.anthropic.models.beta.messages.batches.BetaMessageBatch;
import com.anthropic.models.messages.Model;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BatchCreateParams params = BatchCreateParams.builder()
            .addRequest(BatchCreateParams.Request.builder()
                .customId("my-custom-id-1")
                .params(BatchCreateParams.Request.Params.builder()
                    .maxTokens(1024L)
                    .addUserMessage("Hello, world")
                    .model(Model.CLAUDE_OPUS_4_6)
                    .build())
                .build())
            .build();
        BetaMessageBatch betaMessageBatch = client.beta().messages().batches().create(params);
    }
}
```

#### Response

```json
{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "archived_at": "2024-08-20T18:37:24.100435Z",
  "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
  "created_at": "2024-08-20T18:37:24.100435Z",
  "ended_at": "2024-08-20T18:37:24.100435Z",
  "expires_at": "2024-08-20T18:37:24.100435Z",
  "processing_status": "in_progress",
  "request_counts": {
    "canceled": 10,
    "errored": 30,
    "expired": 10,
    "processing": 100,
    "succeeded": 50
  },
  "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
  "type": "message_batch"
}
```

## Retrieve a Message Batch

`BetaMessageBatch beta().messages().batches().retrieve(BatchRetrieveParamsparams = BatchRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/messages/batches/{message_batch_id}`

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

Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)

### Parameters

- `BatchRetrieveParams params`

  - `Optional<String> messageBatchId`

    ID of the Message Batch.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaMessageBatch:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `Optional<LocalDateTime> archivedAt`

    RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

  - `Optional<LocalDateTime> cancelInitiatedAt`

    RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing the time at which the Message Batch was created.

  - `Optional<LocalDateTime> endedAt`

    RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

    Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

  - `LocalDateTime expiresAt`

    RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.

  - `ProcessingStatus processingStatus`

    Processing status of the Message Batch.

    - `IN_PROGRESS("in_progress")`

    - `CANCELING("canceling")`

    - `ENDED("ended")`

  - `BetaMessageBatchRequestCounts requestCounts`

    Tallies requests within the Message Batch, categorized by their status.

    Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.

    - `long canceled`

      Number of requests in the Message Batch that have been canceled.

      This is zero until processing of the entire Message Batch has ended.

    - `long errored`

      Number of requests in the Message Batch that encountered an error.

      This is zero until processing of the entire Message Batch has ended.

    - `long expired`

      Number of requests in the Message Batch that have expired.

      This is zero until processing of the entire Message Batch has ended.

    - `long processing`

      Number of requests in the Message Batch that are processing.

    - `long succeeded`

      Number of requests in the Message Batch that have completed successfully.

      This is zero until processing of the entire Message Batch has ended.

  - `Optional<String> resultsUrl`

    URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.

    Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.

  - `JsonValue; type "message_batch"constant`

    Object type.

    For Message Batches, this is always `"message_batch"`.

    - `MESSAGE_BATCH("message_batch")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.batches.BatchRetrieveParams;
import com.anthropic.models.beta.messages.batches.BetaMessageBatch;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaMessageBatch betaMessageBatch = client.beta().messages().batches().retrieve("message_batch_id");
    }
}
```

#### Response

```json
{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "archived_at": "2024-08-20T18:37:24.100435Z",
  "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
  "created_at": "2024-08-20T18:37:24.100435Z",
  "ended_at": "2024-08-20T18:37:24.100435Z",
  "expires_at": "2024-08-20T18:37:24.100435Z",
  "processing_status": "in_progress",
  "request_counts": {
    "canceled": 10,
    "errored": 30,
    "expired": 10,
    "processing": 100,
    "succeeded": 50
  },
  "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
  "type": "message_batch"
}
```

## List Message Batches

`BatchListPage beta().messages().batches().list(BatchListParamsparams = BatchListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/messages/batches`

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

Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)

### Parameters

- `BatchListParams params`

  - `Optional<String> afterId`

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

  - `Optional<String> beforeId`

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

  - `Optional<Long> limit`

    Number of items to return per page.

    Defaults to `20`. Ranges from `1` to `1000`.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaMessageBatch:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `Optional<LocalDateTime> archivedAt`

    RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

  - `Optional<LocalDateTime> cancelInitiatedAt`

    RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing the time at which the Message Batch was created.

  - `Optional<LocalDateTime> endedAt`

    RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

    Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

  - `LocalDateTime expiresAt`

    RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.

  - `ProcessingStatus processingStatus`

    Processing status of the Message Batch.

    - `IN_PROGRESS("in_progress")`

    - `CANCELING("canceling")`

    - `ENDED("ended")`

  - `BetaMessageBatchRequestCounts requestCounts`

    Tallies requests within the Message Batch, categorized by their status.

    Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.

    - `long canceled`

      Number of requests in the Message Batch that have been canceled.

      This is zero until processing of the entire Message Batch has ended.

    - `long errored`

      Number of requests in the Message Batch that encountered an error.

      This is zero until processing of the entire Message Batch has ended.

    - `long expired`

      Number of requests in the Message Batch that have expired.

      This is zero until processing of the entire Message Batch has ended.

    - `long processing`

      Number of requests in the Message Batch that are processing.

    - `long succeeded`

      Number of requests in the Message Batch that have completed successfully.

      This is zero until processing of the entire Message Batch has ended.

  - `Optional<String> resultsUrl`

    URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.

    Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.

  - `JsonValue; type "message_batch"constant`

    Object type.

    For Message Batches, this is always `"message_batch"`.

    - `MESSAGE_BATCH("message_batch")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.batches.BatchListPage;
import com.anthropic.models.beta.messages.batches.BatchListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BatchListPage page = client.beta().messages().batches().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
      "archived_at": "2024-08-20T18:37:24.100435Z",
      "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
      "created_at": "2024-08-20T18:37:24.100435Z",
      "ended_at": "2024-08-20T18:37:24.100435Z",
      "expires_at": "2024-08-20T18:37:24.100435Z",
      "processing_status": "in_progress",
      "request_counts": {
        "canceled": 10,
        "errored": 30,
        "expired": 10,
        "processing": 100,
        "succeeded": 50
      },
      "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
      "type": "message_batch"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id"
}
```

## Cancel a Message Batch

`BetaMessageBatch beta().messages().batches().cancel(BatchCancelParamsparams = BatchCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/messages/batches/{message_batch_id}/cancel`

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

The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible.

Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)

### Parameters

- `BatchCancelParams params`

  - `Optional<String> messageBatchId`

    ID of the Message Batch.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaMessageBatch:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `Optional<LocalDateTime> archivedAt`

    RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

  - `Optional<LocalDateTime> cancelInitiatedAt`

    RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing the time at which the Message Batch was created.

  - `Optional<LocalDateTime> endedAt`

    RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

    Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

  - `LocalDateTime expiresAt`

    RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.

  - `ProcessingStatus processingStatus`

    Processing status of the Message Batch.

    - `IN_PROGRESS("in_progress")`

    - `CANCELING("canceling")`

    - `ENDED("ended")`

  - `BetaMessageBatchRequestCounts requestCounts`

    Tallies requests within the Message Batch, categorized by their status.

    Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.

    - `long canceled`

      Number of requests in the Message Batch that have been canceled.

      This is zero until processing of the entire Message Batch has ended.

    - `long errored`

      Number of requests in the Message Batch that encountered an error.

      This is zero until processing of the entire Message Batch has ended.

    - `long expired`

      Number of requests in the Message Batch that have expired.

      This is zero until processing of the entire Message Batch has ended.

    - `long processing`

      Number of requests in the Message Batch that are processing.

    - `long succeeded`

      Number of requests in the Message Batch that have completed successfully.

      This is zero until processing of the entire Message Batch has ended.

  - `Optional<String> resultsUrl`

    URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.

    Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.

  - `JsonValue; type "message_batch"constant`

    Object type.

    For Message Batches, this is always `"message_batch"`.

    - `MESSAGE_BATCH("message_batch")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.batches.BatchCancelParams;
import com.anthropic.models.beta.messages.batches.BetaMessageBatch;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaMessageBatch betaMessageBatch = client.beta().messages().batches().cancel("message_batch_id");
    }
}
```

#### Response

```json
{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "archived_at": "2024-08-20T18:37:24.100435Z",
  "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
  "created_at": "2024-08-20T18:37:24.100435Z",
  "ended_at": "2024-08-20T18:37:24.100435Z",
  "expires_at": "2024-08-20T18:37:24.100435Z",
  "processing_status": "in_progress",
  "request_counts": {
    "canceled": 10,
    "errored": 30,
    "expired": 10,
    "processing": 100,
    "succeeded": 50
  },
  "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
  "type": "message_batch"
}
```

## Delete a Message Batch

`BetaDeletedMessageBatch beta().messages().batches().delete(BatchDeleteParamsparams = BatchDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/messages/batches/{message_batch_id}`

Delete a Message Batch.

Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it.

Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)

### Parameters

- `BatchDeleteParams params`

  - `Optional<String> messageBatchId`

    ID of the Message Batch.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaDeletedMessageBatch:`

  - `String id`

    ID of the Message Batch.

  - `JsonValue; type "message_batch_deleted"constant`

    Deleted object type.

    For Message Batches, this is always `"message_batch_deleted"`.

    - `MESSAGE_BATCH_DELETED("message_batch_deleted")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.batches.BatchDeleteParams;
import com.anthropic.models.beta.messages.batches.BetaDeletedMessageBatch;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaDeletedMessageBatch betaDeletedMessageBatch = client.beta().messages().batches().delete("message_batch_id");
    }
}
```

#### Response

```json
{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch_deleted"
}
```

## Retrieve Message Batch results

`BetaMessageBatchIndividualResponse beta().messages().batches().resultsStreaming(BatchResultsParamsparams = BatchResultsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/messages/batches/{message_batch_id}/results`

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

Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.

Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)

### Parameters

- `BatchResultsParams params`

  - `Optional<String> messageBatchId`

    ID of the Message Batch.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaMessageBatchIndividualResponse:`

  This is a single line in the response `.jsonl` file and does not represent the response as a whole.

  - `String customId`

    Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.

    Must be unique for each request within the Message Batch.

  - `BetaMessageBatchResult result`

    Processing result for this request.

    Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.

    - `class BetaMessageBatchSucceededResult:`

      - `BetaMessage message`

        - `String id`

          Unique object identifier.

          The format and length of IDs may change over time.

        - `Optional<BetaContainer> container`

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

          - `String id`

            Identifier for the container used in this request

          - `LocalDateTime expiresAt`

            The time at which the container will expire.

          - `Optional<List<BetaSkill>> skills`

            Skills loaded in the container

            - `String skillId`

              Skill ID

            - `Type type`

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

              - `ANTHROPIC("anthropic")`

              - `CUSTOM("custom")`

            - `String version`

              Skill version or 'latest' for most recent version

        - `List<BetaContentBlock> content`

          Content generated by the model.

          This is an array of content blocks, each of which has a `type` that determines its shape.

          Example:

          ```json
          [{"type": "text", "text": "Hi, I'm Claude."}]
          ```

          If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.

          For example, if the input `messages` were:

          ```json
          [
            {"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)"}]
          ```

          - `class BetaTextBlock:`

            - `Optional<List<BetaTextCitation>> citations`

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

              - `class BetaCitationCharLocation:`

                - `String citedText`

                - `long documentIndex`

                - `Optional<String> documentTitle`

                - `long endCharIndex`

                - `Optional<String> fileId`

                - `long startCharIndex`

                - `JsonValue; type "char_location"constant`

                  - `CHAR_LOCATION("char_location")`

              - `class BetaCitationPageLocation:`

                - `String citedText`

                - `long documentIndex`

                - `Optional<String> documentTitle`

                - `long endPageNumber`

                - `Optional<String> fileId`

                - `long startPageNumber`

                - `JsonValue; type "page_location"constant`

                  - `PAGE_LOCATION("page_location")`

              - `class BetaCitationContentBlockLocation:`

                - `String citedText`

                  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.

                - `long documentIndex`

                - `Optional<String> documentTitle`

                - `long endBlockIndex`

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

                - `Optional<String> fileId`

                - `long startBlockIndex`

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

                - `JsonValue; type "content_block_location"constant`

                  - `CONTENT_BLOCK_LOCATION("content_block_location")`

              - `class BetaCitationsWebSearchResultLocation:`

                - `String citedText`

                - `String encryptedIndex`

                - `Optional<String> title`

                - `JsonValue; type "web_search_result_location"constant`

                  - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

                - `String url`

              - `class BetaCitationSearchResultLocation:`

                - `String citedText`

                  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.

                - `long endBlockIndex`

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

                - `long searchResultIndex`

                  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.

                - `String source`

                - `long startBlockIndex`

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

                - `Optional<String> title`

                - `JsonValue; type "search_result_location"constant`

                  - `SEARCH_RESULT_LOCATION("search_result_location")`

            - `String text`

            - `JsonValue; type "text"constant`

              - `TEXT("text")`

          - `class BetaThinkingBlock:`

            - `String signature`

            - `String thinking`

            - `JsonValue; type "thinking"constant`

              - `THINKING("thinking")`

          - `class BetaRedactedThinkingBlock:`

            - `String data`

            - `JsonValue; type "redacted_thinking"constant`

              - `REDACTED_THINKING("redacted_thinking")`

          - `class BetaToolUseBlock:`

            - `String id`

            - `Input input`

            - `String name`

            - `JsonValue; type "tool_use"constant`

              - `TOOL_USE("tool_use")`

            - `Optional<Caller> caller`

              Tool invocation directly from the model.

              - `class BetaDirectCaller:`

                Tool invocation directly from the model.

                - `JsonValue; type "direct"constant`

                  - `DIRECT("direct")`

              - `class BetaServerToolCaller:`

                Tool invocation generated by a server-side tool.

                - `String toolId`

                - `JsonValue; type "code_execution_20250825"constant`

                  - `CODE_EXECUTION_20250825("code_execution_20250825")`

              - `class BetaServerToolCaller20260120:`

                - `String toolId`

                - `JsonValue; type "code_execution_20260120"constant`

                  - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `class BetaServerToolUseBlock:`

            - `String id`

            - `Input input`

            - `Name name`

              - `ADVISOR("advisor")`

              - `WEB_SEARCH("web_search")`

              - `WEB_FETCH("web_fetch")`

              - `CODE_EXECUTION("code_execution")`

              - `BASH_CODE_EXECUTION("bash_code_execution")`

              - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

              - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

              - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

            - `JsonValue; type "server_tool_use"constant`

              - `SERVER_TOOL_USE("server_tool_use")`

            - `Optional<Caller> caller`

              Tool invocation directly from the model.

              - `class BetaDirectCaller:`

                Tool invocation directly from the model.

              - `class BetaServerToolCaller:`

                Tool invocation generated by a server-side tool.

              - `class BetaServerToolCaller20260120:`

          - `class BetaWebSearchToolResultBlock:`

            - `BetaWebSearchToolResultBlockContent content`

              - `class BetaWebSearchToolResultError:`

                - `BetaWebSearchToolResultErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `UNAVAILABLE("unavailable")`

                  - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `QUERY_TOO_LONG("query_too_long")`

                  - `REQUEST_TOO_LARGE("request_too_large")`

                - `JsonValue; type "web_search_tool_result_error"constant`

                  - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

              - `List<BetaWebSearchResultBlock>`

                - `String encryptedContent`

                - `Optional<String> pageAge`

                - `String title`

                - `JsonValue; type "web_search_result"constant`

                  - `WEB_SEARCH_RESULT("web_search_result")`

                - `String url`

            - `String toolUseId`

            - `JsonValue; type "web_search_tool_result"constant`

              - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

            - `Optional<Caller> caller`

              Tool invocation directly from the model.

              - `class BetaDirectCaller:`

                Tool invocation directly from the model.

              - `class BetaServerToolCaller:`

                Tool invocation generated by a server-side tool.

              - `class BetaServerToolCaller20260120:`

          - `class BetaWebFetchToolResultBlock:`

            - `Content content`

              - `class BetaWebFetchToolResultErrorBlock:`

                - `BetaWebFetchToolResultErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `URL_TOO_LONG("url_too_long")`

                  - `URL_NOT_ALLOWED("url_not_allowed")`

                  - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

                  - `URL_NOT_ACCESSIBLE("url_not_accessible")`

                  - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                  - `UNAVAILABLE("unavailable")`

                - `JsonValue; type "web_fetch_tool_result_error"constant`

                  - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

              - `class BetaWebFetchBlock:`

                - `BetaDocumentBlock content`

                  - `Optional<BetaCitationConfig> citations`

                    Citation configuration for the document

                    - `boolean enabled`

                  - `Source source`

                    - `class BetaBase64PdfSource:`

                      - `String data`

                      - `JsonValue; mediaType "application/pdf"constant`

                        - `APPLICATION_PDF("application/pdf")`

                      - `JsonValue; type "base64"constant`

                        - `BASE64("base64")`

                    - `class BetaPlainTextSource:`

                      - `String data`

                      - `JsonValue; mediaType "text/plain"constant`

                        - `TEXT_PLAIN("text/plain")`

                      - `JsonValue; type "text"constant`

                        - `TEXT("text")`

                  - `Optional<String> title`

                    The title of the document

                  - `JsonValue; type "document"constant`

                    - `DOCUMENT("document")`

                - `Optional<String> retrievedAt`

                  ISO 8601 timestamp when the content was retrieved

                - `JsonValue; type "web_fetch_result"constant`

                  - `WEB_FETCH_RESULT("web_fetch_result")`

                - `String url`

                  Fetched content URL

            - `String toolUseId`

            - `JsonValue; type "web_fetch_tool_result"constant`

              - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

            - `Optional<Caller> caller`

              Tool invocation directly from the model.

              - `class BetaDirectCaller:`

                Tool invocation directly from the model.

              - `class BetaServerToolCaller:`

                Tool invocation generated by a server-side tool.

              - `class BetaServerToolCaller20260120:`

          - `class BetaAdvisorToolResultBlock:`

            - `Content content`

              - `class BetaAdvisorToolResultError:`

                - `ErrorCode errorCode`

                  - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                  - `PROMPT_TOO_LONG("prompt_too_long")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `OVERLOADED("overloaded")`

                  - `UNAVAILABLE("unavailable")`

                  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                  - `MODEL_NOT_FOUND("model_not_found")`

                - `JsonValue; type "advisor_tool_result_error"constant`

                  - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

              - `class BetaAdvisorResultBlock:`

                - `Optional<String> stopReason`

                  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.

                - `String text`

                - `JsonValue; type "advisor_result"constant`

                  - `ADVISOR_RESULT("advisor_result")`

              - `class BetaAdvisorRedactedResultBlock:`

                - `String encryptedContent`

                  Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

                - `Optional<String> stopReason`

                  The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

                - `JsonValue; type "advisor_redacted_result"constant`

                  - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

            - `String toolUseId`

            - `JsonValue; type "advisor_tool_result"constant`

              - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

          - `class BetaCodeExecutionToolResultBlock:`

            - `BetaCodeExecutionToolResultBlockContent content`

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

              - `class BetaCodeExecutionToolResultError:`

                - `BetaCodeExecutionToolResultErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `UNAVAILABLE("unavailable")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `JsonValue; type "code_execution_tool_result_error"constant`

                  - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

              - `class BetaCodeExecutionResultBlock:`

                - `List<BetaCodeExecutionOutputBlock> content`

                  - `String fileId`

                  - `JsonValue; type "code_execution_output"constant`

                    - `CODE_EXECUTION_OUTPUT("code_execution_output")`

                - `long returnCode`

                - `String stderr`

                - `String stdout`

                - `JsonValue; type "code_execution_result"constant`

                  - `CODE_EXECUTION_RESULT("code_execution_result")`

              - `class BetaEncryptedCodeExecutionResultBlock:`

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

                - `List<BetaCodeExecutionOutputBlock> content`

                  - `String fileId`

                  - `JsonValue; type "code_execution_output"constant`

                - `String encryptedStdout`

                - `long returnCode`

                - `String stderr`

                - `JsonValue; type "encrypted_code_execution_result"constant`

                  - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

            - `String toolUseId`

            - `JsonValue; type "code_execution_tool_result"constant`

              - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

          - `class BetaBashCodeExecutionToolResultBlock:`

            - `Content content`

              - `class BetaBashCodeExecutionToolResultError:`

                - `ErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `UNAVAILABLE("unavailable")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                  - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

                - `JsonValue; type "bash_code_execution_tool_result_error"constant`

                  - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

              - `class BetaBashCodeExecutionResultBlock:`

                - `List<BetaBashCodeExecutionOutputBlock> content`

                  - `String fileId`

                  - `JsonValue; type "bash_code_execution_output"constant`

                    - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

                - `long returnCode`

                - `String stderr`

                - `String stdout`

                - `JsonValue; type "bash_code_execution_result"constant`

                  - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

            - `String toolUseId`

            - `JsonValue; type "bash_code_execution_tool_result"constant`

              - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

          - `class BetaTextEditorCodeExecutionToolResultBlock:`

            - `Content content`

              - `class BetaTextEditorCodeExecutionToolResultError:`

                - `ErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `UNAVAILABLE("unavailable")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                  - `FILE_NOT_FOUND("file_not_found")`

                - `Optional<String> errorMessage`

                - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

                  - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

              - `class BetaTextEditorCodeExecutionViewResultBlock:`

                - `String content`

                - `FileType fileType`

                  - `TEXT("text")`

                  - `IMAGE("image")`

                  - `PDF("pdf")`

                - `Optional<Long> numLines`

                - `Optional<Long> startLine`

                - `Optional<Long> totalLines`

                - `JsonValue; type "text_editor_code_execution_view_result"constant`

                  - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

              - `class BetaTextEditorCodeExecutionCreateResultBlock:`

                - `boolean isFileUpdate`

                - `JsonValue; type "text_editor_code_execution_create_result"constant`

                  - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

              - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

                - `Optional<List<String>> lines`

                - `Optional<Long> newLines`

                - `Optional<Long> newStart`

                - `Optional<Long> oldLines`

                - `Optional<Long> oldStart`

                - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

                  - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

            - `String toolUseId`

            - `JsonValue; type "text_editor_code_execution_tool_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

          - `class BetaToolSearchToolResultBlock:`

            - `Content content`

              - `class BetaToolSearchToolResultError:`

                - `ErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `UNAVAILABLE("unavailable")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `Optional<String> errorMessage`

                - `JsonValue; type "tool_search_tool_result_error"constant`

                  - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

              - `class BetaToolSearchToolSearchResultBlock:`

                - `List<BetaToolReferenceBlock> toolReferences`

                  - `String toolName`

                  - `JsonValue; type "tool_reference"constant`

                    - `TOOL_REFERENCE("tool_reference")`

                - `JsonValue; type "tool_search_tool_search_result"constant`

                  - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

            - `String toolUseId`

            - `JsonValue; type "tool_search_tool_result"constant`

              - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

          - `class BetaMcpToolUseBlock:`

            - `String id`

            - `Input input`

            - `String name`

              The name of the MCP tool

            - `String serverName`

              The name of the MCP server

            - `JsonValue; type "mcp_tool_use"constant`

              - `MCP_TOOL_USE("mcp_tool_use")`

          - `class BetaMcpToolResultBlock:`

            - `Content content`

              - `String`

              - `List<BetaTextBlock>`

                - `Optional<List<BetaTextCitation>> citations`

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

                - `String text`

                - `JsonValue; type "text"constant`

            - `boolean isError`

            - `String toolUseId`

            - `JsonValue; type "mcp_tool_result"constant`

              - `MCP_TOOL_RESULT("mcp_tool_result")`

          - `class BetaContainerUploadBlock:`

            Response model for a file uploaded to the container.

            - `String fileId`

            - `JsonValue; type "container_upload"constant`

              - `CONTAINER_UPLOAD("container_upload")`

          - `class BetaCompactionBlock:`

            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.

            - `Optional<String> content`

              Summary of compacted content, or null if compaction failed

            - `Optional<String> encryptedContent`

              Opaque metadata from prior compaction, to be round-tripped verbatim

            - `JsonValue; type "compaction"constant`

              - `COMPACTION("compaction")`

          - `class BetaFallbackBlock:`

            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 routed directly by the sticky decision 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.

            - `BetaFallbackInfo from`

              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.

              - `Model model`

                The model that will complete your prompt.

                See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

                - `CLAUDE_FABLE_5("claude-fable-5")`

                  Next generation of intelligence for the hardest knowledge work and coding problems

                - `CLAUDE_MYTHOS_5("claude-mythos-5")`

                  Most capable model for cybersecurity and biology research

                - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

                  Frontier intelligence for long-running agents and coding

                - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

                  Frontier intelligence for long-running agents and coding

                - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

                  New class of intelligence, strongest in coding and cybersecurity

                - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

                  Frontier intelligence for long-running agents and coding

                - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

                  Best combination of speed and intelligence

                - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

                  Fastest model with near-frontier intelligence

                - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

                  Fastest model with near-frontier intelligence

                - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

                  Premium model combining maximum intelligence with practical performance

                - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

                  Premium model combining maximum intelligence with practical performance

                - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

                  High-performance model for agents and coding

                - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

                  High-performance model for agents and coding

                - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

                  Exceptional model for specialized complex tasks

                - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

                  Exceptional model for specialized complex tasks

                - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

                  Powerful model for complex tasks

                - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

                  Powerful model for complex tasks

                - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

                  High-performance model with extended thinking

                - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

                  High-performance model with extended thinking

                - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

                  Fast and cost-effective model

            - `BetaFallbackInfo to`

              The fallback model producing the content that follows this block. Its `model` is always the canonical id.

            - `JsonValue; type "fallback"constant`

              - `FALLBACK("fallback")`

        - `Optional<BetaContextManagementResponse> contextManagement`

          Context management response.

          Information about context management strategies applied during the request.

          - `List<AppliedEdit> appliedEdits`

            List of context management edits that were applied.

            - `class BetaClearToolUses20250919EditResponse:`

              - `long clearedInputTokens`

                Number of input tokens cleared by this edit.

              - `long clearedToolUses`

                Number of tool uses that were cleared.

              - `JsonValue; type "clear_tool_uses_20250919"constant`

                The type of context management edit applied.

                - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

            - `class BetaClearThinking20251015EditResponse:`

              - `long clearedInputTokens`

                Number of input tokens cleared by this edit.

              - `long clearedThinkingTurns`

                Number of thinking turns that were cleared.

              - `JsonValue; type "clear_thinking_20251015"constant`

                The type of context management edit applied.

                - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

        - `Optional<BetaDiagnostics> diagnostics`

          Response envelope for request-level diagnostics. Present (possibly
          null) whenever the caller supplied `diagnostics` on the request.

          - `Optional<CacheMissReason> cacheMissReason`

            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.

            - `class BetaCacheMissModelChanged:`

              - `long cacheMissedInputTokens`

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

              - `JsonValue; type "model_changed"constant`

                - `MODEL_CHANGED("model_changed")`

            - `class BetaCacheMissSystemChanged:`

              - `long cacheMissedInputTokens`

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

              - `JsonValue; type "system_changed"constant`

                - `SYSTEM_CHANGED("system_changed")`

            - `class BetaCacheMissToolsChanged:`

              - `long cacheMissedInputTokens`

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

              - `JsonValue; type "tools_changed"constant`

                - `TOOLS_CHANGED("tools_changed")`

            - `class BetaCacheMissMessagesChanged:`

              - `long cacheMissedInputTokens`

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

              - `JsonValue; type "messages_changed"constant`

                - `MESSAGES_CHANGED("messages_changed")`

            - `class BetaCacheMissPreviousMessageNotFound:`

              - `JsonValue; type "previous_message_not_found"constant`

                - `PREVIOUS_MESSAGE_NOT_FOUND("previous_message_not_found")`

            - `class BetaCacheMissUnavailable:`

              - `JsonValue; type "unavailable"constant`

                - `UNAVAILABLE("unavailable")`

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `JsonValue; role "assistant"constant`

          Conversational role of the generated message.

          This will always be `"assistant"`.

          - `ASSISTANT("assistant")`

        - `Optional<BetaRefusalStopDetails> stopDetails`

          Structured information about a refusal.

          - `Optional<Category> category`

            The policy category that triggered the refusal.

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

            - `CYBER("cyber")`

            - `BIO("bio")`

            - `REASONING_EXTRACTION("reasoning_extraction")`

          - `Optional<String> explanation`

            Human-readable explanation of the refusal.

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

          - `Optional<String> fallbackCreditToken`

            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.

          - `Optional<Boolean> fallbackHasPrefillClaim`

            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.

          - `Optional<String> recommendedModel`

            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.

          - `JsonValue; type "refusal"constant`

            - `REFUSAL("refusal")`

        - `Optional<BetaStopReason> stopReason`

          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

          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.

          - `END_TURN("end_turn")`

          - `MAX_TOKENS("max_tokens")`

          - `STOP_SEQUENCE("stop_sequence")`

          - `TOOL_USE("tool_use")`

          - `PAUSE_TURN("pause_turn")`

          - `COMPACTION("compaction")`

          - `REFUSAL("refusal")`

          - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")`

        - `Optional<String> stopSequence`

          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.

        - `JsonValue; type "message"constant`

          Object type.

          For Messages, this is always `"message"`.

          - `MESSAGE("message")`

        - `BetaUsage usage`

          Billing and rate-limit usage.

          Anthropic'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 Claude.

          Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.

          - `Optional<BetaCacheCreation> cacheCreation`

            Breakdown of cached tokens by TTL

            - `long ephemeral1hInputTokens`

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

            - `long ephemeral5mInputTokens`

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

          - `Optional<Long> cacheCreationInputTokens`

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

          - `Optional<Long> cacheReadInputTokens`

            The number of input tokens read from the cache.

          - `Optional<String> inferenceGeo`

            The geographic region where inference was performed for this request.

          - `long inputTokens`

            The number of input tokens which were used.

          - `Optional<List<BetaIterationsUsageItems>> iterations`

            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

            - `class BetaMessageIterationUsage:`

              Token usage for a sampling iteration.

              - `Optional<BetaCacheCreation> cacheCreation`

                Breakdown of cached tokens by TTL

              - `long cacheCreationInputTokens`

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

              - `long cacheReadInputTokens`

                The number of input tokens read from the cache.

              - `long inputTokens`

                The number of input tokens which were used.

              - `Model model`

                The model that will complete your prompt.

                See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

              - `long outputTokens`

                The number of output tokens which were used.

              - `JsonValue; type "message"constant`

                Usage for a sampling iteration

                - `MESSAGE("message")`

            - `class BetaCompactionIterationUsage:`

              Token usage for a compaction iteration.

              - `Optional<BetaCacheCreation> cacheCreation`

                Breakdown of cached tokens by TTL

              - `long cacheCreationInputTokens`

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

              - `long cacheReadInputTokens`

                The number of input tokens read from the cache.

              - `long inputTokens`

                The number of input tokens which were used.

              - `long outputTokens`

                The number of output tokens which were used.

              - `JsonValue; type "compaction"constant`

                Usage for a compaction iteration

                - `COMPACTION("compaction")`

            - `class BetaAdvisorMessageIterationUsage:`

              Token usage for an advisor sub-inference iteration.

              - `Optional<BetaCacheCreation> cacheCreation`

                Breakdown of cached tokens by TTL

              - `long cacheCreationInputTokens`

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

              - `long cacheReadInputTokens`

                The number of input tokens read from the cache.

              - `long inputTokens`

                The number of input tokens which were used.

              - `Model model`

                The model that will complete your prompt.

                See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

              - `long outputTokens`

                The number of output tokens which were used.

              - `JsonValue; type "advisor_message"constant`

                Usage for an advisor sub-inference iteration

                - `ADVISOR_MESSAGE("advisor_message")`

            - `class BetaFallbackMessageIterationUsage:`

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

              - `Optional<BetaCacheCreation> cacheCreation`

                Breakdown of cached tokens by TTL

              - `long cacheCreationInputTokens`

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

              - `long cacheReadInputTokens`

                The number of input tokens read from the cache.

              - `long inputTokens`

                The number of input tokens which were used.

              - `Model model`

                The model that will complete your prompt.

                See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

              - `long outputTokens`

                The number of output tokens which were used.

              - `JsonValue; type "fallback_message"constant`

                Usage for the fallback-model attempt that served the response

                - `FALLBACK_MESSAGE("fallback_message")`

          - `long outputTokens`

            The number of output tokens which were used.

          - `Optional<BetaOutputTokensDetails> outputTokensDetails`

            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.

            - `long thinkingTokens`

              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.

          - `Optional<BetaServerToolUsage> serverToolUse`

            The number of server tool requests.

            - `long webFetchRequests`

              The number of web fetch tool requests.

            - `long webSearchRequests`

              The number of web search tool requests.

          - `Optional<ServiceTier> serviceTier`

            If the request used the priority, standard, or batch tier.

            - `STANDARD("standard")`

            - `PRIORITY("priority")`

            - `BATCH("batch")`

          - `Optional<Speed> speed`

            The inference speed mode used for this request.

            - `STANDARD("standard")`

            - `FAST("fast")`

      - `JsonValue; type "succeeded"constant`

        - `SUCCEEDED("succeeded")`

    - `class BetaMessageBatchErroredResult:`

      - `BetaErrorResponse error`

        - `BetaError error`

          - `class BetaInvalidRequestError:`

            - `String message`

            - `JsonValue; type "invalid_request_error"constant`

              - `INVALID_REQUEST_ERROR("invalid_request_error")`

          - `class BetaAuthenticationError:`

            - `String message`

            - `JsonValue; type "authentication_error"constant`

              - `AUTHENTICATION_ERROR("authentication_error")`

          - `class BetaBillingError:`

            - `String message`

            - `JsonValue; type "billing_error"constant`

              - `BILLING_ERROR("billing_error")`

          - `class BetaPermissionError:`

            - `String message`

            - `JsonValue; type "permission_error"constant`

              - `PERMISSION_ERROR("permission_error")`

          - `class BetaNotFoundError:`

            - `String message`

            - `JsonValue; type "not_found_error"constant`

              - `NOT_FOUND_ERROR("not_found_error")`

          - `class BetaRateLimitError:`

            - `String message`

            - `JsonValue; type "rate_limit_error"constant`

              - `RATE_LIMIT_ERROR("rate_limit_error")`

          - `class BetaGatewayTimeoutError:`

            - `String message`

            - `JsonValue; type "timeout_error"constant`

              - `TIMEOUT_ERROR("timeout_error")`

          - `class BetaApiError:`

            - `String message`

            - `JsonValue; type "api_error"constant`

              - `API_ERROR("api_error")`

          - `class BetaOverloadedError:`

            - `String message`

            - `JsonValue; type "overloaded_error"constant`

              - `OVERLOADED_ERROR("overloaded_error")`

        - `Optional<String> requestId`

        - `JsonValue; type "error"constant`

          - `ERROR("error")`

      - `JsonValue; type "errored"constant`

        - `ERRORED("errored")`

    - `class BetaMessageBatchCanceledResult:`

      - `JsonValue; type "canceled"constant`

        - `CANCELED("canceled")`

    - `class BetaMessageBatchExpiredResult:`

      - `JsonValue; type "expired"constant`

        - `EXPIRED("expired")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.beta.messages.batches.BatchResultsParams;
import com.anthropic.models.beta.messages.batches.BetaMessageBatchIndividualResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        StreamResponse<BetaMessageBatchIndividualResponse> betaMessageBatchIndividualResponse = client.beta().messages().batches().resultsStreaming("message_batch_id");
    }
}
```

## Domain Types

### Beta Deleted Message Batch

- `class BetaDeletedMessageBatch:`

  - `String id`

    ID of the Message Batch.

  - `JsonValue; type "message_batch_deleted"constant`

    Deleted object type.

    For Message Batches, this is always `"message_batch_deleted"`.

    - `MESSAGE_BATCH_DELETED("message_batch_deleted")`

### Beta Message Batch

- `class BetaMessageBatch:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `Optional<LocalDateTime> archivedAt`

    RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

  - `Optional<LocalDateTime> cancelInitiatedAt`

    RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing the time at which the Message Batch was created.

  - `Optional<LocalDateTime> endedAt`

    RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

    Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

  - `LocalDateTime expiresAt`

    RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.

  - `ProcessingStatus processingStatus`

    Processing status of the Message Batch.

    - `IN_PROGRESS("in_progress")`

    - `CANCELING("canceling")`

    - `ENDED("ended")`

  - `BetaMessageBatchRequestCounts requestCounts`

    Tallies requests within the Message Batch, categorized by their status.

    Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.

    - `long canceled`

      Number of requests in the Message Batch that have been canceled.

      This is zero until processing of the entire Message Batch has ended.

    - `long errored`

      Number of requests in the Message Batch that encountered an error.

      This is zero until processing of the entire Message Batch has ended.

    - `long expired`

      Number of requests in the Message Batch that have expired.

      This is zero until processing of the entire Message Batch has ended.

    - `long processing`

      Number of requests in the Message Batch that are processing.

    - `long succeeded`

      Number of requests in the Message Batch that have completed successfully.

      This is zero until processing of the entire Message Batch has ended.

  - `Optional<String> resultsUrl`

    URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.

    Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.

  - `JsonValue; type "message_batch"constant`

    Object type.

    For Message Batches, this is always `"message_batch"`.

    - `MESSAGE_BATCH("message_batch")`

### Beta Message Batch Canceled Result

- `class BetaMessageBatchCanceledResult:`

  - `JsonValue; type "canceled"constant`

    - `CANCELED("canceled")`

### Beta Message Batch Errored Result

- `class BetaMessageBatchErroredResult:`

  - `BetaErrorResponse error`

    - `BetaError error`

      - `class BetaInvalidRequestError:`

        - `String message`

        - `JsonValue; type "invalid_request_error"constant`

          - `INVALID_REQUEST_ERROR("invalid_request_error")`

      - `class BetaAuthenticationError:`

        - `String message`

        - `JsonValue; type "authentication_error"constant`

          - `AUTHENTICATION_ERROR("authentication_error")`

      - `class BetaBillingError:`

        - `String message`

        - `JsonValue; type "billing_error"constant`

          - `BILLING_ERROR("billing_error")`

      - `class BetaPermissionError:`

        - `String message`

        - `JsonValue; type "permission_error"constant`

          - `PERMISSION_ERROR("permission_error")`

      - `class BetaNotFoundError:`

        - `String message`

        - `JsonValue; type "not_found_error"constant`

          - `NOT_FOUND_ERROR("not_found_error")`

      - `class BetaRateLimitError:`

        - `String message`

        - `JsonValue; type "rate_limit_error"constant`

          - `RATE_LIMIT_ERROR("rate_limit_error")`

      - `class BetaGatewayTimeoutError:`

        - `String message`

        - `JsonValue; type "timeout_error"constant`

          - `TIMEOUT_ERROR("timeout_error")`

      - `class BetaApiError:`

        - `String message`

        - `JsonValue; type "api_error"constant`

          - `API_ERROR("api_error")`

      - `class BetaOverloadedError:`

        - `String message`

        - `JsonValue; type "overloaded_error"constant`

          - `OVERLOADED_ERROR("overloaded_error")`

    - `Optional<String> requestId`

    - `JsonValue; type "error"constant`

      - `ERROR("error")`

  - `JsonValue; type "errored"constant`

    - `ERRORED("errored")`

### Beta Message Batch Expired Result

- `class BetaMessageBatchExpiredResult:`

  - `JsonValue; type "expired"constant`

    - `EXPIRED("expired")`

### Beta Message Batch Individual Response

- `class BetaMessageBatchIndividualResponse:`

  This is a single line in the response `.jsonl` file and does not represent the response as a whole.

  - `String customId`

    Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.

    Must be unique for each request within the Message Batch.

  - `BetaMessageBatchResult result`

    Processing result for this request.

    Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.

    - `class BetaMessageBatchSucceededResult:`

      - `BetaMessage message`

        - `String id`

          Unique object identifier.

          The format and length of IDs may change over time.

        - `Optional<BetaContainer> container`

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

          - `String id`

            Identifier for the container used in this request

          - `LocalDateTime expiresAt`

            The time at which the container will expire.

          - `Optional<List<BetaSkill>> skills`

            Skills loaded in the container

            - `String skillId`

              Skill ID

            - `Type type`

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

              - `ANTHROPIC("anthropic")`

              - `CUSTOM("custom")`

            - `String version`

              Skill version or 'latest' for most recent version

        - `List<BetaContentBlock> content`

          Content generated by the model.

          This is an array of content blocks, each of which has a `type` that determines its shape.

          Example:

          ```json
          [{"type": "text", "text": "Hi, I'm Claude."}]
          ```

          If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.

          For example, if the input `messages` were:

          ```json
          [
            {"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)"}]
          ```

          - `class BetaTextBlock:`

            - `Optional<List<BetaTextCitation>> citations`

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

              - `class BetaCitationCharLocation:`

                - `String citedText`

                - `long documentIndex`

                - `Optional<String> documentTitle`

                - `long endCharIndex`

                - `Optional<String> fileId`

                - `long startCharIndex`

                - `JsonValue; type "char_location"constant`

                  - `CHAR_LOCATION("char_location")`

              - `class BetaCitationPageLocation:`

                - `String citedText`

                - `long documentIndex`

                - `Optional<String> documentTitle`

                - `long endPageNumber`

                - `Optional<String> fileId`

                - `long startPageNumber`

                - `JsonValue; type "page_location"constant`

                  - `PAGE_LOCATION("page_location")`

              - `class BetaCitationContentBlockLocation:`

                - `String citedText`

                  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.

                - `long documentIndex`

                - `Optional<String> documentTitle`

                - `long endBlockIndex`

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

                - `Optional<String> fileId`

                - `long startBlockIndex`

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

                - `JsonValue; type "content_block_location"constant`

                  - `CONTENT_BLOCK_LOCATION("content_block_location")`

              - `class BetaCitationsWebSearchResultLocation:`

                - `String citedText`

                - `String encryptedIndex`

                - `Optional<String> title`

                - `JsonValue; type "web_search_result_location"constant`

                  - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

                - `String url`

              - `class BetaCitationSearchResultLocation:`

                - `String citedText`

                  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.

                - `long endBlockIndex`

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

                - `long searchResultIndex`

                  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.

                - `String source`

                - `long startBlockIndex`

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

                - `Optional<String> title`

                - `JsonValue; type "search_result_location"constant`

                  - `SEARCH_RESULT_LOCATION("search_result_location")`

            - `String text`

            - `JsonValue; type "text"constant`

              - `TEXT("text")`

          - `class BetaThinkingBlock:`

            - `String signature`

            - `String thinking`

            - `JsonValue; type "thinking"constant`

              - `THINKING("thinking")`

          - `class BetaRedactedThinkingBlock:`

            - `String data`

            - `JsonValue; type "redacted_thinking"constant`

              - `REDACTED_THINKING("redacted_thinking")`

          - `class BetaToolUseBlock:`

            - `String id`

            - `Input input`

            - `String name`

            - `JsonValue; type "tool_use"constant`

              - `TOOL_USE("tool_use")`

            - `Optional<Caller> caller`

              Tool invocation directly from the model.

              - `class BetaDirectCaller:`

                Tool invocation directly from the model.

                - `JsonValue; type "direct"constant`

                  - `DIRECT("direct")`

              - `class BetaServerToolCaller:`

                Tool invocation generated by a server-side tool.

                - `String toolId`

                - `JsonValue; type "code_execution_20250825"constant`

                  - `CODE_EXECUTION_20250825("code_execution_20250825")`

              - `class BetaServerToolCaller20260120:`

                - `String toolId`

                - `JsonValue; type "code_execution_20260120"constant`

                  - `CODE_EXECUTION_20260120("code_execution_20260120")`

          - `class BetaServerToolUseBlock:`

            - `String id`

            - `Input input`

            - `Name name`

              - `ADVISOR("advisor")`

              - `WEB_SEARCH("web_search")`

              - `WEB_FETCH("web_fetch")`

              - `CODE_EXECUTION("code_execution")`

              - `BASH_CODE_EXECUTION("bash_code_execution")`

              - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

              - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

              - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

            - `JsonValue; type "server_tool_use"constant`

              - `SERVER_TOOL_USE("server_tool_use")`

            - `Optional<Caller> caller`

              Tool invocation directly from the model.

              - `class BetaDirectCaller:`

                Tool invocation directly from the model.

              - `class BetaServerToolCaller:`

                Tool invocation generated by a server-side tool.

              - `class BetaServerToolCaller20260120:`

          - `class BetaWebSearchToolResultBlock:`

            - `BetaWebSearchToolResultBlockContent content`

              - `class BetaWebSearchToolResultError:`

                - `BetaWebSearchToolResultErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `UNAVAILABLE("unavailable")`

                  - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `QUERY_TOO_LONG("query_too_long")`

                  - `REQUEST_TOO_LARGE("request_too_large")`

                - `JsonValue; type "web_search_tool_result_error"constant`

                  - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

              - `List<BetaWebSearchResultBlock>`

                - `String encryptedContent`

                - `Optional<String> pageAge`

                - `String title`

                - `JsonValue; type "web_search_result"constant`

                  - `WEB_SEARCH_RESULT("web_search_result")`

                - `String url`

            - `String toolUseId`

            - `JsonValue; type "web_search_tool_result"constant`

              - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

            - `Optional<Caller> caller`

              Tool invocation directly from the model.

              - `class BetaDirectCaller:`

                Tool invocation directly from the model.

              - `class BetaServerToolCaller:`

                Tool invocation generated by a server-side tool.

              - `class BetaServerToolCaller20260120:`

          - `class BetaWebFetchToolResultBlock:`

            - `Content content`

              - `class BetaWebFetchToolResultErrorBlock:`

                - `BetaWebFetchToolResultErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `URL_TOO_LONG("url_too_long")`

                  - `URL_NOT_ALLOWED("url_not_allowed")`

                  - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

                  - `URL_NOT_ACCESSIBLE("url_not_accessible")`

                  - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                  - `UNAVAILABLE("unavailable")`

                - `JsonValue; type "web_fetch_tool_result_error"constant`

                  - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

              - `class BetaWebFetchBlock:`

                - `BetaDocumentBlock content`

                  - `Optional<BetaCitationConfig> citations`

                    Citation configuration for the document

                    - `boolean enabled`

                  - `Source source`

                    - `class BetaBase64PdfSource:`

                      - `String data`

                      - `JsonValue; mediaType "application/pdf"constant`

                        - `APPLICATION_PDF("application/pdf")`

                      - `JsonValue; type "base64"constant`

                        - `BASE64("base64")`

                    - `class BetaPlainTextSource:`

                      - `String data`

                      - `JsonValue; mediaType "text/plain"constant`

                        - `TEXT_PLAIN("text/plain")`

                      - `JsonValue; type "text"constant`

                        - `TEXT("text")`

                  - `Optional<String> title`

                    The title of the document

                  - `JsonValue; type "document"constant`

                    - `DOCUMENT("document")`

                - `Optional<String> retrievedAt`

                  ISO 8601 timestamp when the content was retrieved

                - `JsonValue; type "web_fetch_result"constant`

                  - `WEB_FETCH_RESULT("web_fetch_result")`

                - `String url`

                  Fetched content URL

            - `String toolUseId`

            - `JsonValue; type "web_fetch_tool_result"constant`

              - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

            - `Optional<Caller> caller`

              Tool invocation directly from the model.

              - `class BetaDirectCaller:`

                Tool invocation directly from the model.

              - `class BetaServerToolCaller:`

                Tool invocation generated by a server-side tool.

              - `class BetaServerToolCaller20260120:`

          - `class BetaAdvisorToolResultBlock:`

            - `Content content`

              - `class BetaAdvisorToolResultError:`

                - `ErrorCode errorCode`

                  - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                  - `PROMPT_TOO_LONG("prompt_too_long")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `OVERLOADED("overloaded")`

                  - `UNAVAILABLE("unavailable")`

                  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                  - `MODEL_NOT_FOUND("model_not_found")`

                - `JsonValue; type "advisor_tool_result_error"constant`

                  - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

              - `class BetaAdvisorResultBlock:`

                - `Optional<String> stopReason`

                  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.

                - `String text`

                - `JsonValue; type "advisor_result"constant`

                  - `ADVISOR_RESULT("advisor_result")`

              - `class BetaAdvisorRedactedResultBlock:`

                - `String encryptedContent`

                  Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

                - `Optional<String> stopReason`

                  The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

                - `JsonValue; type "advisor_redacted_result"constant`

                  - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

            - `String toolUseId`

            - `JsonValue; type "advisor_tool_result"constant`

              - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

          - `class BetaCodeExecutionToolResultBlock:`

            - `BetaCodeExecutionToolResultBlockContent content`

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

              - `class BetaCodeExecutionToolResultError:`

                - `BetaCodeExecutionToolResultErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `UNAVAILABLE("unavailable")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `JsonValue; type "code_execution_tool_result_error"constant`

                  - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

              - `class BetaCodeExecutionResultBlock:`

                - `List<BetaCodeExecutionOutputBlock> content`

                  - `String fileId`

                  - `JsonValue; type "code_execution_output"constant`

                    - `CODE_EXECUTION_OUTPUT("code_execution_output")`

                - `long returnCode`

                - `String stderr`

                - `String stdout`

                - `JsonValue; type "code_execution_result"constant`

                  - `CODE_EXECUTION_RESULT("code_execution_result")`

              - `class BetaEncryptedCodeExecutionResultBlock:`

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

                - `List<BetaCodeExecutionOutputBlock> content`

                  - `String fileId`

                  - `JsonValue; type "code_execution_output"constant`

                - `String encryptedStdout`

                - `long returnCode`

                - `String stderr`

                - `JsonValue; type "encrypted_code_execution_result"constant`

                  - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

            - `String toolUseId`

            - `JsonValue; type "code_execution_tool_result"constant`

              - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

          - `class BetaBashCodeExecutionToolResultBlock:`

            - `Content content`

              - `class BetaBashCodeExecutionToolResultError:`

                - `ErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `UNAVAILABLE("unavailable")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                  - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

                - `JsonValue; type "bash_code_execution_tool_result_error"constant`

                  - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

              - `class BetaBashCodeExecutionResultBlock:`

                - `List<BetaBashCodeExecutionOutputBlock> content`

                  - `String fileId`

                  - `JsonValue; type "bash_code_execution_output"constant`

                    - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

                - `long returnCode`

                - `String stderr`

                - `String stdout`

                - `JsonValue; type "bash_code_execution_result"constant`

                  - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

            - `String toolUseId`

            - `JsonValue; type "bash_code_execution_tool_result"constant`

              - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

          - `class BetaTextEditorCodeExecutionToolResultBlock:`

            - `Content content`

              - `class BetaTextEditorCodeExecutionToolResultError:`

                - `ErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `UNAVAILABLE("unavailable")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                  - `FILE_NOT_FOUND("file_not_found")`

                - `Optional<String> errorMessage`

                - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

                  - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

              - `class BetaTextEditorCodeExecutionViewResultBlock:`

                - `String content`

                - `FileType fileType`

                  - `TEXT("text")`

                  - `IMAGE("image")`

                  - `PDF("pdf")`

                - `Optional<Long> numLines`

                - `Optional<Long> startLine`

                - `Optional<Long> totalLines`

                - `JsonValue; type "text_editor_code_execution_view_result"constant`

                  - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

              - `class BetaTextEditorCodeExecutionCreateResultBlock:`

                - `boolean isFileUpdate`

                - `JsonValue; type "text_editor_code_execution_create_result"constant`

                  - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

              - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

                - `Optional<List<String>> lines`

                - `Optional<Long> newLines`

                - `Optional<Long> newStart`

                - `Optional<Long> oldLines`

                - `Optional<Long> oldStart`

                - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

                  - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

            - `String toolUseId`

            - `JsonValue; type "text_editor_code_execution_tool_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

          - `class BetaToolSearchToolResultBlock:`

            - `Content content`

              - `class BetaToolSearchToolResultError:`

                - `ErrorCode errorCode`

                  - `INVALID_TOOL_INPUT("invalid_tool_input")`

                  - `UNAVAILABLE("unavailable")`

                  - `TOO_MANY_REQUESTS("too_many_requests")`

                  - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `Optional<String> errorMessage`

                - `JsonValue; type "tool_search_tool_result_error"constant`

                  - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

              - `class BetaToolSearchToolSearchResultBlock:`

                - `List<BetaToolReferenceBlock> toolReferences`

                  - `String toolName`

                  - `JsonValue; type "tool_reference"constant`

                    - `TOOL_REFERENCE("tool_reference")`

                - `JsonValue; type "tool_search_tool_search_result"constant`

                  - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

            - `String toolUseId`

            - `JsonValue; type "tool_search_tool_result"constant`

              - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

          - `class BetaMcpToolUseBlock:`

            - `String id`

            - `Input input`

            - `String name`

              The name of the MCP tool

            - `String serverName`

              The name of the MCP server

            - `JsonValue; type "mcp_tool_use"constant`

              - `MCP_TOOL_USE("mcp_tool_use")`

          - `class BetaMcpToolResultBlock:`

            - `Content content`

              - `String`

              - `List<BetaTextBlock>`

                - `Optional<List<BetaTextCitation>> citations`

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

                - `String text`

                - `JsonValue; type "text"constant`

            - `boolean isError`

            - `String toolUseId`

            - `JsonValue; type "mcp_tool_result"constant`

              - `MCP_TOOL_RESULT("mcp_tool_result")`

          - `class BetaContainerUploadBlock:`

            Response model for a file uploaded to the container.

            - `String fileId`

            - `JsonValue; type "container_upload"constant`

              - `CONTAINER_UPLOAD("container_upload")`

          - `class BetaCompactionBlock:`

            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.

            - `Optional<String> content`

              Summary of compacted content, or null if compaction failed

            - `Optional<String> encryptedContent`

              Opaque metadata from prior compaction, to be round-tripped verbatim

            - `JsonValue; type "compaction"constant`

              - `COMPACTION("compaction")`

          - `class BetaFallbackBlock:`

            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 routed directly by the sticky decision 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.

            - `BetaFallbackInfo from`

              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.

              - `Model model`

                The model that will complete your prompt.

                See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

                - `CLAUDE_FABLE_5("claude-fable-5")`

                  Next generation of intelligence for the hardest knowledge work and coding problems

                - `CLAUDE_MYTHOS_5("claude-mythos-5")`

                  Most capable model for cybersecurity and biology research

                - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

                  Frontier intelligence for long-running agents and coding

                - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

                  Frontier intelligence for long-running agents and coding

                - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

                  New class of intelligence, strongest in coding and cybersecurity

                - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

                  Frontier intelligence for long-running agents and coding

                - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

                  Best combination of speed and intelligence

                - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

                  Fastest model with near-frontier intelligence

                - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

                  Fastest model with near-frontier intelligence

                - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

                  Premium model combining maximum intelligence with practical performance

                - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

                  Premium model combining maximum intelligence with practical performance

                - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

                  High-performance model for agents and coding

                - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

                  High-performance model for agents and coding

                - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

                  Exceptional model for specialized complex tasks

                - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

                  Exceptional model for specialized complex tasks

                - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

                  Powerful model for complex tasks

                - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

                  Powerful model for complex tasks

                - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

                  High-performance model with extended thinking

                - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

                  High-performance model with extended thinking

                - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

                  Fast and cost-effective model

            - `BetaFallbackInfo to`

              The fallback model producing the content that follows this block. Its `model` is always the canonical id.

            - `JsonValue; type "fallback"constant`

              - `FALLBACK("fallback")`

        - `Optional<BetaContextManagementResponse> contextManagement`

          Context management response.

          Information about context management strategies applied during the request.

          - `List<AppliedEdit> appliedEdits`

            List of context management edits that were applied.

            - `class BetaClearToolUses20250919EditResponse:`

              - `long clearedInputTokens`

                Number of input tokens cleared by this edit.

              - `long clearedToolUses`

                Number of tool uses that were cleared.

              - `JsonValue; type "clear_tool_uses_20250919"constant`

                The type of context management edit applied.

                - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

            - `class BetaClearThinking20251015EditResponse:`

              - `long clearedInputTokens`

                Number of input tokens cleared by this edit.

              - `long clearedThinkingTurns`

                Number of thinking turns that were cleared.

              - `JsonValue; type "clear_thinking_20251015"constant`

                The type of context management edit applied.

                - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

        - `Optional<BetaDiagnostics> diagnostics`

          Response envelope for request-level diagnostics. Present (possibly
          null) whenever the caller supplied `diagnostics` on the request.

          - `Optional<CacheMissReason> cacheMissReason`

            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.

            - `class BetaCacheMissModelChanged:`

              - `long cacheMissedInputTokens`

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

              - `JsonValue; type "model_changed"constant`

                - `MODEL_CHANGED("model_changed")`

            - `class BetaCacheMissSystemChanged:`

              - `long cacheMissedInputTokens`

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

              - `JsonValue; type "system_changed"constant`

                - `SYSTEM_CHANGED("system_changed")`

            - `class BetaCacheMissToolsChanged:`

              - `long cacheMissedInputTokens`

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

              - `JsonValue; type "tools_changed"constant`

                - `TOOLS_CHANGED("tools_changed")`

            - `class BetaCacheMissMessagesChanged:`

              - `long cacheMissedInputTokens`

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

              - `JsonValue; type "messages_changed"constant`

                - `MESSAGES_CHANGED("messages_changed")`

            - `class BetaCacheMissPreviousMessageNotFound:`

              - `JsonValue; type "previous_message_not_found"constant`

                - `PREVIOUS_MESSAGE_NOT_FOUND("previous_message_not_found")`

            - `class BetaCacheMissUnavailable:`

              - `JsonValue; type "unavailable"constant`

                - `UNAVAILABLE("unavailable")`

        - `Model model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `JsonValue; role "assistant"constant`

          Conversational role of the generated message.

          This will always be `"assistant"`.

          - `ASSISTANT("assistant")`

        - `Optional<BetaRefusalStopDetails> stopDetails`

          Structured information about a refusal.

          - `Optional<Category> category`

            The policy category that triggered the refusal.

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

            - `CYBER("cyber")`

            - `BIO("bio")`

            - `REASONING_EXTRACTION("reasoning_extraction")`

          - `Optional<String> explanation`

            Human-readable explanation of the refusal.

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

          - `Optional<String> fallbackCreditToken`

            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.

          - `Optional<Boolean> fallbackHasPrefillClaim`

            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.

          - `Optional<String> recommendedModel`

            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.

          - `JsonValue; type "refusal"constant`

            - `REFUSAL("refusal")`

        - `Optional<BetaStopReason> stopReason`

          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

          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.

          - `END_TURN("end_turn")`

          - `MAX_TOKENS("max_tokens")`

          - `STOP_SEQUENCE("stop_sequence")`

          - `TOOL_USE("tool_use")`

          - `PAUSE_TURN("pause_turn")`

          - `COMPACTION("compaction")`

          - `REFUSAL("refusal")`

          - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")`

        - `Optional<String> stopSequence`

          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.

        - `JsonValue; type "message"constant`

          Object type.

          For Messages, this is always `"message"`.

          - `MESSAGE("message")`

        - `BetaUsage usage`

          Billing and rate-limit usage.

          Anthropic'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 Claude.

          Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.

          - `Optional<BetaCacheCreation> cacheCreation`

            Breakdown of cached tokens by TTL

            - `long ephemeral1hInputTokens`

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

            - `long ephemeral5mInputTokens`

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

          - `Optional<Long> cacheCreationInputTokens`

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

          - `Optional<Long> cacheReadInputTokens`

            The number of input tokens read from the cache.

          - `Optional<String> inferenceGeo`

            The geographic region where inference was performed for this request.

          - `long inputTokens`

            The number of input tokens which were used.

          - `Optional<List<BetaIterationsUsageItems>> iterations`

            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

            - `class BetaMessageIterationUsage:`

              Token usage for a sampling iteration.

              - `Optional<BetaCacheCreation> cacheCreation`

                Breakdown of cached tokens by TTL

              - `long cacheCreationInputTokens`

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

              - `long cacheReadInputTokens`

                The number of input tokens read from the cache.

              - `long inputTokens`

                The number of input tokens which were used.

              - `Model model`

                The model that will complete your prompt.

                See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

              - `long outputTokens`

                The number of output tokens which were used.

              - `JsonValue; type "message"constant`

                Usage for a sampling iteration

                - `MESSAGE("message")`

            - `class BetaCompactionIterationUsage:`

              Token usage for a compaction iteration.

              - `Optional<BetaCacheCreation> cacheCreation`

                Breakdown of cached tokens by TTL

              - `long cacheCreationInputTokens`

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

              - `long cacheReadInputTokens`

                The number of input tokens read from the cache.

              - `long inputTokens`

                The number of input tokens which were used.

              - `long outputTokens`

                The number of output tokens which were used.

              - `JsonValue; type "compaction"constant`

                Usage for a compaction iteration

                - `COMPACTION("compaction")`

            - `class BetaAdvisorMessageIterationUsage:`

              Token usage for an advisor sub-inference iteration.

              - `Optional<BetaCacheCreation> cacheCreation`

                Breakdown of cached tokens by TTL

              - `long cacheCreationInputTokens`

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

              - `long cacheReadInputTokens`

                The number of input tokens read from the cache.

              - `long inputTokens`

                The number of input tokens which were used.

              - `Model model`

                The model that will complete your prompt.

                See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

              - `long outputTokens`

                The number of output tokens which were used.

              - `JsonValue; type "advisor_message"constant`

                Usage for an advisor sub-inference iteration

                - `ADVISOR_MESSAGE("advisor_message")`

            - `class BetaFallbackMessageIterationUsage:`

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

              - `Optional<BetaCacheCreation> cacheCreation`

                Breakdown of cached tokens by TTL

              - `long cacheCreationInputTokens`

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

              - `long cacheReadInputTokens`

                The number of input tokens read from the cache.

              - `long inputTokens`

                The number of input tokens which were used.

              - `Model model`

                The model that will complete your prompt.

                See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

              - `long outputTokens`

                The number of output tokens which were used.

              - `JsonValue; type "fallback_message"constant`

                Usage for the fallback-model attempt that served the response

                - `FALLBACK_MESSAGE("fallback_message")`

          - `long outputTokens`

            The number of output tokens which were used.

          - `Optional<BetaOutputTokensDetails> outputTokensDetails`

            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.

            - `long thinkingTokens`

              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.

          - `Optional<BetaServerToolUsage> serverToolUse`

            The number of server tool requests.

            - `long webFetchRequests`

              The number of web fetch tool requests.

            - `long webSearchRequests`

              The number of web search tool requests.

          - `Optional<ServiceTier> serviceTier`

            If the request used the priority, standard, or batch tier.

            - `STANDARD("standard")`

            - `PRIORITY("priority")`

            - `BATCH("batch")`

          - `Optional<Speed> speed`

            The inference speed mode used for this request.

            - `STANDARD("standard")`

            - `FAST("fast")`

      - `JsonValue; type "succeeded"constant`

        - `SUCCEEDED("succeeded")`

    - `class BetaMessageBatchErroredResult:`

      - `BetaErrorResponse error`

        - `BetaError error`

          - `class BetaInvalidRequestError:`

            - `String message`

            - `JsonValue; type "invalid_request_error"constant`

              - `INVALID_REQUEST_ERROR("invalid_request_error")`

          - `class BetaAuthenticationError:`

            - `String message`

            - `JsonValue; type "authentication_error"constant`

              - `AUTHENTICATION_ERROR("authentication_error")`

          - `class BetaBillingError:`

            - `String message`

            - `JsonValue; type "billing_error"constant`

              - `BILLING_ERROR("billing_error")`

          - `class BetaPermissionError:`

            - `String message`

            - `JsonValue; type "permission_error"constant`

              - `PERMISSION_ERROR("permission_error")`

          - `class BetaNotFoundError:`

            - `String message`

            - `JsonValue; type "not_found_error"constant`

              - `NOT_FOUND_ERROR("not_found_error")`

          - `class BetaRateLimitError:`

            - `String message`

            - `JsonValue; type "rate_limit_error"constant`

              - `RATE_LIMIT_ERROR("rate_limit_error")`

          - `class BetaGatewayTimeoutError:`

            - `String message`

            - `JsonValue; type "timeout_error"constant`

              - `TIMEOUT_ERROR("timeout_error")`

          - `class BetaApiError:`

            - `String message`

            - `JsonValue; type "api_error"constant`

              - `API_ERROR("api_error")`

          - `class BetaOverloadedError:`

            - `String message`

            - `JsonValue; type "overloaded_error"constant`

              - `OVERLOADED_ERROR("overloaded_error")`

        - `Optional<String> requestId`

        - `JsonValue; type "error"constant`

          - `ERROR("error")`

      - `JsonValue; type "errored"constant`

        - `ERRORED("errored")`

    - `class BetaMessageBatchCanceledResult:`

      - `JsonValue; type "canceled"constant`

        - `CANCELED("canceled")`

    - `class BetaMessageBatchExpiredResult:`

      - `JsonValue; type "expired"constant`

        - `EXPIRED("expired")`

### Beta Message Batch Request Counts

- `class BetaMessageBatchRequestCounts:`

  - `long canceled`

    Number of requests in the Message Batch that have been canceled.

    This is zero until processing of the entire Message Batch has ended.

  - `long errored`

    Number of requests in the Message Batch that encountered an error.

    This is zero until processing of the entire Message Batch has ended.

  - `long expired`

    Number of requests in the Message Batch that have expired.

    This is zero until processing of the entire Message Batch has ended.

  - `long processing`

    Number of requests in the Message Batch that are processing.

  - `long succeeded`

    Number of requests in the Message Batch that have completed successfully.

    This is zero until processing of the entire Message Batch has ended.

### Beta Message Batch Result

- `class BetaMessageBatchResult: A class that can be one of several variants.union`

  Processing result for this request.

  Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.

  - `class BetaMessageBatchSucceededResult:`

    - `BetaMessage message`

      - `String id`

        Unique object identifier.

        The format and length of IDs may change over time.

      - `Optional<BetaContainer> container`

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

        - `String id`

          Identifier for the container used in this request

        - `LocalDateTime expiresAt`

          The time at which the container will expire.

        - `Optional<List<BetaSkill>> skills`

          Skills loaded in the container

          - `String skillId`

            Skill ID

          - `Type type`

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

            - `ANTHROPIC("anthropic")`

            - `CUSTOM("custom")`

          - `String version`

            Skill version or 'latest' for most recent version

      - `List<BetaContentBlock> content`

        Content generated by the model.

        This is an array of content blocks, each of which has a `type` that determines its shape.

        Example:

        ```json
        [{"type": "text", "text": "Hi, I'm Claude."}]
        ```

        If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.

        For example, if the input `messages` were:

        ```json
        [
          {"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)"}]
        ```

        - `class BetaTextBlock:`

          - `Optional<List<BetaTextCitation>> citations`

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

            - `class BetaCitationCharLocation:`

              - `String citedText`

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endCharIndex`

              - `Optional<String> fileId`

              - `long startCharIndex`

              - `JsonValue; type "char_location"constant`

                - `CHAR_LOCATION("char_location")`

            - `class BetaCitationPageLocation:`

              - `String citedText`

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endPageNumber`

              - `Optional<String> fileId`

              - `long startPageNumber`

              - `JsonValue; type "page_location"constant`

                - `PAGE_LOCATION("page_location")`

            - `class BetaCitationContentBlockLocation:`

              - `String citedText`

                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.

              - `long documentIndex`

              - `Optional<String> documentTitle`

              - `long endBlockIndex`

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

              - `Optional<String> fileId`

              - `long startBlockIndex`

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

              - `JsonValue; type "content_block_location"constant`

                - `CONTENT_BLOCK_LOCATION("content_block_location")`

            - `class BetaCitationsWebSearchResultLocation:`

              - `String citedText`

              - `String encryptedIndex`

              - `Optional<String> title`

              - `JsonValue; type "web_search_result_location"constant`

                - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

              - `String url`

            - `class BetaCitationSearchResultLocation:`

              - `String citedText`

                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.

              - `long endBlockIndex`

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

              - `long searchResultIndex`

                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.

              - `String source`

              - `long startBlockIndex`

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

              - `Optional<String> title`

              - `JsonValue; type "search_result_location"constant`

                - `SEARCH_RESULT_LOCATION("search_result_location")`

          - `String text`

          - `JsonValue; type "text"constant`

            - `TEXT("text")`

        - `class BetaThinkingBlock:`

          - `String signature`

          - `String thinking`

          - `JsonValue; type "thinking"constant`

            - `THINKING("thinking")`

        - `class BetaRedactedThinkingBlock:`

          - `String data`

          - `JsonValue; type "redacted_thinking"constant`

            - `REDACTED_THINKING("redacted_thinking")`

        - `class BetaToolUseBlock:`

          - `String id`

          - `Input input`

          - `String name`

          - `JsonValue; type "tool_use"constant`

            - `TOOL_USE("tool_use")`

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

              - `JsonValue; type "direct"constant`

                - `DIRECT("direct")`

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

              - `String toolId`

              - `JsonValue; type "code_execution_20250825"constant`

                - `CODE_EXECUTION_20250825("code_execution_20250825")`

            - `class BetaServerToolCaller20260120:`

              - `String toolId`

              - `JsonValue; type "code_execution_20260120"constant`

                - `CODE_EXECUTION_20260120("code_execution_20260120")`

        - `class BetaServerToolUseBlock:`

          - `String id`

          - `Input input`

          - `Name name`

            - `ADVISOR("advisor")`

            - `WEB_SEARCH("web_search")`

            - `WEB_FETCH("web_fetch")`

            - `CODE_EXECUTION("code_execution")`

            - `BASH_CODE_EXECUTION("bash_code_execution")`

            - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

            - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

            - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

          - `JsonValue; type "server_tool_use"constant`

            - `SERVER_TOOL_USE("server_tool_use")`

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaWebSearchToolResultBlock:`

          - `BetaWebSearchToolResultBlockContent content`

            - `class BetaWebSearchToolResultError:`

              - `BetaWebSearchToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `QUERY_TOO_LONG("query_too_long")`

                - `REQUEST_TOO_LARGE("request_too_large")`

              - `JsonValue; type "web_search_tool_result_error"constant`

                - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

            - `List<BetaWebSearchResultBlock>`

              - `String encryptedContent`

              - `Optional<String> pageAge`

              - `String title`

              - `JsonValue; type "web_search_result"constant`

                - `WEB_SEARCH_RESULT("web_search_result")`

              - `String url`

          - `String toolUseId`

          - `JsonValue; type "web_search_tool_result"constant`

            - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaWebFetchToolResultBlock:`

          - `Content content`

            - `class BetaWebFetchToolResultErrorBlock:`

              - `BetaWebFetchToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `URL_TOO_LONG("url_too_long")`

                - `URL_NOT_ALLOWED("url_not_allowed")`

                - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

                - `URL_NOT_ACCESSIBLE("url_not_accessible")`

                - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `UNAVAILABLE("unavailable")`

              - `JsonValue; type "web_fetch_tool_result_error"constant`

                - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

            - `class BetaWebFetchBlock:`

              - `BetaDocumentBlock content`

                - `Optional<BetaCitationConfig> citations`

                  Citation configuration for the document

                  - `boolean enabled`

                - `Source source`

                  - `class BetaBase64PdfSource:`

                    - `String data`

                    - `JsonValue; mediaType "application/pdf"constant`

                      - `APPLICATION_PDF("application/pdf")`

                    - `JsonValue; type "base64"constant`

                      - `BASE64("base64")`

                  - `class BetaPlainTextSource:`

                    - `String data`

                    - `JsonValue; mediaType "text/plain"constant`

                      - `TEXT_PLAIN("text/plain")`

                    - `JsonValue; type "text"constant`

                      - `TEXT("text")`

                - `Optional<String> title`

                  The title of the document

                - `JsonValue; type "document"constant`

                  - `DOCUMENT("document")`

              - `Optional<String> retrievedAt`

                ISO 8601 timestamp when the content was retrieved

              - `JsonValue; type "web_fetch_result"constant`

                - `WEB_FETCH_RESULT("web_fetch_result")`

              - `String url`

                Fetched content URL

          - `String toolUseId`

          - `JsonValue; type "web_fetch_tool_result"constant`

            - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

          - `Optional<Caller> caller`

            Tool invocation directly from the model.

            - `class BetaDirectCaller:`

              Tool invocation directly from the model.

            - `class BetaServerToolCaller:`

              Tool invocation generated by a server-side tool.

            - `class BetaServerToolCaller20260120:`

        - `class BetaAdvisorToolResultBlock:`

          - `Content content`

            - `class BetaAdvisorToolResultError:`

              - `ErrorCode errorCode`

                - `MAX_USES_EXCEEDED("max_uses_exceeded")`

                - `PROMPT_TOO_LONG("prompt_too_long")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `OVERLOADED("overloaded")`

                - `UNAVAILABLE("unavailable")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `MODEL_NOT_FOUND("model_not_found")`

              - `JsonValue; type "advisor_tool_result_error"constant`

                - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

            - `class BetaAdvisorResultBlock:`

              - `Optional<String> stopReason`

                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.

              - `String text`

              - `JsonValue; type "advisor_result"constant`

                - `ADVISOR_RESULT("advisor_result")`

            - `class BetaAdvisorRedactedResultBlock:`

              - `String encryptedContent`

                Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

              - `Optional<String> stopReason`

                The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

              - `JsonValue; type "advisor_redacted_result"constant`

                - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

          - `String toolUseId`

          - `JsonValue; type "advisor_tool_result"constant`

            - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

        - `class BetaCodeExecutionToolResultBlock:`

          - `BetaCodeExecutionToolResultBlockContent content`

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

            - `class BetaCodeExecutionToolResultError:`

              - `BetaCodeExecutionToolResultErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `JsonValue; type "code_execution_tool_result_error"constant`

                - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

            - `class BetaCodeExecutionResultBlock:`

              - `List<BetaCodeExecutionOutputBlock> content`

                - `String fileId`

                - `JsonValue; type "code_execution_output"constant`

                  - `CODE_EXECUTION_OUTPUT("code_execution_output")`

              - `long returnCode`

              - `String stderr`

              - `String stdout`

              - `JsonValue; type "code_execution_result"constant`

                - `CODE_EXECUTION_RESULT("code_execution_result")`

            - `class BetaEncryptedCodeExecutionResultBlock:`

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

              - `List<BetaCodeExecutionOutputBlock> content`

                - `String fileId`

                - `JsonValue; type "code_execution_output"constant`

              - `String encryptedStdout`

              - `long returnCode`

              - `String stderr`

              - `JsonValue; type "encrypted_code_execution_result"constant`

                - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

          - `String toolUseId`

          - `JsonValue; type "code_execution_tool_result"constant`

            - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

        - `class BetaBashCodeExecutionToolResultBlock:`

          - `Content content`

            - `class BetaBashCodeExecutionToolResultError:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

              - `JsonValue; type "bash_code_execution_tool_result_error"constant`

                - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

            - `class BetaBashCodeExecutionResultBlock:`

              - `List<BetaBashCodeExecutionOutputBlock> content`

                - `String fileId`

                - `JsonValue; type "bash_code_execution_output"constant`

                  - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

              - `long returnCode`

              - `String stderr`

              - `String stdout`

              - `JsonValue; type "bash_code_execution_result"constant`

                - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

          - `String toolUseId`

          - `JsonValue; type "bash_code_execution_tool_result"constant`

            - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

        - `class BetaTextEditorCodeExecutionToolResultBlock:`

          - `Content content`

            - `class BetaTextEditorCodeExecutionToolResultError:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

                - `FILE_NOT_FOUND("file_not_found")`

              - `Optional<String> errorMessage`

              - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

            - `class BetaTextEditorCodeExecutionViewResultBlock:`

              - `String content`

              - `FileType fileType`

                - `TEXT("text")`

                - `IMAGE("image")`

                - `PDF("pdf")`

              - `Optional<Long> numLines`

              - `Optional<Long> startLine`

              - `Optional<Long> totalLines`

              - `JsonValue; type "text_editor_code_execution_view_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

            - `class BetaTextEditorCodeExecutionCreateResultBlock:`

              - `boolean isFileUpdate`

              - `JsonValue; type "text_editor_code_execution_create_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

            - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

              - `Optional<List<String>> lines`

              - `Optional<Long> newLines`

              - `Optional<Long> newStart`

              - `Optional<Long> oldLines`

              - `Optional<Long> oldStart`

              - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

                - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

          - `String toolUseId`

          - `JsonValue; type "text_editor_code_execution_tool_result"constant`

            - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

        - `class BetaToolSearchToolResultBlock:`

          - `Content content`

            - `class BetaToolSearchToolResultError:`

              - `ErrorCode errorCode`

                - `INVALID_TOOL_INPUT("invalid_tool_input")`

                - `UNAVAILABLE("unavailable")`

                - `TOO_MANY_REQUESTS("too_many_requests")`

                - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `Optional<String> errorMessage`

              - `JsonValue; type "tool_search_tool_result_error"constant`

                - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

            - `class BetaToolSearchToolSearchResultBlock:`

              - `List<BetaToolReferenceBlock> toolReferences`

                - `String toolName`

                - `JsonValue; type "tool_reference"constant`

                  - `TOOL_REFERENCE("tool_reference")`

              - `JsonValue; type "tool_search_tool_search_result"constant`

                - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

          - `String toolUseId`

          - `JsonValue; type "tool_search_tool_result"constant`

            - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

        - `class BetaMcpToolUseBlock:`

          - `String id`

          - `Input input`

          - `String name`

            The name of the MCP tool

          - `String serverName`

            The name of the MCP server

          - `JsonValue; type "mcp_tool_use"constant`

            - `MCP_TOOL_USE("mcp_tool_use")`

        - `class BetaMcpToolResultBlock:`

          - `Content content`

            - `String`

            - `List<BetaTextBlock>`

              - `Optional<List<BetaTextCitation>> citations`

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

              - `String text`

              - `JsonValue; type "text"constant`

          - `boolean isError`

          - `String toolUseId`

          - `JsonValue; type "mcp_tool_result"constant`

            - `MCP_TOOL_RESULT("mcp_tool_result")`

        - `class BetaContainerUploadBlock:`

          Response model for a file uploaded to the container.

          - `String fileId`

          - `JsonValue; type "container_upload"constant`

            - `CONTAINER_UPLOAD("container_upload")`

        - `class BetaCompactionBlock:`

          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.

          - `Optional<String> content`

            Summary of compacted content, or null if compaction failed

          - `Optional<String> encryptedContent`

            Opaque metadata from prior compaction, to be round-tripped verbatim

          - `JsonValue; type "compaction"constant`

            - `COMPACTION("compaction")`

        - `class BetaFallbackBlock:`

          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 routed directly by the sticky decision 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.

          - `BetaFallbackInfo from`

            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.

            - `Model model`

              The model that will complete your prompt.

              See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

              - `CLAUDE_FABLE_5("claude-fable-5")`

                Next generation of intelligence for the hardest knowledge work and coding problems

              - `CLAUDE_MYTHOS_5("claude-mythos-5")`

                Most capable model for cybersecurity and biology research

              - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

                New class of intelligence, strongest in coding and cybersecurity

              - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

                Frontier intelligence for long-running agents and coding

              - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

                Best combination of speed and intelligence

              - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

                Fastest model with near-frontier intelligence

              - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

                Fastest model with near-frontier intelligence

              - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

                Premium model combining maximum intelligence with practical performance

              - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

                Premium model combining maximum intelligence with practical performance

              - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

                High-performance model for agents and coding

              - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

                High-performance model for agents and coding

              - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

                Exceptional model for specialized complex tasks

              - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

                Exceptional model for specialized complex tasks

              - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

                Powerful model for complex tasks

              - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

                Powerful model for complex tasks

              - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

                High-performance model with extended thinking

              - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

                High-performance model with extended thinking

              - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

                Fast and cost-effective model

          - `BetaFallbackInfo to`

            The fallback model producing the content that follows this block. Its `model` is always the canonical id.

          - `JsonValue; type "fallback"constant`

            - `FALLBACK("fallback")`

      - `Optional<BetaContextManagementResponse> contextManagement`

        Context management response.

        Information about context management strategies applied during the request.

        - `List<AppliedEdit> appliedEdits`

          List of context management edits that were applied.

          - `class BetaClearToolUses20250919EditResponse:`

            - `long clearedInputTokens`

              Number of input tokens cleared by this edit.

            - `long clearedToolUses`

              Number of tool uses that were cleared.

            - `JsonValue; type "clear_tool_uses_20250919"constant`

              The type of context management edit applied.

              - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

          - `class BetaClearThinking20251015EditResponse:`

            - `long clearedInputTokens`

              Number of input tokens cleared by this edit.

            - `long clearedThinkingTurns`

              Number of thinking turns that were cleared.

            - `JsonValue; type "clear_thinking_20251015"constant`

              The type of context management edit applied.

              - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

      - `Optional<BetaDiagnostics> diagnostics`

        Response envelope for request-level diagnostics. Present (possibly
        null) whenever the caller supplied `diagnostics` on the request.

        - `Optional<CacheMissReason> cacheMissReason`

          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.

          - `class BetaCacheMissModelChanged:`

            - `long cacheMissedInputTokens`

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

            - `JsonValue; type "model_changed"constant`

              - `MODEL_CHANGED("model_changed")`

          - `class BetaCacheMissSystemChanged:`

            - `long cacheMissedInputTokens`

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

            - `JsonValue; type "system_changed"constant`

              - `SYSTEM_CHANGED("system_changed")`

          - `class BetaCacheMissToolsChanged:`

            - `long cacheMissedInputTokens`

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

            - `JsonValue; type "tools_changed"constant`

              - `TOOLS_CHANGED("tools_changed")`

          - `class BetaCacheMissMessagesChanged:`

            - `long cacheMissedInputTokens`

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

            - `JsonValue; type "messages_changed"constant`

              - `MESSAGES_CHANGED("messages_changed")`

          - `class BetaCacheMissPreviousMessageNotFound:`

            - `JsonValue; type "previous_message_not_found"constant`

              - `PREVIOUS_MESSAGE_NOT_FOUND("previous_message_not_found")`

          - `class BetaCacheMissUnavailable:`

            - `JsonValue; type "unavailable"constant`

              - `UNAVAILABLE("unavailable")`

      - `Model model`

        The model that will complete your prompt.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `JsonValue; role "assistant"constant`

        Conversational role of the generated message.

        This will always be `"assistant"`.

        - `ASSISTANT("assistant")`

      - `Optional<BetaRefusalStopDetails> stopDetails`

        Structured information about a refusal.

        - `Optional<Category> category`

          The policy category that triggered the refusal.

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

          - `CYBER("cyber")`

          - `BIO("bio")`

          - `REASONING_EXTRACTION("reasoning_extraction")`

        - `Optional<String> explanation`

          Human-readable explanation of the refusal.

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

        - `Optional<String> fallbackCreditToken`

          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.

        - `Optional<Boolean> fallbackHasPrefillClaim`

          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.

        - `Optional<String> recommendedModel`

          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.

        - `JsonValue; type "refusal"constant`

          - `REFUSAL("refusal")`

      - `Optional<BetaStopReason> stopReason`

        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

        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.

        - `END_TURN("end_turn")`

        - `MAX_TOKENS("max_tokens")`

        - `STOP_SEQUENCE("stop_sequence")`

        - `TOOL_USE("tool_use")`

        - `PAUSE_TURN("pause_turn")`

        - `COMPACTION("compaction")`

        - `REFUSAL("refusal")`

        - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")`

      - `Optional<String> stopSequence`

        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.

      - `JsonValue; type "message"constant`

        Object type.

        For Messages, this is always `"message"`.

        - `MESSAGE("message")`

      - `BetaUsage usage`

        Billing and rate-limit usage.

        Anthropic'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 Claude.

        Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.

        - `Optional<BetaCacheCreation> cacheCreation`

          Breakdown of cached tokens by TTL

          - `long ephemeral1hInputTokens`

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

          - `long ephemeral5mInputTokens`

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

        - `Optional<Long> cacheCreationInputTokens`

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

        - `Optional<Long> cacheReadInputTokens`

          The number of input tokens read from the cache.

        - `Optional<String> inferenceGeo`

          The geographic region where inference was performed for this request.

        - `long inputTokens`

          The number of input tokens which were used.

        - `Optional<List<BetaIterationsUsageItems>> iterations`

          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

          - `class BetaMessageIterationUsage:`

            Token usage for a sampling iteration.

            - `Optional<BetaCacheCreation> cacheCreation`

              Breakdown of cached tokens by TTL

            - `long cacheCreationInputTokens`

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

            - `long cacheReadInputTokens`

              The number of input tokens read from the cache.

            - `long inputTokens`

              The number of input tokens which were used.

            - `Model model`

              The model that will complete your prompt.

              See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

            - `long outputTokens`

              The number of output tokens which were used.

            - `JsonValue; type "message"constant`

              Usage for a sampling iteration

              - `MESSAGE("message")`

          - `class BetaCompactionIterationUsage:`

            Token usage for a compaction iteration.

            - `Optional<BetaCacheCreation> cacheCreation`

              Breakdown of cached tokens by TTL

            - `long cacheCreationInputTokens`

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

            - `long cacheReadInputTokens`

              The number of input tokens read from the cache.

            - `long inputTokens`

              The number of input tokens which were used.

            - `long outputTokens`

              The number of output tokens which were used.

            - `JsonValue; type "compaction"constant`

              Usage for a compaction iteration

              - `COMPACTION("compaction")`

          - `class BetaAdvisorMessageIterationUsage:`

            Token usage for an advisor sub-inference iteration.

            - `Optional<BetaCacheCreation> cacheCreation`

              Breakdown of cached tokens by TTL

            - `long cacheCreationInputTokens`

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

            - `long cacheReadInputTokens`

              The number of input tokens read from the cache.

            - `long inputTokens`

              The number of input tokens which were used.

            - `Model model`

              The model that will complete your prompt.

              See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

            - `long outputTokens`

              The number of output tokens which were used.

            - `JsonValue; type "advisor_message"constant`

              Usage for an advisor sub-inference iteration

              - `ADVISOR_MESSAGE("advisor_message")`

          - `class BetaFallbackMessageIterationUsage:`

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

            - `Optional<BetaCacheCreation> cacheCreation`

              Breakdown of cached tokens by TTL

            - `long cacheCreationInputTokens`

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

            - `long cacheReadInputTokens`

              The number of input tokens read from the cache.

            - `long inputTokens`

              The number of input tokens which were used.

            - `Model model`

              The model that will complete your prompt.

              See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

            - `long outputTokens`

              The number of output tokens which were used.

            - `JsonValue; type "fallback_message"constant`

              Usage for the fallback-model attempt that served the response

              - `FALLBACK_MESSAGE("fallback_message")`

        - `long outputTokens`

          The number of output tokens which were used.

        - `Optional<BetaOutputTokensDetails> outputTokensDetails`

          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.

          - `long thinkingTokens`

            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.

        - `Optional<BetaServerToolUsage> serverToolUse`

          The number of server tool requests.

          - `long webFetchRequests`

            The number of web fetch tool requests.

          - `long webSearchRequests`

            The number of web search tool requests.

        - `Optional<ServiceTier> serviceTier`

          If the request used the priority, standard, or batch tier.

          - `STANDARD("standard")`

          - `PRIORITY("priority")`

          - `BATCH("batch")`

        - `Optional<Speed> speed`

          The inference speed mode used for this request.

          - `STANDARD("standard")`

          - `FAST("fast")`

    - `JsonValue; type "succeeded"constant`

      - `SUCCEEDED("succeeded")`

  - `class BetaMessageBatchErroredResult:`

    - `BetaErrorResponse error`

      - `BetaError error`

        - `class BetaInvalidRequestError:`

          - `String message`

          - `JsonValue; type "invalid_request_error"constant`

            - `INVALID_REQUEST_ERROR("invalid_request_error")`

        - `class BetaAuthenticationError:`

          - `String message`

          - `JsonValue; type "authentication_error"constant`

            - `AUTHENTICATION_ERROR("authentication_error")`

        - `class BetaBillingError:`

          - `String message`

          - `JsonValue; type "billing_error"constant`

            - `BILLING_ERROR("billing_error")`

        - `class BetaPermissionError:`

          - `String message`

          - `JsonValue; type "permission_error"constant`

            - `PERMISSION_ERROR("permission_error")`

        - `class BetaNotFoundError:`

          - `String message`

          - `JsonValue; type "not_found_error"constant`

            - `NOT_FOUND_ERROR("not_found_error")`

        - `class BetaRateLimitError:`

          - `String message`

          - `JsonValue; type "rate_limit_error"constant`

            - `RATE_LIMIT_ERROR("rate_limit_error")`

        - `class BetaGatewayTimeoutError:`

          - `String message`

          - `JsonValue; type "timeout_error"constant`

            - `TIMEOUT_ERROR("timeout_error")`

        - `class BetaApiError:`

          - `String message`

          - `JsonValue; type "api_error"constant`

            - `API_ERROR("api_error")`

        - `class BetaOverloadedError:`

          - `String message`

          - `JsonValue; type "overloaded_error"constant`

            - `OVERLOADED_ERROR("overloaded_error")`

      - `Optional<String> requestId`

      - `JsonValue; type "error"constant`

        - `ERROR("error")`

    - `JsonValue; type "errored"constant`

      - `ERRORED("errored")`

  - `class BetaMessageBatchCanceledResult:`

    - `JsonValue; type "canceled"constant`

      - `CANCELED("canceled")`

  - `class BetaMessageBatchExpiredResult:`

    - `JsonValue; type "expired"constant`

      - `EXPIRED("expired")`

### Beta Message Batch Succeeded Result

- `class BetaMessageBatchSucceededResult:`

  - `BetaMessage message`

    - `String id`

      Unique object identifier.

      The format and length of IDs may change over time.

    - `Optional<BetaContainer> container`

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

      - `String id`

        Identifier for the container used in this request

      - `LocalDateTime expiresAt`

        The time at which the container will expire.

      - `Optional<List<BetaSkill>> skills`

        Skills loaded in the container

        - `String skillId`

          Skill ID

        - `Type type`

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

          - `ANTHROPIC("anthropic")`

          - `CUSTOM("custom")`

        - `String version`

          Skill version or 'latest' for most recent version

    - `List<BetaContentBlock> content`

      Content generated by the model.

      This is an array of content blocks, each of which has a `type` that determines its shape.

      Example:

      ```json
      [{"type": "text", "text": "Hi, I'm Claude."}]
      ```

      If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.

      For example, if the input `messages` were:

      ```json
      [
        {"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)"}]
      ```

      - `class BetaTextBlock:`

        - `Optional<List<BetaTextCitation>> citations`

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

          - `class BetaCitationCharLocation:`

            - `String citedText`

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endCharIndex`

            - `Optional<String> fileId`

            - `long startCharIndex`

            - `JsonValue; type "char_location"constant`

              - `CHAR_LOCATION("char_location")`

          - `class BetaCitationPageLocation:`

            - `String citedText`

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endPageNumber`

            - `Optional<String> fileId`

            - `long startPageNumber`

            - `JsonValue; type "page_location"constant`

              - `PAGE_LOCATION("page_location")`

          - `class BetaCitationContentBlockLocation:`

            - `String citedText`

              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.

            - `long documentIndex`

            - `Optional<String> documentTitle`

            - `long endBlockIndex`

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

            - `Optional<String> fileId`

            - `long startBlockIndex`

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

            - `JsonValue; type "content_block_location"constant`

              - `CONTENT_BLOCK_LOCATION("content_block_location")`

          - `class BetaCitationsWebSearchResultLocation:`

            - `String citedText`

            - `String encryptedIndex`

            - `Optional<String> title`

            - `JsonValue; type "web_search_result_location"constant`

              - `WEB_SEARCH_RESULT_LOCATION("web_search_result_location")`

            - `String url`

          - `class BetaCitationSearchResultLocation:`

            - `String citedText`

              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.

            - `long endBlockIndex`

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

            - `long searchResultIndex`

              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.

            - `String source`

            - `long startBlockIndex`

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

            - `Optional<String> title`

            - `JsonValue; type "search_result_location"constant`

              - `SEARCH_RESULT_LOCATION("search_result_location")`

        - `String text`

        - `JsonValue; type "text"constant`

          - `TEXT("text")`

      - `class BetaThinkingBlock:`

        - `String signature`

        - `String thinking`

        - `JsonValue; type "thinking"constant`

          - `THINKING("thinking")`

      - `class BetaRedactedThinkingBlock:`

        - `String data`

        - `JsonValue; type "redacted_thinking"constant`

          - `REDACTED_THINKING("redacted_thinking")`

      - `class BetaToolUseBlock:`

        - `String id`

        - `Input input`

        - `String name`

        - `JsonValue; type "tool_use"constant`

          - `TOOL_USE("tool_use")`

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

            - `JsonValue; type "direct"constant`

              - `DIRECT("direct")`

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

            - `String toolId`

            - `JsonValue; type "code_execution_20250825"constant`

              - `CODE_EXECUTION_20250825("code_execution_20250825")`

          - `class BetaServerToolCaller20260120:`

            - `String toolId`

            - `JsonValue; type "code_execution_20260120"constant`

              - `CODE_EXECUTION_20260120("code_execution_20260120")`

      - `class BetaServerToolUseBlock:`

        - `String id`

        - `Input input`

        - `Name name`

          - `ADVISOR("advisor")`

          - `WEB_SEARCH("web_search")`

          - `WEB_FETCH("web_fetch")`

          - `CODE_EXECUTION("code_execution")`

          - `BASH_CODE_EXECUTION("bash_code_execution")`

          - `TEXT_EDITOR_CODE_EXECUTION("text_editor_code_execution")`

          - `TOOL_SEARCH_TOOL_REGEX("tool_search_tool_regex")`

          - `TOOL_SEARCH_TOOL_BM25("tool_search_tool_bm25")`

        - `JsonValue; type "server_tool_use"constant`

          - `SERVER_TOOL_USE("server_tool_use")`

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

          - `class BetaServerToolCaller20260120:`

      - `class BetaWebSearchToolResultBlock:`

        - `BetaWebSearchToolResultBlockContent content`

          - `class BetaWebSearchToolResultError:`

            - `BetaWebSearchToolResultErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `MAX_USES_EXCEEDED("max_uses_exceeded")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `QUERY_TOO_LONG("query_too_long")`

              - `REQUEST_TOO_LARGE("request_too_large")`

            - `JsonValue; type "web_search_tool_result_error"constant`

              - `WEB_SEARCH_TOOL_RESULT_ERROR("web_search_tool_result_error")`

          - `List<BetaWebSearchResultBlock>`

            - `String encryptedContent`

            - `Optional<String> pageAge`

            - `String title`

            - `JsonValue; type "web_search_result"constant`

              - `WEB_SEARCH_RESULT("web_search_result")`

            - `String url`

        - `String toolUseId`

        - `JsonValue; type "web_search_tool_result"constant`

          - `WEB_SEARCH_TOOL_RESULT("web_search_tool_result")`

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

          - `class BetaServerToolCaller20260120:`

      - `class BetaWebFetchToolResultBlock:`

        - `Content content`

          - `class BetaWebFetchToolResultErrorBlock:`

            - `BetaWebFetchToolResultErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `URL_TOO_LONG("url_too_long")`

              - `URL_NOT_ALLOWED("url_not_allowed")`

              - `URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")`

              - `URL_NOT_ACCESSIBLE("url_not_accessible")`

              - `UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `MAX_USES_EXCEEDED("max_uses_exceeded")`

              - `UNAVAILABLE("unavailable")`

            - `JsonValue; type "web_fetch_tool_result_error"constant`

              - `WEB_FETCH_TOOL_RESULT_ERROR("web_fetch_tool_result_error")`

          - `class BetaWebFetchBlock:`

            - `BetaDocumentBlock content`

              - `Optional<BetaCitationConfig> citations`

                Citation configuration for the document

                - `boolean enabled`

              - `Source source`

                - `class BetaBase64PdfSource:`

                  - `String data`

                  - `JsonValue; mediaType "application/pdf"constant`

                    - `APPLICATION_PDF("application/pdf")`

                  - `JsonValue; type "base64"constant`

                    - `BASE64("base64")`

                - `class BetaPlainTextSource:`

                  - `String data`

                  - `JsonValue; mediaType "text/plain"constant`

                    - `TEXT_PLAIN("text/plain")`

                  - `JsonValue; type "text"constant`

                    - `TEXT("text")`

              - `Optional<String> title`

                The title of the document

              - `JsonValue; type "document"constant`

                - `DOCUMENT("document")`

            - `Optional<String> retrievedAt`

              ISO 8601 timestamp when the content was retrieved

            - `JsonValue; type "web_fetch_result"constant`

              - `WEB_FETCH_RESULT("web_fetch_result")`

            - `String url`

              Fetched content URL

        - `String toolUseId`

        - `JsonValue; type "web_fetch_tool_result"constant`

          - `WEB_FETCH_TOOL_RESULT("web_fetch_tool_result")`

        - `Optional<Caller> caller`

          Tool invocation directly from the model.

          - `class BetaDirectCaller:`

            Tool invocation directly from the model.

          - `class BetaServerToolCaller:`

            Tool invocation generated by a server-side tool.

          - `class BetaServerToolCaller20260120:`

      - `class BetaAdvisorToolResultBlock:`

        - `Content content`

          - `class BetaAdvisorToolResultError:`

            - `ErrorCode errorCode`

              - `MAX_USES_EXCEEDED("max_uses_exceeded")`

              - `PROMPT_TOO_LONG("prompt_too_long")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `OVERLOADED("overloaded")`

              - `UNAVAILABLE("unavailable")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `MODEL_NOT_FOUND("model_not_found")`

            - `JsonValue; type "advisor_tool_result_error"constant`

              - `ADVISOR_TOOL_RESULT_ERROR("advisor_tool_result_error")`

          - `class BetaAdvisorResultBlock:`

            - `Optional<String> stopReason`

              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.

            - `String text`

            - `JsonValue; type "advisor_result"constant`

              - `ADVISOR_RESULT("advisor_result")`

          - `class BetaAdvisorRedactedResultBlock:`

            - `String encryptedContent`

              Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

            - `Optional<String> stopReason`

              The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`).

            - `JsonValue; type "advisor_redacted_result"constant`

              - `ADVISOR_REDACTED_RESULT("advisor_redacted_result")`

        - `String toolUseId`

        - `JsonValue; type "advisor_tool_result"constant`

          - `ADVISOR_TOOL_RESULT("advisor_tool_result")`

      - `class BetaCodeExecutionToolResultBlock:`

        - `BetaCodeExecutionToolResultBlockContent content`

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

          - `class BetaCodeExecutionToolResultError:`

            - `BetaCodeExecutionToolResultErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `JsonValue; type "code_execution_tool_result_error"constant`

              - `CODE_EXECUTION_TOOL_RESULT_ERROR("code_execution_tool_result_error")`

          - `class BetaCodeExecutionResultBlock:`

            - `List<BetaCodeExecutionOutputBlock> content`

              - `String fileId`

              - `JsonValue; type "code_execution_output"constant`

                - `CODE_EXECUTION_OUTPUT("code_execution_output")`

            - `long returnCode`

            - `String stderr`

            - `String stdout`

            - `JsonValue; type "code_execution_result"constant`

              - `CODE_EXECUTION_RESULT("code_execution_result")`

          - `class BetaEncryptedCodeExecutionResultBlock:`

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

            - `List<BetaCodeExecutionOutputBlock> content`

              - `String fileId`

              - `JsonValue; type "code_execution_output"constant`

            - `String encryptedStdout`

            - `long returnCode`

            - `String stderr`

            - `JsonValue; type "encrypted_code_execution_result"constant`

              - `ENCRYPTED_CODE_EXECUTION_RESULT("encrypted_code_execution_result")`

        - `String toolUseId`

        - `JsonValue; type "code_execution_tool_result"constant`

          - `CODE_EXECUTION_TOOL_RESULT("code_execution_tool_result")`

      - `class BetaBashCodeExecutionToolResultBlock:`

        - `Content content`

          - `class BetaBashCodeExecutionToolResultError:`

            - `ErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `OUTPUT_FILE_TOO_LARGE("output_file_too_large")`

            - `JsonValue; type "bash_code_execution_tool_result_error"constant`

              - `BASH_CODE_EXECUTION_TOOL_RESULT_ERROR("bash_code_execution_tool_result_error")`

          - `class BetaBashCodeExecutionResultBlock:`

            - `List<BetaBashCodeExecutionOutputBlock> content`

              - `String fileId`

              - `JsonValue; type "bash_code_execution_output"constant`

                - `BASH_CODE_EXECUTION_OUTPUT("bash_code_execution_output")`

            - `long returnCode`

            - `String stderr`

            - `String stdout`

            - `JsonValue; type "bash_code_execution_result"constant`

              - `BASH_CODE_EXECUTION_RESULT("bash_code_execution_result")`

        - `String toolUseId`

        - `JsonValue; type "bash_code_execution_tool_result"constant`

          - `BASH_CODE_EXECUTION_TOOL_RESULT("bash_code_execution_tool_result")`

      - `class BetaTextEditorCodeExecutionToolResultBlock:`

        - `Content content`

          - `class BetaTextEditorCodeExecutionToolResultError:`

            - `ErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

              - `FILE_NOT_FOUND("file_not_found")`

            - `Optional<String> errorMessage`

            - `JsonValue; type "text_editor_code_execution_tool_result_error"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT_ERROR("text_editor_code_execution_tool_result_error")`

          - `class BetaTextEditorCodeExecutionViewResultBlock:`

            - `String content`

            - `FileType fileType`

              - `TEXT("text")`

              - `IMAGE("image")`

              - `PDF("pdf")`

            - `Optional<Long> numLines`

            - `Optional<Long> startLine`

            - `Optional<Long> totalLines`

            - `JsonValue; type "text_editor_code_execution_view_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_VIEW_RESULT("text_editor_code_execution_view_result")`

          - `class BetaTextEditorCodeExecutionCreateResultBlock:`

            - `boolean isFileUpdate`

            - `JsonValue; type "text_editor_code_execution_create_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_CREATE_RESULT("text_editor_code_execution_create_result")`

          - `class BetaTextEditorCodeExecutionStrReplaceResultBlock:`

            - `Optional<List<String>> lines`

            - `Optional<Long> newLines`

            - `Optional<Long> newStart`

            - `Optional<Long> oldLines`

            - `Optional<Long> oldStart`

            - `JsonValue; type "text_editor_code_execution_str_replace_result"constant`

              - `TEXT_EDITOR_CODE_EXECUTION_STR_REPLACE_RESULT("text_editor_code_execution_str_replace_result")`

        - `String toolUseId`

        - `JsonValue; type "text_editor_code_execution_tool_result"constant`

          - `TEXT_EDITOR_CODE_EXECUTION_TOOL_RESULT("text_editor_code_execution_tool_result")`

      - `class BetaToolSearchToolResultBlock:`

        - `Content content`

          - `class BetaToolSearchToolResultError:`

            - `ErrorCode errorCode`

              - `INVALID_TOOL_INPUT("invalid_tool_input")`

              - `UNAVAILABLE("unavailable")`

              - `TOO_MANY_REQUESTS("too_many_requests")`

              - `EXECUTION_TIME_EXCEEDED("execution_time_exceeded")`

            - `Optional<String> errorMessage`

            - `JsonValue; type "tool_search_tool_result_error"constant`

              - `TOOL_SEARCH_TOOL_RESULT_ERROR("tool_search_tool_result_error")`

          - `class BetaToolSearchToolSearchResultBlock:`

            - `List<BetaToolReferenceBlock> toolReferences`

              - `String toolName`

              - `JsonValue; type "tool_reference"constant`

                - `TOOL_REFERENCE("tool_reference")`

            - `JsonValue; type "tool_search_tool_search_result"constant`

              - `TOOL_SEARCH_TOOL_SEARCH_RESULT("tool_search_tool_search_result")`

        - `String toolUseId`

        - `JsonValue; type "tool_search_tool_result"constant`

          - `TOOL_SEARCH_TOOL_RESULT("tool_search_tool_result")`

      - `class BetaMcpToolUseBlock:`

        - `String id`

        - `Input input`

        - `String name`

          The name of the MCP tool

        - `String serverName`

          The name of the MCP server

        - `JsonValue; type "mcp_tool_use"constant`

          - `MCP_TOOL_USE("mcp_tool_use")`

      - `class BetaMcpToolResultBlock:`

        - `Content content`

          - `String`

          - `List<BetaTextBlock>`

            - `Optional<List<BetaTextCitation>> citations`

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

            - `String text`

            - `JsonValue; type "text"constant`

        - `boolean isError`

        - `String toolUseId`

        - `JsonValue; type "mcp_tool_result"constant`

          - `MCP_TOOL_RESULT("mcp_tool_result")`

      - `class BetaContainerUploadBlock:`

        Response model for a file uploaded to the container.

        - `String fileId`

        - `JsonValue; type "container_upload"constant`

          - `CONTAINER_UPLOAD("container_upload")`

      - `class BetaCompactionBlock:`

        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.

        - `Optional<String> content`

          Summary of compacted content, or null if compaction failed

        - `Optional<String> encryptedContent`

          Opaque metadata from prior compaction, to be round-tripped verbatim

        - `JsonValue; type "compaction"constant`

          - `COMPACTION("compaction")`

      - `class BetaFallbackBlock:`

        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 routed directly by the sticky decision 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.

        - `BetaFallbackInfo from`

          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.

          - `Model model`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

            - `CLAUDE_FABLE_5("claude-fable-5")`

              Next generation of intelligence for the hardest knowledge work and coding problems

            - `CLAUDE_MYTHOS_5("claude-mythos-5")`

              Most capable model for cybersecurity and biology research

            - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

              Frontier intelligence for long-running agents and coding

            - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

              Frontier intelligence for long-running agents and coding

            - `CLAUDE_MYTHOS_PREVIEW("claude-mythos-preview")`

              New class of intelligence, strongest in coding and cybersecurity

            - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

              Frontier intelligence for long-running agents and coding

            - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

              Best combination of speed and intelligence

            - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

              Fastest model with near-frontier intelligence

            - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

              Fastest model with near-frontier intelligence

            - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

              Premium model combining maximum intelligence with practical performance

            - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

              Premium model combining maximum intelligence with practical performance

            - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

              High-performance model for agents and coding

            - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

              High-performance model for agents and coding

            - `CLAUDE_OPUS_4_1("claude-opus-4-1")`

              Exceptional model for specialized complex tasks

            - `CLAUDE_OPUS_4_1_20250805("claude-opus-4-1-20250805")`

              Exceptional model for specialized complex tasks

            - `CLAUDE_OPUS_4_0("claude-opus-4-0")`

              Powerful model for complex tasks

            - `CLAUDE_OPUS_4_20250514("claude-opus-4-20250514")`

              Powerful model for complex tasks

            - `CLAUDE_SONNET_4_0("claude-sonnet-4-0")`

              High-performance model with extended thinking

            - `CLAUDE_SONNET_4_20250514("claude-sonnet-4-20250514")`

              High-performance model with extended thinking

            - `CLAUDE_3_HAIKU_20240307("claude-3-haiku-20240307")`

              Fast and cost-effective model

        - `BetaFallbackInfo to`

          The fallback model producing the content that follows this block. Its `model` is always the canonical id.

        - `JsonValue; type "fallback"constant`

          - `FALLBACK("fallback")`

    - `Optional<BetaContextManagementResponse> contextManagement`

      Context management response.

      Information about context management strategies applied during the request.

      - `List<AppliedEdit> appliedEdits`

        List of context management edits that were applied.

        - `class BetaClearToolUses20250919EditResponse:`

          - `long clearedInputTokens`

            Number of input tokens cleared by this edit.

          - `long clearedToolUses`

            Number of tool uses that were cleared.

          - `JsonValue; type "clear_tool_uses_20250919"constant`

            The type of context management edit applied.

            - `CLEAR_TOOL_USES_20250919("clear_tool_uses_20250919")`

        - `class BetaClearThinking20251015EditResponse:`

          - `long clearedInputTokens`

            Number of input tokens cleared by this edit.

          - `long clearedThinkingTurns`

            Number of thinking turns that were cleared.

          - `JsonValue; type "clear_thinking_20251015"constant`

            The type of context management edit applied.

            - `CLEAR_THINKING_20251015("clear_thinking_20251015")`

    - `Optional<BetaDiagnostics> diagnostics`

      Response envelope for request-level diagnostics. Present (possibly
      null) whenever the caller supplied `diagnostics` on the request.

      - `Optional<CacheMissReason> cacheMissReason`

        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.

        - `class BetaCacheMissModelChanged:`

          - `long cacheMissedInputTokens`

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

          - `JsonValue; type "model_changed"constant`

            - `MODEL_CHANGED("model_changed")`

        - `class BetaCacheMissSystemChanged:`

          - `long cacheMissedInputTokens`

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

          - `JsonValue; type "system_changed"constant`

            - `SYSTEM_CHANGED("system_changed")`

        - `class BetaCacheMissToolsChanged:`

          - `long cacheMissedInputTokens`

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

          - `JsonValue; type "tools_changed"constant`

            - `TOOLS_CHANGED("tools_changed")`

        - `class BetaCacheMissMessagesChanged:`

          - `long cacheMissedInputTokens`

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

          - `JsonValue; type "messages_changed"constant`

            - `MESSAGES_CHANGED("messages_changed")`

        - `class BetaCacheMissPreviousMessageNotFound:`

          - `JsonValue; type "previous_message_not_found"constant`

            - `PREVIOUS_MESSAGE_NOT_FOUND("previous_message_not_found")`

        - `class BetaCacheMissUnavailable:`

          - `JsonValue; type "unavailable"constant`

            - `UNAVAILABLE("unavailable")`

    - `Model model`

      The model that will complete your prompt.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `JsonValue; role "assistant"constant`

      Conversational role of the generated message.

      This will always be `"assistant"`.

      - `ASSISTANT("assistant")`

    - `Optional<BetaRefusalStopDetails> stopDetails`

      Structured information about a refusal.

      - `Optional<Category> category`

        The policy category that triggered the refusal.

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

        - `CYBER("cyber")`

        - `BIO("bio")`

        - `REASONING_EXTRACTION("reasoning_extraction")`

      - `Optional<String> explanation`

        Human-readable explanation of the refusal.

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

      - `Optional<String> fallbackCreditToken`

        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.

      - `Optional<Boolean> fallbackHasPrefillClaim`

        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.

      - `Optional<String> recommendedModel`

        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.

      - `JsonValue; type "refusal"constant`

        - `REFUSAL("refusal")`

    - `Optional<BetaStopReason> stopReason`

      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

      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.

      - `END_TURN("end_turn")`

      - `MAX_TOKENS("max_tokens")`

      - `STOP_SEQUENCE("stop_sequence")`

      - `TOOL_USE("tool_use")`

      - `PAUSE_TURN("pause_turn")`

      - `COMPACTION("compaction")`

      - `REFUSAL("refusal")`

      - `MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")`

    - `Optional<String> stopSequence`

      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.

    - `JsonValue; type "message"constant`

      Object type.

      For Messages, this is always `"message"`.

      - `MESSAGE("message")`

    - `BetaUsage usage`

      Billing and rate-limit usage.

      Anthropic'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 Claude.

      Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`.

      - `Optional<BetaCacheCreation> cacheCreation`

        Breakdown of cached tokens by TTL

        - `long ephemeral1hInputTokens`

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

        - `long ephemeral5mInputTokens`

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

      - `Optional<Long> cacheCreationInputTokens`

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

      - `Optional<Long> cacheReadInputTokens`

        The number of input tokens read from the cache.

      - `Optional<String> inferenceGeo`

        The geographic region where inference was performed for this request.

      - `long inputTokens`

        The number of input tokens which were used.

      - `Optional<List<BetaIterationsUsageItems>> iterations`

        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

        - `class BetaMessageIterationUsage:`

          Token usage for a sampling iteration.

          - `Optional<BetaCacheCreation> cacheCreation`

            Breakdown of cached tokens by TTL

          - `long cacheCreationInputTokens`

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

          - `long cacheReadInputTokens`

            The number of input tokens read from the cache.

          - `long inputTokens`

            The number of input tokens which were used.

          - `Model model`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `long outputTokens`

            The number of output tokens which were used.

          - `JsonValue; type "message"constant`

            Usage for a sampling iteration

            - `MESSAGE("message")`

        - `class BetaCompactionIterationUsage:`

          Token usage for a compaction iteration.

          - `Optional<BetaCacheCreation> cacheCreation`

            Breakdown of cached tokens by TTL

          - `long cacheCreationInputTokens`

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

          - `long cacheReadInputTokens`

            The number of input tokens read from the cache.

          - `long inputTokens`

            The number of input tokens which were used.

          - `long outputTokens`

            The number of output tokens which were used.

          - `JsonValue; type "compaction"constant`

            Usage for a compaction iteration

            - `COMPACTION("compaction")`

        - `class BetaAdvisorMessageIterationUsage:`

          Token usage for an advisor sub-inference iteration.

          - `Optional<BetaCacheCreation> cacheCreation`

            Breakdown of cached tokens by TTL

          - `long cacheCreationInputTokens`

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

          - `long cacheReadInputTokens`

            The number of input tokens read from the cache.

          - `long inputTokens`

            The number of input tokens which were used.

          - `Model model`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `long outputTokens`

            The number of output tokens which were used.

          - `JsonValue; type "advisor_message"constant`

            Usage for an advisor sub-inference iteration

            - `ADVISOR_MESSAGE("advisor_message")`

        - `class BetaFallbackMessageIterationUsage:`

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

          - `Optional<BetaCacheCreation> cacheCreation`

            Breakdown of cached tokens by TTL

          - `long cacheCreationInputTokens`

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

          - `long cacheReadInputTokens`

            The number of input tokens read from the cache.

          - `long inputTokens`

            The number of input tokens which were used.

          - `Model model`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `long outputTokens`

            The number of output tokens which were used.

          - `JsonValue; type "fallback_message"constant`

            Usage for the fallback-model attempt that served the response

            - `FALLBACK_MESSAGE("fallback_message")`

      - `long outputTokens`

        The number of output tokens which were used.

      - `Optional<BetaOutputTokensDetails> outputTokensDetails`

        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.

        - `long thinkingTokens`

          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.

      - `Optional<BetaServerToolUsage> serverToolUse`

        The number of server tool requests.

        - `long webFetchRequests`

          The number of web fetch tool requests.

        - `long webSearchRequests`

          The number of web search tool requests.

      - `Optional<ServiceTier> serviceTier`

        If the request used the priority, standard, or batch tier.

        - `STANDARD("standard")`

        - `PRIORITY("priority")`

        - `BATCH("batch")`

      - `Optional<Speed> speed`

        The inference speed mode used for this request.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `JsonValue; type "succeeded"constant`

    - `SUCCEEDED("succeeded")`

# Agents

## Create Agent

`BetaManagedAgentsAgent beta().agents().create(AgentCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/agents`

Create Agent

### Parameters

- `AgentCreateParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Model model`

    Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control

    - `enum BetaManagedAgentsModel:`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `class BetaManagedAgentsModelConfigParams:`

      An object that defines additional configuration control over model use

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `String name`

    Human-readable name for the agent.

  - `Optional<String> description`

    Description of what the agent does.

  - `Optional<List<BetaManagedAgentsUrlMcpServerParams>> mcpServers`

    MCP servers this agent connects to. Maximum 20. Names must be unique within the array.

    - `String name`

      Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.

    - `Type type`

      - `URL("url")`

    - `String url`

      Endpoint URL for the MCP server.

  - `Optional<Metadata> metadata`

    Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

  - `Optional<BetaManagedAgentsMultiagentParams> multiagent`

    A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster.

  - `Optional<List<BetaManagedAgentsSkillParams>> skills`

    Skills available to the agent.

    - `class BetaManagedAgentsAnthropicSkillParams:`

      An Anthropic-managed skill.

      - `String skillId`

        Identifier of the Anthropic skill (e.g., "xlsx").

      - `Type type`

        - `ANTHROPIC("anthropic")`

      - `Optional<String> version`

        Version to pin. Defaults to latest if omitted.

    - `class BetaManagedAgentsCustomSkillParams:`

      A user-created custom skill.

      - `String skillId`

        Tagged ID of the custom skill (e.g., "skill_01XJ5...").

      - `Type type`

        - `CUSTOM("custom")`

      - `Optional<String> version`

        Version to pin. Defaults to latest if omitted.

  - `Optional<String> system`

    System prompt for the agent.

  - `Optional<List<Tool>> tools`

    Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed.

    - `class BetaManagedAgentsAgentToolset20260401Params:`

      Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

      - `Optional<List<BetaManagedAgentsAgentToolConfigParams>> configs`

        Per-tool configuration overrides.

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `Optional<Boolean> enabled`

          Whether this tool is enabled and available to Claude. Overrides the default_config setting.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `Optional<BetaManagedAgentsAgentToolsetDefaultConfigParams> defaultConfig`

        Default configuration for all tools in a toolset.

        - `Optional<Boolean> enabled`

          Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

    - `class BetaManagedAgentsMcpToolsetParams:`

      Configuration for tools from an MCP server defined in `mcp_servers`.

      - `String mcpServerName`

        Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

      - `Optional<List<BetaManagedAgentsMcpToolConfigParams>> configs`

        Per-tool configuration overrides.

        - `String name`

          Name of the MCP tool to configure. 1-128 characters.

        - `Optional<Boolean> enabled`

          Whether this tool is enabled. Overrides the `default_config` setting.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Optional<BetaManagedAgentsMcpToolsetDefaultConfigParams> defaultConfig`

        Default configuration for all tools from an MCP server.

        - `Optional<Boolean> enabled`

          Whether tools are enabled by default. Defaults to true if not specified.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

    - `class BetaManagedAgentsCustomToolParams:`

      A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.

      - `String description`

        Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters.

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

        Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.

      - `Type type`

        - `CUSTOM("custom")`

### Returns

- `class BetaManagedAgentsAgent:`

  A Managed Agents `agent`.

  - `String id`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

  - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

    - `String name`

    - `Type type`

      - `URL("url")`

    - `String url`

  - `Metadata metadata`

  - `BetaManagedAgentsModelConfig model`

    Model identifier and configuration.

    - `BetaManagedAgentsModel id`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

  - `Optional<BetaManagedAgentsMultiagent> multiagent`

    Resolved coordinator topology with a concrete agent roster.

    - `List<BetaManagedAgentsAgentReference> agents`

      Agents the coordinator may spawn as session threads, each resolved to a specific version.

      - `String id`

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Type type`

      - `COORDINATOR("coordinator")`

  - `String name`

  - `List<Skill> skills`

    - `class BetaManagedAgentsAnthropicSkill:`

      A resolved Anthropic-managed skill.

      - `String skillId`

      - `Type type`

        - `ANTHROPIC("anthropic")`

      - `String version`

    - `class BetaManagedAgentsCustomSkill:`

      A resolved user-created custom skill.

      - `String skillId`

      - `Type type`

        - `CUSTOM("custom")`

      - `String version`

  - `Optional<String> system`

  - `List<Tool> tools`

    - `class BetaManagedAgentsAgentToolset20260401:`

      - `List<BetaManagedAgentsAgentToolConfig> configs`

        - `boolean enabled`

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

        Resolved default configuration for agent tools.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

    - `class BetaManagedAgentsMcpToolset:`

      - `List<BetaManagedAgentsMcpToolConfig> configs`

        - `boolean enabled`

        - `String name`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

        Resolved default configuration for all tools from an MCP server.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `String mcpServerName`

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

    - `class BetaManagedAgentsCustomTool:`

      A custom tool as returned in API responses.

      - `String description`

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

      - `Type type`

        - `CUSTOM("custom")`

  - `Type type`

    - `AGENT("agent")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `long version`

    The agent's current version. Starts at 1 and increments when the agent is modified.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.agents.AgentCreateParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsAgent;
import com.anthropic.models.beta.agents.BetaManagedAgentsModel;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        AgentCreateParams params = AgentCreateParams.builder()
            .model(BetaManagedAgentsModel.CLAUDE_SONNET_4_6)
            .name("My First Agent")
            .build();
        BetaManagedAgentsAgent betaManagedAgentsAgent = client.beta().agents().create(params);
    }
}
```

#### Response

```json
{
  "id": "agent_011CZkYpogX7uDKUyvBTophP",
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "description": "A general-purpose starter agent.",
  "mcp_servers": [
    {
      "name": "example-mcp",
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse"
    }
  ],
  "metadata": {
    "foo": "bar"
  },
  "model": {
    "id": "claude-sonnet-4-6",
    "speed": "standard"
  },
  "multiagent": {
    "agents": [
      {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "type": "agent",
        "version": 1
      }
    ],
    "type": "coordinator"
  },
  "name": "My First Agent",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "type": "custom",
      "version": "2"
    }
  ],
  "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
  "tools": [
    {
      "configs": [
        {
          "enabled": true,
          "name": "bash",
          "permission_policy": {
            "type": "always_allow"
          }
        }
      ],
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_ask"
        }
      },
      "type": "agent_toolset_20260401"
    }
  ],
  "type": "agent",
  "updated_at": "2026-03-15T10:00:00Z",
  "version": 1
}
```

## List Agents

`AgentListPage beta().agents().list(AgentListParamsparams = AgentListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/agents`

List Agents

### Parameters

- `AgentListParams params`

  - `Optional<LocalDateTime> createdAtGte`

    Return agents created at or after this time (inclusive).

  - `Optional<LocalDateTime> createdAtLte`

    Return agents created at or before this time (inclusive).

  - `Optional<Boolean> includeArchived`

    Include archived agents in results. Defaults to false.

  - `Optional<Long> limit`

    Maximum results per page. Default 20, maximum 100.

  - `Optional<String> page`

    Opaque pagination cursor from a previous response.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsAgent:`

  A Managed Agents `agent`.

  - `String id`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

  - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

    - `String name`

    - `Type type`

      - `URL("url")`

    - `String url`

  - `Metadata metadata`

  - `BetaManagedAgentsModelConfig model`

    Model identifier and configuration.

    - `BetaManagedAgentsModel id`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

  - `Optional<BetaManagedAgentsMultiagent> multiagent`

    Resolved coordinator topology with a concrete agent roster.

    - `List<BetaManagedAgentsAgentReference> agents`

      Agents the coordinator may spawn as session threads, each resolved to a specific version.

      - `String id`

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Type type`

      - `COORDINATOR("coordinator")`

  - `String name`

  - `List<Skill> skills`

    - `class BetaManagedAgentsAnthropicSkill:`

      A resolved Anthropic-managed skill.

      - `String skillId`

      - `Type type`

        - `ANTHROPIC("anthropic")`

      - `String version`

    - `class BetaManagedAgentsCustomSkill:`

      A resolved user-created custom skill.

      - `String skillId`

      - `Type type`

        - `CUSTOM("custom")`

      - `String version`

  - `Optional<String> system`

  - `List<Tool> tools`

    - `class BetaManagedAgentsAgentToolset20260401:`

      - `List<BetaManagedAgentsAgentToolConfig> configs`

        - `boolean enabled`

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

        Resolved default configuration for agent tools.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

    - `class BetaManagedAgentsMcpToolset:`

      - `List<BetaManagedAgentsMcpToolConfig> configs`

        - `boolean enabled`

        - `String name`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

        Resolved default configuration for all tools from an MCP server.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `String mcpServerName`

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

    - `class BetaManagedAgentsCustomTool:`

      A custom tool as returned in API responses.

      - `String description`

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

      - `Type type`

        - `CUSTOM("custom")`

  - `Type type`

    - `AGENT("agent")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `long version`

    The agent's current version. Starts at 1 and increments when the agent is modified.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.agents.AgentListPage;
import com.anthropic.models.beta.agents.AgentListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        AgentListPage page = client.beta().agents().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "agent_011CZkYpogX7uDKUyvBTophP",
      "archived_at": null,
      "created_at": "2026-03-15T10:00:00Z",
      "description": "A general-purpose starter agent.",
      "mcp_servers": [
        {
          "name": "example-mcp",
          "type": "url",
          "url": "https://example-server.modelcontextprotocol.io/sse"
        }
      ],
      "metadata": {
        "foo": "bar"
      },
      "model": {
        "id": "claude-sonnet-4-6",
        "speed": "standard"
      },
      "multiagent": {
        "agents": [
          {
            "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
            "type": "agent",
            "version": 1
          }
        ],
        "type": "coordinator"
      },
      "name": "My First Agent",
      "skills": [
        {
          "skill_id": "xlsx",
          "type": "anthropic",
          "version": "1"
        },
        {
          "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
          "type": "custom",
          "version": "2"
        }
      ],
      "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
      "tools": [
        {
          "configs": [
            {
              "enabled": true,
              "name": "bash",
              "permission_policy": {
                "type": "always_allow"
              }
            }
          ],
          "default_config": {
            "enabled": true,
            "permission_policy": {
              "type": "always_ask"
            }
          },
          "type": "agent_toolset_20260401"
        }
      ],
      "type": "agent",
      "updated_at": "2026-03-15T10:00:00Z",
      "version": 1
    }
  ],
  "next_page": "next_page"
}
```

## Get Agent

`BetaManagedAgentsAgent beta().agents().retrieve(AgentRetrieveParamsparams = AgentRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/agents/{agent_id}`

Get Agent

### Parameters

- `AgentRetrieveParams params`

  - `Optional<String> agentId`

  - `Optional<Long> version`

    Agent version. Omit for the most recent version. Must be at least 1 if specified.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsAgent:`

  A Managed Agents `agent`.

  - `String id`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

  - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

    - `String name`

    - `Type type`

      - `URL("url")`

    - `String url`

  - `Metadata metadata`

  - `BetaManagedAgentsModelConfig model`

    Model identifier and configuration.

    - `BetaManagedAgentsModel id`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

  - `Optional<BetaManagedAgentsMultiagent> multiagent`

    Resolved coordinator topology with a concrete agent roster.

    - `List<BetaManagedAgentsAgentReference> agents`

      Agents the coordinator may spawn as session threads, each resolved to a specific version.

      - `String id`

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Type type`

      - `COORDINATOR("coordinator")`

  - `String name`

  - `List<Skill> skills`

    - `class BetaManagedAgentsAnthropicSkill:`

      A resolved Anthropic-managed skill.

      - `String skillId`

      - `Type type`

        - `ANTHROPIC("anthropic")`

      - `String version`

    - `class BetaManagedAgentsCustomSkill:`

      A resolved user-created custom skill.

      - `String skillId`

      - `Type type`

        - `CUSTOM("custom")`

      - `String version`

  - `Optional<String> system`

  - `List<Tool> tools`

    - `class BetaManagedAgentsAgentToolset20260401:`

      - `List<BetaManagedAgentsAgentToolConfig> configs`

        - `boolean enabled`

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

        Resolved default configuration for agent tools.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

    - `class BetaManagedAgentsMcpToolset:`

      - `List<BetaManagedAgentsMcpToolConfig> configs`

        - `boolean enabled`

        - `String name`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

        Resolved default configuration for all tools from an MCP server.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `String mcpServerName`

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

    - `class BetaManagedAgentsCustomTool:`

      A custom tool as returned in API responses.

      - `String description`

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

      - `Type type`

        - `CUSTOM("custom")`

  - `Type type`

    - `AGENT("agent")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `long version`

    The agent's current version. Starts at 1 and increments when the agent is modified.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.agents.AgentRetrieveParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsAgent;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsAgent betaManagedAgentsAgent = client.beta().agents().retrieve("agent_011CZkYpogX7uDKUyvBTophP");
    }
}
```

#### Response

```json
{
  "id": "agent_011CZkYpogX7uDKUyvBTophP",
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "description": "A general-purpose starter agent.",
  "mcp_servers": [
    {
      "name": "example-mcp",
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse"
    }
  ],
  "metadata": {
    "foo": "bar"
  },
  "model": {
    "id": "claude-sonnet-4-6",
    "speed": "standard"
  },
  "multiagent": {
    "agents": [
      {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "type": "agent",
        "version": 1
      }
    ],
    "type": "coordinator"
  },
  "name": "My First Agent",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "type": "custom",
      "version": "2"
    }
  ],
  "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
  "tools": [
    {
      "configs": [
        {
          "enabled": true,
          "name": "bash",
          "permission_policy": {
            "type": "always_allow"
          }
        }
      ],
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_ask"
        }
      },
      "type": "agent_toolset_20260401"
    }
  ],
  "type": "agent",
  "updated_at": "2026-03-15T10:00:00Z",
  "version": 1
}
```

## Update Agent

`BetaManagedAgentsAgent beta().agents().update(AgentUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/agents/{agent_id}`

Update Agent

### Parameters

- `AgentUpdateParams params`

  - `Optional<String> agentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `long version`

    The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version.

  - `Optional<String> description`

    Description. Omit to preserve; send empty string or null to clear.

  - `Optional<List<BetaManagedAgentsUrlMcpServerParams>> mcpServers`

    MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20.

    - `String name`

      Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.

    - `Type type`

      - `URL("url")`

    - `String url`

      Endpoint URL for the MCP server.

  - `Optional<Metadata> metadata`

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars.

  - `Optional<Model> model`

    Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared.

    - `enum BetaManagedAgentsModel:`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `class BetaManagedAgentsModelConfigParams:`

      An object that defines additional configuration control over model use

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `Optional<BetaManagedAgentsMultiagentParams> multiagent`

    A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster.

  - `Optional<String> name`

    Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.

  - `Optional<List<BetaManagedAgentsSkillParams>> skills`

    Skills. Full replacement. Omit to preserve; send empty array or null to clear.

    - `class BetaManagedAgentsAnthropicSkillParams:`

      An Anthropic-managed skill.

      - `String skillId`

        Identifier of the Anthropic skill (e.g., "xlsx").

      - `Type type`

        - `ANTHROPIC("anthropic")`

      - `Optional<String> version`

        Version to pin. Defaults to latest if omitted.

    - `class BetaManagedAgentsCustomSkillParams:`

      A user-created custom skill.

      - `String skillId`

        Tagged ID of the custom skill (e.g., "skill_01XJ5...").

      - `Type type`

        - `CUSTOM("custom")`

      - `Optional<String> version`

        Version to pin. Defaults to latest if omitted.

  - `Optional<String> system`

    System prompt. Omit to preserve; send empty string or null to clear.

  - `Optional<List<Tool>> tools`

    Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed.

    - `class BetaManagedAgentsAgentToolset20260401Params:`

      Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

      - `Optional<List<BetaManagedAgentsAgentToolConfigParams>> configs`

        Per-tool configuration overrides.

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `Optional<Boolean> enabled`

          Whether this tool is enabled and available to Claude. Overrides the default_config setting.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `Optional<BetaManagedAgentsAgentToolsetDefaultConfigParams> defaultConfig`

        Default configuration for all tools in a toolset.

        - `Optional<Boolean> enabled`

          Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

    - `class BetaManagedAgentsMcpToolsetParams:`

      Configuration for tools from an MCP server defined in `mcp_servers`.

      - `String mcpServerName`

        Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

      - `Optional<List<BetaManagedAgentsMcpToolConfigParams>> configs`

        Per-tool configuration overrides.

        - `String name`

          Name of the MCP tool to configure. 1-128 characters.

        - `Optional<Boolean> enabled`

          Whether this tool is enabled. Overrides the `default_config` setting.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Optional<BetaManagedAgentsMcpToolsetDefaultConfigParams> defaultConfig`

        Default configuration for all tools from an MCP server.

        - `Optional<Boolean> enabled`

          Whether tools are enabled by default. Defaults to true if not specified.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

    - `class BetaManagedAgentsCustomToolParams:`

      A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.

      - `String description`

        Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters.

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

        Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.

      - `Type type`

        - `CUSTOM("custom")`

### Returns

- `class BetaManagedAgentsAgent:`

  A Managed Agents `agent`.

  - `String id`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

  - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

    - `String name`

    - `Type type`

      - `URL("url")`

    - `String url`

  - `Metadata metadata`

  - `BetaManagedAgentsModelConfig model`

    Model identifier and configuration.

    - `BetaManagedAgentsModel id`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

  - `Optional<BetaManagedAgentsMultiagent> multiagent`

    Resolved coordinator topology with a concrete agent roster.

    - `List<BetaManagedAgentsAgentReference> agents`

      Agents the coordinator may spawn as session threads, each resolved to a specific version.

      - `String id`

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Type type`

      - `COORDINATOR("coordinator")`

  - `String name`

  - `List<Skill> skills`

    - `class BetaManagedAgentsAnthropicSkill:`

      A resolved Anthropic-managed skill.

      - `String skillId`

      - `Type type`

        - `ANTHROPIC("anthropic")`

      - `String version`

    - `class BetaManagedAgentsCustomSkill:`

      A resolved user-created custom skill.

      - `String skillId`

      - `Type type`

        - `CUSTOM("custom")`

      - `String version`

  - `Optional<String> system`

  - `List<Tool> tools`

    - `class BetaManagedAgentsAgentToolset20260401:`

      - `List<BetaManagedAgentsAgentToolConfig> configs`

        - `boolean enabled`

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

        Resolved default configuration for agent tools.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

    - `class BetaManagedAgentsMcpToolset:`

      - `List<BetaManagedAgentsMcpToolConfig> configs`

        - `boolean enabled`

        - `String name`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

        Resolved default configuration for all tools from an MCP server.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `String mcpServerName`

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

    - `class BetaManagedAgentsCustomTool:`

      A custom tool as returned in API responses.

      - `String description`

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

      - `Type type`

        - `CUSTOM("custom")`

  - `Type type`

    - `AGENT("agent")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `long version`

    The agent's current version. Starts at 1 and increments when the agent is modified.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.agents.AgentUpdateParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsAgent;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        AgentUpdateParams params = AgentUpdateParams.builder()
            .agentId("agent_011CZkYpogX7uDKUyvBTophP")
            .version(1)
            .build();
        BetaManagedAgentsAgent betaManagedAgentsAgent = client.beta().agents().update(params);
    }
}
```

#### Response

```json
{
  "id": "agent_011CZkYpogX7uDKUyvBTophP",
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "description": "A general-purpose starter agent.",
  "mcp_servers": [
    {
      "name": "example-mcp",
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse"
    }
  ],
  "metadata": {
    "foo": "bar"
  },
  "model": {
    "id": "claude-sonnet-4-6",
    "speed": "standard"
  },
  "multiagent": {
    "agents": [
      {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "type": "agent",
        "version": 1
      }
    ],
    "type": "coordinator"
  },
  "name": "My First Agent",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "type": "custom",
      "version": "2"
    }
  ],
  "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
  "tools": [
    {
      "configs": [
        {
          "enabled": true,
          "name": "bash",
          "permission_policy": {
            "type": "always_allow"
          }
        }
      ],
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_ask"
        }
      },
      "type": "agent_toolset_20260401"
    }
  ],
  "type": "agent",
  "updated_at": "2026-03-15T10:00:00Z",
  "version": 1
}
```

## Archive Agent

`BetaManagedAgentsAgent beta().agents().archive(AgentArchiveParamsparams = AgentArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/agents/{agent_id}/archive`

Archive Agent

### Parameters

- `AgentArchiveParams params`

  - `Optional<String> agentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsAgent:`

  A Managed Agents `agent`.

  - `String id`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

  - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

    - `String name`

    - `Type type`

      - `URL("url")`

    - `String url`

  - `Metadata metadata`

  - `BetaManagedAgentsModelConfig model`

    Model identifier and configuration.

    - `BetaManagedAgentsModel id`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

  - `Optional<BetaManagedAgentsMultiagent> multiagent`

    Resolved coordinator topology with a concrete agent roster.

    - `List<BetaManagedAgentsAgentReference> agents`

      Agents the coordinator may spawn as session threads, each resolved to a specific version.

      - `String id`

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Type type`

      - `COORDINATOR("coordinator")`

  - `String name`

  - `List<Skill> skills`

    - `class BetaManagedAgentsAnthropicSkill:`

      A resolved Anthropic-managed skill.

      - `String skillId`

      - `Type type`

        - `ANTHROPIC("anthropic")`

      - `String version`

    - `class BetaManagedAgentsCustomSkill:`

      A resolved user-created custom skill.

      - `String skillId`

      - `Type type`

        - `CUSTOM("custom")`

      - `String version`

  - `Optional<String> system`

  - `List<Tool> tools`

    - `class BetaManagedAgentsAgentToolset20260401:`

      - `List<BetaManagedAgentsAgentToolConfig> configs`

        - `boolean enabled`

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

        Resolved default configuration for agent tools.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

    - `class BetaManagedAgentsMcpToolset:`

      - `List<BetaManagedAgentsMcpToolConfig> configs`

        - `boolean enabled`

        - `String name`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

        Resolved default configuration for all tools from an MCP server.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `String mcpServerName`

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

    - `class BetaManagedAgentsCustomTool:`

      A custom tool as returned in API responses.

      - `String description`

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

      - `Type type`

        - `CUSTOM("custom")`

  - `Type type`

    - `AGENT("agent")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `long version`

    The agent's current version. Starts at 1 and increments when the agent is modified.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.agents.AgentArchiveParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsAgent;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsAgent betaManagedAgentsAgent = client.beta().agents().archive("agent_011CZkYpogX7uDKUyvBTophP");
    }
}
```

#### Response

```json
{
  "id": "agent_011CZkYpogX7uDKUyvBTophP",
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "description": "A general-purpose starter agent.",
  "mcp_servers": [
    {
      "name": "example-mcp",
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse"
    }
  ],
  "metadata": {
    "foo": "bar"
  },
  "model": {
    "id": "claude-sonnet-4-6",
    "speed": "standard"
  },
  "multiagent": {
    "agents": [
      {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "type": "agent",
        "version": 1
      }
    ],
    "type": "coordinator"
  },
  "name": "My First Agent",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "type": "custom",
      "version": "2"
    }
  ],
  "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
  "tools": [
    {
      "configs": [
        {
          "enabled": true,
          "name": "bash",
          "permission_policy": {
            "type": "always_allow"
          }
        }
      ],
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_ask"
        }
      },
      "type": "agent_toolset_20260401"
    }
  ],
  "type": "agent",
  "updated_at": "2026-03-15T10:00:00Z",
  "version": 1
}
```

## Domain Types

### Beta Managed Agents Agent

- `class BetaManagedAgentsAgent:`

  A Managed Agents `agent`.

  - `String id`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

  - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

    - `String name`

    - `Type type`

      - `URL("url")`

    - `String url`

  - `Metadata metadata`

  - `BetaManagedAgentsModelConfig model`

    Model identifier and configuration.

    - `BetaManagedAgentsModel id`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

  - `Optional<BetaManagedAgentsMultiagent> multiagent`

    Resolved coordinator topology with a concrete agent roster.

    - `List<BetaManagedAgentsAgentReference> agents`

      Agents the coordinator may spawn as session threads, each resolved to a specific version.

      - `String id`

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Type type`

      - `COORDINATOR("coordinator")`

  - `String name`

  - `List<Skill> skills`

    - `class BetaManagedAgentsAnthropicSkill:`

      A resolved Anthropic-managed skill.

      - `String skillId`

      - `Type type`

        - `ANTHROPIC("anthropic")`

      - `String version`

    - `class BetaManagedAgentsCustomSkill:`

      A resolved user-created custom skill.

      - `String skillId`

      - `Type type`

        - `CUSTOM("custom")`

      - `String version`

  - `Optional<String> system`

  - `List<Tool> tools`

    - `class BetaManagedAgentsAgentToolset20260401:`

      - `List<BetaManagedAgentsAgentToolConfig> configs`

        - `boolean enabled`

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

        Resolved default configuration for agent tools.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

    - `class BetaManagedAgentsMcpToolset:`

      - `List<BetaManagedAgentsMcpToolConfig> configs`

        - `boolean enabled`

        - `String name`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

        Resolved default configuration for all tools from an MCP server.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `String mcpServerName`

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

    - `class BetaManagedAgentsCustomTool:`

      A custom tool as returned in API responses.

      - `String description`

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

      - `Type type`

        - `CUSTOM("custom")`

  - `Type type`

    - `AGENT("agent")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `long version`

    The agent's current version. Starts at 1 and increments when the agent is modified.

### Beta Managed Agents Agent Reference

- `class BetaManagedAgentsAgentReference:`

  A resolved agent reference with a concrete version.

  - `String id`

  - `Type type`

    - `AGENT("agent")`

  - `long version`

### Beta Managed Agents Agent Tool Config

- `class BetaManagedAgentsAgentToolConfig:`

  Configuration for a specific agent tool.

  - `boolean enabled`

  - `Name name`

    Built-in agent tool identifier.

    - `BASH("bash")`

    - `EDIT("edit")`

    - `READ("read")`

    - `WRITE("write")`

    - `GLOB("glob")`

    - `GREP("grep")`

    - `WEB_FETCH("web_fetch")`

    - `WEB_SEARCH("web_search")`

  - `PermissionPolicy permissionPolicy`

    Permission policy for tool execution.

    - `class BetaManagedAgentsAlwaysAllowPolicy:`

      Tool calls are automatically approved without user confirmation.

      - `Type type`

        - `ALWAYS_ALLOW("always_allow")`

    - `class BetaManagedAgentsAlwaysAskPolicy:`

      Tool calls require user confirmation before execution.

      - `Type type`

        - `ALWAYS_ASK("always_ask")`

### Beta Managed Agents Agent Tool Config Params

- `class BetaManagedAgentsAgentToolConfigParams:`

  Configuration override for a specific tool within a toolset.

  - `Name name`

    Built-in agent tool identifier.

    - `BASH("bash")`

    - `EDIT("edit")`

    - `READ("read")`

    - `WRITE("write")`

    - `GLOB("glob")`

    - `GREP("grep")`

    - `WEB_FETCH("web_fetch")`

    - `WEB_SEARCH("web_search")`

  - `Optional<Boolean> enabled`

    Whether this tool is enabled and available to Claude. Overrides the default_config setting.

  - `Optional<PermissionPolicy> permissionPolicy`

    Permission policy for tool execution.

    - `class BetaManagedAgentsAlwaysAllowPolicy:`

      Tool calls are automatically approved without user confirmation.

      - `Type type`

        - `ALWAYS_ALLOW("always_allow")`

    - `class BetaManagedAgentsAlwaysAskPolicy:`

      Tool calls require user confirmation before execution.

      - `Type type`

        - `ALWAYS_ASK("always_ask")`

### Beta Managed Agents Agent Toolset Default Config

- `class BetaManagedAgentsAgentToolsetDefaultConfig:`

  Resolved default configuration for agent tools.

  - `boolean enabled`

  - `PermissionPolicy permissionPolicy`

    Permission policy for tool execution.

    - `class BetaManagedAgentsAlwaysAllowPolicy:`

      Tool calls are automatically approved without user confirmation.

      - `Type type`

        - `ALWAYS_ALLOW("always_allow")`

    - `class BetaManagedAgentsAlwaysAskPolicy:`

      Tool calls require user confirmation before execution.

      - `Type type`

        - `ALWAYS_ASK("always_ask")`

### Beta Managed Agents Agent Toolset Default Config Params

- `class BetaManagedAgentsAgentToolsetDefaultConfigParams:`

  Default configuration for all tools in a toolset.

  - `Optional<Boolean> enabled`

    Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

  - `Optional<PermissionPolicy> permissionPolicy`

    Permission policy for tool execution.

    - `class BetaManagedAgentsAlwaysAllowPolicy:`

      Tool calls are automatically approved without user confirmation.

      - `Type type`

        - `ALWAYS_ALLOW("always_allow")`

    - `class BetaManagedAgentsAlwaysAskPolicy:`

      Tool calls require user confirmation before execution.

      - `Type type`

        - `ALWAYS_ASK("always_ask")`

### Beta Managed Agents Agent Toolset20260401

- `class BetaManagedAgentsAgentToolset20260401:`

  - `List<BetaManagedAgentsAgentToolConfig> configs`

    - `boolean enabled`

    - `Name name`

      Built-in agent tool identifier.

      - `BASH("bash")`

      - `EDIT("edit")`

      - `READ("read")`

      - `WRITE("write")`

      - `GLOB("glob")`

      - `GREP("grep")`

      - `WEB_FETCH("web_fetch")`

      - `WEB_SEARCH("web_search")`

    - `PermissionPolicy permissionPolicy`

      Permission policy for tool execution.

      - `class BetaManagedAgentsAlwaysAllowPolicy:`

        Tool calls are automatically approved without user confirmation.

        - `Type type`

          - `ALWAYS_ALLOW("always_allow")`

      - `class BetaManagedAgentsAlwaysAskPolicy:`

        Tool calls require user confirmation before execution.

        - `Type type`

          - `ALWAYS_ASK("always_ask")`

  - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

    Resolved default configuration for agent tools.

    - `boolean enabled`

    - `PermissionPolicy permissionPolicy`

      Permission policy for tool execution.

      - `class BetaManagedAgentsAlwaysAllowPolicy:`

        Tool calls are automatically approved without user confirmation.

      - `class BetaManagedAgentsAlwaysAskPolicy:`

        Tool calls require user confirmation before execution.

  - `Type type`

    - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

### Beta Managed Agents Agent Toolset20260401 Bash Input

- `class BetaManagedAgentsAgentToolset20260401BashInput:`

  Input payload for the `bash` tool of the
  `agent_toolset_20260401` toolset. All fields are optional;
  a normal invocation supplies `command`, while `restart=true`
  (with no `command`) reboots the runner-side bash session.

  - `Optional<String> command`

    Shell command to execute. Omit only when `restart` is true.

  - `Optional<Boolean> restart`

    When true, restart the persistent bash session instead of
    running a command. Subsequent calls without `restart` will
    run against the fresh session.

  - `Optional<Long> timeoutMs`

    Per-call timeout in milliseconds. Defaults to the
    runner-wide tool timeout when omitted or zero.

### Beta Managed Agents Agent Toolset20260401 Edit Input

- `class BetaManagedAgentsAgentToolset20260401EditInput:`

  Input payload for the `edit` tool. Performs a string
  replacement in the named file; by default `old_string` must
  occur exactly once.

  - `String filePath`

    Path of the file to edit.

  - `String newString`

    Replacement text.

  - `String oldString`

    Substring to find and replace.

  - `Optional<Boolean> replaceAll`

    When true, replace every occurrence of `old_string`
    instead of requiring a unique match.

### Beta Managed Agents Agent Toolset20260401 Glob Input

- `class BetaManagedAgentsAgentToolset20260401GlobInput:`

  Input payload for the `glob` tool. Returns paths matching a
  doublestar glob pattern, newest first.

  - `String pattern`

    Doublestar glob pattern (e.g. `**/*.go`). Absolute patterns
    are only permitted when the runner is configured to allow
    them.

  - `Optional<String> path`

    Optional directory root to search under. Defaults to the
    runner's working directory.

### Beta Managed Agents Agent Toolset20260401 Grep Input

- `class BetaManagedAgentsAgentToolset20260401GrepInput:`

  Input payload for the `grep` tool. Searches file contents for
  a regular expression, returning matching lines.

  - `String pattern`

    Regular expression to search for.

  - `Optional<String> path`

    Optional directory root to search under. Defaults to the
    runner's working directory.

### Beta Managed Agents Agent Toolset20260401 Params

- `class BetaManagedAgentsAgentToolset20260401Params:`

  Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.

  - `Type type`

    - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

  - `Optional<List<BetaManagedAgentsAgentToolConfigParams>> configs`

    Per-tool configuration overrides.

    - `Name name`

      Built-in agent tool identifier.

      - `BASH("bash")`

      - `EDIT("edit")`

      - `READ("read")`

      - `WRITE("write")`

      - `GLOB("glob")`

      - `GREP("grep")`

      - `WEB_FETCH("web_fetch")`

      - `WEB_SEARCH("web_search")`

    - `Optional<Boolean> enabled`

      Whether this tool is enabled and available to Claude. Overrides the default_config setting.

    - `Optional<PermissionPolicy> permissionPolicy`

      Permission policy for tool execution.

      - `class BetaManagedAgentsAlwaysAllowPolicy:`

        Tool calls are automatically approved without user confirmation.

        - `Type type`

          - `ALWAYS_ALLOW("always_allow")`

      - `class BetaManagedAgentsAlwaysAskPolicy:`

        Tool calls require user confirmation before execution.

        - `Type type`

          - `ALWAYS_ASK("always_ask")`

  - `Optional<BetaManagedAgentsAgentToolsetDefaultConfigParams> defaultConfig`

    Default configuration for all tools in a toolset.

    - `Optional<Boolean> enabled`

      Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

    - `Optional<PermissionPolicy> permissionPolicy`

      Permission policy for tool execution.

      - `class BetaManagedAgentsAlwaysAllowPolicy:`

        Tool calls are automatically approved without user confirmation.

      - `class BetaManagedAgentsAlwaysAskPolicy:`

        Tool calls require user confirmation before execution.

### Beta Managed Agents Agent Toolset20260401 Read Input

- `class BetaManagedAgentsAgentToolset20260401ReadInput:`

  Input payload for the `read` tool. Reads file contents
  relative to the runner's working directory (or absolute when
  the runner permits).

  - `String filePath`

    Path of the file to read.

  - `Optional<List<Long>> viewRange`

    Optional `[start_line, end_line]` 1-indexed inclusive
    range. When omitted the entire file is returned.
    `end_line` of 0 or negative means "to end of file".

### Beta Managed Agents Agent Toolset20260401 Write Input

- `class BetaManagedAgentsAgentToolset20260401WriteInput:`

  Input payload for the `write` tool. Writes (overwriting) the
  entire file contents.

  - `String content`

    Full file contents to write.

  - `String filePath`

    Path of the file to write.

### Beta Managed Agents Always Allow Policy

- `class BetaManagedAgentsAlwaysAllowPolicy:`

  Tool calls are automatically approved without user confirmation.

  - `Type type`

    - `ALWAYS_ALLOW("always_allow")`

### Beta Managed Agents Always Ask Policy

- `class BetaManagedAgentsAlwaysAskPolicy:`

  Tool calls require user confirmation before execution.

  - `Type type`

    - `ALWAYS_ASK("always_ask")`

### Beta Managed Agents Anthropic Skill

- `class BetaManagedAgentsAnthropicSkill:`

  A resolved Anthropic-managed skill.

  - `String skillId`

  - `Type type`

    - `ANTHROPIC("anthropic")`

  - `String version`

### Beta Managed Agents Anthropic Skill Params

- `class BetaManagedAgentsAnthropicSkillParams:`

  An Anthropic-managed skill.

  - `String skillId`

    Identifier of the Anthropic skill (e.g., "xlsx").

  - `Type type`

    - `ANTHROPIC("anthropic")`

  - `Optional<String> version`

    Version to pin. Defaults to latest if omitted.

### Beta Managed Agents Custom Skill

- `class BetaManagedAgentsCustomSkill:`

  A resolved user-created custom skill.

  - `String skillId`

  - `Type type`

    - `CUSTOM("custom")`

  - `String version`

### Beta Managed Agents Custom Skill Params

- `class BetaManagedAgentsCustomSkillParams:`

  A user-created custom skill.

  - `String skillId`

    Tagged ID of the custom skill (e.g., "skill_01XJ5...").

  - `Type type`

    - `CUSTOM("custom")`

  - `Optional<String> version`

    Version to pin. Defaults to latest if omitted.

### Beta Managed Agents Custom Tool

- `class BetaManagedAgentsCustomTool:`

  A custom tool as returned in API responses.

  - `String description`

  - `BetaManagedAgentsCustomToolInputSchema inputSchema`

    JSON Schema for custom tool input parameters.

    - `JsonValue; type "object"constant`

      - `OBJECT("object")`

    - `Optional<Properties> properties`

    - `Optional<List<String>> required`

  - `String name`

  - `Type type`

    - `CUSTOM("custom")`

### Beta Managed Agents Custom Tool Input Schema

- `class BetaManagedAgentsCustomToolInputSchema:`

  JSON Schema for custom tool input parameters.

  - `JsonValue; type "object"constant`

    - `OBJECT("object")`

  - `Optional<Properties> properties`

  - `Optional<List<String>> required`

### Beta Managed Agents Custom Tool Params

- `class BetaManagedAgentsCustomToolParams:`

  A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.

  - `String description`

    Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters.

  - `BetaManagedAgentsCustomToolInputSchema inputSchema`

    JSON Schema for custom tool input parameters.

    - `JsonValue; type "object"constant`

      - `OBJECT("object")`

    - `Optional<Properties> properties`

    - `Optional<List<String>> required`

  - `String name`

    Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.

  - `Type type`

    - `CUSTOM("custom")`

### Beta Managed Agents MCP Server URL Definition

- `class BetaManagedAgentsMcpServerUrlDefinition:`

  URL-based MCP server connection as returned in API responses.

  - `String name`

  - `Type type`

    - `URL("url")`

  - `String url`

### Beta Managed Agents MCP Tool Config

- `class BetaManagedAgentsMcpToolConfig:`

  Resolved configuration for a specific MCP tool.

  - `boolean enabled`

  - `String name`

  - `PermissionPolicy permissionPolicy`

    Permission policy for tool execution.

    - `class BetaManagedAgentsAlwaysAllowPolicy:`

      Tool calls are automatically approved without user confirmation.

      - `Type type`

        - `ALWAYS_ALLOW("always_allow")`

    - `class BetaManagedAgentsAlwaysAskPolicy:`

      Tool calls require user confirmation before execution.

      - `Type type`

        - `ALWAYS_ASK("always_ask")`

### Beta Managed Agents MCP Tool Config Params

- `class BetaManagedAgentsMcpToolConfigParams:`

  Configuration override for a specific MCP tool.

  - `String name`

    Name of the MCP tool to configure. 1-128 characters.

  - `Optional<Boolean> enabled`

    Whether this tool is enabled. Overrides the `default_config` setting.

  - `Optional<PermissionPolicy> permissionPolicy`

    Permission policy for tool execution.

    - `class BetaManagedAgentsAlwaysAllowPolicy:`

      Tool calls are automatically approved without user confirmation.

      - `Type type`

        - `ALWAYS_ALLOW("always_allow")`

    - `class BetaManagedAgentsAlwaysAskPolicy:`

      Tool calls require user confirmation before execution.

      - `Type type`

        - `ALWAYS_ASK("always_ask")`

### Beta Managed Agents MCP Toolset

- `class BetaManagedAgentsMcpToolset:`

  - `List<BetaManagedAgentsMcpToolConfig> configs`

    - `boolean enabled`

    - `String name`

    - `PermissionPolicy permissionPolicy`

      Permission policy for tool execution.

      - `class BetaManagedAgentsAlwaysAllowPolicy:`

        Tool calls are automatically approved without user confirmation.

        - `Type type`

          - `ALWAYS_ALLOW("always_allow")`

      - `class BetaManagedAgentsAlwaysAskPolicy:`

        Tool calls require user confirmation before execution.

        - `Type type`

          - `ALWAYS_ASK("always_ask")`

  - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

    Resolved default configuration for all tools from an MCP server.

    - `boolean enabled`

    - `PermissionPolicy permissionPolicy`

      Permission policy for tool execution.

      - `class BetaManagedAgentsAlwaysAllowPolicy:`

        Tool calls are automatically approved without user confirmation.

      - `class BetaManagedAgentsAlwaysAskPolicy:`

        Tool calls require user confirmation before execution.

  - `String mcpServerName`

  - `Type type`

    - `MCP_TOOLSET("mcp_toolset")`

### Beta Managed Agents MCP Toolset Default Config

- `class BetaManagedAgentsMcpToolsetDefaultConfig:`

  Resolved default configuration for all tools from an MCP server.

  - `boolean enabled`

  - `PermissionPolicy permissionPolicy`

    Permission policy for tool execution.

    - `class BetaManagedAgentsAlwaysAllowPolicy:`

      Tool calls are automatically approved without user confirmation.

      - `Type type`

        - `ALWAYS_ALLOW("always_allow")`

    - `class BetaManagedAgentsAlwaysAskPolicy:`

      Tool calls require user confirmation before execution.

      - `Type type`

        - `ALWAYS_ASK("always_ask")`

### Beta Managed Agents MCP Toolset Default Config Params

- `class BetaManagedAgentsMcpToolsetDefaultConfigParams:`

  Default configuration for all tools from an MCP server.

  - `Optional<Boolean> enabled`

    Whether tools are enabled by default. Defaults to true if not specified.

  - `Optional<PermissionPolicy> permissionPolicy`

    Permission policy for tool execution.

    - `class BetaManagedAgentsAlwaysAllowPolicy:`

      Tool calls are automatically approved without user confirmation.

      - `Type type`

        - `ALWAYS_ALLOW("always_allow")`

    - `class BetaManagedAgentsAlwaysAskPolicy:`

      Tool calls require user confirmation before execution.

      - `Type type`

        - `ALWAYS_ASK("always_ask")`

### Beta Managed Agents MCP Toolset Params

- `class BetaManagedAgentsMcpToolsetParams:`

  Configuration for tools from an MCP server defined in `mcp_servers`.

  - `String mcpServerName`

    Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.

  - `Type type`

    - `MCP_TOOLSET("mcp_toolset")`

  - `Optional<List<BetaManagedAgentsMcpToolConfigParams>> configs`

    Per-tool configuration overrides.

    - `String name`

      Name of the MCP tool to configure. 1-128 characters.

    - `Optional<Boolean> enabled`

      Whether this tool is enabled. Overrides the `default_config` setting.

    - `Optional<PermissionPolicy> permissionPolicy`

      Permission policy for tool execution.

      - `class BetaManagedAgentsAlwaysAllowPolicy:`

        Tool calls are automatically approved without user confirmation.

        - `Type type`

          - `ALWAYS_ALLOW("always_allow")`

      - `class BetaManagedAgentsAlwaysAskPolicy:`

        Tool calls require user confirmation before execution.

        - `Type type`

          - `ALWAYS_ASK("always_ask")`

  - `Optional<BetaManagedAgentsMcpToolsetDefaultConfigParams> defaultConfig`

    Default configuration for all tools from an MCP server.

    - `Optional<Boolean> enabled`

      Whether tools are enabled by default. Defaults to true if not specified.

    - `Optional<PermissionPolicy> permissionPolicy`

      Permission policy for tool execution.

      - `class BetaManagedAgentsAlwaysAllowPolicy:`

        Tool calls are automatically approved without user confirmation.

      - `class BetaManagedAgentsAlwaysAskPolicy:`

        Tool calls require user confirmation before execution.

### Beta Managed Agents Model

- `enum BetaManagedAgentsModel:`

  The model that will power your agent.

  See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

  - `CLAUDE_FABLE_5("claude-fable-5")`

    Next generation of intelligence for the hardest knowledge work and coding problems

  - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

    Frontier intelligence for long-running agents and coding

  - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

    Frontier intelligence for long-running agents and coding

  - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

    Most intelligent model for building agents and coding

  - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

    Best combination of speed and intelligence

  - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

    Fastest model with near-frontier intelligence

  - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

    Fastest model with near-frontier intelligence

  - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

    Premium model combining maximum intelligence with practical performance

  - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

    Premium model combining maximum intelligence with practical performance

  - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

    High-performance model for agents and coding

  - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

    High-performance model for agents and coding

### Beta Managed Agents Model Config

- `class BetaManagedAgentsModelConfig:`

  Model identifier and configuration.

  - `BetaManagedAgentsModel id`

    The model that will power your agent.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `CLAUDE_FABLE_5("claude-fable-5")`

      Next generation of intelligence for the hardest knowledge work and coding problems

    - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

      Most intelligent model for building agents and coding

    - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

      Best combination of speed and intelligence

    - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

      High-performance model for agents and coding

    - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

      High-performance model for agents and coding

  - `Optional<Speed> speed`

    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.

    - `STANDARD("standard")`

    - `FAST("fast")`

### Beta Managed Agents Model Config Params

- `class BetaManagedAgentsModelConfigParams:`

  An object that defines additional configuration control over model use

  - `BetaManagedAgentsModel id`

    The model that will power your agent.

    See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

    - `CLAUDE_FABLE_5("claude-fable-5")`

      Next generation of intelligence for the hardest knowledge work and coding problems

    - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

      Frontier intelligence for long-running agents and coding

    - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

      Most intelligent model for building agents and coding

    - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

      Best combination of speed and intelligence

    - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

      Fastest model with near-frontier intelligence

    - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

      Premium model combining maximum intelligence with practical performance

    - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

      High-performance model for agents and coding

    - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

      High-performance model for agents and coding

  - `Optional<Speed> speed`

    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.

    - `STANDARD("standard")`

    - `FAST("fast")`

### Beta Managed Agents Multiagent Coordinator

- `class BetaManagedAgentsMultiagentCoordinator:`

  Resolved coordinator topology with a concrete agent roster.

  - `List<BetaManagedAgentsAgentReference> agents`

    Agents the coordinator may spawn as session threads, each resolved to a specific version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Type type`

    - `COORDINATOR("coordinator")`

### Beta Managed Agents Multiagent Coordinator Params

- `class BetaManagedAgentsMultiagentCoordinatorParams:`

  A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster.

  - `List<BetaManagedAgentsMultiagentRosterEntryParams> agents`

    Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1).

    - `String`

    - `class BetaManagedAgentsAgentParams:`

      Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version

      - `String id`

        The `agent` ID.

      - `Type type`

        - `AGENT("agent")`

      - `Optional<Long> version`

        The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.

    - `class BetaManagedAgentsMultiagentSelfParams:`

      Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.

      - `Type type`

        - `SELF("self")`

  - `Type type`

    - `COORDINATOR("coordinator")`

### Beta Managed Agents Multiagent Self Params

- `class BetaManagedAgentsMultiagentSelfParams:`

  Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.

  - `Type type`

    - `SELF("self")`

### Beta Managed Agents Session Thread Agent

- `class BetaManagedAgentsSessionThreadAgent:`

  Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.

  - `String id`

  - `Optional<String> description`

  - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

    - `String name`

    - `Type type`

      - `URL("url")`

    - `String url`

  - `BetaManagedAgentsModelConfig model`

    Model identifier and configuration.

    - `BetaManagedAgentsModel id`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

  - `String name`

  - `List<Skill> skills`

    - `class BetaManagedAgentsAnthropicSkill:`

      A resolved Anthropic-managed skill.

      - `String skillId`

      - `Type type`

        - `ANTHROPIC("anthropic")`

      - `String version`

    - `class BetaManagedAgentsCustomSkill:`

      A resolved user-created custom skill.

      - `String skillId`

      - `Type type`

        - `CUSTOM("custom")`

      - `String version`

  - `Optional<String> system`

  - `List<Tool> tools`

    - `class BetaManagedAgentsAgentToolset20260401:`

      - `List<BetaManagedAgentsAgentToolConfig> configs`

        - `boolean enabled`

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

        Resolved default configuration for agent tools.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

    - `class BetaManagedAgentsMcpToolset:`

      - `List<BetaManagedAgentsMcpToolConfig> configs`

        - `boolean enabled`

        - `String name`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

        Resolved default configuration for all tools from an MCP server.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `String mcpServerName`

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

    - `class BetaManagedAgentsCustomTool:`

      A custom tool as returned in API responses.

      - `String description`

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

      - `Type type`

        - `CUSTOM("custom")`

  - `Type type`

    - `AGENT("agent")`

  - `long version`

### Beta Managed Agents Skill Params

- `class BetaManagedAgentsSkillParams: A class that can be one of several variants.union`

  Skill to load in the session container.

  - `class BetaManagedAgentsAnthropicSkillParams:`

    An Anthropic-managed skill.

    - `String skillId`

      Identifier of the Anthropic skill (e.g., "xlsx").

    - `Type type`

      - `ANTHROPIC("anthropic")`

    - `Optional<String> version`

      Version to pin. Defaults to latest if omitted.

  - `class BetaManagedAgentsCustomSkillParams:`

    A user-created custom skill.

    - `String skillId`

      Tagged ID of the custom skill (e.g., "skill_01XJ5...").

    - `Type type`

      - `CUSTOM("custom")`

    - `Optional<String> version`

      Version to pin. Defaults to latest if omitted.

### Beta Managed Agents URL MCP Server Params

- `class BetaManagedAgentsUrlMcpServerParams:`

  URL-based MCP server connection.

  - `String name`

    Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.

  - `Type type`

    - `URL("url")`

  - `String url`

    Endpoint URL for the MCP server.

# Versions

## List Agent Versions

`VersionListPage beta().agents().versions().list(VersionListParamsparams = VersionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/agents/{agent_id}/versions`

List Agent Versions

### Parameters

- `VersionListParams params`

  - `Optional<String> agentId`

  - `Optional<Long> limit`

    Maximum results per page. Default 20, maximum 100.

  - `Optional<String> page`

    Opaque pagination cursor.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsAgent:`

  A Managed Agents `agent`.

  - `String id`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

  - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

    - `String name`

    - `Type type`

      - `URL("url")`

    - `String url`

  - `Metadata metadata`

  - `BetaManagedAgentsModelConfig model`

    Model identifier and configuration.

    - `BetaManagedAgentsModel id`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

  - `Optional<BetaManagedAgentsMultiagent> multiagent`

    Resolved coordinator topology with a concrete agent roster.

    - `List<BetaManagedAgentsAgentReference> agents`

      Agents the coordinator may spawn as session threads, each resolved to a specific version.

      - `String id`

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Type type`

      - `COORDINATOR("coordinator")`

  - `String name`

  - `List<Skill> skills`

    - `class BetaManagedAgentsAnthropicSkill:`

      A resolved Anthropic-managed skill.

      - `String skillId`

      - `Type type`

        - `ANTHROPIC("anthropic")`

      - `String version`

    - `class BetaManagedAgentsCustomSkill:`

      A resolved user-created custom skill.

      - `String skillId`

      - `Type type`

        - `CUSTOM("custom")`

      - `String version`

  - `Optional<String> system`

  - `List<Tool> tools`

    - `class BetaManagedAgentsAgentToolset20260401:`

      - `List<BetaManagedAgentsAgentToolConfig> configs`

        - `boolean enabled`

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

        Resolved default configuration for agent tools.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

    - `class BetaManagedAgentsMcpToolset:`

      - `List<BetaManagedAgentsMcpToolConfig> configs`

        - `boolean enabled`

        - `String name`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

        Resolved default configuration for all tools from an MCP server.

        - `boolean enabled`

        - `PermissionPolicy permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `String mcpServerName`

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

    - `class BetaManagedAgentsCustomTool:`

      A custom tool as returned in API responses.

      - `String description`

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

      - `Type type`

        - `CUSTOM("custom")`

  - `Type type`

    - `AGENT("agent")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `long version`

    The agent's current version. Starts at 1 and increments when the agent is modified.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.agents.versions.VersionListPage;
import com.anthropic.models.beta.agents.versions.VersionListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        VersionListPage page = client.beta().agents().versions().list("agent_011CZkYpogX7uDKUyvBTophP");
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "agent_011CZkYpogX7uDKUyvBTophP",
      "archived_at": null,
      "created_at": "2026-03-15T10:00:00Z",
      "description": "A general-purpose starter agent.",
      "mcp_servers": [
        {
          "name": "example-mcp",
          "type": "url",
          "url": "https://example-server.modelcontextprotocol.io/sse"
        }
      ],
      "metadata": {
        "foo": "bar"
      },
      "model": {
        "id": "claude-sonnet-4-6",
        "speed": "standard"
      },
      "multiagent": {
        "agents": [
          {
            "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
            "type": "agent",
            "version": 1
          }
        ],
        "type": "coordinator"
      },
      "name": "My First Agent",
      "skills": [
        {
          "skill_id": "xlsx",
          "type": "anthropic",
          "version": "1"
        },
        {
          "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
          "type": "custom",
          "version": "2"
        }
      ],
      "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
      "tools": [
        {
          "configs": [
            {
              "enabled": true,
              "name": "bash",
              "permission_policy": {
                "type": "always_allow"
              }
            }
          ],
          "default_config": {
            "enabled": true,
            "permission_policy": {
              "type": "always_ask"
            }
          },
          "type": "agent_toolset_20260401"
        }
      ],
      "type": "agent",
      "updated_at": "2026-03-15T10:00:00Z",
      "version": 1
    }
  ],
  "next_page": "next_page"
}
```

# Environments

## Create Environment

`BetaEnvironment beta().environments().create(EnvironmentCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/environments`

Create a new environment with the specified configuration.

### Parameters

- `EnvironmentCreateParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `String name`

    Human-readable name for the environment

  - `Optional<Config> config`

    Environment configuration

    - `class BetaCloudConfigParams:`

      Request params for `cloud` environment configuration.

      Fields default to null; on update, omitted fields preserve the
      existing value.

      - `JsonValue; type "cloud"constant`

        Environment type

        - `CLOUD("cloud")`

      - `Optional<Networking> networking`

        Network configuration policy. Omit on update to preserve the existing value.

        - `class BetaUnrestrictedNetwork:`

          Unrestricted network access.

          - `JsonValue; type "unrestricted"constant`

            Network policy type

            - `UNRESTRICTED("unrestricted")`

        - `class BetaLimitedNetworkParams:`

          Limited network request params.

          Fields default to null; on update, omitted fields preserve the
          existing value.

          - `JsonValue; type "limited"constant`

            Network policy type

            - `LIMITED("limited")`

          - `Optional<Boolean> allowMcpServers`

            Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.

          - `Optional<Boolean> allowPackageManagers`

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`.

          - `Optional<List<String>> allowedHosts`

            Specifies domains the container can reach.

      - `Optional<BetaPackagesParams> packages`

        Specify packages (and optionally their versions) available in this environment.

        When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest.

        - `Optional<List<String>> apt`

          Ubuntu/Debian packages to install

        - `Optional<List<String>> cargo`

          Rust packages to install

        - `Optional<List<String>> gem`

          Ruby packages to install

        - `Optional<List<String>> go`

          Go packages to install

        - `Optional<List<String>> npm`

          Node.js packages to install

        - `Optional<List<String>> pip`

          Python packages to install

        - `Optional<Type> type`

          Package configuration type

          - `PACKAGES("packages")`

    - `class BetaSelfHostedConfigParams:`

      Request params for `self_hosted` environment configuration.

      - `JsonValue; type "self_hosted"constant`

        Environment type

        - `SELF_HOSTED("self_hosted")`

  - `Optional<String> description`

    Optional description of the environment

  - `Optional<Metadata> metadata`

    User-provided metadata key-value pairs

  - `Optional<Scope> scope`

    The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. Only applicable for self-hosted environments. If not specified, defaults based on organization type.

    - `ORGANIZATION("organization")`

    - `ACCOUNT("account")`

### Returns

- `class BetaEnvironment:`

  Unified Environment resource for both cloud and self-hosted environments.

  - `String id`

    Environment identifier (e.g., 'env_...')

  - `Optional<String> archivedAt`

    RFC 3339 timestamp when environment was archived, or null if not archived

  - `Config config`

    Environment configuration (either Anthropic Cloud or self-hosted)

    - `class BetaCloudConfig:`

      `cloud` environment configuration.

      - `Networking networking`

        Network configuration policy.

        - `class BetaUnrestrictedNetwork:`

          Unrestricted network access.

          - `JsonValue; type "unrestricted"constant`

            Network policy type

            - `UNRESTRICTED("unrestricted")`

        - `class BetaLimitedNetwork:`

          Limited network access.

          - `boolean allowMcpServers`

            Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array.

          - `boolean allowPackageManagers`

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array.

          - `List<String> allowedHosts`

            Specifies domains the container can reach.

          - `JsonValue; type "limited"constant`

            Network policy type

            - `LIMITED("limited")`

      - `BetaPackages packages`

        Package manager configuration.

        - `List<String> apt`

          Ubuntu/Debian packages to install

        - `List<String> cargo`

          Rust packages to install

        - `List<String> gem`

          Ruby packages to install

        - `List<String> go`

          Go packages to install

        - `List<String> npm`

          Node.js packages to install

        - `List<String> pip`

          Python packages to install

        - `Optional<Type> type`

          Package configuration type

          - `PACKAGES("packages")`

      - `JsonValue; type "cloud"constant`

        Environment type

        - `CLOUD("cloud")`

    - `class BetaSelfHostedConfig:`

      Configuration for self-hosted environments.

      - `JsonValue; type "self_hosted"constant`

        Environment type

        - `SELF_HOSTED("self_hosted")`

  - `String createdAt`

    RFC 3339 timestamp when environment was created

  - `String description`

    User-provided description for the environment

  - `Metadata metadata`

    User-provided metadata key-value pairs

  - `String name`

    Human-readable name for the environment

  - `JsonValue; type "environment"constant`

    The type of object (always 'environment')

    - `ENVIRONMENT("environment")`

  - `String updatedAt`

    RFC 3339 timestamp when environment was last updated

  - `Optional<Scope> scope`

    The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

    - `ORGANIZATION("organization")`

    - `ACCOUNT("account")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.BetaEnvironment;
import com.anthropic.models.beta.environments.EnvironmentCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        EnvironmentCreateParams params = EnvironmentCreateParams.builder()
            .name("python-data-analysis")
            .build();
        BetaEnvironment betaEnvironment = client.beta().environments().create(params);
    }
}
```

#### Response

```json
{
  "id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "archived_at": null,
  "config": {
    "networking": {
      "allow_mcp_servers": false,
      "allow_package_managers": true,
      "allowed_hosts": [
        "api.example.com"
      ],
      "type": "limited"
    },
    "packages": {
      "apt": [
        "string"
      ],
      "cargo": [
        "string"
      ],
      "gem": [
        "string"
      ],
      "go": [
        "string"
      ],
      "npm": [
        "string"
      ],
      "pip": [
        "pandas",
        "numpy"
      ],
      "type": "packages"
    },
    "type": "cloud"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "description": "Python environment with data-analysis packages.",
  "metadata": {},
  "name": "python-data-analysis",
  "type": "environment",
  "updated_at": "2026-03-15T10:00:00Z",
  "scope": "organization"
}
```

## List Environments

`EnvironmentListPage beta().environments().list(EnvironmentListParamsparams = EnvironmentListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/environments`

List environments with pagination support.

### Parameters

- `EnvironmentListParams params`

  - `Optional<Boolean> includeArchived`

    Include archived environments in the response

  - `Optional<Long> limit`

    Maximum number of environments to return

  - `Optional<String> page`

    Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaEnvironment:`

  Unified Environment resource for both cloud and self-hosted environments.

  - `String id`

    Environment identifier (e.g., 'env_...')

  - `Optional<String> archivedAt`

    RFC 3339 timestamp when environment was archived, or null if not archived

  - `Config config`

    Environment configuration (either Anthropic Cloud or self-hosted)

    - `class BetaCloudConfig:`

      `cloud` environment configuration.

      - `Networking networking`

        Network configuration policy.

        - `class BetaUnrestrictedNetwork:`

          Unrestricted network access.

          - `JsonValue; type "unrestricted"constant`

            Network policy type

            - `UNRESTRICTED("unrestricted")`

        - `class BetaLimitedNetwork:`

          Limited network access.

          - `boolean allowMcpServers`

            Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array.

          - `boolean allowPackageManagers`

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array.

          - `List<String> allowedHosts`

            Specifies domains the container can reach.

          - `JsonValue; type "limited"constant`

            Network policy type

            - `LIMITED("limited")`

      - `BetaPackages packages`

        Package manager configuration.

        - `List<String> apt`

          Ubuntu/Debian packages to install

        - `List<String> cargo`

          Rust packages to install

        - `List<String> gem`

          Ruby packages to install

        - `List<String> go`

          Go packages to install

        - `List<String> npm`

          Node.js packages to install

        - `List<String> pip`

          Python packages to install

        - `Optional<Type> type`

          Package configuration type

          - `PACKAGES("packages")`

      - `JsonValue; type "cloud"constant`

        Environment type

        - `CLOUD("cloud")`

    - `class BetaSelfHostedConfig:`

      Configuration for self-hosted environments.

      - `JsonValue; type "self_hosted"constant`

        Environment type

        - `SELF_HOSTED("self_hosted")`

  - `String createdAt`

    RFC 3339 timestamp when environment was created

  - `String description`

    User-provided description for the environment

  - `Metadata metadata`

    User-provided metadata key-value pairs

  - `String name`

    Human-readable name for the environment

  - `JsonValue; type "environment"constant`

    The type of object (always 'environment')

    - `ENVIRONMENT("environment")`

  - `String updatedAt`

    RFC 3339 timestamp when environment was last updated

  - `Optional<Scope> scope`

    The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

    - `ORGANIZATION("organization")`

    - `ACCOUNT("account")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.EnvironmentListPage;
import com.anthropic.models.beta.environments.EnvironmentListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        EnvironmentListPage page = client.beta().environments().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
      "archived_at": null,
      "config": {
        "networking": {
          "allow_mcp_servers": false,
          "allow_package_managers": true,
          "allowed_hosts": [
            "api.example.com"
          ],
          "type": "limited"
        },
        "packages": {
          "apt": [
            "string"
          ],
          "cargo": [
            "string"
          ],
          "gem": [
            "string"
          ],
          "go": [
            "string"
          ],
          "npm": [
            "string"
          ],
          "pip": [
            "pandas",
            "numpy"
          ],
          "type": "packages"
        },
        "type": "cloud"
      },
      "created_at": "2026-03-15T10:00:00Z",
      "description": "Python environment with data-analysis packages.",
      "metadata": {},
      "name": "python-data-analysis",
      "type": "environment",
      "updated_at": "2026-03-15T10:00:00Z",
      "scope": "organization"
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```

## Get Environment

`BetaEnvironment beta().environments().retrieve(EnvironmentRetrieveParamsparams = EnvironmentRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/environments/{environment_id}`

Retrieve a specific environment by ID.

### Parameters

- `EnvironmentRetrieveParams params`

  - `Optional<String> environmentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaEnvironment:`

  Unified Environment resource for both cloud and self-hosted environments.

  - `String id`

    Environment identifier (e.g., 'env_...')

  - `Optional<String> archivedAt`

    RFC 3339 timestamp when environment was archived, or null if not archived

  - `Config config`

    Environment configuration (either Anthropic Cloud or self-hosted)

    - `class BetaCloudConfig:`

      `cloud` environment configuration.

      - `Networking networking`

        Network configuration policy.

        - `class BetaUnrestrictedNetwork:`

          Unrestricted network access.

          - `JsonValue; type "unrestricted"constant`

            Network policy type

            - `UNRESTRICTED("unrestricted")`

        - `class BetaLimitedNetwork:`

          Limited network access.

          - `boolean allowMcpServers`

            Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array.

          - `boolean allowPackageManagers`

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array.

          - `List<String> allowedHosts`

            Specifies domains the container can reach.

          - `JsonValue; type "limited"constant`

            Network policy type

            - `LIMITED("limited")`

      - `BetaPackages packages`

        Package manager configuration.

        - `List<String> apt`

          Ubuntu/Debian packages to install

        - `List<String> cargo`

          Rust packages to install

        - `List<String> gem`

          Ruby packages to install

        - `List<String> go`

          Go packages to install

        - `List<String> npm`

          Node.js packages to install

        - `List<String> pip`

          Python packages to install

        - `Optional<Type> type`

          Package configuration type

          - `PACKAGES("packages")`

      - `JsonValue; type "cloud"constant`

        Environment type

        - `CLOUD("cloud")`

    - `class BetaSelfHostedConfig:`

      Configuration for self-hosted environments.

      - `JsonValue; type "self_hosted"constant`

        Environment type

        - `SELF_HOSTED("self_hosted")`

  - `String createdAt`

    RFC 3339 timestamp when environment was created

  - `String description`

    User-provided description for the environment

  - `Metadata metadata`

    User-provided metadata key-value pairs

  - `String name`

    Human-readable name for the environment

  - `JsonValue; type "environment"constant`

    The type of object (always 'environment')

    - `ENVIRONMENT("environment")`

  - `String updatedAt`

    RFC 3339 timestamp when environment was last updated

  - `Optional<Scope> scope`

    The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

    - `ORGANIZATION("organization")`

    - `ACCOUNT("account")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.BetaEnvironment;
import com.anthropic.models.beta.environments.EnvironmentRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaEnvironment betaEnvironment = client.beta().environments().retrieve("env_011CZkZ9X2dpNyB7HsEFoRfW");
    }
}
```

#### Response

```json
{
  "id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "archived_at": null,
  "config": {
    "networking": {
      "allow_mcp_servers": false,
      "allow_package_managers": true,
      "allowed_hosts": [
        "api.example.com"
      ],
      "type": "limited"
    },
    "packages": {
      "apt": [
        "string"
      ],
      "cargo": [
        "string"
      ],
      "gem": [
        "string"
      ],
      "go": [
        "string"
      ],
      "npm": [
        "string"
      ],
      "pip": [
        "pandas",
        "numpy"
      ],
      "type": "packages"
    },
    "type": "cloud"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "description": "Python environment with data-analysis packages.",
  "metadata": {},
  "name": "python-data-analysis",
  "type": "environment",
  "updated_at": "2026-03-15T10:00:00Z",
  "scope": "organization"
}
```

## Update Environment

`BetaEnvironment beta().environments().update(EnvironmentUpdateParamsparams = EnvironmentUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/environments/{environment_id}`

Update an existing environment's configuration.

### Parameters

- `EnvironmentUpdateParams params`

  - `Optional<String> environmentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<Config> config`

    Updated environment configuration

    - `class BetaCloudConfigParams:`

      Request params for `cloud` environment configuration.

      Fields default to null; on update, omitted fields preserve the
      existing value.

      - `JsonValue; type "cloud"constant`

        Environment type

        - `CLOUD("cloud")`

      - `Optional<Networking> networking`

        Network configuration policy. Omit on update to preserve the existing value.

        - `class BetaUnrestrictedNetwork:`

          Unrestricted network access.

          - `JsonValue; type "unrestricted"constant`

            Network policy type

            - `UNRESTRICTED("unrestricted")`

        - `class BetaLimitedNetworkParams:`

          Limited network request params.

          Fields default to null; on update, omitted fields preserve the
          existing value.

          - `JsonValue; type "limited"constant`

            Network policy type

            - `LIMITED("limited")`

          - `Optional<Boolean> allowMcpServers`

            Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.

          - `Optional<Boolean> allowPackageManagers`

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`.

          - `Optional<List<String>> allowedHosts`

            Specifies domains the container can reach.

      - `Optional<BetaPackagesParams> packages`

        Specify packages (and optionally their versions) available in this environment.

        When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest.

        - `Optional<List<String>> apt`

          Ubuntu/Debian packages to install

        - `Optional<List<String>> cargo`

          Rust packages to install

        - `Optional<List<String>> gem`

          Ruby packages to install

        - `Optional<List<String>> go`

          Go packages to install

        - `Optional<List<String>> npm`

          Node.js packages to install

        - `Optional<List<String>> pip`

          Python packages to install

        - `Optional<Type> type`

          Package configuration type

          - `PACKAGES("packages")`

    - `class BetaSelfHostedConfigParams:`

      Request params for `self_hosted` environment configuration.

      - `JsonValue; type "self_hosted"constant`

        Environment type

        - `SELF_HOSTED("self_hosted")`

  - `Optional<String> description`

    Updated description of the environment

  - `Optional<Metadata> metadata`

    User-provided metadata key-value pairs. Set a value to null or empty string to delete the key.

  - `Optional<String> name`

    Updated name for the environment

  - `Optional<Scope> scope`

    The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only.

    - `ORGANIZATION("organization")`

    - `ACCOUNT("account")`

### Returns

- `class BetaEnvironment:`

  Unified Environment resource for both cloud and self-hosted environments.

  - `String id`

    Environment identifier (e.g., 'env_...')

  - `Optional<String> archivedAt`

    RFC 3339 timestamp when environment was archived, or null if not archived

  - `Config config`

    Environment configuration (either Anthropic Cloud or self-hosted)

    - `class BetaCloudConfig:`

      `cloud` environment configuration.

      - `Networking networking`

        Network configuration policy.

        - `class BetaUnrestrictedNetwork:`

          Unrestricted network access.

          - `JsonValue; type "unrestricted"constant`

            Network policy type

            - `UNRESTRICTED("unrestricted")`

        - `class BetaLimitedNetwork:`

          Limited network access.

          - `boolean allowMcpServers`

            Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array.

          - `boolean allowPackageManagers`

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array.

          - `List<String> allowedHosts`

            Specifies domains the container can reach.

          - `JsonValue; type "limited"constant`

            Network policy type

            - `LIMITED("limited")`

      - `BetaPackages packages`

        Package manager configuration.

        - `List<String> apt`

          Ubuntu/Debian packages to install

        - `List<String> cargo`

          Rust packages to install

        - `List<String> gem`

          Ruby packages to install

        - `List<String> go`

          Go packages to install

        - `List<String> npm`

          Node.js packages to install

        - `List<String> pip`

          Python packages to install

        - `Optional<Type> type`

          Package configuration type

          - `PACKAGES("packages")`

      - `JsonValue; type "cloud"constant`

        Environment type

        - `CLOUD("cloud")`

    - `class BetaSelfHostedConfig:`

      Configuration for self-hosted environments.

      - `JsonValue; type "self_hosted"constant`

        Environment type

        - `SELF_HOSTED("self_hosted")`

  - `String createdAt`

    RFC 3339 timestamp when environment was created

  - `String description`

    User-provided description for the environment

  - `Metadata metadata`

    User-provided metadata key-value pairs

  - `String name`

    Human-readable name for the environment

  - `JsonValue; type "environment"constant`

    The type of object (always 'environment')

    - `ENVIRONMENT("environment")`

  - `String updatedAt`

    RFC 3339 timestamp when environment was last updated

  - `Optional<Scope> scope`

    The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

    - `ORGANIZATION("organization")`

    - `ACCOUNT("account")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.BetaEnvironment;
import com.anthropic.models.beta.environments.EnvironmentUpdateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaEnvironment betaEnvironment = client.beta().environments().update("env_011CZkZ9X2dpNyB7HsEFoRfW");
    }
}
```

#### Response

```json
{
  "id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "archived_at": null,
  "config": {
    "networking": {
      "allow_mcp_servers": false,
      "allow_package_managers": true,
      "allowed_hosts": [
        "api.example.com"
      ],
      "type": "limited"
    },
    "packages": {
      "apt": [
        "string"
      ],
      "cargo": [
        "string"
      ],
      "gem": [
        "string"
      ],
      "go": [
        "string"
      ],
      "npm": [
        "string"
      ],
      "pip": [
        "pandas",
        "numpy"
      ],
      "type": "packages"
    },
    "type": "cloud"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "description": "Python environment with data-analysis packages.",
  "metadata": {},
  "name": "python-data-analysis",
  "type": "environment",
  "updated_at": "2026-03-15T10:00:00Z",
  "scope": "organization"
}
```

## Delete Environment

`BetaEnvironmentDeleteResponse beta().environments().delete(EnvironmentDeleteParamsparams = EnvironmentDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/environments/{environment_id}`

Delete an environment by ID. Returns a confirmation of the deletion.

### Parameters

- `EnvironmentDeleteParams params`

  - `Optional<String> environmentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaEnvironmentDeleteResponse:`

  Response after deleting an environment.

  - `String id`

    Environment identifier

  - `JsonValue; type "environment_deleted"constant`

    The type of response

    - `ENVIRONMENT_DELETED("environment_deleted")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.BetaEnvironmentDeleteResponse;
import com.anthropic.models.beta.environments.EnvironmentDeleteParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaEnvironmentDeleteResponse betaEnvironmentDeleteResponse = client.beta().environments().delete("env_011CZkZ9X2dpNyB7HsEFoRfW");
    }
}
```

#### Response

```json
{
  "id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "type": "environment_deleted"
}
```

## Archive Environment

`BetaEnvironment beta().environments().archive(EnvironmentArchiveParamsparams = EnvironmentArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/environments/{environment_id}/archive`

Archive an environment by ID. Archived environments cannot be used to create new sessions.

### Parameters

- `EnvironmentArchiveParams params`

  - `Optional<String> environmentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaEnvironment:`

  Unified Environment resource for both cloud and self-hosted environments.

  - `String id`

    Environment identifier (e.g., 'env_...')

  - `Optional<String> archivedAt`

    RFC 3339 timestamp when environment was archived, or null if not archived

  - `Config config`

    Environment configuration (either Anthropic Cloud or self-hosted)

    - `class BetaCloudConfig:`

      `cloud` environment configuration.

      - `Networking networking`

        Network configuration policy.

        - `class BetaUnrestrictedNetwork:`

          Unrestricted network access.

          - `JsonValue; type "unrestricted"constant`

            Network policy type

            - `UNRESTRICTED("unrestricted")`

        - `class BetaLimitedNetwork:`

          Limited network access.

          - `boolean allowMcpServers`

            Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array.

          - `boolean allowPackageManagers`

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array.

          - `List<String> allowedHosts`

            Specifies domains the container can reach.

          - `JsonValue; type "limited"constant`

            Network policy type

            - `LIMITED("limited")`

      - `BetaPackages packages`

        Package manager configuration.

        - `List<String> apt`

          Ubuntu/Debian packages to install

        - `List<String> cargo`

          Rust packages to install

        - `List<String> gem`

          Ruby packages to install

        - `List<String> go`

          Go packages to install

        - `List<String> npm`

          Node.js packages to install

        - `List<String> pip`

          Python packages to install

        - `Optional<Type> type`

          Package configuration type

          - `PACKAGES("packages")`

      - `JsonValue; type "cloud"constant`

        Environment type

        - `CLOUD("cloud")`

    - `class BetaSelfHostedConfig:`

      Configuration for self-hosted environments.

      - `JsonValue; type "self_hosted"constant`

        Environment type

        - `SELF_HOSTED("self_hosted")`

  - `String createdAt`

    RFC 3339 timestamp when environment was created

  - `String description`

    User-provided description for the environment

  - `Metadata metadata`

    User-provided metadata key-value pairs

  - `String name`

    Human-readable name for the environment

  - `JsonValue; type "environment"constant`

    The type of object (always 'environment')

    - `ENVIRONMENT("environment")`

  - `String updatedAt`

    RFC 3339 timestamp when environment was last updated

  - `Optional<Scope> scope`

    The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

    - `ORGANIZATION("organization")`

    - `ACCOUNT("account")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.BetaEnvironment;
import com.anthropic.models.beta.environments.EnvironmentArchiveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaEnvironment betaEnvironment = client.beta().environments().archive("env_011CZkZ9X2dpNyB7HsEFoRfW");
    }
}
```

#### Response

```json
{
  "id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "archived_at": null,
  "config": {
    "networking": {
      "allow_mcp_servers": false,
      "allow_package_managers": true,
      "allowed_hosts": [
        "api.example.com"
      ],
      "type": "limited"
    },
    "packages": {
      "apt": [
        "string"
      ],
      "cargo": [
        "string"
      ],
      "gem": [
        "string"
      ],
      "go": [
        "string"
      ],
      "npm": [
        "string"
      ],
      "pip": [
        "pandas",
        "numpy"
      ],
      "type": "packages"
    },
    "type": "cloud"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "description": "Python environment with data-analysis packages.",
  "metadata": {},
  "name": "python-data-analysis",
  "type": "environment",
  "updated_at": "2026-03-15T10:00:00Z",
  "scope": "organization"
}
```

## Domain Types

### Beta Cloud Config

- `class BetaCloudConfig:`

  `cloud` environment configuration.

  - `Networking networking`

    Network configuration policy.

    - `class BetaUnrestrictedNetwork:`

      Unrestricted network access.

      - `JsonValue; type "unrestricted"constant`

        Network policy type

        - `UNRESTRICTED("unrestricted")`

    - `class BetaLimitedNetwork:`

      Limited network access.

      - `boolean allowMcpServers`

        Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array.

      - `boolean allowPackageManagers`

        Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array.

      - `List<String> allowedHosts`

        Specifies domains the container can reach.

      - `JsonValue; type "limited"constant`

        Network policy type

        - `LIMITED("limited")`

  - `BetaPackages packages`

    Package manager configuration.

    - `List<String> apt`

      Ubuntu/Debian packages to install

    - `List<String> cargo`

      Rust packages to install

    - `List<String> gem`

      Ruby packages to install

    - `List<String> go`

      Go packages to install

    - `List<String> npm`

      Node.js packages to install

    - `List<String> pip`

      Python packages to install

    - `Optional<Type> type`

      Package configuration type

      - `PACKAGES("packages")`

  - `JsonValue; type "cloud"constant`

    Environment type

    - `CLOUD("cloud")`

### Beta Cloud Config Params

- `class BetaCloudConfigParams:`

  Request params for `cloud` environment configuration.

  Fields default to null; on update, omitted fields preserve the
  existing value.

  - `JsonValue; type "cloud"constant`

    Environment type

    - `CLOUD("cloud")`

  - `Optional<Networking> networking`

    Network configuration policy. Omit on update to preserve the existing value.

    - `class BetaUnrestrictedNetwork:`

      Unrestricted network access.

      - `JsonValue; type "unrestricted"constant`

        Network policy type

        - `UNRESTRICTED("unrestricted")`

    - `class BetaLimitedNetworkParams:`

      Limited network request params.

      Fields default to null; on update, omitted fields preserve the
      existing value.

      - `JsonValue; type "limited"constant`

        Network policy type

        - `LIMITED("limited")`

      - `Optional<Boolean> allowMcpServers`

        Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.

      - `Optional<Boolean> allowPackageManagers`

        Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`.

      - `Optional<List<String>> allowedHosts`

        Specifies domains the container can reach.

  - `Optional<BetaPackagesParams> packages`

    Specify packages (and optionally their versions) available in this environment.

    When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest.

    - `Optional<List<String>> apt`

      Ubuntu/Debian packages to install

    - `Optional<List<String>> cargo`

      Rust packages to install

    - `Optional<List<String>> gem`

      Ruby packages to install

    - `Optional<List<String>> go`

      Go packages to install

    - `Optional<List<String>> npm`

      Node.js packages to install

    - `Optional<List<String>> pip`

      Python packages to install

    - `Optional<Type> type`

      Package configuration type

      - `PACKAGES("packages")`

### Beta Environment

- `class BetaEnvironment:`

  Unified Environment resource for both cloud and self-hosted environments.

  - `String id`

    Environment identifier (e.g., 'env_...')

  - `Optional<String> archivedAt`

    RFC 3339 timestamp when environment was archived, or null if not archived

  - `Config config`

    Environment configuration (either Anthropic Cloud or self-hosted)

    - `class BetaCloudConfig:`

      `cloud` environment configuration.

      - `Networking networking`

        Network configuration policy.

        - `class BetaUnrestrictedNetwork:`

          Unrestricted network access.

          - `JsonValue; type "unrestricted"constant`

            Network policy type

            - `UNRESTRICTED("unrestricted")`

        - `class BetaLimitedNetwork:`

          Limited network access.

          - `boolean allowMcpServers`

            Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array.

          - `boolean allowPackageManagers`

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array.

          - `List<String> allowedHosts`

            Specifies domains the container can reach.

          - `JsonValue; type "limited"constant`

            Network policy type

            - `LIMITED("limited")`

      - `BetaPackages packages`

        Package manager configuration.

        - `List<String> apt`

          Ubuntu/Debian packages to install

        - `List<String> cargo`

          Rust packages to install

        - `List<String> gem`

          Ruby packages to install

        - `List<String> go`

          Go packages to install

        - `List<String> npm`

          Node.js packages to install

        - `List<String> pip`

          Python packages to install

        - `Optional<Type> type`

          Package configuration type

          - `PACKAGES("packages")`

      - `JsonValue; type "cloud"constant`

        Environment type

        - `CLOUD("cloud")`

    - `class BetaSelfHostedConfig:`

      Configuration for self-hosted environments.

      - `JsonValue; type "self_hosted"constant`

        Environment type

        - `SELF_HOSTED("self_hosted")`

  - `String createdAt`

    RFC 3339 timestamp when environment was created

  - `String description`

    User-provided description for the environment

  - `Metadata metadata`

    User-provided metadata key-value pairs

  - `String name`

    Human-readable name for the environment

  - `JsonValue; type "environment"constant`

    The type of object (always 'environment')

    - `ENVIRONMENT("environment")`

  - `String updatedAt`

    RFC 3339 timestamp when environment was last updated

  - `Optional<Scope> scope`

    The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

    - `ORGANIZATION("organization")`

    - `ACCOUNT("account")`

### Beta Environment Delete Response

- `class BetaEnvironmentDeleteResponse:`

  Response after deleting an environment.

  - `String id`

    Environment identifier

  - `JsonValue; type "environment_deleted"constant`

    The type of response

    - `ENVIRONMENT_DELETED("environment_deleted")`

### Beta Limited Network

- `class BetaLimitedNetwork:`

  Limited network access.

  - `boolean allowMcpServers`

    Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array.

  - `boolean allowPackageManagers`

    Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array.

  - `List<String> allowedHosts`

    Specifies domains the container can reach.

  - `JsonValue; type "limited"constant`

    Network policy type

    - `LIMITED("limited")`

### Beta Limited Network Params

- `class BetaLimitedNetworkParams:`

  Limited network request params.

  Fields default to null; on update, omitted fields preserve the
  existing value.

  - `JsonValue; type "limited"constant`

    Network policy type

    - `LIMITED("limited")`

  - `Optional<Boolean> allowMcpServers`

    Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.

  - `Optional<Boolean> allowPackageManagers`

    Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`.

  - `Optional<List<String>> allowedHosts`

    Specifies domains the container can reach.

### Beta Packages

- `class BetaPackages:`

  Packages (and their versions) available in this environment.

  - `List<String> apt`

    Ubuntu/Debian packages to install

  - `List<String> cargo`

    Rust packages to install

  - `List<String> gem`

    Ruby packages to install

  - `List<String> go`

    Go packages to install

  - `List<String> npm`

    Node.js packages to install

  - `List<String> pip`

    Python packages to install

  - `Optional<Type> type`

    Package configuration type

    - `PACKAGES("packages")`

### Beta Packages Params

- `class BetaPackagesParams:`

  Specify packages (and optionally their versions) available in this environment.

  When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest.

  - `Optional<List<String>> apt`

    Ubuntu/Debian packages to install

  - `Optional<List<String>> cargo`

    Rust packages to install

  - `Optional<List<String>> gem`

    Ruby packages to install

  - `Optional<List<String>> go`

    Go packages to install

  - `Optional<List<String>> npm`

    Node.js packages to install

  - `Optional<List<String>> pip`

    Python packages to install

  - `Optional<Type> type`

    Package configuration type

    - `PACKAGES("packages")`

### Beta Self Hosted Config

- `class BetaSelfHostedConfig:`

  Configuration for self-hosted environments.

  - `JsonValue; type "self_hosted"constant`

    Environment type

    - `SELF_HOSTED("self_hosted")`

### Beta Self Hosted Config Params

- `class BetaSelfHostedConfigParams:`

  Request params for `self_hosted` environment configuration.

  - `JsonValue; type "self_hosted"constant`

    Environment type

    - `SELF_HOSTED("self_hosted")`

### Beta Unrestricted Network

- `class BetaUnrestrictedNetwork:`

  Unrestricted network access.

  - `JsonValue; type "unrestricted"constant`

    Network policy type

    - `UNRESTRICTED("unrestricted")`

# Work

## Get Work Item

`BetaSelfHostedWork beta().environments().work().retrieve(WorkRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/environments/{environment_id}/work/{work_id}`

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Retrieve detailed information about a specific work item.

### Parameters

- `WorkRetrieveParams params`

  - `String environmentId`

  - `Optional<String> workId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaSelfHostedWork:`

  Work resource representing a unit of work in a self-hosted environment.

  Work items are queued when sessions are created or when long-dormant sessions
  receive new messages. The environment worker polls for work to execute in a
  self-hosted sandbox.

  - `String id`

    Work identifier (e.g., 'work_...')

  - `Optional<String> acknowledgedAt`

    RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox

  - `String createdAt`

    RFC 3339 timestamp when work was created

  - `BetaSessionWorkData data`

    The actual work to be performed

    - `String id`

      Session identifier (e.g., 'session_...')

    - `JsonValue; type "session"constant`

      Type of work data

      - `SESSION("session")`

  - `String environmentId`

    Environment identifier this work belongs to (e.g., `env_...`)

  - `Optional<String> latestHeartbeatAt`

    RFC 3339 timestamp of the most recent heartbeat

  - `Metadata metadata`

    User-provided metadata key-value pairs associated with this work item

  - `Optional<String> startedAt`

    RFC 3339 timestamp when work execution started

  - `State state`

    Current state of the work item

    - `QUEUED("queued")`

    - `STARTING("starting")`

    - `ACTIVE("active")`

    - `STOPPING("stopping")`

    - `STOPPED("stopped")`

  - `Optional<String> stopRequestedAt`

    RFC 3339 timestamp when stop was requested

  - `Optional<String> stoppedAt`

    RFC 3339 timestamp when work execution stopped

  - `JsonValue; type "work"constant`

    The type of object (always 'work')

    - `WORK("work")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWork;
import com.anthropic.models.beta.environments.work.WorkRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        WorkRetrieveParams params = WorkRetrieveParams.builder()
            .environmentId("env_011CZkZ9X2dpNyB7HsEFoRfW")
            .workId("work_id")
            .build();
        BetaSelfHostedWork betaSelfHostedWork = client.beta().environments().work().retrieve(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "acknowledged_at": "acknowledged_at",
  "created_at": "created_at",
  "data": {
    "id": "id",
    "type": "session"
  },
  "environment_id": "environment_id",
  "latest_heartbeat_at": "latest_heartbeat_at",
  "metadata": {
    "foo": "string"
  },
  "started_at": "started_at",
  "state": "queued",
  "stop_requested_at": "stop_requested_at",
  "stopped_at": "stopped_at",
  "type": "work"
}
```

## Poll for Work

`BetaSelfHostedWork beta().environments().work().poll(WorkPollParamsparams = WorkPollParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/environments/{environment_id}/work/poll`

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Long poll for work items in the queue.

### Parameters

- `WorkPollParams params`

  - `Optional<String> environmentId`

  - `Optional<Long> blockMs`

    How long to wait for work to arrive before returning. Must be 1-999 in milliseconds. Defaults to non-blocking (returns immediately if no work is available).

  - `Optional<Long> reclaimOlderThanMs`

    Reclaim unacknowledged work items older than this many milliseconds. If omitted, uses the default (5000ms).

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<String> anthropicWorkerId`

    Unique identifier for the specific worker polling, used to track aggregated environment-level work metrics in Console

### Returns

- `class BetaSelfHostedWork:`

  Work resource representing a unit of work in a self-hosted environment.

  Work items are queued when sessions are created or when long-dormant sessions
  receive new messages. The environment worker polls for work to execute in a
  self-hosted sandbox.

  - `String id`

    Work identifier (e.g., 'work_...')

  - `Optional<String> acknowledgedAt`

    RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox

  - `String createdAt`

    RFC 3339 timestamp when work was created

  - `BetaSessionWorkData data`

    The actual work to be performed

    - `String id`

      Session identifier (e.g., 'session_...')

    - `JsonValue; type "session"constant`

      Type of work data

      - `SESSION("session")`

  - `String environmentId`

    Environment identifier this work belongs to (e.g., `env_...`)

  - `Optional<String> latestHeartbeatAt`

    RFC 3339 timestamp of the most recent heartbeat

  - `Metadata metadata`

    User-provided metadata key-value pairs associated with this work item

  - `Optional<String> startedAt`

    RFC 3339 timestamp when work execution started

  - `State state`

    Current state of the work item

    - `QUEUED("queued")`

    - `STARTING("starting")`

    - `ACTIVE("active")`

    - `STOPPING("stopping")`

    - `STOPPED("stopped")`

  - `Optional<String> stopRequestedAt`

    RFC 3339 timestamp when stop was requested

  - `Optional<String> stoppedAt`

    RFC 3339 timestamp when work execution stopped

  - `JsonValue; type "work"constant`

    The type of object (always 'work')

    - `WORK("work")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWork;
import com.anthropic.models.beta.environments.work.WorkPollParams;
import java.util.Optional;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        Optional<BetaSelfHostedWork> betaSelfHostedWork = client.beta().environments().work().poll("env_011CZkZ9X2dpNyB7HsEFoRfW");
    }
}
```

#### Response

```json
{
  "id": "id",
  "acknowledged_at": "acknowledged_at",
  "created_at": "created_at",
  "data": {
    "id": "id",
    "type": "session"
  },
  "environment_id": "environment_id",
  "latest_heartbeat_at": "latest_heartbeat_at",
  "metadata": {
    "foo": "string"
  },
  "started_at": "started_at",
  "state": "queued",
  "stop_requested_at": "stop_requested_at",
  "stopped_at": "stopped_at",
  "type": "work"
}
```

## Acknowledge Work

`BetaSelfHostedWork beta().environments().work().ack(WorkAckParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/environments/{environment_id}/work/{work_id}/ack`

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Acknowledge receipt of a work item, transitioning it from 'queued' to 'starting' and removing it from the queue.

### Parameters

- `WorkAckParams params`

  - `String environmentId`

  - `Optional<String> workId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaSelfHostedWork:`

  Work resource representing a unit of work in a self-hosted environment.

  Work items are queued when sessions are created or when long-dormant sessions
  receive new messages. The environment worker polls for work to execute in a
  self-hosted sandbox.

  - `String id`

    Work identifier (e.g., 'work_...')

  - `Optional<String> acknowledgedAt`

    RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox

  - `String createdAt`

    RFC 3339 timestamp when work was created

  - `BetaSessionWorkData data`

    The actual work to be performed

    - `String id`

      Session identifier (e.g., 'session_...')

    - `JsonValue; type "session"constant`

      Type of work data

      - `SESSION("session")`

  - `String environmentId`

    Environment identifier this work belongs to (e.g., `env_...`)

  - `Optional<String> latestHeartbeatAt`

    RFC 3339 timestamp of the most recent heartbeat

  - `Metadata metadata`

    User-provided metadata key-value pairs associated with this work item

  - `Optional<String> startedAt`

    RFC 3339 timestamp when work execution started

  - `State state`

    Current state of the work item

    - `QUEUED("queued")`

    - `STARTING("starting")`

    - `ACTIVE("active")`

    - `STOPPING("stopping")`

    - `STOPPED("stopped")`

  - `Optional<String> stopRequestedAt`

    RFC 3339 timestamp when stop was requested

  - `Optional<String> stoppedAt`

    RFC 3339 timestamp when work execution stopped

  - `JsonValue; type "work"constant`

    The type of object (always 'work')

    - `WORK("work")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWork;
import com.anthropic.models.beta.environments.work.WorkAckParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        WorkAckParams params = WorkAckParams.builder()
            .environmentId("env_011CZkZ9X2dpNyB7HsEFoRfW")
            .workId("work_id")
            .build();
        BetaSelfHostedWork betaSelfHostedWork = client.beta().environments().work().ack(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "acknowledged_at": "acknowledged_at",
  "created_at": "created_at",
  "data": {
    "id": "id",
    "type": "session"
  },
  "environment_id": "environment_id",
  "latest_heartbeat_at": "latest_heartbeat_at",
  "metadata": {
    "foo": "string"
  },
  "started_at": "started_at",
  "state": "queued",
  "stop_requested_at": "stop_requested_at",
  "stopped_at": "stopped_at",
  "type": "work"
}
```

## Record Heartbeat

`BetaSelfHostedWorkHeartbeatResponse beta().environments().work().heartbeat(WorkHeartbeatParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/environments/{environment_id}/work/{work_id}/heartbeat`

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Record a heartbeat for a work item to maintain the lease.

### Parameters

- `WorkHeartbeatParams params`

  - `String environmentId`

  - `Optional<String> workId`

  - `Optional<Long> desiredTtlSeconds`

    Desired TTL in seconds

  - `Optional<String> expectedLastHeartbeat`

    Expected last_heartbeat for conditional update (optimistic concurrency). Use literal 'NO_HEARTBEAT' to claim an unclaimed lease (first heartbeat). For subsequent heartbeats, echo the server's previous last_heartbeat value exactly. Returns 412 Precondition Failed if the actual value doesn't match.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaSelfHostedWorkHeartbeatResponse:`

  Response after recording a heartbeat for a work item.

  - `String lastHeartbeat`

    RFC 3339 timestamp of the actual heartbeat from DB

  - `boolean leaseExtended`

    Whether the heartbeat succeeded in extending the lease

  - `State state`

    Current state of the work item (active/stopping/stopped)

    - `QUEUED("queued")`

    - `STARTING("starting")`

    - `ACTIVE("active")`

    - `STOPPING("stopping")`

    - `STOPPED("stopped")`

  - `long ttlSeconds`

    Effective TTL applied to the lease

  - `JsonValue; type "work_heartbeat"constant`

    The type of response

    - `WORK_HEARTBEAT("work_heartbeat")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWorkHeartbeatResponse;
import com.anthropic.models.beta.environments.work.WorkHeartbeatParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        WorkHeartbeatParams params = WorkHeartbeatParams.builder()
            .environmentId("env_011CZkZ9X2dpNyB7HsEFoRfW")
            .workId("work_id")
            .build();
        BetaSelfHostedWorkHeartbeatResponse betaSelfHostedWorkHeartbeatResponse = client.beta().environments().work().heartbeat(params);
    }
}
```

#### Response

```json
{
  "last_heartbeat": "last_heartbeat",
  "lease_extended": true,
  "state": "queued",
  "ttl_seconds": 0,
  "type": "work_heartbeat"
}
```

## Stop Work

`BetaSelfHostedWork beta().environments().work().stop(WorkStopParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/environments/{environment_id}/work/{work_id}/stop`

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Stop a work item, initiating graceful or forced shutdown.

### Parameters

- `WorkStopParams params`

  - `String environmentId`

  - `Optional<String> workId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `BetaSelfHostedWorkStopRequest betaSelfHostedWorkStopRequest`

    Request to stop a work item.

### Returns

- `class BetaSelfHostedWork:`

  Work resource representing a unit of work in a self-hosted environment.

  Work items are queued when sessions are created or when long-dormant sessions
  receive new messages. The environment worker polls for work to execute in a
  self-hosted sandbox.

  - `String id`

    Work identifier (e.g., 'work_...')

  - `Optional<String> acknowledgedAt`

    RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox

  - `String createdAt`

    RFC 3339 timestamp when work was created

  - `BetaSessionWorkData data`

    The actual work to be performed

    - `String id`

      Session identifier (e.g., 'session_...')

    - `JsonValue; type "session"constant`

      Type of work data

      - `SESSION("session")`

  - `String environmentId`

    Environment identifier this work belongs to (e.g., `env_...`)

  - `Optional<String> latestHeartbeatAt`

    RFC 3339 timestamp of the most recent heartbeat

  - `Metadata metadata`

    User-provided metadata key-value pairs associated with this work item

  - `Optional<String> startedAt`

    RFC 3339 timestamp when work execution started

  - `State state`

    Current state of the work item

    - `QUEUED("queued")`

    - `STARTING("starting")`

    - `ACTIVE("active")`

    - `STOPPING("stopping")`

    - `STOPPED("stopped")`

  - `Optional<String> stopRequestedAt`

    RFC 3339 timestamp when stop was requested

  - `Optional<String> stoppedAt`

    RFC 3339 timestamp when work execution stopped

  - `JsonValue; type "work"constant`

    The type of object (always 'work')

    - `WORK("work")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWork;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWorkStopRequest;
import com.anthropic.models.beta.environments.work.WorkStopParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        WorkStopParams params = WorkStopParams.builder()
            .environmentId("env_011CZkZ9X2dpNyB7HsEFoRfW")
            .workId("work_id")
            .betaSelfHostedWorkStopRequest(BetaSelfHostedWorkStopRequest.builder().build())
            .build();
        BetaSelfHostedWork betaSelfHostedWork = client.beta().environments().work().stop(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "acknowledged_at": "acknowledged_at",
  "created_at": "created_at",
  "data": {
    "id": "id",
    "type": "session"
  },
  "environment_id": "environment_id",
  "latest_heartbeat_at": "latest_heartbeat_at",
  "metadata": {
    "foo": "string"
  },
  "started_at": "started_at",
  "state": "queued",
  "stop_requested_at": "stop_requested_at",
  "stopped_at": "stopped_at",
  "type": "work"
}
```

## List Work Items

`WorkListPage beta().environments().work().list(WorkListParamsparams = WorkListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/environments/{environment_id}/work`

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

List work items in an environment.

### Parameters

- `WorkListParams params`

  - `Optional<String> environmentId`

  - `Optional<Long> limit`

    Maximum number of work items to return

  - `Optional<String> page`

    Opaque cursor from previous response for pagination

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaSelfHostedWork:`

  Work resource representing a unit of work in a self-hosted environment.

  Work items are queued when sessions are created or when long-dormant sessions
  receive new messages. The environment worker polls for work to execute in a
  self-hosted sandbox.

  - `String id`

    Work identifier (e.g., 'work_...')

  - `Optional<String> acknowledgedAt`

    RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox

  - `String createdAt`

    RFC 3339 timestamp when work was created

  - `BetaSessionWorkData data`

    The actual work to be performed

    - `String id`

      Session identifier (e.g., 'session_...')

    - `JsonValue; type "session"constant`

      Type of work data

      - `SESSION("session")`

  - `String environmentId`

    Environment identifier this work belongs to (e.g., `env_...`)

  - `Optional<String> latestHeartbeatAt`

    RFC 3339 timestamp of the most recent heartbeat

  - `Metadata metadata`

    User-provided metadata key-value pairs associated with this work item

  - `Optional<String> startedAt`

    RFC 3339 timestamp when work execution started

  - `State state`

    Current state of the work item

    - `QUEUED("queued")`

    - `STARTING("starting")`

    - `ACTIVE("active")`

    - `STOPPING("stopping")`

    - `STOPPED("stopped")`

  - `Optional<String> stopRequestedAt`

    RFC 3339 timestamp when stop was requested

  - `Optional<String> stoppedAt`

    RFC 3339 timestamp when work execution stopped

  - `JsonValue; type "work"constant`

    The type of object (always 'work')

    - `WORK("work")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.work.WorkListPage;
import com.anthropic.models.beta.environments.work.WorkListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        WorkListPage page = client.beta().environments().work().list("env_011CZkZ9X2dpNyB7HsEFoRfW");
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "id",
      "acknowledged_at": "acknowledged_at",
      "created_at": "created_at",
      "data": {
        "id": "id",
        "type": "session"
      },
      "environment_id": "environment_id",
      "latest_heartbeat_at": "latest_heartbeat_at",
      "metadata": {
        "foo": "string"
      },
      "started_at": "started_at",
      "state": "queued",
      "stop_requested_at": "stop_requested_at",
      "stopped_at": "stopped_at",
      "type": "work"
    }
  ],
  "next_page": "next_page"
}
```

## Update Work Item

`BetaSelfHostedWork beta().environments().work().update(WorkUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/environments/{environment_id}/work/{work_id}`

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Update work item metadata with merge semantics.

### Parameters

- `WorkUpdateParams params`

  - `String environmentId`

  - `Optional<String> workId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `BetaSelfHostedWorkUpdateRequest betaSelfHostedWorkUpdateRequest`

    Request to update work item metadata.

### Returns

- `class BetaSelfHostedWork:`

  Work resource representing a unit of work in a self-hosted environment.

  Work items are queued when sessions are created or when long-dormant sessions
  receive new messages. The environment worker polls for work to execute in a
  self-hosted sandbox.

  - `String id`

    Work identifier (e.g., 'work_...')

  - `Optional<String> acknowledgedAt`

    RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox

  - `String createdAt`

    RFC 3339 timestamp when work was created

  - `BetaSessionWorkData data`

    The actual work to be performed

    - `String id`

      Session identifier (e.g., 'session_...')

    - `JsonValue; type "session"constant`

      Type of work data

      - `SESSION("session")`

  - `String environmentId`

    Environment identifier this work belongs to (e.g., `env_...`)

  - `Optional<String> latestHeartbeatAt`

    RFC 3339 timestamp of the most recent heartbeat

  - `Metadata metadata`

    User-provided metadata key-value pairs associated with this work item

  - `Optional<String> startedAt`

    RFC 3339 timestamp when work execution started

  - `State state`

    Current state of the work item

    - `QUEUED("queued")`

    - `STARTING("starting")`

    - `ACTIVE("active")`

    - `STOPPING("stopping")`

    - `STOPPED("stopped")`

  - `Optional<String> stopRequestedAt`

    RFC 3339 timestamp when stop was requested

  - `Optional<String> stoppedAt`

    RFC 3339 timestamp when work execution stopped

  - `JsonValue; type "work"constant`

    The type of object (always 'work')

    - `WORK("work")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWork;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWorkUpdateRequest;
import com.anthropic.models.beta.environments.work.WorkUpdateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        WorkUpdateParams params = WorkUpdateParams.builder()
            .environmentId("env_011CZkZ9X2dpNyB7HsEFoRfW")
            .workId("work_id")
            .betaSelfHostedWorkUpdateRequest(BetaSelfHostedWorkUpdateRequest.builder()
                .metadata(BetaSelfHostedWorkUpdateRequest.Metadata.builder()
                    .putAdditionalProperty("foo", JsonValue.from("string"))
                    .build())
                .build())
            .build();
        BetaSelfHostedWork betaSelfHostedWork = client.beta().environments().work().update(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "acknowledged_at": "acknowledged_at",
  "created_at": "created_at",
  "data": {
    "id": "id",
    "type": "session"
  },
  "environment_id": "environment_id",
  "latest_heartbeat_at": "latest_heartbeat_at",
  "metadata": {
    "foo": "string"
  },
  "started_at": "started_at",
  "state": "queued",
  "stop_requested_at": "stop_requested_at",
  "stopped_at": "stopped_at",
  "type": "work"
}
```

## Get Queue Statistics

`BetaSelfHostedWorkQueueStats beta().environments().work().stats(WorkStatsParamsparams = WorkStatsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/environments/{environment_id}/work/stats`

Get statistics about the work queue for an environment.

### Parameters

- `WorkStatsParams params`

  - `Optional<String> environmentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaSelfHostedWorkQueueStats:`

  Statistics about the work queue for an environment.

  Uses Redis Stream consumer group metrics for O(1) queries.

  - `long depth`

    Number of work items waiting to be picked up (lag from consumer group)

  - `Optional<String> oldestQueuedAt`

    RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty

  - `long pending`

    Number of work items being processed (polled but not acknowledged)

  - `JsonValue; type "work_queue_stats"constant`

    The type of object

    - `WORK_QUEUE_STATS("work_queue_stats")`

  - `Optional<Long> workersPolling`

    Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWorkQueueStats;
import com.anthropic.models.beta.environments.work.WorkStatsParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaSelfHostedWorkQueueStats betaSelfHostedWorkQueueStats = client.beta().environments().work().stats("env_011CZkZ9X2dpNyB7HsEFoRfW");
    }
}
```

#### Response

```json
{
  "depth": 0,
  "oldest_queued_at": "oldest_queued_at",
  "pending": 0,
  "type": "work_queue_stats",
  "workers_polling": 0
}
```

## Domain Types

### Beta Self Hosted Work

- `class BetaSelfHostedWork:`

  Work resource representing a unit of work in a self-hosted environment.

  Work items are queued when sessions are created or when long-dormant sessions
  receive new messages. The environment worker polls for work to execute in a
  self-hosted sandbox.

  - `String id`

    Work identifier (e.g., 'work_...')

  - `Optional<String> acknowledgedAt`

    RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox

  - `String createdAt`

    RFC 3339 timestamp when work was created

  - `BetaSessionWorkData data`

    The actual work to be performed

    - `String id`

      Session identifier (e.g., 'session_...')

    - `JsonValue; type "session"constant`

      Type of work data

      - `SESSION("session")`

  - `String environmentId`

    Environment identifier this work belongs to (e.g., `env_...`)

  - `Optional<String> latestHeartbeatAt`

    RFC 3339 timestamp of the most recent heartbeat

  - `Metadata metadata`

    User-provided metadata key-value pairs associated with this work item

  - `Optional<String> startedAt`

    RFC 3339 timestamp when work execution started

  - `State state`

    Current state of the work item

    - `QUEUED("queued")`

    - `STARTING("starting")`

    - `ACTIVE("active")`

    - `STOPPING("stopping")`

    - `STOPPED("stopped")`

  - `Optional<String> stopRequestedAt`

    RFC 3339 timestamp when stop was requested

  - `Optional<String> stoppedAt`

    RFC 3339 timestamp when work execution stopped

  - `JsonValue; type "work"constant`

    The type of object (always 'work')

    - `WORK("work")`

### Beta Self Hosted Work Heartbeat Response

- `class BetaSelfHostedWorkHeartbeatResponse:`

  Response after recording a heartbeat for a work item.

  - `String lastHeartbeat`

    RFC 3339 timestamp of the actual heartbeat from DB

  - `boolean leaseExtended`

    Whether the heartbeat succeeded in extending the lease

  - `State state`

    Current state of the work item (active/stopping/stopped)

    - `QUEUED("queued")`

    - `STARTING("starting")`

    - `ACTIVE("active")`

    - `STOPPING("stopping")`

    - `STOPPED("stopped")`

  - `long ttlSeconds`

    Effective TTL applied to the lease

  - `JsonValue; type "work_heartbeat"constant`

    The type of response

    - `WORK_HEARTBEAT("work_heartbeat")`

### Beta Self Hosted Work List Response

- `class BetaSelfHostedWorkListResponse:`

  Response when listing work items with cursor-based pagination.

  - `List<BetaSelfHostedWork> data`

    List of work items

    - `String id`

      Work identifier (e.g., 'work_...')

    - `Optional<String> acknowledgedAt`

      RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox

    - `String createdAt`

      RFC 3339 timestamp when work was created

    - `BetaSessionWorkData data`

      The actual work to be performed

      - `String id`

        Session identifier (e.g., 'session_...')

      - `JsonValue; type "session"constant`

        Type of work data

        - `SESSION("session")`

    - `String environmentId`

      Environment identifier this work belongs to (e.g., `env_...`)

    - `Optional<String> latestHeartbeatAt`

      RFC 3339 timestamp of the most recent heartbeat

    - `Metadata metadata`

      User-provided metadata key-value pairs associated with this work item

    - `Optional<String> startedAt`

      RFC 3339 timestamp when work execution started

    - `State state`

      Current state of the work item

      - `QUEUED("queued")`

      - `STARTING("starting")`

      - `ACTIVE("active")`

      - `STOPPING("stopping")`

      - `STOPPED("stopped")`

    - `Optional<String> stopRequestedAt`

      RFC 3339 timestamp when stop was requested

    - `Optional<String> stoppedAt`

      RFC 3339 timestamp when work execution stopped

    - `JsonValue; type "work"constant`

      The type of object (always 'work')

      - `WORK("work")`

  - `Optional<String> nextPage`

    Opaque cursor for fetching the next page of results

### Beta Self Hosted Work Queue Stats

- `class BetaSelfHostedWorkQueueStats:`

  Statistics about the work queue for an environment.

  Uses Redis Stream consumer group metrics for O(1) queries.

  - `long depth`

    Number of work items waiting to be picked up (lag from consumer group)

  - `Optional<String> oldestQueuedAt`

    RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty

  - `long pending`

    Number of work items being processed (polled but not acknowledged)

  - `JsonValue; type "work_queue_stats"constant`

    The type of object

    - `WORK_QUEUE_STATS("work_queue_stats")`

  - `Optional<Long> workersPolling`

    Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests.

### Beta Self Hosted Work Stop Request

- `class BetaSelfHostedWorkStopRequest:`

  Request to stop a work item.

  - `Optional<Boolean> force`

    If true, immediately stop work without graceful shutdown

### Beta Self Hosted Work Update Request

- `class BetaSelfHostedWorkUpdateRequest:`

  Request to update work item metadata.

  - `Metadata metadata`

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve existing metadata.

### Beta Session Work Data

- `class BetaSessionWorkData:`

  Work data for session work items.

  This resource type is used when work represents a session that needs to be executed
  in a self-hosted environment.

  - `String id`

    Session identifier (e.g., 'session_...')

  - `JsonValue; type "session"constant`

    Type of work data

    - `SESSION("session")`

# Sessions

## Create Session

`BetaManagedAgentsSession beta().sessions().create(SessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/sessions`

Create Session

### Parameters

- `SessionCreateParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Agent agent`

    Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified.

    - `String`

    - `class BetaManagedAgentsAgentParams:`

      Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version

      - `String id`

        The `agent` ID.

      - `Type type`

        - `AGENT("agent")`

      - `Optional<Long> version`

        The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.

  - `String environmentId`

    ID of the `environment` defining the container configuration for this session.

  - `Optional<Metadata> metadata`

    Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

  - `Optional<List<Resource>> resources`

    Resources (e.g. repositories, files) to mount into the session's container.

    - `class BetaManagedAgentsGitHubRepositoryResourceParams:`

      Mount a GitHub repository into the session's container.

      - `String authorizationToken`

        GitHub authorization token used to clone the repository.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceParams:`

      Mount a file uploaded via the Files API into the session.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceParam:`

      Parameters for attaching a memory store to an agent session.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<String> title`

    Human-readable session title.

  - `Optional<List<String>> vaultIds`

    Vault IDs for stored credentials the agent can use during the session.

### Returns

- `class BetaManagedAgentsSession:`

  A Managed Agents `session`.

  - `String id`

  - `BetaManagedAgentsSessionAgent agent`

    Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

      Resolved coordinator topology with full agent definitions for each roster member.

      - `List<BetaManagedAgentsSessionThreadAgent> agents`

        Full `agent` definitions the coordinator may spawn as session threads.

        - `String id`

        - `Optional<String> description`

        - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

          - `String name`

          - `Type type`

          - `String url`

        - `BetaManagedAgentsModelConfig model`

          Model identifier and configuration.

        - `String name`

        - `List<Skill> skills`

          - `class BetaManagedAgentsAnthropicSkill:`

            A resolved Anthropic-managed skill.

            - `String skillId`

            - `Type type`

              - `ANTHROPIC("anthropic")`

            - `String version`

          - `class BetaManagedAgentsCustomSkill:`

            A resolved user-created custom skill.

            - `String skillId`

            - `Type type`

              - `CUSTOM("custom")`

            - `String version`

        - `Optional<String> system`

        - `List<Tool> tools`

          - `class BetaManagedAgentsAgentToolset20260401:`

            - `List<BetaManagedAgentsAgentToolConfig> configs`

              - `boolean enabled`

              - `Name name`

                Built-in agent tool identifier.

                - `BASH("bash")`

                - `EDIT("edit")`

                - `READ("read")`

                - `WRITE("write")`

                - `GLOB("glob")`

                - `GREP("grep")`

                - `WEB_FETCH("web_fetch")`

                - `WEB_SEARCH("web_search")`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                  - `Type type`

                    - `ALWAYS_ALLOW("always_allow")`

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

                  - `Type type`

                    - `ALWAYS_ASK("always_ask")`

            - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

              Resolved default configuration for agent tools.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `Type type`

              - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

          - `class BetaManagedAgentsMcpToolset:`

            - `List<BetaManagedAgentsMcpToolConfig> configs`

              - `boolean enabled`

              - `String name`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

              Resolved default configuration for all tools from an MCP server.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `String mcpServerName`

            - `Type type`

              - `MCP_TOOLSET("mcp_toolset")`

          - `class BetaManagedAgentsCustomTool:`

            A custom tool as returned in API responses.

            - `String description`

            - `BetaManagedAgentsCustomToolInputSchema inputSchema`

              JSON Schema for custom tool input parameters.

              - `JsonValue; type "object"constant`

                - `OBJECT("object")`

              - `Optional<Properties> properties`

              - `Optional<List<String>> required`

            - `String name`

            - `Type type`

              - `CUSTOM("custom")`

        - `Type type`

          - `AGENT("agent")`

        - `long version`

      - `Type type`

        - `COORDINATOR("coordinator")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

      - `class BetaManagedAgentsMcpToolset:`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String environmentId`

  - `Metadata metadata`

  - `List<BetaManagedAgentsOutcomeEvaluationResource> outcomeEvaluations`

    Per-outcome evaluation state. One entry per define_outcome event sent to the session.

    - `Optional<LocalDateTime> completedAt`

      A timestamp in RFC 3339 format

    - `String description`

      What the agent should produce.

    - `Optional<String> explanation`

      Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.

    - `long iteration`

      0-indexed revision cycle the outcome is currently on.

    - `String outcomeId`

      Server-generated outc_ ID for this outcome.

    - `String result`

      Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.

    - `Type type`

      - `OUTCOME_EVALUATION("outcome_evaluation")`

  - `List<BetaManagedAgentsSessionResource> resources`

    - `class BetaManagedAgentsGitHubRepositoryResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String mountPath`

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

      - `String url`

      - `Optional<Checkout> checkout`

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

    - `class BetaManagedAgentsFileResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String fileId`

      - `String mountPath`

      - `Type type`

        - `FILE("file")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

    - `class BetaManagedAgentsMemoryStoreResource:`

      A memory store attached to an agent session.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> description`

        Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

      - `Optional<String> mountPath`

        Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

      - `Optional<String> name`

        Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

  - `BetaManagedAgentsSessionStats stats`

    Timing statistics for a session.

    - `Optional<Double> activeSeconds`

      Cumulative time in seconds the session spent in running status. Excludes idle time.

    - `Optional<Double> durationSeconds`

      Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

  - `Status status`

    SessionStatus enum

    - `RESCHEDULING("rescheduling")`

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `TERMINATED("terminated")`

  - `Optional<String> title`

  - `Type type`

    - `SESSION("session")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `BetaManagedAgentsSessionUsage usage`

    Cumulative token usage for a session across all turns.

    - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

      Prompt-cache creation token usage broken down by cache lifetime.

      - `Optional<Long> ephemeral1hInputTokens`

        Tokens used to create 1-hour ephemeral cache entries.

      - `Optional<Long> ephemeral5mInputTokens`

        Tokens used to create 5-minute ephemeral cache entries.

    - `Optional<Long> cacheReadInputTokens`

      Total tokens read from prompt cache.

    - `Optional<Long> inputTokens`

      Total input tokens consumed across all turns.

    - `Optional<Long> outputTokens`

      Total output tokens generated across all turns.

  - `List<String> vaultIds`

    Vault IDs attached to the session at creation. Empty when no vaults were supplied.

  - `Optional<String> deploymentId`

    Deployment ID when the session was created from a deployment reference. Null otherwise.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.BetaManagedAgentsSession;
import com.anthropic.models.beta.sessions.SessionCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        SessionCreateParams params = SessionCreateParams.builder()
            .agent("agent_011CZkYpogX7uDKUyvBTophP")
            .environmentId("env_011CZkZ9X2dpNyB7HsEFoRfW")
            .build();
        BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().create(params);
    }
}
```

#### Response

```json
{
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "agent": {
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "description": "A general-purpose starter agent.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-sonnet-4-6",
      "speed": "standard"
    },
    "multiagent": {
      "agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "description": "A focused research subagent.",
          "mcp_servers": [
            {
              "name": "example-mcp",
              "type": "url",
              "url": "https://example-server.modelcontextprotocol.io/sse"
            }
          ],
          "model": {
            "id": "claude-sonnet-4-6",
            "speed": "standard"
          },
          "name": "Researcher",
          "skills": [
            {
              "skill_id": "xlsx",
              "type": "anthropic",
              "version": "1"
            }
          ],
          "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
          "tools": [
            {
              "configs": [
                {
                  "enabled": true,
                  "name": "bash",
                  "permission_policy": {
                    "type": "always_allow"
                  }
                }
              ],
              "default_config": {
                "enabled": true,
                "permission_policy": {
                  "type": "always_ask"
                }
              },
              "type": "agent_toolset_20260401"
            }
          ],
          "type": "agent",
          "version": 1
        }
      ],
      "type": "coordinator"
    },
    "name": "My First Agent",
    "skills": [
      {
        "skill_id": "xlsx",
        "type": "anthropic",
        "version": "1"
      },
      {
        "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
        "type": "custom",
        "version": "2"
      }
    ],
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            }
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "metadata": {},
  "outcome_evaluations": [
    {
      "completed_at": "2026-03-15T10:02:31Z",
      "description": "Produce a 2-page summary as summary.md",
      "explanation": "All five sections present with inline citations.",
      "iteration": 0,
      "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
      "result": "satisfied",
      "type": "outcome_evaluation"
    }
  ],
  "resources": [
    {
      "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
      "created_at": "2026-03-15T10:00:00Z",
      "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
      "mount_path": "/uploads/receipt.pdf",
      "type": "file",
      "updated_at": "2026-03-15T10:00:00Z"
    },
    {
      "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
      "created_at": "2026-03-15T10:00:00Z",
      "mount_path": "/workspace/example-repo",
      "type": "github_repository",
      "updated_at": "2026-03-15T10:00:00Z",
      "url": "https://github.com/example-org/example-repo",
      "checkout": {
        "name": "main",
        "type": "branch"
      }
    }
  ],
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "status": "idle",
  "title": "Order #1234 inquiry",
  "type": "session",
  "updated_at": "2026-03-15T10:00:00Z",
  "usage": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  },
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ],
  "deployment_id": "deployment_id"
}
```

## List Sessions

`SessionListPage beta().sessions().list(SessionListParamsparams = SessionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/sessions`

List Sessions

### Parameters

- `SessionListParams params`

  - `Optional<String> agentId`

    Filter sessions created with this agent ID.

  - `Optional<Long> agentVersion`

    Filter by agent version. Only applies when agent_id is also set.

  - `Optional<LocalDateTime> createdAtGt`

    Return sessions created after this time (exclusive).

  - `Optional<LocalDateTime> createdAtGte`

    Return sessions created at or after this time (inclusive).

  - `Optional<LocalDateTime> createdAtLt`

    Return sessions created before this time (exclusive).

  - `Optional<LocalDateTime> createdAtLte`

    Return sessions created at or before this time (inclusive).

  - `Optional<String> deploymentId`

    Filter sessions created by this deployment ID.

  - `Optional<Boolean> includeArchived`

    When true, includes archived sessions. Default: false (exclude archived).

  - `Optional<Long> limit`

    Maximum number of results to return.

  - `Optional<String> memoryStoreId`

    Filter sessions whose resources contain a memory_store with this memory store ID.

  - `Optional<Order> order`

    Sort direction for results, ordered by created_at. Defaults to desc (newest first).

    - `ASC("asc")`

    - `DESC("desc")`

  - `Optional<String> page`

    Opaque pagination cursor from a previous response.

  - `Optional<List<Status>> statuses`

    Filter by session status. Repeat the parameter to match any of multiple statuses.

    - `RESCHEDULING("rescheduling")`

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `TERMINATED("terminated")`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsSession:`

  A Managed Agents `session`.

  - `String id`

  - `BetaManagedAgentsSessionAgent agent`

    Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

      Resolved coordinator topology with full agent definitions for each roster member.

      - `List<BetaManagedAgentsSessionThreadAgent> agents`

        Full `agent` definitions the coordinator may spawn as session threads.

        - `String id`

        - `Optional<String> description`

        - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

          - `String name`

          - `Type type`

          - `String url`

        - `BetaManagedAgentsModelConfig model`

          Model identifier and configuration.

        - `String name`

        - `List<Skill> skills`

          - `class BetaManagedAgentsAnthropicSkill:`

            A resolved Anthropic-managed skill.

            - `String skillId`

            - `Type type`

              - `ANTHROPIC("anthropic")`

            - `String version`

          - `class BetaManagedAgentsCustomSkill:`

            A resolved user-created custom skill.

            - `String skillId`

            - `Type type`

              - `CUSTOM("custom")`

            - `String version`

        - `Optional<String> system`

        - `List<Tool> tools`

          - `class BetaManagedAgentsAgentToolset20260401:`

            - `List<BetaManagedAgentsAgentToolConfig> configs`

              - `boolean enabled`

              - `Name name`

                Built-in agent tool identifier.

                - `BASH("bash")`

                - `EDIT("edit")`

                - `READ("read")`

                - `WRITE("write")`

                - `GLOB("glob")`

                - `GREP("grep")`

                - `WEB_FETCH("web_fetch")`

                - `WEB_SEARCH("web_search")`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                  - `Type type`

                    - `ALWAYS_ALLOW("always_allow")`

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

                  - `Type type`

                    - `ALWAYS_ASK("always_ask")`

            - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

              Resolved default configuration for agent tools.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `Type type`

              - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

          - `class BetaManagedAgentsMcpToolset:`

            - `List<BetaManagedAgentsMcpToolConfig> configs`

              - `boolean enabled`

              - `String name`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

              Resolved default configuration for all tools from an MCP server.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `String mcpServerName`

            - `Type type`

              - `MCP_TOOLSET("mcp_toolset")`

          - `class BetaManagedAgentsCustomTool:`

            A custom tool as returned in API responses.

            - `String description`

            - `BetaManagedAgentsCustomToolInputSchema inputSchema`

              JSON Schema for custom tool input parameters.

              - `JsonValue; type "object"constant`

                - `OBJECT("object")`

              - `Optional<Properties> properties`

              - `Optional<List<String>> required`

            - `String name`

            - `Type type`

              - `CUSTOM("custom")`

        - `Type type`

          - `AGENT("agent")`

        - `long version`

      - `Type type`

        - `COORDINATOR("coordinator")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

      - `class BetaManagedAgentsMcpToolset:`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String environmentId`

  - `Metadata metadata`

  - `List<BetaManagedAgentsOutcomeEvaluationResource> outcomeEvaluations`

    Per-outcome evaluation state. One entry per define_outcome event sent to the session.

    - `Optional<LocalDateTime> completedAt`

      A timestamp in RFC 3339 format

    - `String description`

      What the agent should produce.

    - `Optional<String> explanation`

      Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.

    - `long iteration`

      0-indexed revision cycle the outcome is currently on.

    - `String outcomeId`

      Server-generated outc_ ID for this outcome.

    - `String result`

      Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.

    - `Type type`

      - `OUTCOME_EVALUATION("outcome_evaluation")`

  - `List<BetaManagedAgentsSessionResource> resources`

    - `class BetaManagedAgentsGitHubRepositoryResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String mountPath`

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

      - `String url`

      - `Optional<Checkout> checkout`

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

    - `class BetaManagedAgentsFileResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String fileId`

      - `String mountPath`

      - `Type type`

        - `FILE("file")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

    - `class BetaManagedAgentsMemoryStoreResource:`

      A memory store attached to an agent session.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> description`

        Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

      - `Optional<String> mountPath`

        Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

      - `Optional<String> name`

        Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

  - `BetaManagedAgentsSessionStats stats`

    Timing statistics for a session.

    - `Optional<Double> activeSeconds`

      Cumulative time in seconds the session spent in running status. Excludes idle time.

    - `Optional<Double> durationSeconds`

      Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

  - `Status status`

    SessionStatus enum

    - `RESCHEDULING("rescheduling")`

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `TERMINATED("terminated")`

  - `Optional<String> title`

  - `Type type`

    - `SESSION("session")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `BetaManagedAgentsSessionUsage usage`

    Cumulative token usage for a session across all turns.

    - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

      Prompt-cache creation token usage broken down by cache lifetime.

      - `Optional<Long> ephemeral1hInputTokens`

        Tokens used to create 1-hour ephemeral cache entries.

      - `Optional<Long> ephemeral5mInputTokens`

        Tokens used to create 5-minute ephemeral cache entries.

    - `Optional<Long> cacheReadInputTokens`

      Total tokens read from prompt cache.

    - `Optional<Long> inputTokens`

      Total input tokens consumed across all turns.

    - `Optional<Long> outputTokens`

      Total output tokens generated across all turns.

  - `List<String> vaultIds`

    Vault IDs attached to the session at creation. Empty when no vaults were supplied.

  - `Optional<String> deploymentId`

    Deployment ID when the session was created from a deployment reference. Null otherwise.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.SessionListPage;
import com.anthropic.models.beta.sessions.SessionListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        SessionListPage page = client.beta().sessions().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
      "agent": {
        "id": "agent_011CZkYpogX7uDKUyvBTophP",
        "description": "A general-purpose starter agent.",
        "mcp_servers": [
          {
            "name": "example-mcp",
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse"
          }
        ],
        "model": {
          "id": "claude-sonnet-4-6",
          "speed": "standard"
        },
        "multiagent": {
          "agents": [
            {
              "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
              "description": "A focused research subagent.",
              "mcp_servers": [
                {
                  "name": "example-mcp",
                  "type": "url",
                  "url": "https://example-server.modelcontextprotocol.io/sse"
                }
              ],
              "model": {
                "id": "claude-sonnet-4-6",
                "speed": "standard"
              },
              "name": "Researcher",
              "skills": [
                {
                  "skill_id": "xlsx",
                  "type": "anthropic",
                  "version": "1"
                }
              ],
              "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
              "tools": [
                {
                  "configs": [
                    {
                      "enabled": true,
                      "name": "bash",
                      "permission_policy": {
                        "type": "always_allow"
                      }
                    }
                  ],
                  "default_config": {
                    "enabled": true,
                    "permission_policy": {
                      "type": "always_ask"
                    }
                  },
                  "type": "agent_toolset_20260401"
                }
              ],
              "type": "agent",
              "version": 1
            }
          ],
          "type": "coordinator"
        },
        "name": "My First Agent",
        "skills": [
          {
            "skill_id": "xlsx",
            "type": "anthropic",
            "version": "1"
          },
          {
            "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
            "type": "custom",
            "version": "2"
          }
        ],
        "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
        "tools": [
          {
            "configs": [
              {
                "enabled": true,
                "name": "bash",
                "permission_policy": {
                  "type": "always_allow"
                }
              }
            ],
            "default_config": {
              "enabled": true,
              "permission_policy": {
                "type": "always_ask"
              }
            },
            "type": "agent_toolset_20260401"
          }
        ],
        "type": "agent",
        "version": 1
      },
      "archived_at": null,
      "created_at": "2026-03-15T10:00:00Z",
      "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
      "metadata": {},
      "outcome_evaluations": [
        {
          "completed_at": "2026-03-15T10:02:31Z",
          "description": "Produce a 2-page summary as summary.md",
          "explanation": "All five sections present with inline citations.",
          "iteration": 0,
          "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
          "result": "satisfied",
          "type": "outcome_evaluation"
        }
      ],
      "resources": [
        {
          "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
          "created_at": "2026-03-15T10:00:00Z",
          "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
          "mount_path": "/uploads/receipt.pdf",
          "type": "file",
          "updated_at": "2026-03-15T10:00:00Z"
        },
        {
          "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
          "created_at": "2026-03-15T10:00:00Z",
          "mount_path": "/workspace/example-repo",
          "type": "github_repository",
          "updated_at": "2026-03-15T10:00:00Z",
          "url": "https://github.com/example-org/example-repo",
          "checkout": {
            "name": "main",
            "type": "branch"
          }
        }
      ],
      "stats": {
        "active_seconds": 0,
        "duration_seconds": 0
      },
      "status": "idle",
      "title": "Order #1234 inquiry",
      "type": "session",
      "updated_at": "2026-03-15T10:00:00Z",
      "usage": {
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 0
        },
        "cache_read_input_tokens": 0,
        "input_tokens": 0,
        "output_tokens": 0
      },
      "vault_ids": [
        "vlt_011CZkZDLs7fYzm1hXNPeRjv"
      ],
      "deployment_id": "deployment_id"
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```

## Get Session

`BetaManagedAgentsSession beta().sessions().retrieve(SessionRetrieveParamsparams = SessionRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/sessions/{session_id}`

Get Session

### Parameters

- `SessionRetrieveParams params`

  - `Optional<String> sessionId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsSession:`

  A Managed Agents `session`.

  - `String id`

  - `BetaManagedAgentsSessionAgent agent`

    Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

      Resolved coordinator topology with full agent definitions for each roster member.

      - `List<BetaManagedAgentsSessionThreadAgent> agents`

        Full `agent` definitions the coordinator may spawn as session threads.

        - `String id`

        - `Optional<String> description`

        - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

          - `String name`

          - `Type type`

          - `String url`

        - `BetaManagedAgentsModelConfig model`

          Model identifier and configuration.

        - `String name`

        - `List<Skill> skills`

          - `class BetaManagedAgentsAnthropicSkill:`

            A resolved Anthropic-managed skill.

            - `String skillId`

            - `Type type`

              - `ANTHROPIC("anthropic")`

            - `String version`

          - `class BetaManagedAgentsCustomSkill:`

            A resolved user-created custom skill.

            - `String skillId`

            - `Type type`

              - `CUSTOM("custom")`

            - `String version`

        - `Optional<String> system`

        - `List<Tool> tools`

          - `class BetaManagedAgentsAgentToolset20260401:`

            - `List<BetaManagedAgentsAgentToolConfig> configs`

              - `boolean enabled`

              - `Name name`

                Built-in agent tool identifier.

                - `BASH("bash")`

                - `EDIT("edit")`

                - `READ("read")`

                - `WRITE("write")`

                - `GLOB("glob")`

                - `GREP("grep")`

                - `WEB_FETCH("web_fetch")`

                - `WEB_SEARCH("web_search")`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                  - `Type type`

                    - `ALWAYS_ALLOW("always_allow")`

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

                  - `Type type`

                    - `ALWAYS_ASK("always_ask")`

            - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

              Resolved default configuration for agent tools.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `Type type`

              - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

          - `class BetaManagedAgentsMcpToolset:`

            - `List<BetaManagedAgentsMcpToolConfig> configs`

              - `boolean enabled`

              - `String name`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

              Resolved default configuration for all tools from an MCP server.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `String mcpServerName`

            - `Type type`

              - `MCP_TOOLSET("mcp_toolset")`

          - `class BetaManagedAgentsCustomTool:`

            A custom tool as returned in API responses.

            - `String description`

            - `BetaManagedAgentsCustomToolInputSchema inputSchema`

              JSON Schema for custom tool input parameters.

              - `JsonValue; type "object"constant`

                - `OBJECT("object")`

              - `Optional<Properties> properties`

              - `Optional<List<String>> required`

            - `String name`

            - `Type type`

              - `CUSTOM("custom")`

        - `Type type`

          - `AGENT("agent")`

        - `long version`

      - `Type type`

        - `COORDINATOR("coordinator")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

      - `class BetaManagedAgentsMcpToolset:`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String environmentId`

  - `Metadata metadata`

  - `List<BetaManagedAgentsOutcomeEvaluationResource> outcomeEvaluations`

    Per-outcome evaluation state. One entry per define_outcome event sent to the session.

    - `Optional<LocalDateTime> completedAt`

      A timestamp in RFC 3339 format

    - `String description`

      What the agent should produce.

    - `Optional<String> explanation`

      Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.

    - `long iteration`

      0-indexed revision cycle the outcome is currently on.

    - `String outcomeId`

      Server-generated outc_ ID for this outcome.

    - `String result`

      Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.

    - `Type type`

      - `OUTCOME_EVALUATION("outcome_evaluation")`

  - `List<BetaManagedAgentsSessionResource> resources`

    - `class BetaManagedAgentsGitHubRepositoryResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String mountPath`

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

      - `String url`

      - `Optional<Checkout> checkout`

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

    - `class BetaManagedAgentsFileResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String fileId`

      - `String mountPath`

      - `Type type`

        - `FILE("file")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

    - `class BetaManagedAgentsMemoryStoreResource:`

      A memory store attached to an agent session.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> description`

        Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

      - `Optional<String> mountPath`

        Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

      - `Optional<String> name`

        Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

  - `BetaManagedAgentsSessionStats stats`

    Timing statistics for a session.

    - `Optional<Double> activeSeconds`

      Cumulative time in seconds the session spent in running status. Excludes idle time.

    - `Optional<Double> durationSeconds`

      Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

  - `Status status`

    SessionStatus enum

    - `RESCHEDULING("rescheduling")`

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `TERMINATED("terminated")`

  - `Optional<String> title`

  - `Type type`

    - `SESSION("session")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `BetaManagedAgentsSessionUsage usage`

    Cumulative token usage for a session across all turns.

    - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

      Prompt-cache creation token usage broken down by cache lifetime.

      - `Optional<Long> ephemeral1hInputTokens`

        Tokens used to create 1-hour ephemeral cache entries.

      - `Optional<Long> ephemeral5mInputTokens`

        Tokens used to create 5-minute ephemeral cache entries.

    - `Optional<Long> cacheReadInputTokens`

      Total tokens read from prompt cache.

    - `Optional<Long> inputTokens`

      Total input tokens consumed across all turns.

    - `Optional<Long> outputTokens`

      Total output tokens generated across all turns.

  - `List<String> vaultIds`

    Vault IDs attached to the session at creation. Empty when no vaults were supplied.

  - `Optional<String> deploymentId`

    Deployment ID when the session was created from a deployment reference. Null otherwise.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.BetaManagedAgentsSession;
import com.anthropic.models.beta.sessions.SessionRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().retrieve("sesn_011CZkZAtmR3yMPDzynEDxu7");
    }
}
```

#### Response

```json
{
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "agent": {
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "description": "A general-purpose starter agent.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-sonnet-4-6",
      "speed": "standard"
    },
    "multiagent": {
      "agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "description": "A focused research subagent.",
          "mcp_servers": [
            {
              "name": "example-mcp",
              "type": "url",
              "url": "https://example-server.modelcontextprotocol.io/sse"
            }
          ],
          "model": {
            "id": "claude-sonnet-4-6",
            "speed": "standard"
          },
          "name": "Researcher",
          "skills": [
            {
              "skill_id": "xlsx",
              "type": "anthropic",
              "version": "1"
            }
          ],
          "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
          "tools": [
            {
              "configs": [
                {
                  "enabled": true,
                  "name": "bash",
                  "permission_policy": {
                    "type": "always_allow"
                  }
                }
              ],
              "default_config": {
                "enabled": true,
                "permission_policy": {
                  "type": "always_ask"
                }
              },
              "type": "agent_toolset_20260401"
            }
          ],
          "type": "agent",
          "version": 1
        }
      ],
      "type": "coordinator"
    },
    "name": "My First Agent",
    "skills": [
      {
        "skill_id": "xlsx",
        "type": "anthropic",
        "version": "1"
      },
      {
        "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
        "type": "custom",
        "version": "2"
      }
    ],
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            }
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "metadata": {},
  "outcome_evaluations": [
    {
      "completed_at": "2026-03-15T10:02:31Z",
      "description": "Produce a 2-page summary as summary.md",
      "explanation": "All five sections present with inline citations.",
      "iteration": 0,
      "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
      "result": "satisfied",
      "type": "outcome_evaluation"
    }
  ],
  "resources": [
    {
      "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
      "created_at": "2026-03-15T10:00:00Z",
      "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
      "mount_path": "/uploads/receipt.pdf",
      "type": "file",
      "updated_at": "2026-03-15T10:00:00Z"
    },
    {
      "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
      "created_at": "2026-03-15T10:00:00Z",
      "mount_path": "/workspace/example-repo",
      "type": "github_repository",
      "updated_at": "2026-03-15T10:00:00Z",
      "url": "https://github.com/example-org/example-repo",
      "checkout": {
        "name": "main",
        "type": "branch"
      }
    }
  ],
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "status": "idle",
  "title": "Order #1234 inquiry",
  "type": "session",
  "updated_at": "2026-03-15T10:00:00Z",
  "usage": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  },
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ],
  "deployment_id": "deployment_id"
}
```

## Update Session

`BetaManagedAgentsSession beta().sessions().update(SessionUpdateParamsparams = SessionUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/sessions/{session_id}`

Update Session

### Parameters

- `SessionUpdateParams params`

  - `Optional<String> sessionId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<BetaManagedAgentsSessionAgentUpdate> agent`

    Mid-session agent configuration update. Only `tools` and `mcp_servers` are updatable. Full replacement: the provided array becomes the new value. To preserve existing entries, GET the session, modify the array, and POST it back.

  - `Optional<Metadata> metadata`

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.

  - `Optional<String> title`

    Human-readable session title.

  - `Optional<List<String>> vaultIds`

    Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.

### Returns

- `class BetaManagedAgentsSession:`

  A Managed Agents `session`.

  - `String id`

  - `BetaManagedAgentsSessionAgent agent`

    Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

      Resolved coordinator topology with full agent definitions for each roster member.

      - `List<BetaManagedAgentsSessionThreadAgent> agents`

        Full `agent` definitions the coordinator may spawn as session threads.

        - `String id`

        - `Optional<String> description`

        - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

          - `String name`

          - `Type type`

          - `String url`

        - `BetaManagedAgentsModelConfig model`

          Model identifier and configuration.

        - `String name`

        - `List<Skill> skills`

          - `class BetaManagedAgentsAnthropicSkill:`

            A resolved Anthropic-managed skill.

            - `String skillId`

            - `Type type`

              - `ANTHROPIC("anthropic")`

            - `String version`

          - `class BetaManagedAgentsCustomSkill:`

            A resolved user-created custom skill.

            - `String skillId`

            - `Type type`

              - `CUSTOM("custom")`

            - `String version`

        - `Optional<String> system`

        - `List<Tool> tools`

          - `class BetaManagedAgentsAgentToolset20260401:`

            - `List<BetaManagedAgentsAgentToolConfig> configs`

              - `boolean enabled`

              - `Name name`

                Built-in agent tool identifier.

                - `BASH("bash")`

                - `EDIT("edit")`

                - `READ("read")`

                - `WRITE("write")`

                - `GLOB("glob")`

                - `GREP("grep")`

                - `WEB_FETCH("web_fetch")`

                - `WEB_SEARCH("web_search")`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                  - `Type type`

                    - `ALWAYS_ALLOW("always_allow")`

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

                  - `Type type`

                    - `ALWAYS_ASK("always_ask")`

            - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

              Resolved default configuration for agent tools.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `Type type`

              - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

          - `class BetaManagedAgentsMcpToolset:`

            - `List<BetaManagedAgentsMcpToolConfig> configs`

              - `boolean enabled`

              - `String name`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

              Resolved default configuration for all tools from an MCP server.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `String mcpServerName`

            - `Type type`

              - `MCP_TOOLSET("mcp_toolset")`

          - `class BetaManagedAgentsCustomTool:`

            A custom tool as returned in API responses.

            - `String description`

            - `BetaManagedAgentsCustomToolInputSchema inputSchema`

              JSON Schema for custom tool input parameters.

              - `JsonValue; type "object"constant`

                - `OBJECT("object")`

              - `Optional<Properties> properties`

              - `Optional<List<String>> required`

            - `String name`

            - `Type type`

              - `CUSTOM("custom")`

        - `Type type`

          - `AGENT("agent")`

        - `long version`

      - `Type type`

        - `COORDINATOR("coordinator")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

      - `class BetaManagedAgentsMcpToolset:`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String environmentId`

  - `Metadata metadata`

  - `List<BetaManagedAgentsOutcomeEvaluationResource> outcomeEvaluations`

    Per-outcome evaluation state. One entry per define_outcome event sent to the session.

    - `Optional<LocalDateTime> completedAt`

      A timestamp in RFC 3339 format

    - `String description`

      What the agent should produce.

    - `Optional<String> explanation`

      Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.

    - `long iteration`

      0-indexed revision cycle the outcome is currently on.

    - `String outcomeId`

      Server-generated outc_ ID for this outcome.

    - `String result`

      Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.

    - `Type type`

      - `OUTCOME_EVALUATION("outcome_evaluation")`

  - `List<BetaManagedAgentsSessionResource> resources`

    - `class BetaManagedAgentsGitHubRepositoryResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String mountPath`

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

      - `String url`

      - `Optional<Checkout> checkout`

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

    - `class BetaManagedAgentsFileResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String fileId`

      - `String mountPath`

      - `Type type`

        - `FILE("file")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

    - `class BetaManagedAgentsMemoryStoreResource:`

      A memory store attached to an agent session.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> description`

        Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

      - `Optional<String> mountPath`

        Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

      - `Optional<String> name`

        Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

  - `BetaManagedAgentsSessionStats stats`

    Timing statistics for a session.

    - `Optional<Double> activeSeconds`

      Cumulative time in seconds the session spent in running status. Excludes idle time.

    - `Optional<Double> durationSeconds`

      Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

  - `Status status`

    SessionStatus enum

    - `RESCHEDULING("rescheduling")`

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `TERMINATED("terminated")`

  - `Optional<String> title`

  - `Type type`

    - `SESSION("session")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `BetaManagedAgentsSessionUsage usage`

    Cumulative token usage for a session across all turns.

    - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

      Prompt-cache creation token usage broken down by cache lifetime.

      - `Optional<Long> ephemeral1hInputTokens`

        Tokens used to create 1-hour ephemeral cache entries.

      - `Optional<Long> ephemeral5mInputTokens`

        Tokens used to create 5-minute ephemeral cache entries.

    - `Optional<Long> cacheReadInputTokens`

      Total tokens read from prompt cache.

    - `Optional<Long> inputTokens`

      Total input tokens consumed across all turns.

    - `Optional<Long> outputTokens`

      Total output tokens generated across all turns.

  - `List<String> vaultIds`

    Vault IDs attached to the session at creation. Empty when no vaults were supplied.

  - `Optional<String> deploymentId`

    Deployment ID when the session was created from a deployment reference. Null otherwise.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.BetaManagedAgentsSession;
import com.anthropic.models.beta.sessions.SessionUpdateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().update("sesn_011CZkZAtmR3yMPDzynEDxu7");
    }
}
```

#### Response

```json
{
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "agent": {
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "description": "A general-purpose starter agent.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-sonnet-4-6",
      "speed": "standard"
    },
    "multiagent": {
      "agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "description": "A focused research subagent.",
          "mcp_servers": [
            {
              "name": "example-mcp",
              "type": "url",
              "url": "https://example-server.modelcontextprotocol.io/sse"
            }
          ],
          "model": {
            "id": "claude-sonnet-4-6",
            "speed": "standard"
          },
          "name": "Researcher",
          "skills": [
            {
              "skill_id": "xlsx",
              "type": "anthropic",
              "version": "1"
            }
          ],
          "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
          "tools": [
            {
              "configs": [
                {
                  "enabled": true,
                  "name": "bash",
                  "permission_policy": {
                    "type": "always_allow"
                  }
                }
              ],
              "default_config": {
                "enabled": true,
                "permission_policy": {
                  "type": "always_ask"
                }
              },
              "type": "agent_toolset_20260401"
            }
          ],
          "type": "agent",
          "version": 1
        }
      ],
      "type": "coordinator"
    },
    "name": "My First Agent",
    "skills": [
      {
        "skill_id": "xlsx",
        "type": "anthropic",
        "version": "1"
      },
      {
        "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
        "type": "custom",
        "version": "2"
      }
    ],
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            }
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "metadata": {},
  "outcome_evaluations": [
    {
      "completed_at": "2026-03-15T10:02:31Z",
      "description": "Produce a 2-page summary as summary.md",
      "explanation": "All five sections present with inline citations.",
      "iteration": 0,
      "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
      "result": "satisfied",
      "type": "outcome_evaluation"
    }
  ],
  "resources": [
    {
      "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
      "created_at": "2026-03-15T10:00:00Z",
      "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
      "mount_path": "/uploads/receipt.pdf",
      "type": "file",
      "updated_at": "2026-03-15T10:00:00Z"
    },
    {
      "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
      "created_at": "2026-03-15T10:00:00Z",
      "mount_path": "/workspace/example-repo",
      "type": "github_repository",
      "updated_at": "2026-03-15T10:00:00Z",
      "url": "https://github.com/example-org/example-repo",
      "checkout": {
        "name": "main",
        "type": "branch"
      }
    }
  ],
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "status": "idle",
  "title": "Order #1234 inquiry",
  "type": "session",
  "updated_at": "2026-03-15T10:00:00Z",
  "usage": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  },
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ],
  "deployment_id": "deployment_id"
}
```

## Delete Session

`BetaManagedAgentsDeletedSession beta().sessions().delete(SessionDeleteParamsparams = SessionDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/sessions/{session_id}`

Delete Session

### Parameters

- `SessionDeleteParams params`

  - `Optional<String> sessionId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeletedSession:`

  Confirmation that a `session` has been permanently deleted.

  - `String id`

  - `Type type`

    - `SESSION_DELETED("session_deleted")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.BetaManagedAgentsDeletedSession;
import com.anthropic.models.beta.sessions.SessionDeleteParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsDeletedSession betaManagedAgentsDeletedSession = client.beta().sessions().delete("sesn_011CZkZAtmR3yMPDzynEDxu7");
    }
}
```

#### Response

```json
{
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "type": "session_deleted"
}
```

## Archive Session

`BetaManagedAgentsSession beta().sessions().archive(SessionArchiveParamsparams = SessionArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/sessions/{session_id}/archive`

Archive Session

### Parameters

- `SessionArchiveParams params`

  - `Optional<String> sessionId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsSession:`

  A Managed Agents `session`.

  - `String id`

  - `BetaManagedAgentsSessionAgent agent`

    Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

      Resolved coordinator topology with full agent definitions for each roster member.

      - `List<BetaManagedAgentsSessionThreadAgent> agents`

        Full `agent` definitions the coordinator may spawn as session threads.

        - `String id`

        - `Optional<String> description`

        - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

          - `String name`

          - `Type type`

          - `String url`

        - `BetaManagedAgentsModelConfig model`

          Model identifier and configuration.

        - `String name`

        - `List<Skill> skills`

          - `class BetaManagedAgentsAnthropicSkill:`

            A resolved Anthropic-managed skill.

            - `String skillId`

            - `Type type`

              - `ANTHROPIC("anthropic")`

            - `String version`

          - `class BetaManagedAgentsCustomSkill:`

            A resolved user-created custom skill.

            - `String skillId`

            - `Type type`

              - `CUSTOM("custom")`

            - `String version`

        - `Optional<String> system`

        - `List<Tool> tools`

          - `class BetaManagedAgentsAgentToolset20260401:`

            - `List<BetaManagedAgentsAgentToolConfig> configs`

              - `boolean enabled`

              - `Name name`

                Built-in agent tool identifier.

                - `BASH("bash")`

                - `EDIT("edit")`

                - `READ("read")`

                - `WRITE("write")`

                - `GLOB("glob")`

                - `GREP("grep")`

                - `WEB_FETCH("web_fetch")`

                - `WEB_SEARCH("web_search")`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                  - `Type type`

                    - `ALWAYS_ALLOW("always_allow")`

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

                  - `Type type`

                    - `ALWAYS_ASK("always_ask")`

            - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

              Resolved default configuration for agent tools.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `Type type`

              - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

          - `class BetaManagedAgentsMcpToolset:`

            - `List<BetaManagedAgentsMcpToolConfig> configs`

              - `boolean enabled`

              - `String name`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

              Resolved default configuration for all tools from an MCP server.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `String mcpServerName`

            - `Type type`

              - `MCP_TOOLSET("mcp_toolset")`

          - `class BetaManagedAgentsCustomTool:`

            A custom tool as returned in API responses.

            - `String description`

            - `BetaManagedAgentsCustomToolInputSchema inputSchema`

              JSON Schema for custom tool input parameters.

              - `JsonValue; type "object"constant`

                - `OBJECT("object")`

              - `Optional<Properties> properties`

              - `Optional<List<String>> required`

            - `String name`

            - `Type type`

              - `CUSTOM("custom")`

        - `Type type`

          - `AGENT("agent")`

        - `long version`

      - `Type type`

        - `COORDINATOR("coordinator")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

      - `class BetaManagedAgentsMcpToolset:`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String environmentId`

  - `Metadata metadata`

  - `List<BetaManagedAgentsOutcomeEvaluationResource> outcomeEvaluations`

    Per-outcome evaluation state. One entry per define_outcome event sent to the session.

    - `Optional<LocalDateTime> completedAt`

      A timestamp in RFC 3339 format

    - `String description`

      What the agent should produce.

    - `Optional<String> explanation`

      Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.

    - `long iteration`

      0-indexed revision cycle the outcome is currently on.

    - `String outcomeId`

      Server-generated outc_ ID for this outcome.

    - `String result`

      Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.

    - `Type type`

      - `OUTCOME_EVALUATION("outcome_evaluation")`

  - `List<BetaManagedAgentsSessionResource> resources`

    - `class BetaManagedAgentsGitHubRepositoryResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String mountPath`

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

      - `String url`

      - `Optional<Checkout> checkout`

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

    - `class BetaManagedAgentsFileResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String fileId`

      - `String mountPath`

      - `Type type`

        - `FILE("file")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

    - `class BetaManagedAgentsMemoryStoreResource:`

      A memory store attached to an agent session.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> description`

        Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

      - `Optional<String> mountPath`

        Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

      - `Optional<String> name`

        Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

  - `BetaManagedAgentsSessionStats stats`

    Timing statistics for a session.

    - `Optional<Double> activeSeconds`

      Cumulative time in seconds the session spent in running status. Excludes idle time.

    - `Optional<Double> durationSeconds`

      Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

  - `Status status`

    SessionStatus enum

    - `RESCHEDULING("rescheduling")`

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `TERMINATED("terminated")`

  - `Optional<String> title`

  - `Type type`

    - `SESSION("session")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `BetaManagedAgentsSessionUsage usage`

    Cumulative token usage for a session across all turns.

    - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

      Prompt-cache creation token usage broken down by cache lifetime.

      - `Optional<Long> ephemeral1hInputTokens`

        Tokens used to create 1-hour ephemeral cache entries.

      - `Optional<Long> ephemeral5mInputTokens`

        Tokens used to create 5-minute ephemeral cache entries.

    - `Optional<Long> cacheReadInputTokens`

      Total tokens read from prompt cache.

    - `Optional<Long> inputTokens`

      Total input tokens consumed across all turns.

    - `Optional<Long> outputTokens`

      Total output tokens generated across all turns.

  - `List<String> vaultIds`

    Vault IDs attached to the session at creation. Empty when no vaults were supplied.

  - `Optional<String> deploymentId`

    Deployment ID when the session was created from a deployment reference. Null otherwise.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.BetaManagedAgentsSession;
import com.anthropic.models.beta.sessions.SessionArchiveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsSession betaManagedAgentsSession = client.beta().sessions().archive("sesn_011CZkZAtmR3yMPDzynEDxu7");
    }
}
```

#### Response

```json
{
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "agent": {
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "description": "A general-purpose starter agent.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-sonnet-4-6",
      "speed": "standard"
    },
    "multiagent": {
      "agents": [
        {
          "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
          "description": "A focused research subagent.",
          "mcp_servers": [
            {
              "name": "example-mcp",
              "type": "url",
              "url": "https://example-server.modelcontextprotocol.io/sse"
            }
          ],
          "model": {
            "id": "claude-sonnet-4-6",
            "speed": "standard"
          },
          "name": "Researcher",
          "skills": [
            {
              "skill_id": "xlsx",
              "type": "anthropic",
              "version": "1"
            }
          ],
          "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
          "tools": [
            {
              "configs": [
                {
                  "enabled": true,
                  "name": "bash",
                  "permission_policy": {
                    "type": "always_allow"
                  }
                }
              ],
              "default_config": {
                "enabled": true,
                "permission_policy": {
                  "type": "always_ask"
                }
              },
              "type": "agent_toolset_20260401"
            }
          ],
          "type": "agent",
          "version": 1
        }
      ],
      "type": "coordinator"
    },
    "name": "My First Agent",
    "skills": [
      {
        "skill_id": "xlsx",
        "type": "anthropic",
        "version": "1"
      },
      {
        "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
        "type": "custom",
        "version": "2"
      }
    ],
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            }
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "metadata": {},
  "outcome_evaluations": [
    {
      "completed_at": "2026-03-15T10:02:31Z",
      "description": "Produce a 2-page summary as summary.md",
      "explanation": "All five sections present with inline citations.",
      "iteration": 0,
      "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
      "result": "satisfied",
      "type": "outcome_evaluation"
    }
  ],
  "resources": [
    {
      "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
      "created_at": "2026-03-15T10:00:00Z",
      "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
      "mount_path": "/uploads/receipt.pdf",
      "type": "file",
      "updated_at": "2026-03-15T10:00:00Z"
    },
    {
      "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
      "created_at": "2026-03-15T10:00:00Z",
      "mount_path": "/workspace/example-repo",
      "type": "github_repository",
      "updated_at": "2026-03-15T10:00:00Z",
      "url": "https://github.com/example-org/example-repo",
      "checkout": {
        "name": "main",
        "type": "branch"
      }
    }
  ],
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "status": "idle",
  "title": "Order #1234 inquiry",
  "type": "session",
  "updated_at": "2026-03-15T10:00:00Z",
  "usage": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  },
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ],
  "deployment_id": "deployment_id"
}
```

## Domain Types

### Beta Managed Agents Agent Params

- `class BetaManagedAgentsAgentParams:`

  Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version

  - `String id`

    The `agent` ID.

  - `Type type`

    - `AGENT("agent")`

  - `Optional<Long> version`

    The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.

### Beta Managed Agents Branch Checkout

- `class BetaManagedAgentsBranchCheckout:`

  - `String name`

    Branch name to check out.

  - `Type type`

    - `BRANCH("branch")`

### Beta Managed Agents Cache Creation Usage

- `class BetaManagedAgentsCacheCreationUsage:`

  Prompt-cache creation token usage broken down by cache lifetime.

  - `Optional<Long> ephemeral1hInputTokens`

    Tokens used to create 1-hour ephemeral cache entries.

  - `Optional<Long> ephemeral5mInputTokens`

    Tokens used to create 5-minute ephemeral cache entries.

### Beta Managed Agents Commit Checkout

- `class BetaManagedAgentsCommitCheckout:`

  - `String sha`

    Full commit SHA to check out.

  - `Type type`

    - `COMMIT("commit")`

### Beta Managed Agents Deleted Session

- `class BetaManagedAgentsDeletedSession:`

  Confirmation that a `session` has been permanently deleted.

  - `String id`

  - `Type type`

    - `SESSION_DELETED("session_deleted")`

### Beta Managed Agents File Resource Params

- `class BetaManagedAgentsFileResourceParams:`

  Mount a file uploaded via the Files API into the session.

  - `String fileId`

    ID of a previously uploaded file.

  - `Type type`

    - `FILE("file")`

  - `Optional<String> mountPath`

    Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

### Beta Managed Agents GitHub Repository Resource Params

- `class BetaManagedAgentsGitHubRepositoryResourceParams:`

  Mount a GitHub repository into the session's container.

  - `String authorizationToken`

    GitHub authorization token used to clone the repository.

  - `Type type`

    - `GITHUB_REPOSITORY("github_repository")`

  - `String url`

    Github URL of the repository

  - `Optional<Checkout> checkout`

    Branch or commit to check out. Defaults to the repository's default branch.

    - `class BetaManagedAgentsBranchCheckout:`

      - `String name`

        Branch name to check out.

      - `Type type`

        - `BRANCH("branch")`

    - `class BetaManagedAgentsCommitCheckout:`

      - `String sha`

        Full commit SHA to check out.

      - `Type type`

        - `COMMIT("commit")`

  - `Optional<String> mountPath`

    Mount path in the container. Defaults to `/workspace/<repo-name>`.

### Beta Managed Agents Memory Store Resource Param

- `class BetaManagedAgentsMemoryStoreResourceParam:`

  Parameters for attaching a memory store to an agent session.

  - `String memoryStoreId`

    The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

  - `Type type`

    - `MEMORY_STORE("memory_store")`

  - `Optional<Access> access`

    Access mode for an attached memory store.

    - `READ_WRITE("read_write")`

    - `READ_ONLY("read_only")`

  - `Optional<String> instructions`

    Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

### Beta Managed Agents Multiagent

- `class BetaManagedAgentsMultiagent:`

  Resolved coordinator topology with a concrete agent roster.

  - `List<BetaManagedAgentsAgentReference> agents`

    Agents the coordinator may spawn as session threads, each resolved to a specific version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Type type`

    - `COORDINATOR("coordinator")`

### Beta Managed Agents Multiagent Params

- `class BetaManagedAgentsMultiagentParams:`

  A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster.

  - `List<BetaManagedAgentsMultiagentRosterEntryParams> agents`

    Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1).

    - `String`

    - `class BetaManagedAgentsAgentParams:`

      Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version

      - `String id`

        The `agent` ID.

      - `Type type`

        - `AGENT("agent")`

      - `Optional<Long> version`

        The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.

    - `class BetaManagedAgentsMultiagentSelfParams:`

      Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.

      - `Type type`

        - `SELF("self")`

  - `Type type`

    - `COORDINATOR("coordinator")`

### Beta Managed Agents Multiagent Roster Entry Params

- `class BetaManagedAgentsMultiagentRosterEntryParams: A class that can be one of several variants.union`

  An entry in a multiagent roster: an agent ID string, a versioned agent reference, or `self`.

  - `String`

  - `class BetaManagedAgentsAgentParams:`

    Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version

    - `String id`

      The `agent` ID.

    - `Type type`

      - `AGENT("agent")`

    - `Optional<Long> version`

      The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.

  - `class BetaManagedAgentsMultiagentSelfParams:`

    Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.

    - `Type type`

      - `SELF("self")`

### Beta Managed Agents Outcome Evaluation Resource

- `class BetaManagedAgentsOutcomeEvaluationResource:`

  Evaluation state for a single outcome defined via a define_outcome event.

  - `Optional<LocalDateTime> completedAt`

    A timestamp in RFC 3339 format

  - `String description`

    What the agent should produce.

  - `Optional<String> explanation`

    Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.

  - `long iteration`

    0-indexed revision cycle the outcome is currently on.

  - `String outcomeId`

    Server-generated outc_ ID for this outcome.

  - `String result`

    Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.

  - `Type type`

    - `OUTCOME_EVALUATION("outcome_evaluation")`

### Beta Managed Agents Session

- `class BetaManagedAgentsSession:`

  A Managed Agents `session`.

  - `String id`

  - `BetaManagedAgentsSessionAgent agent`

    Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

      Resolved coordinator topology with full agent definitions for each roster member.

      - `List<BetaManagedAgentsSessionThreadAgent> agents`

        Full `agent` definitions the coordinator may spawn as session threads.

        - `String id`

        - `Optional<String> description`

        - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

          - `String name`

          - `Type type`

          - `String url`

        - `BetaManagedAgentsModelConfig model`

          Model identifier and configuration.

        - `String name`

        - `List<Skill> skills`

          - `class BetaManagedAgentsAnthropicSkill:`

            A resolved Anthropic-managed skill.

            - `String skillId`

            - `Type type`

              - `ANTHROPIC("anthropic")`

            - `String version`

          - `class BetaManagedAgentsCustomSkill:`

            A resolved user-created custom skill.

            - `String skillId`

            - `Type type`

              - `CUSTOM("custom")`

            - `String version`

        - `Optional<String> system`

        - `List<Tool> tools`

          - `class BetaManagedAgentsAgentToolset20260401:`

            - `List<BetaManagedAgentsAgentToolConfig> configs`

              - `boolean enabled`

              - `Name name`

                Built-in agent tool identifier.

                - `BASH("bash")`

                - `EDIT("edit")`

                - `READ("read")`

                - `WRITE("write")`

                - `GLOB("glob")`

                - `GREP("grep")`

                - `WEB_FETCH("web_fetch")`

                - `WEB_SEARCH("web_search")`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                  - `Type type`

                    - `ALWAYS_ALLOW("always_allow")`

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

                  - `Type type`

                    - `ALWAYS_ASK("always_ask")`

            - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

              Resolved default configuration for agent tools.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `Type type`

              - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

          - `class BetaManagedAgentsMcpToolset:`

            - `List<BetaManagedAgentsMcpToolConfig> configs`

              - `boolean enabled`

              - `String name`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

              Resolved default configuration for all tools from an MCP server.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `String mcpServerName`

            - `Type type`

              - `MCP_TOOLSET("mcp_toolset")`

          - `class BetaManagedAgentsCustomTool:`

            A custom tool as returned in API responses.

            - `String description`

            - `BetaManagedAgentsCustomToolInputSchema inputSchema`

              JSON Schema for custom tool input parameters.

              - `JsonValue; type "object"constant`

                - `OBJECT("object")`

              - `Optional<Properties> properties`

              - `Optional<List<String>> required`

            - `String name`

            - `Type type`

              - `CUSTOM("custom")`

        - `Type type`

          - `AGENT("agent")`

        - `long version`

      - `Type type`

        - `COORDINATOR("coordinator")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

      - `class BetaManagedAgentsMcpToolset:`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String environmentId`

  - `Metadata metadata`

  - `List<BetaManagedAgentsOutcomeEvaluationResource> outcomeEvaluations`

    Per-outcome evaluation state. One entry per define_outcome event sent to the session.

    - `Optional<LocalDateTime> completedAt`

      A timestamp in RFC 3339 format

    - `String description`

      What the agent should produce.

    - `Optional<String> explanation`

      Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.

    - `long iteration`

      0-indexed revision cycle the outcome is currently on.

    - `String outcomeId`

      Server-generated outc_ ID for this outcome.

    - `String result`

      Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.

    - `Type type`

      - `OUTCOME_EVALUATION("outcome_evaluation")`

  - `List<BetaManagedAgentsSessionResource> resources`

    - `class BetaManagedAgentsGitHubRepositoryResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String mountPath`

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

      - `String url`

      - `Optional<Checkout> checkout`

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

    - `class BetaManagedAgentsFileResource:`

      - `String id`

      - `LocalDateTime createdAt`

        A timestamp in RFC 3339 format

      - `String fileId`

      - `String mountPath`

      - `Type type`

        - `FILE("file")`

      - `LocalDateTime updatedAt`

        A timestamp in RFC 3339 format

    - `class BetaManagedAgentsMemoryStoreResource:`

      A memory store attached to an agent session.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> description`

        Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

      - `Optional<String> mountPath`

        Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

      - `Optional<String> name`

        Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

  - `BetaManagedAgentsSessionStats stats`

    Timing statistics for a session.

    - `Optional<Double> activeSeconds`

      Cumulative time in seconds the session spent in running status. Excludes idle time.

    - `Optional<Double> durationSeconds`

      Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

  - `Status status`

    SessionStatus enum

    - `RESCHEDULING("rescheduling")`

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `TERMINATED("terminated")`

  - `Optional<String> title`

  - `Type type`

    - `SESSION("session")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `BetaManagedAgentsSessionUsage usage`

    Cumulative token usage for a session across all turns.

    - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

      Prompt-cache creation token usage broken down by cache lifetime.

      - `Optional<Long> ephemeral1hInputTokens`

        Tokens used to create 1-hour ephemeral cache entries.

      - `Optional<Long> ephemeral5mInputTokens`

        Tokens used to create 5-minute ephemeral cache entries.

    - `Optional<Long> cacheReadInputTokens`

      Total tokens read from prompt cache.

    - `Optional<Long> inputTokens`

      Total input tokens consumed across all turns.

    - `Optional<Long> outputTokens`

      Total output tokens generated across all turns.

  - `List<String> vaultIds`

    Vault IDs attached to the session at creation. Empty when no vaults were supplied.

  - `Optional<String> deploymentId`

    Deployment ID when the session was created from a deployment reference. Null otherwise.

### Beta Managed Agents Session Agent

- `class BetaManagedAgentsSessionAgent:`

  Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

  - `String id`

  - `Optional<String> description`

  - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

    - `String name`

    - `Type type`

      - `URL("url")`

    - `String url`

  - `BetaManagedAgentsModelConfig model`

    Model identifier and configuration.

    - `BetaManagedAgentsModel id`

      The model that will power your agent.

      See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

      - `CLAUDE_FABLE_5("claude-fable-5")`

        Next generation of intelligence for the hardest knowledge work and coding problems

      - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

        Frontier intelligence for long-running agents and coding

      - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

        Most intelligent model for building agents and coding

      - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

        Best combination of speed and intelligence

      - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

        Fastest model with near-frontier intelligence

      - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

        Premium model combining maximum intelligence with practical performance

      - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

        High-performance model for agents and coding

      - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

        High-performance model for agents and coding

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

  - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

    Resolved coordinator topology with full agent definitions for each roster member.

    - `List<BetaManagedAgentsSessionThreadAgent> agents`

      Full `agent` definitions the coordinator may spawn as session threads.

      - `String id`

      - `Optional<String> description`

      - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

        - `String name`

        - `Type type`

        - `String url`

      - `BetaManagedAgentsModelConfig model`

        Model identifier and configuration.

      - `String name`

      - `List<Skill> skills`

        - `class BetaManagedAgentsAnthropicSkill:`

          A resolved Anthropic-managed skill.

          - `String skillId`

          - `Type type`

            - `ANTHROPIC("anthropic")`

          - `String version`

        - `class BetaManagedAgentsCustomSkill:`

          A resolved user-created custom skill.

          - `String skillId`

          - `Type type`

            - `CUSTOM("custom")`

          - `String version`

      - `Optional<String> system`

      - `List<Tool> tools`

        - `class BetaManagedAgentsAgentToolset20260401:`

          - `List<BetaManagedAgentsAgentToolConfig> configs`

            - `boolean enabled`

            - `Name name`

              Built-in agent tool identifier.

              - `BASH("bash")`

              - `EDIT("edit")`

              - `READ("read")`

              - `WRITE("write")`

              - `GLOB("glob")`

              - `GREP("grep")`

              - `WEB_FETCH("web_fetch")`

              - `WEB_SEARCH("web_search")`

            - `PermissionPolicy permissionPolicy`

              Permission policy for tool execution.

              - `class BetaManagedAgentsAlwaysAllowPolicy:`

                Tool calls are automatically approved without user confirmation.

                - `Type type`

                  - `ALWAYS_ALLOW("always_allow")`

              - `class BetaManagedAgentsAlwaysAskPolicy:`

                Tool calls require user confirmation before execution.

                - `Type type`

                  - `ALWAYS_ASK("always_ask")`

          - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

            Resolved default configuration for agent tools.

            - `boolean enabled`

            - `PermissionPolicy permissionPolicy`

              Permission policy for tool execution.

              - `class BetaManagedAgentsAlwaysAllowPolicy:`

                Tool calls are automatically approved without user confirmation.

              - `class BetaManagedAgentsAlwaysAskPolicy:`

                Tool calls require user confirmation before execution.

          - `Type type`

            - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

        - `class BetaManagedAgentsMcpToolset:`

          - `List<BetaManagedAgentsMcpToolConfig> configs`

            - `boolean enabled`

            - `String name`

            - `PermissionPolicy permissionPolicy`

              Permission policy for tool execution.

              - `class BetaManagedAgentsAlwaysAllowPolicy:`

                Tool calls are automatically approved without user confirmation.

              - `class BetaManagedAgentsAlwaysAskPolicy:`

                Tool calls require user confirmation before execution.

          - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

            Resolved default configuration for all tools from an MCP server.

            - `boolean enabled`

            - `PermissionPolicy permissionPolicy`

              Permission policy for tool execution.

              - `class BetaManagedAgentsAlwaysAllowPolicy:`

                Tool calls are automatically approved without user confirmation.

              - `class BetaManagedAgentsAlwaysAskPolicy:`

                Tool calls require user confirmation before execution.

          - `String mcpServerName`

          - `Type type`

            - `MCP_TOOLSET("mcp_toolset")`

        - `class BetaManagedAgentsCustomTool:`

          A custom tool as returned in API responses.

          - `String description`

          - `BetaManagedAgentsCustomToolInputSchema inputSchema`

            JSON Schema for custom tool input parameters.

            - `JsonValue; type "object"constant`

              - `OBJECT("object")`

            - `Optional<Properties> properties`

            - `Optional<List<String>> required`

          - `String name`

          - `Type type`

            - `CUSTOM("custom")`

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Type type`

      - `COORDINATOR("coordinator")`

  - `String name`

  - `List<Skill> skills`

    - `class BetaManagedAgentsAnthropicSkill:`

      A resolved Anthropic-managed skill.

    - `class BetaManagedAgentsCustomSkill:`

      A resolved user-created custom skill.

  - `Optional<String> system`

  - `List<Tool> tools`

    - `class BetaManagedAgentsAgentToolset20260401:`

    - `class BetaManagedAgentsMcpToolset:`

    - `class BetaManagedAgentsCustomTool:`

      A custom tool as returned in API responses.

  - `Type type`

    - `AGENT("agent")`

  - `long version`

### Beta Managed Agents Session Agent Update

- `class BetaManagedAgentsSessionAgentUpdate:`

  Mid-session agent configuration update. Only `tools` and `mcp_servers` are updatable. Full replacement: the provided array becomes the new value. To preserve existing entries, GET the session, modify the array, and POST it back.

  - `Optional<List<BetaManagedAgentsUrlMcpServerParams>> mcpServers`

    Replacement MCP server list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.

    - `String name`

      Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.

    - `Type type`

      - `URL("url")`

    - `String url`

      Endpoint URL for the MCP server.

  - `Optional<List<Tool>> tools`

    Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.

    - `class BetaManagedAgentsAgentToolset20260401Params:`

      Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.

      - `Type type`

        - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

      - `Optional<List<BetaManagedAgentsAgentToolConfigParams>> configs`

        Per-tool configuration overrides.

        - `Name name`

          Built-in agent tool identifier.

          - `BASH("bash")`

          - `EDIT("edit")`

          - `READ("read")`

          - `WRITE("write")`

          - `GLOB("glob")`

          - `GREP("grep")`

          - `WEB_FETCH("web_fetch")`

          - `WEB_SEARCH("web_search")`

        - `Optional<Boolean> enabled`

          Whether this tool is enabled and available to Claude. Overrides the default_config setting.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

            - `Type type`

              - `ALWAYS_ALLOW("always_allow")`

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

            - `Type type`

              - `ALWAYS_ASK("always_ask")`

      - `Optional<BetaManagedAgentsAgentToolsetDefaultConfigParams> defaultConfig`

        Default configuration for all tools in a toolset.

        - `Optional<Boolean> enabled`

          Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

    - `class BetaManagedAgentsMcpToolsetParams:`

      Configuration for tools from an MCP server defined in `mcp_servers`.

      - `String mcpServerName`

        Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.

      - `Type type`

        - `MCP_TOOLSET("mcp_toolset")`

      - `Optional<List<BetaManagedAgentsMcpToolConfigParams>> configs`

        Per-tool configuration overrides.

        - `String name`

          Name of the MCP tool to configure. 1-128 characters.

        - `Optional<Boolean> enabled`

          Whether this tool is enabled. Overrides the `default_config` setting.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

      - `Optional<BetaManagedAgentsMcpToolsetDefaultConfigParams> defaultConfig`

        Default configuration for all tools from an MCP server.

        - `Optional<Boolean> enabled`

          Whether tools are enabled by default. Defaults to true if not specified.

        - `Optional<PermissionPolicy> permissionPolicy`

          Permission policy for tool execution.

          - `class BetaManagedAgentsAlwaysAllowPolicy:`

            Tool calls are automatically approved without user confirmation.

          - `class BetaManagedAgentsAlwaysAskPolicy:`

            Tool calls require user confirmation before execution.

    - `class BetaManagedAgentsCustomToolParams:`

      A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.

      - `String description`

        Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters.

      - `BetaManagedAgentsCustomToolInputSchema inputSchema`

        JSON Schema for custom tool input parameters.

        - `JsonValue; type "object"constant`

          - `OBJECT("object")`

        - `Optional<Properties> properties`

        - `Optional<List<String>> required`

      - `String name`

        Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.

      - `Type type`

        - `CUSTOM("custom")`

### Beta Managed Agents Session Multiagent Coordinator

- `class BetaManagedAgentsSessionMultiagentCoordinator:`

  Resolved coordinator topology with full agent definitions for each roster member.

  - `List<BetaManagedAgentsSessionThreadAgent> agents`

    Full `agent` definitions the coordinator may spawn as session threads.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

        - `String skillId`

        - `Type type`

          - `ANTHROPIC("anthropic")`

        - `String version`

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

        - `String skillId`

        - `Type type`

          - `CUSTOM("custom")`

        - `String version`

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

        - `List<BetaManagedAgentsAgentToolConfig> configs`

          - `boolean enabled`

          - `Name name`

            Built-in agent tool identifier.

            - `BASH("bash")`

            - `EDIT("edit")`

            - `READ("read")`

            - `WRITE("write")`

            - `GLOB("glob")`

            - `GREP("grep")`

            - `WEB_FETCH("web_fetch")`

            - `WEB_SEARCH("web_search")`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

              - `Type type`

                - `ALWAYS_ALLOW("always_allow")`

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

              - `Type type`

                - `ALWAYS_ASK("always_ask")`

        - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

          Resolved default configuration for agent tools.

          - `boolean enabled`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `Type type`

          - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

      - `class BetaManagedAgentsMcpToolset:`

        - `List<BetaManagedAgentsMcpToolConfig> configs`

          - `boolean enabled`

          - `String name`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

          Resolved default configuration for all tools from an MCP server.

          - `boolean enabled`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `String mcpServerName`

        - `Type type`

          - `MCP_TOOLSET("mcp_toolset")`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

        - `String description`

        - `BetaManagedAgentsCustomToolInputSchema inputSchema`

          JSON Schema for custom tool input parameters.

          - `JsonValue; type "object"constant`

            - `OBJECT("object")`

          - `Optional<Properties> properties`

          - `Optional<List<String>> required`

        - `String name`

        - `Type type`

          - `CUSTOM("custom")`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Type type`

    - `COORDINATOR("coordinator")`

### Beta Managed Agents Session Stats

- `class BetaManagedAgentsSessionStats:`

  Timing statistics for a session.

  - `Optional<Double> activeSeconds`

    Cumulative time in seconds the session spent in running status. Excludes idle time.

  - `Optional<Double> durationSeconds`

    Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

### Beta Managed Agents Session Updated Event

- `class BetaManagedAgentsSessionUpdatedEvent:`

  Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

  - `String id`

    Unique identifier for this event.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SESSION_UPDATED("session.updated")`

  - `Optional<BetaManagedAgentsSessionAgent> agent`

    Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

      Resolved coordinator topology with full agent definitions for each roster member.

      - `List<BetaManagedAgentsSessionThreadAgent> agents`

        Full `agent` definitions the coordinator may spawn as session threads.

        - `String id`

        - `Optional<String> description`

        - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

          - `String name`

          - `Type type`

          - `String url`

        - `BetaManagedAgentsModelConfig model`

          Model identifier and configuration.

        - `String name`

        - `List<Skill> skills`

          - `class BetaManagedAgentsAnthropicSkill:`

            A resolved Anthropic-managed skill.

            - `String skillId`

            - `Type type`

              - `ANTHROPIC("anthropic")`

            - `String version`

          - `class BetaManagedAgentsCustomSkill:`

            A resolved user-created custom skill.

            - `String skillId`

            - `Type type`

              - `CUSTOM("custom")`

            - `String version`

        - `Optional<String> system`

        - `List<Tool> tools`

          - `class BetaManagedAgentsAgentToolset20260401:`

            - `List<BetaManagedAgentsAgentToolConfig> configs`

              - `boolean enabled`

              - `Name name`

                Built-in agent tool identifier.

                - `BASH("bash")`

                - `EDIT("edit")`

                - `READ("read")`

                - `WRITE("write")`

                - `GLOB("glob")`

                - `GREP("grep")`

                - `WEB_FETCH("web_fetch")`

                - `WEB_SEARCH("web_search")`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                  - `Type type`

                    - `ALWAYS_ALLOW("always_allow")`

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

                  - `Type type`

                    - `ALWAYS_ASK("always_ask")`

            - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

              Resolved default configuration for agent tools.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `Type type`

              - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

          - `class BetaManagedAgentsMcpToolset:`

            - `List<BetaManagedAgentsMcpToolConfig> configs`

              - `boolean enabled`

              - `String name`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

              Resolved default configuration for all tools from an MCP server.

              - `boolean enabled`

              - `PermissionPolicy permissionPolicy`

                Permission policy for tool execution.

                - `class BetaManagedAgentsAlwaysAllowPolicy:`

                  Tool calls are automatically approved without user confirmation.

                - `class BetaManagedAgentsAlwaysAskPolicy:`

                  Tool calls require user confirmation before execution.

            - `String mcpServerName`

            - `Type type`

              - `MCP_TOOLSET("mcp_toolset")`

          - `class BetaManagedAgentsCustomTool:`

            A custom tool as returned in API responses.

            - `String description`

            - `BetaManagedAgentsCustomToolInputSchema inputSchema`

              JSON Schema for custom tool input parameters.

              - `JsonValue; type "object"constant`

                - `OBJECT("object")`

              - `Optional<Properties> properties`

              - `Optional<List<String>> required`

            - `String name`

            - `Type type`

              - `CUSTOM("custom")`

        - `Type type`

          - `AGENT("agent")`

        - `long version`

      - `Type type`

        - `COORDINATOR("coordinator")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

      - `class BetaManagedAgentsMcpToolset:`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<Metadata> metadata`

    The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.

  - `Optional<String> title`

    The session's new title. Present only when the update changed it.

### Beta Managed Agents Session Usage

- `class BetaManagedAgentsSessionUsage:`

  Cumulative token usage for a session across all turns.

  - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

    Prompt-cache creation token usage broken down by cache lifetime.

    - `Optional<Long> ephemeral1hInputTokens`

      Tokens used to create 1-hour ephemeral cache entries.

    - `Optional<Long> ephemeral5mInputTokens`

      Tokens used to create 5-minute ephemeral cache entries.

  - `Optional<Long> cacheReadInputTokens`

    Total tokens read from prompt cache.

  - `Optional<Long> inputTokens`

    Total input tokens consumed across all turns.

  - `Optional<Long> outputTokens`

    Total output tokens generated across all turns.

### Beta Managed Agents System Content Block

- `class BetaManagedAgentsSystemContentBlock:`

  Regular text content.

  - `String text`

    The text content.

  - `Type type`

    - `TEXT("text")`

### Beta Managed Agents System Message Event

- `class BetaManagedAgentsSystemMessageEvent:`

  A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

  - `String id`

    Unique identifier for this event.

  - `List<BetaManagedAgentsSystemContentBlock> content`

    System content blocks. Text-only.

    - `String text`

      The text content.

    - `Type type`

      - `TEXT("text")`

  - `Type type`

    - `SYSTEM_MESSAGE("system.message")`

  - `Optional<LocalDateTime> processedAt`

    A timestamp in RFC 3339 format

### Beta Managed Agents User Tool Result Event

- `class BetaManagedAgentsUserToolResultEvent:`

  Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

  - `String id`

    Unique identifier for this event.

  - `String toolUseId`

    The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

  - `Type type`

    - `USER_TOOL_RESULT("user.tool_result")`

  - `Optional<List<Content>> content`

    The result content returned by the tool.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

    - `class BetaManagedAgentsSearchResultBlock:`

      A block containing a web search result.

      - `BetaManagedAgentsSearchResultCitations citations`

        Citation settings for a search result.

        - `boolean enabled`

          Whether citations are enabled for this search result.

      - `List<BetaManagedAgentsSearchResultContent> content`

        Array of text content blocks from the search result.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `String source`

        The URL source of the search result.

      - `String title`

        The title of the search result.

      - `Type type`

        - `SEARCH_RESULT("search_result")`

  - `Optional<Boolean> isError`

    Whether the tool execution resulted in an error.

  - `Optional<LocalDateTime> processedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> sessionThreadId`

    Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

# Events

## List Events

`EventListPage beta().sessions().events().list(EventListParamsparams = EventListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/sessions/{session_id}/events`

List Events

### Parameters

- `EventListParams params`

  - `Optional<String> sessionId`

  - `Optional<LocalDateTime> createdAtGt`

    Return events created after this time (exclusive).

  - `Optional<LocalDateTime> createdAtGte`

    Return events created at or after this time (inclusive).

  - `Optional<LocalDateTime> createdAtLt`

    Return events created before this time (exclusive).

  - `Optional<LocalDateTime> createdAtLte`

    Return events created at or before this time (inclusive).

  - `Optional<Long> limit`

    Query parameter for limit

  - `Optional<Order> order`

    Sort direction for results, ordered by created_at. Defaults to asc (chronological).

    - `ASC("asc")`

    - `DESC("desc")`

  - `Optional<String> page`

    Opaque pagination cursor from a previous response's next_page.

  - `Optional<List<String>> types`

    Filter by event type. Values match the `type` field on returned events (for example, `user.message` or `agent.tool_use`). Omit to return all event types.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union`

  Union type for all event types in a session.

  - `class BetaManagedAgentsUserMessageEvent:`

    A user message event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Array of content blocks comprising the user message.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

        - `Source source`

          Union type for image source variants.

          - `class BetaManagedAgentsBase64ImageSource:`

            Base64-encoded image data.

            - `String data`

              Base64-encoded image data.

            - `String mediaType`

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsUrlImageSource:`

            Image referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the image to fetch.

          - `class BetaManagedAgentsFileImageSource:`

            Image referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `IMAGE("image")`

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `Source source`

          Union type for document source variants.

          - `class BetaManagedAgentsBase64DocumentSource:`

            Base64-encoded document data.

            - `String data`

              Base64-encoded document data.

            - `String mediaType`

              MIME type of the document (e.g., "application/pdf").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsPlainTextDocumentSource:`

            Plain text document content.

            - `String data`

              The plain text content.

            - `MediaType mediaType`

              MIME type of the text content. Must be "text/plain".

              - `TEXT_PLAIN("text/plain")`

            - `Type type`

              - `TEXT("text")`

          - `class BetaManagedAgentsUrlDocumentSource:`

            Document referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the document to fetch.

          - `class BetaManagedAgentsFileDocumentSource:`

            Document referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `DOCUMENT("document")`

        - `Optional<String> context`

          Additional context about the document for the model.

        - `Optional<String> title`

          The title of the document.

    - `Type type`

      - `USER_MESSAGE("user.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsUserInterruptEvent:`

    An interrupt event that pauses agent execution and returns control to the user.

    - `String id`

      Unique identifier for this event.

    - `Type type`

      - `USER_INTERRUPT("user.interrupt")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

  - `class BetaManagedAgentsUserToolConfirmationEvent:`

    A tool confirmation event that approves or denies a pending tool execution.

    - `String id`

      Unique identifier for this event.

    - `Result result`

      UserToolConfirmationResult enum

      - `ALLOW("allow")`

      - `DENY("deny")`

    - `String toolUseId`

      The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

    - `Optional<String> denyMessage`

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

  - `class BetaManagedAgentsUserCustomToolResultEvent:`

    Event sent by the client providing the result of a custom tool execution.

    - `String id`

      Unique identifier for this event.

    - `String customToolUseId`

      The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

        - `BetaManagedAgentsSearchResultCitations citations`

          Citation settings for a search result.

          - `boolean enabled`

            Whether citations are enabled for this search result.

        - `List<BetaManagedAgentsSearchResultContent> content`

          Array of text content blocks from the search result.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `String source`

          The URL source of the search result.

        - `String title`

          The title of the search result.

        - `Type type`

          - `SEARCH_RESULT("search_result")`

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsAgentCustomToolUseEvent:`

    Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the custom tool being called.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.

  - `class BetaManagedAgentsAgentMessageEvent:`

    An agent response event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsTextBlock> content`

      Array of text blocks comprising the agent response.

      - `String text`

        The text content.

      - `Type type`

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MESSAGE("agent.message")`

  - `class BetaManagedAgentsAgentThinkingEvent:`

    Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THINKING("agent.thinking")`

  - `class BetaManagedAgentsAgentMcpToolUseEvent:`

    Event emitted when the agent invokes a tool provided by an MCP server.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String mcpServerName`

      Name of the MCP server providing the tool.

    - `String name`

      Name of the MCP tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentMcpToolResultEvent:`

    Event representing the result of an MCP tool execution.

    - `String id`

      Unique identifier for this event.

    - `String mcpToolUseId`

      The id of the `agent.mcp_tool_use` event this result corresponds to.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentToolUseEvent:`

    Event emitted when the agent invokes a built-in agent tool.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the agent tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_TOOL_USE("agent.tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentToolResultEvent:`

    Event representing the result of an agent tool execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to.

    - `Type type`

      - `AGENT_TOOL_RESULT("agent.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentThreadMessageReceivedEvent:`

    Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `String fromSessionThreadId`

      Public `sthr_` ID of the thread that sent the message.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_MESSAGE_RECEIVED("agent.thread_message_received")`

    - `Optional<String> fromAgentName`

      Name of the callable agent this message came from. Absent when received from the primary agent.

  - `class BetaManagedAgentsAgentThreadMessageSentEvent:`

    Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toSessionThreadId`

      Public `sthr_` ID of the thread the message was sent to.

    - `Type type`

      - `AGENT_THREAD_MESSAGE_SENT("agent.thread_message_sent")`

    - `Optional<String> toAgentName`

      Name of the callable agent this message was sent to. Absent when sent to the primary agent.

  - `class BetaManagedAgentsAgentThreadContextCompactedEvent:`

    Indicates that context compaction (summarization) occurred during the session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")`

  - `class BetaManagedAgentsSessionErrorEvent:`

    An error event indicating a problem occurred during session execution.

    - `String id`

      Unique identifier for this event.

    - `Error error`

      An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

      - `class BetaManagedAgentsUnknownError:`

        An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

            - `Type type`

              - `RETRYING("retrying")`

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            - `Type type`

              - `EXHAUSTED("exhausted")`

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

            - `Type type`

              - `TERMINAL("terminal")`

        - `Type type`

          - `UNKNOWN_ERROR("unknown_error")`

      - `class BetaManagedAgentsModelOverloadedError:`

        The model is currently overloaded. Emitted after automatic retries are exhausted.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_OVERLOADED_ERROR("model_overloaded_error")`

      - `class BetaManagedAgentsModelRateLimitedError:`

        The model request was rate-limited.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")`

      - `class BetaManagedAgentsModelRequestFailedError:`

        A model request failed for a reason other than overload or rate-limiting.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")`

      - `class BetaManagedAgentsMcpConnectionFailedError:`

        Failed to connect to an MCP server.

        - `String mcpServerName`

          Name of the MCP server that failed to connect.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")`

      - `class BetaManagedAgentsMcpAuthenticationFailedError:`

        Authentication to an MCP server failed.

        - `String mcpServerName`

          Name of the MCP server that failed authentication.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")`

      - `class BetaManagedAgentsBillingError:`

        The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `BILLING_ERROR("billing_error")`

      - `class BetaManagedAgentsCredentialHostUnreachableError:`

        An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

        - `String credentialId`

          ID of the affected credential.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `CREDENTIAL_HOST_UNREACHABLE_ERROR("credential_host_unreachable_error")`

        - `String vaultId`

          ID of the vault containing the affected credential.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_ERROR("session.error")`

  - `class BetaManagedAgentsSessionStatusRescheduledEvent:`

    Indicates the session is recovering from an error state and is rescheduled for execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

  - `class BetaManagedAgentsSessionStatusRunningEvent:`

    Indicates the session is actively running and the agent is working.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RUNNING("session.status_running")`

  - `class BetaManagedAgentsSessionStatusIdleEvent:`

    Indicates the agent has paused and is awaiting user input.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

        - `Type type`

          - `END_TURN("end_turn")`

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

        - `List<String> eventIds`

          The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

        - `Type type`

          - `REQUIRES_ACTION("requires_action")`

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

        - `Type type`

          - `RETRIES_EXHAUSTED("retries_exhausted")`

    - `Type type`

      - `SESSION_STATUS_IDLE("session.status_idle")`

  - `class BetaManagedAgentsSessionStatusTerminatedEvent:`

    Indicates the session has terminated, either due to an error or completion.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_TERMINATED("session.status_terminated")`

  - `class BetaManagedAgentsSessionThreadCreatedEvent:`

    Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the callable agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public `sthr_` ID of the newly created thread.

    - `Type type`

      - `SESSION_THREAD_CREATED("session.thread_created")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationStartEvent:`

    Emitted when an outcome evaluation cycle begins.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_START("span.outcome_evaluation_start")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationEndEvent:`

    Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.

    - `String id`

      Unique identifier for this event.

    - `String explanation`

      Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeEvaluationStartId`

      The id of the corresponding `span.outcome_evaluation_start` event.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String result`

      Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_END("span.outcome_evaluation_end")`

    - `BetaManagedAgentsSpanModelUsage usage`

      Token usage for a single model request.

      - `long cacheCreationInputTokens`

        Tokens used to create prompt cache in this request.

      - `long cacheReadInputTokens`

        Tokens read from prompt cache in this request.

      - `long inputTokens`

        Input tokens consumed by this request.

      - `long outputTokens`

        Output tokens generated by this request.

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `class BetaManagedAgentsSpanModelRequestStartEvent:`

    Emitted when a model request is initiated by the agent.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_START("span.model_request_start")`

  - `class BetaManagedAgentsSpanModelRequestEndEvent:`

    Emitted when a model request completes.

    - `String id`

      Unique identifier for this event.

    - `Optional<Boolean> isError`

      Whether the model request resulted in an error.

    - `String modelRequestStartId`

      The id of the corresponding `span.model_request_start` event.

    - `BetaManagedAgentsSpanModelUsage modelUsage`

      Token usage for a single model request.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_END("span.model_request_end")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent:`

    Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_ONGOING("span.outcome_evaluation_ongoing")`

  - `class BetaManagedAgentsUserDefineOutcomeEvent:`

    Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

    - `String id`

      Unique identifier for this event.

    - `String description`

      What the agent should produce. Copied from the input event.

    - `Optional<Long> maxIterations`

      Evaluate-then-revise cycles before giving up. Default 3, max 20.

    - `String outcomeId`

      Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Rubric rubric`

      Rubric for grading the quality of an outcome.

      - `class BetaManagedAgentsFileRubric:`

        Rubric referenced by a file uploaded via the Files API.

        - `String fileId`

          ID of the rubric file.

        - `Type type`

          - `FILE("file")`

      - `class BetaManagedAgentsTextRubric:`

        Rubric content provided inline as text.

        - `String content`

          Rubric content. Plain text or markdown — the grader treats it as freeform text.

        - `Type type`

          - `TEXT("text")`

    - `Type type`

      - `USER_DEFINE_OUTCOME("user.define_outcome")`

  - `class BetaManagedAgentsSessionDeletedEvent:`

    Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_DELETED("session.deleted")`

  - `class BetaManagedAgentsSessionThreadStatusRunningEvent:`

    A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that started running.

    - `Type type`

      - `SESSION_THREAD_STATUS_RUNNING("session.thread_status_running")`

  - `class BetaManagedAgentsSessionThreadStatusIdleEvent:`

    A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that went idle.

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

    - `Type type`

      - `SESSION_THREAD_STATUS_IDLE("session.thread_status_idle")`

  - `class BetaManagedAgentsSessionThreadStatusTerminatedEvent:`

    A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that terminated.

    - `Type type`

      - `SESSION_THREAD_STATUS_TERMINATED("session.thread_status_terminated")`

  - `class BetaManagedAgentsUserToolResultEvent:`

    Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

    - `String id`

      Unique identifier for this event.

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_RESULT("user.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsSessionThreadStatusRescheduledEvent:`

    A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that is retrying.

    - `Type type`

      - `SESSION_THREAD_STATUS_RESCHEDULED("session.thread_status_rescheduled")`

  - `class BetaManagedAgentsSessionUpdatedEvent:`

    Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_UPDATED("session.updated")`

    - `Optional<BetaManagedAgentsSessionAgent> agent`

      Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

      - `String id`

      - `Optional<String> description`

      - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

        - `String name`

        - `Type type`

          - `URL("url")`

        - `String url`

      - `BetaManagedAgentsModelConfig model`

        Model identifier and configuration.

        - `BetaManagedAgentsModel id`

          The model that will power your agent.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Most intelligent model for building agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

        - `Optional<Speed> speed`

          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.

          - `STANDARD("standard")`

          - `FAST("fast")`

      - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

        Resolved coordinator topology with full agent definitions for each roster member.

        - `List<BetaManagedAgentsSessionThreadAgent> agents`

          Full `agent` definitions the coordinator may spawn as session threads.

          - `String id`

          - `Optional<String> description`

          - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

            - `String name`

            - `Type type`

            - `String url`

          - `BetaManagedAgentsModelConfig model`

            Model identifier and configuration.

          - `String name`

          - `List<Skill> skills`

            - `class BetaManagedAgentsAnthropicSkill:`

              A resolved Anthropic-managed skill.

              - `String skillId`

              - `Type type`

                - `ANTHROPIC("anthropic")`

              - `String version`

            - `class BetaManagedAgentsCustomSkill:`

              A resolved user-created custom skill.

              - `String skillId`

              - `Type type`

                - `CUSTOM("custom")`

              - `String version`

          - `Optional<String> system`

          - `List<Tool> tools`

            - `class BetaManagedAgentsAgentToolset20260401:`

              - `List<BetaManagedAgentsAgentToolConfig> configs`

                - `boolean enabled`

                - `Name name`

                  Built-in agent tool identifier.

                  - `BASH("bash")`

                  - `EDIT("edit")`

                  - `READ("read")`

                  - `WRITE("write")`

                  - `GLOB("glob")`

                  - `GREP("grep")`

                  - `WEB_FETCH("web_fetch")`

                  - `WEB_SEARCH("web_search")`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                    - `Type type`

                      - `ALWAYS_ALLOW("always_allow")`

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

                    - `Type type`

                      - `ALWAYS_ASK("always_ask")`

              - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

                Resolved default configuration for agent tools.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `Type type`

                - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

            - `class BetaManagedAgentsMcpToolset:`

              - `List<BetaManagedAgentsMcpToolConfig> configs`

                - `boolean enabled`

                - `String name`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

                Resolved default configuration for all tools from an MCP server.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `String mcpServerName`

              - `Type type`

                - `MCP_TOOLSET("mcp_toolset")`

            - `class BetaManagedAgentsCustomTool:`

              A custom tool as returned in API responses.

              - `String description`

              - `BetaManagedAgentsCustomToolInputSchema inputSchema`

                JSON Schema for custom tool input parameters.

                - `JsonValue; type "object"constant`

                  - `OBJECT("object")`

                - `Optional<Properties> properties`

                - `Optional<List<String>> required`

              - `String name`

              - `Type type`

                - `CUSTOM("custom")`

          - `Type type`

            - `AGENT("agent")`

          - `long version`

        - `Type type`

          - `COORDINATOR("coordinator")`

      - `String name`

      - `List<Skill> skills`

        - `class BetaManagedAgentsAnthropicSkill:`

          A resolved Anthropic-managed skill.

        - `class BetaManagedAgentsCustomSkill:`

          A resolved user-created custom skill.

      - `Optional<String> system`

      - `List<Tool> tools`

        - `class BetaManagedAgentsAgentToolset20260401:`

        - `class BetaManagedAgentsMcpToolset:`

        - `class BetaManagedAgentsCustomTool:`

          A custom tool as returned in API responses.

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Optional<Metadata> metadata`

      The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.

    - `Optional<String> title`

      The session's new title. Present only when the update changed it.

  - `class BetaManagedAgentsSystemMessageEvent:`

    A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsSystemContentBlock> content`

      System content blocks. Text-only.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `Type type`

      - `SYSTEM_MESSAGE("system.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.events.EventListPage;
import com.anthropic.models.beta.sessions.events.EventListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        EventListPage page = client.beta().sessions().events().list("sesn_011CZkZAtmR3yMPDzynEDxu7");
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message",
      "processed_at": "2026-03-15T10:00:00Z"
    },
    {
      "id": "sevt_011CZkZHPq1jCdq5lbRTjiVnz",
      "content": [
        {
          "text": "Let me look up order #1234 for you.",
          "type": "text"
        }
      ],
      "processed_at": "2026-03-15T10:00:00Z",
      "type": "agent.message"
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```

## Send Events

`BetaManagedAgentsSendSessionEvents beta().sessions().events().send(EventSendParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/sessions/{session_id}/events`

Send Events

### Parameters

- `EventSendParams params`

  - `Optional<String> sessionId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `List<BetaManagedAgentsEventParams> events`

    Events to send to the `session`.

    - `class BetaManagedAgentsUserMessageEventParams:`

      Parameters for sending a user message to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsUserInterruptEventParams:`

      Parameters for sending an interrupt to pause the agent.

      - `Type type`

        - `USER_INTERRUPT("user.interrupt")`

      - `Optional<String> sessionThreadId`

        If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

    - `class BetaManagedAgentsUserToolConfirmationEventParams:`

      Parameters for confirming or denying a tool execution request.

      - `Result result`

        UserToolConfirmationResult enum

        - `ALLOW("allow")`

        - `DENY("deny")`

      - `String toolUseId`

        The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

      - `Type type`

        - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

      - `Optional<String> denyMessage`

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    - `class BetaManagedAgentsUserCustomToolResultEventParams:`

      Parameters for providing the result of a custom tool execution.

      - `String customToolUseId`

        The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

      - `Type type`

        - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

      - `Optional<List<Content>> content`

        The result content returned by the tool.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `class BetaManagedAgentsSearchResultBlock:`

          A block containing a web search result.

          - `BetaManagedAgentsSearchResultCitations citations`

            Citation settings for a search result.

            - `boolean enabled`

              Whether citations are enabled for this search result.

          - `List<BetaManagedAgentsSearchResultContent> content`

            Array of text content blocks from the search result.

            - `String text`

              The text content.

            - `Type type`

              - `TEXT("text")`

          - `String source`

            The URL source of the search result.

          - `String title`

            The title of the search result.

          - `Type type`

            - `SEARCH_RESULT("search_result")`

      - `Optional<Boolean> isError`

        Whether the tool execution resulted in an error.

    - `class BetaManagedAgentsUserDefineOutcomeEventParams:`

      Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubricParams:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubricParams:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsUserToolResultEventParams:`

      Parameters for providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

      - `String toolUseId`

        The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

      - `Type type`

        - `USER_TOOL_RESULT("user.tool_result")`

      - `Optional<List<Content>> content`

        The result content returned by the tool.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `class BetaManagedAgentsSearchResultBlock:`

          A block containing a web search result.

      - `Optional<Boolean> isError`

        Whether the tool execution resulted in an error.

    - `class BetaManagedAgentsSystemMessageEventParams:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

### Returns

- `class BetaManagedAgentsSendSessionEvents:`

  Events that were successfully sent to the session.

  - `Optional<List<Data>> data`

    Sent events

    - `class BetaManagedAgentsUserMessageEvent:`

      A user message event in the session conversation.

      - `String id`

        Unique identifier for this event.

      - `List<Content> content`

        Array of content blocks comprising the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

    - `class BetaManagedAgentsUserInterruptEvent:`

      An interrupt event that pauses agent execution and returns control to the user.

      - `String id`

        Unique identifier for this event.

      - `Type type`

        - `USER_INTERRUPT("user.interrupt")`

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

      - `Optional<String> sessionThreadId`

        If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

    - `class BetaManagedAgentsUserToolConfirmationEvent:`

      A tool confirmation event that approves or denies a pending tool execution.

      - `String id`

        Unique identifier for this event.

      - `Result result`

        UserToolConfirmationResult enum

        - `ALLOW("allow")`

        - `DENY("deny")`

      - `String toolUseId`

        The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

      - `Type type`

        - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

      - `Optional<String> denyMessage`

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

      - `Optional<String> sessionThreadId`

        When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

    - `class BetaManagedAgentsUserCustomToolResultEvent:`

      Event sent by the client providing the result of a custom tool execution.

      - `String id`

        Unique identifier for this event.

      - `String customToolUseId`

        The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

      - `Type type`

        - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

      - `Optional<List<Content>> content`

        The result content returned by the tool.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `class BetaManagedAgentsSearchResultBlock:`

          A block containing a web search result.

          - `BetaManagedAgentsSearchResultCitations citations`

            Citation settings for a search result.

            - `boolean enabled`

              Whether citations are enabled for this search result.

          - `List<BetaManagedAgentsSearchResultContent> content`

            Array of text content blocks from the search result.

            - `String text`

              The text content.

            - `Type type`

              - `TEXT("text")`

          - `String source`

            The URL source of the search result.

          - `String title`

            The title of the search result.

          - `Type type`

            - `SEARCH_RESULT("search_result")`

      - `Optional<Boolean> isError`

        Whether the tool execution resulted in an error.

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

      - `Optional<String> sessionThreadId`

        Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

    - `class BetaManagedAgentsUserDefineOutcomeEvent:`

      Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

      - `String id`

        Unique identifier for this event.

      - `String description`

        What the agent should produce. Copied from the input event.

      - `Optional<Long> maxIterations`

        Evaluate-then-revise cycles before giving up. Default 3, max 20.

      - `String outcomeId`

        Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

      - `LocalDateTime processedAt`

        A timestamp in RFC 3339 format

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubric:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubric:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

    - `class BetaManagedAgentsUserToolResultEvent:`

      Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

      - `String id`

        Unique identifier for this event.

      - `String toolUseId`

        The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

      - `Type type`

        - `USER_TOOL_RESULT("user.tool_result")`

      - `Optional<List<Content>> content`

        The result content returned by the tool.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `class BetaManagedAgentsSearchResultBlock:`

          A block containing a web search result.

      - `Optional<Boolean> isError`

        Whether the tool execution resulted in an error.

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

      - `Optional<String> sessionThreadId`

        Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

    - `class BetaManagedAgentsSystemMessageEvent:`

      A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

      - `String id`

        Unique identifier for this event.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsSendSessionEvents;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsTextBlock;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams;
import com.anthropic.models.beta.sessions.events.EventSendParams;
import java.util.List;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        EventSendParams params = EventSendParams.builder()
            .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7")
            .addUserMessageEvent(List.of(BetaManagedAgentsUserMessageEventParams.Content.ofText(BetaManagedAgentsTextBlock.builder()
                .text("Where is my order #1234?")
                .type(BetaManagedAgentsTextBlock.Type.TEXT)
                .build())))
            .build();
        BetaManagedAgentsSendSessionEvents betaManagedAgentsSendSessionEvents = client.beta().sessions().events().send(params);
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message",
      "processed_at": "2026-03-15T10:00:00Z"
    }
  ]
}
```

## Stream Events

`BetaManagedAgentsStreamSessionEvents beta().sessions().events().streamStreaming(EventStreamParamsparams = EventStreamParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/sessions/{session_id}/events/stream`

Stream Events

### Parameters

- `EventStreamParams params`

  - `Optional<String> sessionId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union`

  Server-sent event in the session stream.

  - `class BetaManagedAgentsUserMessageEvent:`

    A user message event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Array of content blocks comprising the user message.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

        - `Source source`

          Union type for image source variants.

          - `class BetaManagedAgentsBase64ImageSource:`

            Base64-encoded image data.

            - `String data`

              Base64-encoded image data.

            - `String mediaType`

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsUrlImageSource:`

            Image referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the image to fetch.

          - `class BetaManagedAgentsFileImageSource:`

            Image referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `IMAGE("image")`

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `Source source`

          Union type for document source variants.

          - `class BetaManagedAgentsBase64DocumentSource:`

            Base64-encoded document data.

            - `String data`

              Base64-encoded document data.

            - `String mediaType`

              MIME type of the document (e.g., "application/pdf").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsPlainTextDocumentSource:`

            Plain text document content.

            - `String data`

              The plain text content.

            - `MediaType mediaType`

              MIME type of the text content. Must be "text/plain".

              - `TEXT_PLAIN("text/plain")`

            - `Type type`

              - `TEXT("text")`

          - `class BetaManagedAgentsUrlDocumentSource:`

            Document referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the document to fetch.

          - `class BetaManagedAgentsFileDocumentSource:`

            Document referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `DOCUMENT("document")`

        - `Optional<String> context`

          Additional context about the document for the model.

        - `Optional<String> title`

          The title of the document.

    - `Type type`

      - `USER_MESSAGE("user.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsUserInterruptEvent:`

    An interrupt event that pauses agent execution and returns control to the user.

    - `String id`

      Unique identifier for this event.

    - `Type type`

      - `USER_INTERRUPT("user.interrupt")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

  - `class BetaManagedAgentsUserToolConfirmationEvent:`

    A tool confirmation event that approves or denies a pending tool execution.

    - `String id`

      Unique identifier for this event.

    - `Result result`

      UserToolConfirmationResult enum

      - `ALLOW("allow")`

      - `DENY("deny")`

    - `String toolUseId`

      The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

    - `Optional<String> denyMessage`

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

  - `class BetaManagedAgentsUserCustomToolResultEvent:`

    Event sent by the client providing the result of a custom tool execution.

    - `String id`

      Unique identifier for this event.

    - `String customToolUseId`

      The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

        - `BetaManagedAgentsSearchResultCitations citations`

          Citation settings for a search result.

          - `boolean enabled`

            Whether citations are enabled for this search result.

        - `List<BetaManagedAgentsSearchResultContent> content`

          Array of text content blocks from the search result.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `String source`

          The URL source of the search result.

        - `String title`

          The title of the search result.

        - `Type type`

          - `SEARCH_RESULT("search_result")`

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsAgentCustomToolUseEvent:`

    Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the custom tool being called.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.

  - `class BetaManagedAgentsAgentMessageEvent:`

    An agent response event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsTextBlock> content`

      Array of text blocks comprising the agent response.

      - `String text`

        The text content.

      - `Type type`

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MESSAGE("agent.message")`

  - `class BetaManagedAgentsAgentThinkingEvent:`

    Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THINKING("agent.thinking")`

  - `class BetaManagedAgentsAgentMcpToolUseEvent:`

    Event emitted when the agent invokes a tool provided by an MCP server.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String mcpServerName`

      Name of the MCP server providing the tool.

    - `String name`

      Name of the MCP tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentMcpToolResultEvent:`

    Event representing the result of an MCP tool execution.

    - `String id`

      Unique identifier for this event.

    - `String mcpToolUseId`

      The id of the `agent.mcp_tool_use` event this result corresponds to.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentToolUseEvent:`

    Event emitted when the agent invokes a built-in agent tool.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the agent tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_TOOL_USE("agent.tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentToolResultEvent:`

    Event representing the result of an agent tool execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to.

    - `Type type`

      - `AGENT_TOOL_RESULT("agent.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentThreadMessageReceivedEvent:`

    Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `String fromSessionThreadId`

      Public `sthr_` ID of the thread that sent the message.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_MESSAGE_RECEIVED("agent.thread_message_received")`

    - `Optional<String> fromAgentName`

      Name of the callable agent this message came from. Absent when received from the primary agent.

  - `class BetaManagedAgentsAgentThreadMessageSentEvent:`

    Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toSessionThreadId`

      Public `sthr_` ID of the thread the message was sent to.

    - `Type type`

      - `AGENT_THREAD_MESSAGE_SENT("agent.thread_message_sent")`

    - `Optional<String> toAgentName`

      Name of the callable agent this message was sent to. Absent when sent to the primary agent.

  - `class BetaManagedAgentsAgentThreadContextCompactedEvent:`

    Indicates that context compaction (summarization) occurred during the session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")`

  - `class BetaManagedAgentsSessionErrorEvent:`

    An error event indicating a problem occurred during session execution.

    - `String id`

      Unique identifier for this event.

    - `Error error`

      An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

      - `class BetaManagedAgentsUnknownError:`

        An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

            - `Type type`

              - `RETRYING("retrying")`

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            - `Type type`

              - `EXHAUSTED("exhausted")`

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

            - `Type type`

              - `TERMINAL("terminal")`

        - `Type type`

          - `UNKNOWN_ERROR("unknown_error")`

      - `class BetaManagedAgentsModelOverloadedError:`

        The model is currently overloaded. Emitted after automatic retries are exhausted.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_OVERLOADED_ERROR("model_overloaded_error")`

      - `class BetaManagedAgentsModelRateLimitedError:`

        The model request was rate-limited.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")`

      - `class BetaManagedAgentsModelRequestFailedError:`

        A model request failed for a reason other than overload or rate-limiting.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")`

      - `class BetaManagedAgentsMcpConnectionFailedError:`

        Failed to connect to an MCP server.

        - `String mcpServerName`

          Name of the MCP server that failed to connect.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")`

      - `class BetaManagedAgentsMcpAuthenticationFailedError:`

        Authentication to an MCP server failed.

        - `String mcpServerName`

          Name of the MCP server that failed authentication.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")`

      - `class BetaManagedAgentsBillingError:`

        The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `BILLING_ERROR("billing_error")`

      - `class BetaManagedAgentsCredentialHostUnreachableError:`

        An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

        - `String credentialId`

          ID of the affected credential.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `CREDENTIAL_HOST_UNREACHABLE_ERROR("credential_host_unreachable_error")`

        - `String vaultId`

          ID of the vault containing the affected credential.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_ERROR("session.error")`

  - `class BetaManagedAgentsSessionStatusRescheduledEvent:`

    Indicates the session is recovering from an error state and is rescheduled for execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

  - `class BetaManagedAgentsSessionStatusRunningEvent:`

    Indicates the session is actively running and the agent is working.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RUNNING("session.status_running")`

  - `class BetaManagedAgentsSessionStatusIdleEvent:`

    Indicates the agent has paused and is awaiting user input.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

        - `Type type`

          - `END_TURN("end_turn")`

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

        - `List<String> eventIds`

          The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

        - `Type type`

          - `REQUIRES_ACTION("requires_action")`

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

        - `Type type`

          - `RETRIES_EXHAUSTED("retries_exhausted")`

    - `Type type`

      - `SESSION_STATUS_IDLE("session.status_idle")`

  - `class BetaManagedAgentsSessionStatusTerminatedEvent:`

    Indicates the session has terminated, either due to an error or completion.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_TERMINATED("session.status_terminated")`

  - `class BetaManagedAgentsSessionThreadCreatedEvent:`

    Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the callable agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public `sthr_` ID of the newly created thread.

    - `Type type`

      - `SESSION_THREAD_CREATED("session.thread_created")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationStartEvent:`

    Emitted when an outcome evaluation cycle begins.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_START("span.outcome_evaluation_start")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationEndEvent:`

    Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.

    - `String id`

      Unique identifier for this event.

    - `String explanation`

      Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeEvaluationStartId`

      The id of the corresponding `span.outcome_evaluation_start` event.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String result`

      Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_END("span.outcome_evaluation_end")`

    - `BetaManagedAgentsSpanModelUsage usage`

      Token usage for a single model request.

      - `long cacheCreationInputTokens`

        Tokens used to create prompt cache in this request.

      - `long cacheReadInputTokens`

        Tokens read from prompt cache in this request.

      - `long inputTokens`

        Input tokens consumed by this request.

      - `long outputTokens`

        Output tokens generated by this request.

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `class BetaManagedAgentsSpanModelRequestStartEvent:`

    Emitted when a model request is initiated by the agent.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_START("span.model_request_start")`

  - `class BetaManagedAgentsSpanModelRequestEndEvent:`

    Emitted when a model request completes.

    - `String id`

      Unique identifier for this event.

    - `Optional<Boolean> isError`

      Whether the model request resulted in an error.

    - `String modelRequestStartId`

      The id of the corresponding `span.model_request_start` event.

    - `BetaManagedAgentsSpanModelUsage modelUsage`

      Token usage for a single model request.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_END("span.model_request_end")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent:`

    Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_ONGOING("span.outcome_evaluation_ongoing")`

  - `class BetaManagedAgentsUserDefineOutcomeEvent:`

    Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

    - `String id`

      Unique identifier for this event.

    - `String description`

      What the agent should produce. Copied from the input event.

    - `Optional<Long> maxIterations`

      Evaluate-then-revise cycles before giving up. Default 3, max 20.

    - `String outcomeId`

      Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Rubric rubric`

      Rubric for grading the quality of an outcome.

      - `class BetaManagedAgentsFileRubric:`

        Rubric referenced by a file uploaded via the Files API.

        - `String fileId`

          ID of the rubric file.

        - `Type type`

          - `FILE("file")`

      - `class BetaManagedAgentsTextRubric:`

        Rubric content provided inline as text.

        - `String content`

          Rubric content. Plain text or markdown — the grader treats it as freeform text.

        - `Type type`

          - `TEXT("text")`

    - `Type type`

      - `USER_DEFINE_OUTCOME("user.define_outcome")`

  - `class BetaManagedAgentsSessionDeletedEvent:`

    Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_DELETED("session.deleted")`

  - `class BetaManagedAgentsSessionThreadStatusRunningEvent:`

    A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that started running.

    - `Type type`

      - `SESSION_THREAD_STATUS_RUNNING("session.thread_status_running")`

  - `class BetaManagedAgentsSessionThreadStatusIdleEvent:`

    A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that went idle.

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

    - `Type type`

      - `SESSION_THREAD_STATUS_IDLE("session.thread_status_idle")`

  - `class BetaManagedAgentsSessionThreadStatusTerminatedEvent:`

    A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that terminated.

    - `Type type`

      - `SESSION_THREAD_STATUS_TERMINATED("session.thread_status_terminated")`

  - `class BetaManagedAgentsUserToolResultEvent:`

    Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

    - `String id`

      Unique identifier for this event.

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_RESULT("user.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsSessionThreadStatusRescheduledEvent:`

    A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that is retrying.

    - `Type type`

      - `SESSION_THREAD_STATUS_RESCHEDULED("session.thread_status_rescheduled")`

  - `class BetaManagedAgentsSessionUpdatedEvent:`

    Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_UPDATED("session.updated")`

    - `Optional<BetaManagedAgentsSessionAgent> agent`

      Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

      - `String id`

      - `Optional<String> description`

      - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

        - `String name`

        - `Type type`

          - `URL("url")`

        - `String url`

      - `BetaManagedAgentsModelConfig model`

        Model identifier and configuration.

        - `BetaManagedAgentsModel id`

          The model that will power your agent.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Most intelligent model for building agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

        - `Optional<Speed> speed`

          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.

          - `STANDARD("standard")`

          - `FAST("fast")`

      - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

        Resolved coordinator topology with full agent definitions for each roster member.

        - `List<BetaManagedAgentsSessionThreadAgent> agents`

          Full `agent` definitions the coordinator may spawn as session threads.

          - `String id`

          - `Optional<String> description`

          - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

            - `String name`

            - `Type type`

            - `String url`

          - `BetaManagedAgentsModelConfig model`

            Model identifier and configuration.

          - `String name`

          - `List<Skill> skills`

            - `class BetaManagedAgentsAnthropicSkill:`

              A resolved Anthropic-managed skill.

              - `String skillId`

              - `Type type`

                - `ANTHROPIC("anthropic")`

              - `String version`

            - `class BetaManagedAgentsCustomSkill:`

              A resolved user-created custom skill.

              - `String skillId`

              - `Type type`

                - `CUSTOM("custom")`

              - `String version`

          - `Optional<String> system`

          - `List<Tool> tools`

            - `class BetaManagedAgentsAgentToolset20260401:`

              - `List<BetaManagedAgentsAgentToolConfig> configs`

                - `boolean enabled`

                - `Name name`

                  Built-in agent tool identifier.

                  - `BASH("bash")`

                  - `EDIT("edit")`

                  - `READ("read")`

                  - `WRITE("write")`

                  - `GLOB("glob")`

                  - `GREP("grep")`

                  - `WEB_FETCH("web_fetch")`

                  - `WEB_SEARCH("web_search")`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                    - `Type type`

                      - `ALWAYS_ALLOW("always_allow")`

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

                    - `Type type`

                      - `ALWAYS_ASK("always_ask")`

              - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

                Resolved default configuration for agent tools.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `Type type`

                - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

            - `class BetaManagedAgentsMcpToolset:`

              - `List<BetaManagedAgentsMcpToolConfig> configs`

                - `boolean enabled`

                - `String name`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

                Resolved default configuration for all tools from an MCP server.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `String mcpServerName`

              - `Type type`

                - `MCP_TOOLSET("mcp_toolset")`

            - `class BetaManagedAgentsCustomTool:`

              A custom tool as returned in API responses.

              - `String description`

              - `BetaManagedAgentsCustomToolInputSchema inputSchema`

                JSON Schema for custom tool input parameters.

                - `JsonValue; type "object"constant`

                  - `OBJECT("object")`

                - `Optional<Properties> properties`

                - `Optional<List<String>> required`

              - `String name`

              - `Type type`

                - `CUSTOM("custom")`

          - `Type type`

            - `AGENT("agent")`

          - `long version`

        - `Type type`

          - `COORDINATOR("coordinator")`

      - `String name`

      - `List<Skill> skills`

        - `class BetaManagedAgentsAnthropicSkill:`

          A resolved Anthropic-managed skill.

        - `class BetaManagedAgentsCustomSkill:`

          A resolved user-created custom skill.

      - `Optional<String> system`

      - `List<Tool> tools`

        - `class BetaManagedAgentsAgentToolset20260401:`

        - `class BetaManagedAgentsMcpToolset:`

        - `class BetaManagedAgentsCustomTool:`

          A custom tool as returned in API responses.

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Optional<Metadata> metadata`

      The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.

    - `Optional<String> title`

      The session's new title. Present only when the update changed it.

  - `class BetaManagedAgentsSystemMessageEvent:`

    A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsSystemContentBlock> content`

      System content blocks. Text-only.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `Type type`

      - `SYSTEM_MESSAGE("system.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsStreamSessionEvents;
import com.anthropic.models.beta.sessions.events.EventStreamParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        StreamResponse<BetaManagedAgentsStreamSessionEvents> betaManagedAgentsStreamSessionEvents = client.beta().sessions().events().streamStreaming("sesn_011CZkZAtmR3yMPDzynEDxu7");
    }
}
```

#### Response

```json
{
  "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
  "content": [
    {
      "text": "Where is my order #1234?",
      "type": "text"
    }
  ],
  "type": "user.message",
  "processed_at": "2026-03-15T10:00:00Z"
}
```

## Domain Types

### Beta Managed Agents Agent Custom Tool Use Event

- `class BetaManagedAgentsAgentCustomToolUseEvent:`

  Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.

  - `String id`

    Unique identifier for this event.

  - `Input input`

    Input parameters for the tool call.

  - `String name`

    Name of the custom tool being called.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")`

  - `Optional<String> sessionThreadId`

    When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.

### Beta Managed Agents Agent MCP Tool Result Event

- `class BetaManagedAgentsAgentMcpToolResultEvent:`

  Event representing the result of an MCP tool execution.

  - `String id`

    Unique identifier for this event.

  - `String mcpToolUseId`

    The id of the `agent.mcp_tool_use` event this result corresponds to.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")`

  - `Optional<List<Content>> content`

    The result content returned by the tool.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

    - `class BetaManagedAgentsSearchResultBlock:`

      A block containing a web search result.

      - `BetaManagedAgentsSearchResultCitations citations`

        Citation settings for a search result.

        - `boolean enabled`

          Whether citations are enabled for this search result.

      - `List<BetaManagedAgentsSearchResultContent> content`

        Array of text content blocks from the search result.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `String source`

        The URL source of the search result.

      - `String title`

        The title of the search result.

      - `Type type`

        - `SEARCH_RESULT("search_result")`

  - `Optional<Boolean> isError`

    Whether the tool execution resulted in an error.

### Beta Managed Agents Agent MCP Tool Use Event

- `class BetaManagedAgentsAgentMcpToolUseEvent:`

  Event emitted when the agent invokes a tool provided by an MCP server.

  - `String id`

    Unique identifier for this event.

  - `Input input`

    Input parameters for the tool call.

  - `String mcpServerName`

    Name of the MCP server providing the tool.

  - `String name`

    Name of the MCP tool being used.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")`

  - `Optional<EvaluatedPermission> evaluatedPermission`

    AgentEvaluatedPermission enum

    - `ALLOW("allow")`

    - `ASK("ask")`

    - `DENY("deny")`

  - `Optional<String> sessionThreadId`

    When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

### Beta Managed Agents Agent Message Event

- `class BetaManagedAgentsAgentMessageEvent:`

  An agent response event in the session conversation.

  - `String id`

    Unique identifier for this event.

  - `List<BetaManagedAgentsTextBlock> content`

    Array of text blocks comprising the agent response.

    - `String text`

      The text content.

    - `Type type`

      - `TEXT("text")`

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `AGENT_MESSAGE("agent.message")`

### Beta Managed Agents Agent Thinking Event

- `class BetaManagedAgentsAgentThinkingEvent:`

  Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

  - `String id`

    Unique identifier for this event.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `AGENT_THINKING("agent.thinking")`

### Beta Managed Agents Agent Thread Context Compacted Event

- `class BetaManagedAgentsAgentThreadContextCompactedEvent:`

  Indicates that context compaction (summarization) occurred during the session.

  - `String id`

    Unique identifier for this event.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")`

### Beta Managed Agents Agent Thread Message Received Event

- `class BetaManagedAgentsAgentThreadMessageReceivedEvent:`

  Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

  - `String id`

    Unique identifier for this event.

  - `List<Content> content`

    Message content blocks.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

  - `String fromSessionThreadId`

    Public `sthr_` ID of the thread that sent the message.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `AGENT_THREAD_MESSAGE_RECEIVED("agent.thread_message_received")`

  - `Optional<String> fromAgentName`

    Name of the callable agent this message came from. Absent when received from the primary agent.

### Beta Managed Agents Agent Thread Message Sent Event

- `class BetaManagedAgentsAgentThreadMessageSentEvent:`

  Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

  - `String id`

    Unique identifier for this event.

  - `List<Content> content`

    Message content blocks.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `String toSessionThreadId`

    Public `sthr_` ID of the thread the message was sent to.

  - `Type type`

    - `AGENT_THREAD_MESSAGE_SENT("agent.thread_message_sent")`

  - `Optional<String> toAgentName`

    Name of the callable agent this message was sent to. Absent when sent to the primary agent.

### Beta Managed Agents Agent Tool Result Event

- `class BetaManagedAgentsAgentToolResultEvent:`

  Event representing the result of an agent tool execution.

  - `String id`

    Unique identifier for this event.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `String toolUseId`

    The id of the `agent.tool_use` event this result corresponds to.

  - `Type type`

    - `AGENT_TOOL_RESULT("agent.tool_result")`

  - `Optional<List<Content>> content`

    The result content returned by the tool.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

    - `class BetaManagedAgentsSearchResultBlock:`

      A block containing a web search result.

      - `BetaManagedAgentsSearchResultCitations citations`

        Citation settings for a search result.

        - `boolean enabled`

          Whether citations are enabled for this search result.

      - `List<BetaManagedAgentsSearchResultContent> content`

        Array of text content blocks from the search result.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `String source`

        The URL source of the search result.

      - `String title`

        The title of the search result.

      - `Type type`

        - `SEARCH_RESULT("search_result")`

  - `Optional<Boolean> isError`

    Whether the tool execution resulted in an error.

### Beta Managed Agents Agent Tool Use Event

- `class BetaManagedAgentsAgentToolUseEvent:`

  Event emitted when the agent invokes a built-in agent tool.

  - `String id`

    Unique identifier for this event.

  - `Input input`

    Input parameters for the tool call.

  - `String name`

    Name of the agent tool being used.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `AGENT_TOOL_USE("agent.tool_use")`

  - `Optional<EvaluatedPermission> evaluatedPermission`

    AgentEvaluatedPermission enum

    - `ALLOW("allow")`

    - `ASK("ask")`

    - `DENY("deny")`

  - `Optional<String> sessionThreadId`

    When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

### Beta Managed Agents Base64 Document Source

- `class BetaManagedAgentsBase64DocumentSource:`

  Base64-encoded document data.

  - `String data`

    Base64-encoded document data.

  - `String mediaType`

    MIME type of the document (e.g., "application/pdf").

  - `Type type`

    - `BASE64("base64")`

### Beta Managed Agents Base64 Image Source

- `class BetaManagedAgentsBase64ImageSource:`

  Base64-encoded image data.

  - `String data`

    Base64-encoded image data.

  - `String mediaType`

    MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

  - `Type type`

    - `BASE64("base64")`

### Beta Managed Agents Billing Error

- `class BetaManagedAgentsBillingError:`

  The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

  - `String message`

    Human-readable error description.

  - `RetryStatus retryStatus`

    What the client should do next in response to this error.

    - `class BetaManagedAgentsRetryStatusRetrying:`

      The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

      - `Type type`

        - `RETRYING("retrying")`

    - `class BetaManagedAgentsRetryStatusExhausted:`

      This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

      - `Type type`

        - `EXHAUSTED("exhausted")`

    - `class BetaManagedAgentsRetryStatusTerminal:`

      The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `TERMINAL("terminal")`

  - `Type type`

    - `BILLING_ERROR("billing_error")`

### Beta Managed Agents Credential Host Unreachable Error

- `class BetaManagedAgentsCredentialHostUnreachableError:`

  An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

  - `String credentialId`

    ID of the affected credential.

  - `String message`

    Human-readable error description.

  - `RetryStatus retryStatus`

    What the client should do next in response to this error.

    - `class BetaManagedAgentsRetryStatusRetrying:`

      The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

      - `Type type`

        - `RETRYING("retrying")`

    - `class BetaManagedAgentsRetryStatusExhausted:`

      This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

      - `Type type`

        - `EXHAUSTED("exhausted")`

    - `class BetaManagedAgentsRetryStatusTerminal:`

      The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `TERMINAL("terminal")`

  - `Type type`

    - `CREDENTIAL_HOST_UNREACHABLE_ERROR("credential_host_unreachable_error")`

  - `String vaultId`

    ID of the vault containing the affected credential.

### Beta Managed Agents Document Block

- `class BetaManagedAgentsDocumentBlock:`

  Document content, either specified directly as base64 data, as text, or as a reference via a URL.

  - `Source source`

    Union type for document source variants.

    - `class BetaManagedAgentsBase64DocumentSource:`

      Base64-encoded document data.

      - `String data`

        Base64-encoded document data.

      - `String mediaType`

        MIME type of the document (e.g., "application/pdf").

      - `Type type`

        - `BASE64("base64")`

    - `class BetaManagedAgentsPlainTextDocumentSource:`

      Plain text document content.

      - `String data`

        The plain text content.

      - `MediaType mediaType`

        MIME type of the text content. Must be "text/plain".

        - `TEXT_PLAIN("text/plain")`

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsUrlDocumentSource:`

      Document referenced by URL.

      - `Type type`

        - `URL("url")`

      - `String url`

        URL of the document to fetch.

    - `class BetaManagedAgentsFileDocumentSource:`

      Document referenced by file ID.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

  - `Type type`

    - `DOCUMENT("document")`

  - `Optional<String> context`

    Additional context about the document for the model.

  - `Optional<String> title`

    The title of the document.

### Beta Managed Agents Event Params

- `class BetaManagedAgentsEventParams: A class that can be one of several variants.union`

  Union type for event parameters that can be sent to a session.

  - `class BetaManagedAgentsUserMessageEventParams:`

    Parameters for sending a user message to the session.

    - `List<Content> content`

      Array of content blocks for the user message.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

        - `Source source`

          Union type for image source variants.

          - `class BetaManagedAgentsBase64ImageSource:`

            Base64-encoded image data.

            - `String data`

              Base64-encoded image data.

            - `String mediaType`

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsUrlImageSource:`

            Image referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the image to fetch.

          - `class BetaManagedAgentsFileImageSource:`

            Image referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `IMAGE("image")`

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `Source source`

          Union type for document source variants.

          - `class BetaManagedAgentsBase64DocumentSource:`

            Base64-encoded document data.

            - `String data`

              Base64-encoded document data.

            - `String mediaType`

              MIME type of the document (e.g., "application/pdf").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsPlainTextDocumentSource:`

            Plain text document content.

            - `String data`

              The plain text content.

            - `MediaType mediaType`

              MIME type of the text content. Must be "text/plain".

              - `TEXT_PLAIN("text/plain")`

            - `Type type`

              - `TEXT("text")`

          - `class BetaManagedAgentsUrlDocumentSource:`

            Document referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the document to fetch.

          - `class BetaManagedAgentsFileDocumentSource:`

            Document referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `DOCUMENT("document")`

        - `Optional<String> context`

          Additional context about the document for the model.

        - `Optional<String> title`

          The title of the document.

    - `Type type`

      - `USER_MESSAGE("user.message")`

  - `class BetaManagedAgentsUserInterruptEventParams:`

    Parameters for sending an interrupt to pause the agent.

    - `Type type`

      - `USER_INTERRUPT("user.interrupt")`

    - `Optional<String> sessionThreadId`

      If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

  - `class BetaManagedAgentsUserToolConfirmationEventParams:`

    Parameters for confirming or denying a tool execution request.

    - `Result result`

      UserToolConfirmationResult enum

      - `ALLOW("allow")`

      - `DENY("deny")`

    - `String toolUseId`

      The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

    - `Optional<String> denyMessage`

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

  - `class BetaManagedAgentsUserCustomToolResultEventParams:`

    Parameters for providing the result of a custom tool execution.

    - `String customToolUseId`

      The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

        - `BetaManagedAgentsSearchResultCitations citations`

          Citation settings for a search result.

          - `boolean enabled`

            Whether citations are enabled for this search result.

        - `List<BetaManagedAgentsSearchResultContent> content`

          Array of text content blocks from the search result.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `String source`

          The URL source of the search result.

        - `String title`

          The title of the search result.

        - `Type type`

          - `SEARCH_RESULT("search_result")`

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsUserDefineOutcomeEventParams:`

    Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

    - `String description`

      What the agent should produce. This is the task specification.

    - `Rubric rubric`

      Rubric for grading the quality of an outcome.

      - `class BetaManagedAgentsFileRubricParams:`

        Rubric referenced by a file uploaded via the Files API.

        - `String fileId`

          ID of the rubric file.

        - `Type type`

          - `FILE("file")`

      - `class BetaManagedAgentsTextRubricParams:`

        Rubric content provided inline as text.

        - `String content`

          Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

        - `Type type`

          - `TEXT("text")`

    - `Type type`

      - `USER_DEFINE_OUTCOME("user.define_outcome")`

    - `Optional<Long> maxIterations`

      Eval→revision cycles before giving up. Default 3, max 20.

  - `class BetaManagedAgentsUserToolResultEventParams:`

    Parameters for providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_RESULT("user.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsSystemMessageEventParams:`

    Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages.

    - `List<BetaManagedAgentsSystemContentBlock> content`

      System content blocks to append. Text-only.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `Type type`

      - `SYSTEM_MESSAGE("system.message")`

### Beta Managed Agents File Document Source

- `class BetaManagedAgentsFileDocumentSource:`

  Document referenced by file ID.

  - `String fileId`

    ID of a previously uploaded file.

  - `Type type`

    - `FILE("file")`

### Beta Managed Agents File Image Source

- `class BetaManagedAgentsFileImageSource:`

  Image referenced by file ID.

  - `String fileId`

    ID of a previously uploaded file.

  - `Type type`

    - `FILE("file")`

### Beta Managed Agents File Rubric

- `class BetaManagedAgentsFileRubric:`

  Rubric referenced by a file uploaded via the Files API.

  - `String fileId`

    ID of the rubric file.

  - `Type type`

    - `FILE("file")`

### Beta Managed Agents File Rubric Params

- `class BetaManagedAgentsFileRubricParams:`

  Rubric referenced by a file uploaded via the Files API.

  - `String fileId`

    ID of the rubric file.

  - `Type type`

    - `FILE("file")`

### Beta Managed Agents Image Block

- `class BetaManagedAgentsImageBlock:`

  Image content specified directly as base64 data or as a reference via a URL.

  - `Source source`

    Union type for image source variants.

    - `class BetaManagedAgentsBase64ImageSource:`

      Base64-encoded image data.

      - `String data`

        Base64-encoded image data.

      - `String mediaType`

        MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

      - `Type type`

        - `BASE64("base64")`

    - `class BetaManagedAgentsUrlImageSource:`

      Image referenced by URL.

      - `Type type`

        - `URL("url")`

      - `String url`

        URL of the image to fetch.

    - `class BetaManagedAgentsFileImageSource:`

      Image referenced by file ID.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

  - `Type type`

    - `IMAGE("image")`

### Beta Managed Agents MCP Authentication Failed Error

- `class BetaManagedAgentsMcpAuthenticationFailedError:`

  Authentication to an MCP server failed.

  - `String mcpServerName`

    Name of the MCP server that failed authentication.

  - `String message`

    Human-readable error description.

  - `RetryStatus retryStatus`

    What the client should do next in response to this error.

    - `class BetaManagedAgentsRetryStatusRetrying:`

      The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

      - `Type type`

        - `RETRYING("retrying")`

    - `class BetaManagedAgentsRetryStatusExhausted:`

      This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

      - `Type type`

        - `EXHAUSTED("exhausted")`

    - `class BetaManagedAgentsRetryStatusTerminal:`

      The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `TERMINAL("terminal")`

  - `Type type`

    - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")`

### Beta Managed Agents MCP Connection Failed Error

- `class BetaManagedAgentsMcpConnectionFailedError:`

  Failed to connect to an MCP server.

  - `String mcpServerName`

    Name of the MCP server that failed to connect.

  - `String message`

    Human-readable error description.

  - `RetryStatus retryStatus`

    What the client should do next in response to this error.

    - `class BetaManagedAgentsRetryStatusRetrying:`

      The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

      - `Type type`

        - `RETRYING("retrying")`

    - `class BetaManagedAgentsRetryStatusExhausted:`

      This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

      - `Type type`

        - `EXHAUSTED("exhausted")`

    - `class BetaManagedAgentsRetryStatusTerminal:`

      The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `TERMINAL("terminal")`

  - `Type type`

    - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")`

### Beta Managed Agents Model Overloaded Error

- `class BetaManagedAgentsModelOverloadedError:`

  The model is currently overloaded. Emitted after automatic retries are exhausted.

  - `String message`

    Human-readable error description.

  - `RetryStatus retryStatus`

    What the client should do next in response to this error.

    - `class BetaManagedAgentsRetryStatusRetrying:`

      The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

      - `Type type`

        - `RETRYING("retrying")`

    - `class BetaManagedAgentsRetryStatusExhausted:`

      This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

      - `Type type`

        - `EXHAUSTED("exhausted")`

    - `class BetaManagedAgentsRetryStatusTerminal:`

      The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `TERMINAL("terminal")`

  - `Type type`

    - `MODEL_OVERLOADED_ERROR("model_overloaded_error")`

### Beta Managed Agents Model Rate Limited Error

- `class BetaManagedAgentsModelRateLimitedError:`

  The model request was rate-limited.

  - `String message`

    Human-readable error description.

  - `RetryStatus retryStatus`

    What the client should do next in response to this error.

    - `class BetaManagedAgentsRetryStatusRetrying:`

      The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

      - `Type type`

        - `RETRYING("retrying")`

    - `class BetaManagedAgentsRetryStatusExhausted:`

      This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

      - `Type type`

        - `EXHAUSTED("exhausted")`

    - `class BetaManagedAgentsRetryStatusTerminal:`

      The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `TERMINAL("terminal")`

  - `Type type`

    - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")`

### Beta Managed Agents Model Request Failed Error

- `class BetaManagedAgentsModelRequestFailedError:`

  A model request failed for a reason other than overload or rate-limiting.

  - `String message`

    Human-readable error description.

  - `RetryStatus retryStatus`

    What the client should do next in response to this error.

    - `class BetaManagedAgentsRetryStatusRetrying:`

      The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

      - `Type type`

        - `RETRYING("retrying")`

    - `class BetaManagedAgentsRetryStatusExhausted:`

      This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

      - `Type type`

        - `EXHAUSTED("exhausted")`

    - `class BetaManagedAgentsRetryStatusTerminal:`

      The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `TERMINAL("terminal")`

  - `Type type`

    - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")`

### Beta Managed Agents Plain Text Document Source

- `class BetaManagedAgentsPlainTextDocumentSource:`

  Plain text document content.

  - `String data`

    The plain text content.

  - `MediaType mediaType`

    MIME type of the text content. Must be "text/plain".

    - `TEXT_PLAIN("text/plain")`

  - `Type type`

    - `TEXT("text")`

### Beta Managed Agents Retry Status Exhausted

- `class BetaManagedAgentsRetryStatusExhausted:`

  This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

  - `Type type`

    - `EXHAUSTED("exhausted")`

### Beta Managed Agents Retry Status Retrying

- `class BetaManagedAgentsRetryStatusRetrying:`

  The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

  - `Type type`

    - `RETRYING("retrying")`

### Beta Managed Agents Retry Status Terminal

- `class BetaManagedAgentsRetryStatusTerminal:`

  The session encountered a terminal error and will transition to `terminated` state.

  - `Type type`

    - `TERMINAL("terminal")`

### Beta Managed Agents Search Result Block

- `class BetaManagedAgentsSearchResultBlock:`

  A block containing a web search result.

  - `BetaManagedAgentsSearchResultCitations citations`

    Citation settings for a search result.

    - `boolean enabled`

      Whether citations are enabled for this search result.

  - `List<BetaManagedAgentsSearchResultContent> content`

    Array of text content blocks from the search result.

    - `String text`

      The text content.

    - `Type type`

      - `TEXT("text")`

  - `String source`

    The URL source of the search result.

  - `String title`

    The title of the search result.

  - `Type type`

    - `SEARCH_RESULT("search_result")`

### Beta Managed Agents Search Result Citations

- `class BetaManagedAgentsSearchResultCitations:`

  Citation settings for a search result.

  - `boolean enabled`

    Whether citations are enabled for this search result.

### Beta Managed Agents Search Result Content

- `class BetaManagedAgentsSearchResultContent:`

  Text content within a search result.

  - `String text`

    The text content.

  - `Type type`

    - `TEXT("text")`

### Beta Managed Agents Send Session Events

- `class BetaManagedAgentsSendSessionEvents:`

  Events that were successfully sent to the session.

  - `Optional<List<Data>> data`

    Sent events

    - `class BetaManagedAgentsUserMessageEvent:`

      A user message event in the session conversation.

      - `String id`

        Unique identifier for this event.

      - `List<Content> content`

        Array of content blocks comprising the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

    - `class BetaManagedAgentsUserInterruptEvent:`

      An interrupt event that pauses agent execution and returns control to the user.

      - `String id`

        Unique identifier for this event.

      - `Type type`

        - `USER_INTERRUPT("user.interrupt")`

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

      - `Optional<String> sessionThreadId`

        If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

    - `class BetaManagedAgentsUserToolConfirmationEvent:`

      A tool confirmation event that approves or denies a pending tool execution.

      - `String id`

        Unique identifier for this event.

      - `Result result`

        UserToolConfirmationResult enum

        - `ALLOW("allow")`

        - `DENY("deny")`

      - `String toolUseId`

        The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

      - `Type type`

        - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

      - `Optional<String> denyMessage`

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

      - `Optional<String> sessionThreadId`

        When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

    - `class BetaManagedAgentsUserCustomToolResultEvent:`

      Event sent by the client providing the result of a custom tool execution.

      - `String id`

        Unique identifier for this event.

      - `String customToolUseId`

        The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

      - `Type type`

        - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

      - `Optional<List<Content>> content`

        The result content returned by the tool.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `class BetaManagedAgentsSearchResultBlock:`

          A block containing a web search result.

          - `BetaManagedAgentsSearchResultCitations citations`

            Citation settings for a search result.

            - `boolean enabled`

              Whether citations are enabled for this search result.

          - `List<BetaManagedAgentsSearchResultContent> content`

            Array of text content blocks from the search result.

            - `String text`

              The text content.

            - `Type type`

              - `TEXT("text")`

          - `String source`

            The URL source of the search result.

          - `String title`

            The title of the search result.

          - `Type type`

            - `SEARCH_RESULT("search_result")`

      - `Optional<Boolean> isError`

        Whether the tool execution resulted in an error.

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

      - `Optional<String> sessionThreadId`

        Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

    - `class BetaManagedAgentsUserDefineOutcomeEvent:`

      Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

      - `String id`

        Unique identifier for this event.

      - `String description`

        What the agent should produce. Copied from the input event.

      - `Optional<Long> maxIterations`

        Evaluate-then-revise cycles before giving up. Default 3, max 20.

      - `String outcomeId`

        Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

      - `LocalDateTime processedAt`

        A timestamp in RFC 3339 format

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubric:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubric:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

    - `class BetaManagedAgentsUserToolResultEvent:`

      Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

      - `String id`

        Unique identifier for this event.

      - `String toolUseId`

        The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

      - `Type type`

        - `USER_TOOL_RESULT("user.tool_result")`

      - `Optional<List<Content>> content`

        The result content returned by the tool.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `class BetaManagedAgentsSearchResultBlock:`

          A block containing a web search result.

      - `Optional<Boolean> isError`

        Whether the tool execution resulted in an error.

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

      - `Optional<String> sessionThreadId`

        Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

    - `class BetaManagedAgentsSystemMessageEvent:`

      A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

      - `String id`

        Unique identifier for this event.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

      - `Optional<LocalDateTime> processedAt`

        A timestamp in RFC 3339 format

### Beta Managed Agents Session Deleted Event

- `class BetaManagedAgentsSessionDeletedEvent:`

  Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

  - `String id`

    Unique identifier for this event.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SESSION_DELETED("session.deleted")`

### Beta Managed Agents Session End Turn

- `class BetaManagedAgentsSessionEndTurn:`

  The agent completed its turn naturally and is ready for the next user message.

  - `Type type`

    - `END_TURN("end_turn")`

### Beta Managed Agents Session Error Event

- `class BetaManagedAgentsSessionErrorEvent:`

  An error event indicating a problem occurred during session execution.

  - `String id`

    Unique identifier for this event.

  - `Error error`

    An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

    - `class BetaManagedAgentsUnknownError:`

      An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

      - `String message`

        Human-readable error description.

      - `RetryStatus retryStatus`

        What the client should do next in response to this error.

        - `class BetaManagedAgentsRetryStatusRetrying:`

          The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `Type type`

            - `RETRYING("retrying")`

        - `class BetaManagedAgentsRetryStatusExhausted:`

          This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `Type type`

            - `EXHAUSTED("exhausted")`

        - `class BetaManagedAgentsRetryStatusTerminal:`

          The session encountered a terminal error and will transition to `terminated` state.

          - `Type type`

            - `TERMINAL("terminal")`

      - `Type type`

        - `UNKNOWN_ERROR("unknown_error")`

    - `class BetaManagedAgentsModelOverloadedError:`

      The model is currently overloaded. Emitted after automatic retries are exhausted.

      - `String message`

        Human-readable error description.

      - `RetryStatus retryStatus`

        What the client should do next in response to this error.

        - `class BetaManagedAgentsRetryStatusRetrying:`

          The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

        - `class BetaManagedAgentsRetryStatusExhausted:`

          This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        - `class BetaManagedAgentsRetryStatusTerminal:`

          The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `MODEL_OVERLOADED_ERROR("model_overloaded_error")`

    - `class BetaManagedAgentsModelRateLimitedError:`

      The model request was rate-limited.

      - `String message`

        Human-readable error description.

      - `RetryStatus retryStatus`

        What the client should do next in response to this error.

        - `class BetaManagedAgentsRetryStatusRetrying:`

          The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

        - `class BetaManagedAgentsRetryStatusExhausted:`

          This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        - `class BetaManagedAgentsRetryStatusTerminal:`

          The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")`

    - `class BetaManagedAgentsModelRequestFailedError:`

      A model request failed for a reason other than overload or rate-limiting.

      - `String message`

        Human-readable error description.

      - `RetryStatus retryStatus`

        What the client should do next in response to this error.

        - `class BetaManagedAgentsRetryStatusRetrying:`

          The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

        - `class BetaManagedAgentsRetryStatusExhausted:`

          This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        - `class BetaManagedAgentsRetryStatusTerminal:`

          The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")`

    - `class BetaManagedAgentsMcpConnectionFailedError:`

      Failed to connect to an MCP server.

      - `String mcpServerName`

        Name of the MCP server that failed to connect.

      - `String message`

        Human-readable error description.

      - `RetryStatus retryStatus`

        What the client should do next in response to this error.

        - `class BetaManagedAgentsRetryStatusRetrying:`

          The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

        - `class BetaManagedAgentsRetryStatusExhausted:`

          This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        - `class BetaManagedAgentsRetryStatusTerminal:`

          The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")`

    - `class BetaManagedAgentsMcpAuthenticationFailedError:`

      Authentication to an MCP server failed.

      - `String mcpServerName`

        Name of the MCP server that failed authentication.

      - `String message`

        Human-readable error description.

      - `RetryStatus retryStatus`

        What the client should do next in response to this error.

        - `class BetaManagedAgentsRetryStatusRetrying:`

          The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

        - `class BetaManagedAgentsRetryStatusExhausted:`

          This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        - `class BetaManagedAgentsRetryStatusTerminal:`

          The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")`

    - `class BetaManagedAgentsBillingError:`

      The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

      - `String message`

        Human-readable error description.

      - `RetryStatus retryStatus`

        What the client should do next in response to this error.

        - `class BetaManagedAgentsRetryStatusRetrying:`

          The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

        - `class BetaManagedAgentsRetryStatusExhausted:`

          This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        - `class BetaManagedAgentsRetryStatusTerminal:`

          The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `BILLING_ERROR("billing_error")`

    - `class BetaManagedAgentsCredentialHostUnreachableError:`

      An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

      - `String credentialId`

        ID of the affected credential.

      - `String message`

        Human-readable error description.

      - `RetryStatus retryStatus`

        What the client should do next in response to this error.

        - `class BetaManagedAgentsRetryStatusRetrying:`

          The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

        - `class BetaManagedAgentsRetryStatusExhausted:`

          This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        - `class BetaManagedAgentsRetryStatusTerminal:`

          The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `CREDENTIAL_HOST_UNREACHABLE_ERROR("credential_host_unreachable_error")`

      - `String vaultId`

        ID of the vault containing the affected credential.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SESSION_ERROR("session.error")`

### Beta Managed Agents Session Event

- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union`

  Union type for all event types in a session.

  - `class BetaManagedAgentsUserMessageEvent:`

    A user message event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Array of content blocks comprising the user message.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

        - `Source source`

          Union type for image source variants.

          - `class BetaManagedAgentsBase64ImageSource:`

            Base64-encoded image data.

            - `String data`

              Base64-encoded image data.

            - `String mediaType`

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsUrlImageSource:`

            Image referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the image to fetch.

          - `class BetaManagedAgentsFileImageSource:`

            Image referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `IMAGE("image")`

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `Source source`

          Union type for document source variants.

          - `class BetaManagedAgentsBase64DocumentSource:`

            Base64-encoded document data.

            - `String data`

              Base64-encoded document data.

            - `String mediaType`

              MIME type of the document (e.g., "application/pdf").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsPlainTextDocumentSource:`

            Plain text document content.

            - `String data`

              The plain text content.

            - `MediaType mediaType`

              MIME type of the text content. Must be "text/plain".

              - `TEXT_PLAIN("text/plain")`

            - `Type type`

              - `TEXT("text")`

          - `class BetaManagedAgentsUrlDocumentSource:`

            Document referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the document to fetch.

          - `class BetaManagedAgentsFileDocumentSource:`

            Document referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `DOCUMENT("document")`

        - `Optional<String> context`

          Additional context about the document for the model.

        - `Optional<String> title`

          The title of the document.

    - `Type type`

      - `USER_MESSAGE("user.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsUserInterruptEvent:`

    An interrupt event that pauses agent execution and returns control to the user.

    - `String id`

      Unique identifier for this event.

    - `Type type`

      - `USER_INTERRUPT("user.interrupt")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

  - `class BetaManagedAgentsUserToolConfirmationEvent:`

    A tool confirmation event that approves or denies a pending tool execution.

    - `String id`

      Unique identifier for this event.

    - `Result result`

      UserToolConfirmationResult enum

      - `ALLOW("allow")`

      - `DENY("deny")`

    - `String toolUseId`

      The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

    - `Optional<String> denyMessage`

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

  - `class BetaManagedAgentsUserCustomToolResultEvent:`

    Event sent by the client providing the result of a custom tool execution.

    - `String id`

      Unique identifier for this event.

    - `String customToolUseId`

      The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

        - `BetaManagedAgentsSearchResultCitations citations`

          Citation settings for a search result.

          - `boolean enabled`

            Whether citations are enabled for this search result.

        - `List<BetaManagedAgentsSearchResultContent> content`

          Array of text content blocks from the search result.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `String source`

          The URL source of the search result.

        - `String title`

          The title of the search result.

        - `Type type`

          - `SEARCH_RESULT("search_result")`

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsAgentCustomToolUseEvent:`

    Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the custom tool being called.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.

  - `class BetaManagedAgentsAgentMessageEvent:`

    An agent response event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsTextBlock> content`

      Array of text blocks comprising the agent response.

      - `String text`

        The text content.

      - `Type type`

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MESSAGE("agent.message")`

  - `class BetaManagedAgentsAgentThinkingEvent:`

    Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THINKING("agent.thinking")`

  - `class BetaManagedAgentsAgentMcpToolUseEvent:`

    Event emitted when the agent invokes a tool provided by an MCP server.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String mcpServerName`

      Name of the MCP server providing the tool.

    - `String name`

      Name of the MCP tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentMcpToolResultEvent:`

    Event representing the result of an MCP tool execution.

    - `String id`

      Unique identifier for this event.

    - `String mcpToolUseId`

      The id of the `agent.mcp_tool_use` event this result corresponds to.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentToolUseEvent:`

    Event emitted when the agent invokes a built-in agent tool.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the agent tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_TOOL_USE("agent.tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentToolResultEvent:`

    Event representing the result of an agent tool execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to.

    - `Type type`

      - `AGENT_TOOL_RESULT("agent.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentThreadMessageReceivedEvent:`

    Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `String fromSessionThreadId`

      Public `sthr_` ID of the thread that sent the message.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_MESSAGE_RECEIVED("agent.thread_message_received")`

    - `Optional<String> fromAgentName`

      Name of the callable agent this message came from. Absent when received from the primary agent.

  - `class BetaManagedAgentsAgentThreadMessageSentEvent:`

    Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toSessionThreadId`

      Public `sthr_` ID of the thread the message was sent to.

    - `Type type`

      - `AGENT_THREAD_MESSAGE_SENT("agent.thread_message_sent")`

    - `Optional<String> toAgentName`

      Name of the callable agent this message was sent to. Absent when sent to the primary agent.

  - `class BetaManagedAgentsAgentThreadContextCompactedEvent:`

    Indicates that context compaction (summarization) occurred during the session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")`

  - `class BetaManagedAgentsSessionErrorEvent:`

    An error event indicating a problem occurred during session execution.

    - `String id`

      Unique identifier for this event.

    - `Error error`

      An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

      - `class BetaManagedAgentsUnknownError:`

        An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

            - `Type type`

              - `RETRYING("retrying")`

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            - `Type type`

              - `EXHAUSTED("exhausted")`

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

            - `Type type`

              - `TERMINAL("terminal")`

        - `Type type`

          - `UNKNOWN_ERROR("unknown_error")`

      - `class BetaManagedAgentsModelOverloadedError:`

        The model is currently overloaded. Emitted after automatic retries are exhausted.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_OVERLOADED_ERROR("model_overloaded_error")`

      - `class BetaManagedAgentsModelRateLimitedError:`

        The model request was rate-limited.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")`

      - `class BetaManagedAgentsModelRequestFailedError:`

        A model request failed for a reason other than overload or rate-limiting.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")`

      - `class BetaManagedAgentsMcpConnectionFailedError:`

        Failed to connect to an MCP server.

        - `String mcpServerName`

          Name of the MCP server that failed to connect.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")`

      - `class BetaManagedAgentsMcpAuthenticationFailedError:`

        Authentication to an MCP server failed.

        - `String mcpServerName`

          Name of the MCP server that failed authentication.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")`

      - `class BetaManagedAgentsBillingError:`

        The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `BILLING_ERROR("billing_error")`

      - `class BetaManagedAgentsCredentialHostUnreachableError:`

        An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

        - `String credentialId`

          ID of the affected credential.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `CREDENTIAL_HOST_UNREACHABLE_ERROR("credential_host_unreachable_error")`

        - `String vaultId`

          ID of the vault containing the affected credential.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_ERROR("session.error")`

  - `class BetaManagedAgentsSessionStatusRescheduledEvent:`

    Indicates the session is recovering from an error state and is rescheduled for execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

  - `class BetaManagedAgentsSessionStatusRunningEvent:`

    Indicates the session is actively running and the agent is working.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RUNNING("session.status_running")`

  - `class BetaManagedAgentsSessionStatusIdleEvent:`

    Indicates the agent has paused and is awaiting user input.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

        - `Type type`

          - `END_TURN("end_turn")`

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

        - `List<String> eventIds`

          The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

        - `Type type`

          - `REQUIRES_ACTION("requires_action")`

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

        - `Type type`

          - `RETRIES_EXHAUSTED("retries_exhausted")`

    - `Type type`

      - `SESSION_STATUS_IDLE("session.status_idle")`

  - `class BetaManagedAgentsSessionStatusTerminatedEvent:`

    Indicates the session has terminated, either due to an error or completion.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_TERMINATED("session.status_terminated")`

  - `class BetaManagedAgentsSessionThreadCreatedEvent:`

    Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the callable agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public `sthr_` ID of the newly created thread.

    - `Type type`

      - `SESSION_THREAD_CREATED("session.thread_created")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationStartEvent:`

    Emitted when an outcome evaluation cycle begins.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_START("span.outcome_evaluation_start")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationEndEvent:`

    Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.

    - `String id`

      Unique identifier for this event.

    - `String explanation`

      Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeEvaluationStartId`

      The id of the corresponding `span.outcome_evaluation_start` event.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String result`

      Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_END("span.outcome_evaluation_end")`

    - `BetaManagedAgentsSpanModelUsage usage`

      Token usage for a single model request.

      - `long cacheCreationInputTokens`

        Tokens used to create prompt cache in this request.

      - `long cacheReadInputTokens`

        Tokens read from prompt cache in this request.

      - `long inputTokens`

        Input tokens consumed by this request.

      - `long outputTokens`

        Output tokens generated by this request.

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `class BetaManagedAgentsSpanModelRequestStartEvent:`

    Emitted when a model request is initiated by the agent.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_START("span.model_request_start")`

  - `class BetaManagedAgentsSpanModelRequestEndEvent:`

    Emitted when a model request completes.

    - `String id`

      Unique identifier for this event.

    - `Optional<Boolean> isError`

      Whether the model request resulted in an error.

    - `String modelRequestStartId`

      The id of the corresponding `span.model_request_start` event.

    - `BetaManagedAgentsSpanModelUsage modelUsage`

      Token usage for a single model request.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_END("span.model_request_end")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent:`

    Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_ONGOING("span.outcome_evaluation_ongoing")`

  - `class BetaManagedAgentsUserDefineOutcomeEvent:`

    Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

    - `String id`

      Unique identifier for this event.

    - `String description`

      What the agent should produce. Copied from the input event.

    - `Optional<Long> maxIterations`

      Evaluate-then-revise cycles before giving up. Default 3, max 20.

    - `String outcomeId`

      Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Rubric rubric`

      Rubric for grading the quality of an outcome.

      - `class BetaManagedAgentsFileRubric:`

        Rubric referenced by a file uploaded via the Files API.

        - `String fileId`

          ID of the rubric file.

        - `Type type`

          - `FILE("file")`

      - `class BetaManagedAgentsTextRubric:`

        Rubric content provided inline as text.

        - `String content`

          Rubric content. Plain text or markdown — the grader treats it as freeform text.

        - `Type type`

          - `TEXT("text")`

    - `Type type`

      - `USER_DEFINE_OUTCOME("user.define_outcome")`

  - `class BetaManagedAgentsSessionDeletedEvent:`

    Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_DELETED("session.deleted")`

  - `class BetaManagedAgentsSessionThreadStatusRunningEvent:`

    A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that started running.

    - `Type type`

      - `SESSION_THREAD_STATUS_RUNNING("session.thread_status_running")`

  - `class BetaManagedAgentsSessionThreadStatusIdleEvent:`

    A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that went idle.

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

    - `Type type`

      - `SESSION_THREAD_STATUS_IDLE("session.thread_status_idle")`

  - `class BetaManagedAgentsSessionThreadStatusTerminatedEvent:`

    A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that terminated.

    - `Type type`

      - `SESSION_THREAD_STATUS_TERMINATED("session.thread_status_terminated")`

  - `class BetaManagedAgentsUserToolResultEvent:`

    Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

    - `String id`

      Unique identifier for this event.

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_RESULT("user.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsSessionThreadStatusRescheduledEvent:`

    A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that is retrying.

    - `Type type`

      - `SESSION_THREAD_STATUS_RESCHEDULED("session.thread_status_rescheduled")`

  - `class BetaManagedAgentsSessionUpdatedEvent:`

    Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_UPDATED("session.updated")`

    - `Optional<BetaManagedAgentsSessionAgent> agent`

      Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

      - `String id`

      - `Optional<String> description`

      - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

        - `String name`

        - `Type type`

          - `URL("url")`

        - `String url`

      - `BetaManagedAgentsModelConfig model`

        Model identifier and configuration.

        - `BetaManagedAgentsModel id`

          The model that will power your agent.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Most intelligent model for building agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

        - `Optional<Speed> speed`

          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.

          - `STANDARD("standard")`

          - `FAST("fast")`

      - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

        Resolved coordinator topology with full agent definitions for each roster member.

        - `List<BetaManagedAgentsSessionThreadAgent> agents`

          Full `agent` definitions the coordinator may spawn as session threads.

          - `String id`

          - `Optional<String> description`

          - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

            - `String name`

            - `Type type`

            - `String url`

          - `BetaManagedAgentsModelConfig model`

            Model identifier and configuration.

          - `String name`

          - `List<Skill> skills`

            - `class BetaManagedAgentsAnthropicSkill:`

              A resolved Anthropic-managed skill.

              - `String skillId`

              - `Type type`

                - `ANTHROPIC("anthropic")`

              - `String version`

            - `class BetaManagedAgentsCustomSkill:`

              A resolved user-created custom skill.

              - `String skillId`

              - `Type type`

                - `CUSTOM("custom")`

              - `String version`

          - `Optional<String> system`

          - `List<Tool> tools`

            - `class BetaManagedAgentsAgentToolset20260401:`

              - `List<BetaManagedAgentsAgentToolConfig> configs`

                - `boolean enabled`

                - `Name name`

                  Built-in agent tool identifier.

                  - `BASH("bash")`

                  - `EDIT("edit")`

                  - `READ("read")`

                  - `WRITE("write")`

                  - `GLOB("glob")`

                  - `GREP("grep")`

                  - `WEB_FETCH("web_fetch")`

                  - `WEB_SEARCH("web_search")`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                    - `Type type`

                      - `ALWAYS_ALLOW("always_allow")`

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

                    - `Type type`

                      - `ALWAYS_ASK("always_ask")`

              - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

                Resolved default configuration for agent tools.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `Type type`

                - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

            - `class BetaManagedAgentsMcpToolset:`

              - `List<BetaManagedAgentsMcpToolConfig> configs`

                - `boolean enabled`

                - `String name`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

                Resolved default configuration for all tools from an MCP server.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `String mcpServerName`

              - `Type type`

                - `MCP_TOOLSET("mcp_toolset")`

            - `class BetaManagedAgentsCustomTool:`

              A custom tool as returned in API responses.

              - `String description`

              - `BetaManagedAgentsCustomToolInputSchema inputSchema`

                JSON Schema for custom tool input parameters.

                - `JsonValue; type "object"constant`

                  - `OBJECT("object")`

                - `Optional<Properties> properties`

                - `Optional<List<String>> required`

              - `String name`

              - `Type type`

                - `CUSTOM("custom")`

          - `Type type`

            - `AGENT("agent")`

          - `long version`

        - `Type type`

          - `COORDINATOR("coordinator")`

      - `String name`

      - `List<Skill> skills`

        - `class BetaManagedAgentsAnthropicSkill:`

          A resolved Anthropic-managed skill.

        - `class BetaManagedAgentsCustomSkill:`

          A resolved user-created custom skill.

      - `Optional<String> system`

      - `List<Tool> tools`

        - `class BetaManagedAgentsAgentToolset20260401:`

        - `class BetaManagedAgentsMcpToolset:`

        - `class BetaManagedAgentsCustomTool:`

          A custom tool as returned in API responses.

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Optional<Metadata> metadata`

      The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.

    - `Optional<String> title`

      The session's new title. Present only when the update changed it.

  - `class BetaManagedAgentsSystemMessageEvent:`

    A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsSystemContentBlock> content`

      System content blocks. Text-only.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `Type type`

      - `SYSTEM_MESSAGE("system.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

### Beta Managed Agents Session Requires Action

- `class BetaManagedAgentsSessionRequiresAction:`

  The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

  - `List<String> eventIds`

    The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

  - `Type type`

    - `REQUIRES_ACTION("requires_action")`

### Beta Managed Agents Session Retries Exhausted

- `class BetaManagedAgentsSessionRetriesExhausted:`

  The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

  - `Type type`

    - `RETRIES_EXHAUSTED("retries_exhausted")`

### Beta Managed Agents Session Status Idle Event

- `class BetaManagedAgentsSessionStatusIdleEvent:`

  Indicates the agent has paused and is awaiting user input.

  - `String id`

    Unique identifier for this event.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `StopReason stopReason`

    The agent completed its turn naturally and is ready for the next user message.

    - `class BetaManagedAgentsSessionEndTurn:`

      The agent completed its turn naturally and is ready for the next user message.

      - `Type type`

        - `END_TURN("end_turn")`

    - `class BetaManagedAgentsSessionRequiresAction:`

      The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

      - `List<String> eventIds`

        The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

      - `Type type`

        - `REQUIRES_ACTION("requires_action")`

    - `class BetaManagedAgentsSessionRetriesExhausted:`

      The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

      - `Type type`

        - `RETRIES_EXHAUSTED("retries_exhausted")`

  - `Type type`

    - `SESSION_STATUS_IDLE("session.status_idle")`

### Beta Managed Agents Session Status Rescheduled Event

- `class BetaManagedAgentsSessionStatusRescheduledEvent:`

  Indicates the session is recovering from an error state and is rescheduled for execution.

  - `String id`

    Unique identifier for this event.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

### Beta Managed Agents Session Status Running Event

- `class BetaManagedAgentsSessionStatusRunningEvent:`

  Indicates the session is actively running and the agent is working.

  - `String id`

    Unique identifier for this event.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SESSION_STATUS_RUNNING("session.status_running")`

### Beta Managed Agents Session Status Terminated Event

- `class BetaManagedAgentsSessionStatusTerminatedEvent:`

  Indicates the session has terminated, either due to an error or completion.

  - `String id`

    Unique identifier for this event.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SESSION_STATUS_TERMINATED("session.status_terminated")`

### Beta Managed Agents Session Thread Created Event

- `class BetaManagedAgentsSessionThreadCreatedEvent:`

  Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

  - `String id`

    Unique identifier for this event.

  - `String agentName`

    Name of the callable agent the thread runs.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `String sessionThreadId`

    Public `sthr_` ID of the newly created thread.

  - `Type type`

    - `SESSION_THREAD_CREATED("session.thread_created")`

### Beta Managed Agents Session Thread Status Idle Event

- `class BetaManagedAgentsSessionThreadStatusIdleEvent:`

  A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

  - `String id`

    Unique identifier for this event.

  - `String agentName`

    Name of the agent the thread runs.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `String sessionThreadId`

    Public sthr_ ID of the thread that went idle.

  - `StopReason stopReason`

    The agent completed its turn naturally and is ready for the next user message.

    - `class BetaManagedAgentsSessionEndTurn:`

      The agent completed its turn naturally and is ready for the next user message.

      - `Type type`

        - `END_TURN("end_turn")`

    - `class BetaManagedAgentsSessionRequiresAction:`

      The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

      - `List<String> eventIds`

        The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

      - `Type type`

        - `REQUIRES_ACTION("requires_action")`

    - `class BetaManagedAgentsSessionRetriesExhausted:`

      The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

      - `Type type`

        - `RETRIES_EXHAUSTED("retries_exhausted")`

  - `Type type`

    - `SESSION_THREAD_STATUS_IDLE("session.thread_status_idle")`

### Beta Managed Agents Session Thread Status Rescheduled Event

- `class BetaManagedAgentsSessionThreadStatusRescheduledEvent:`

  A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

  - `String id`

    Unique identifier for this event.

  - `String agentName`

    Name of the agent the thread runs.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `String sessionThreadId`

    Public sthr_ ID of the thread that is retrying.

  - `Type type`

    - `SESSION_THREAD_STATUS_RESCHEDULED("session.thread_status_rescheduled")`

### Beta Managed Agents Session Thread Status Running Event

- `class BetaManagedAgentsSessionThreadStatusRunningEvent:`

  A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

  - `String id`

    Unique identifier for this event.

  - `String agentName`

    Name of the agent the thread runs.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `String sessionThreadId`

    Public sthr_ ID of the thread that started running.

  - `Type type`

    - `SESSION_THREAD_STATUS_RUNNING("session.thread_status_running")`

### Beta Managed Agents Session Thread Status Terminated Event

- `class BetaManagedAgentsSessionThreadStatusTerminatedEvent:`

  A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

  - `String id`

    Unique identifier for this event.

  - `String agentName`

    Name of the agent the thread runs.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `String sessionThreadId`

    Public sthr_ ID of the thread that terminated.

  - `Type type`

    - `SESSION_THREAD_STATUS_TERMINATED("session.thread_status_terminated")`

### Beta Managed Agents Span Model Request End Event

- `class BetaManagedAgentsSpanModelRequestEndEvent:`

  Emitted when a model request completes.

  - `String id`

    Unique identifier for this event.

  - `Optional<Boolean> isError`

    Whether the model request resulted in an error.

  - `String modelRequestStartId`

    The id of the corresponding `span.model_request_start` event.

  - `BetaManagedAgentsSpanModelUsage modelUsage`

    Token usage for a single model request.

    - `long cacheCreationInputTokens`

      Tokens used to create prompt cache in this request.

    - `long cacheReadInputTokens`

      Tokens read from prompt cache in this request.

    - `long inputTokens`

      Input tokens consumed by this request.

    - `long outputTokens`

      Output tokens generated by this request.

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SPAN_MODEL_REQUEST_END("span.model_request_end")`

### Beta Managed Agents Span Model Request Start Event

- `class BetaManagedAgentsSpanModelRequestStartEvent:`

  Emitted when a model request is initiated by the agent.

  - `String id`

    Unique identifier for this event.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SPAN_MODEL_REQUEST_START("span.model_request_start")`

### Beta Managed Agents Span Model Usage

- `class BetaManagedAgentsSpanModelUsage:`

  Token usage for a single model request.

  - `long cacheCreationInputTokens`

    Tokens used to create prompt cache in this request.

  - `long cacheReadInputTokens`

    Tokens read from prompt cache in this request.

  - `long inputTokens`

    Input tokens consumed by this request.

  - `long outputTokens`

    Output tokens generated by this request.

  - `Optional<Speed> speed`

    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.

    - `STANDARD("standard")`

    - `FAST("fast")`

### Beta Managed Agents Span Outcome Evaluation End Event

- `class BetaManagedAgentsSpanOutcomeEvaluationEndEvent:`

  Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.

  - `String id`

    Unique identifier for this event.

  - `String explanation`

    Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

  - `long iteration`

    0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

  - `String outcomeEvaluationStartId`

    The id of the corresponding `span.outcome_evaluation_start` event.

  - `String outcomeId`

    The `outc_` ID of the outcome being evaluated.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `String result`

    Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.

  - `Type type`

    - `SPAN_OUTCOME_EVALUATION_END("span.outcome_evaluation_end")`

  - `BetaManagedAgentsSpanModelUsage usage`

    Token usage for a single model request.

    - `long cacheCreationInputTokens`

      Tokens used to create prompt cache in this request.

    - `long cacheReadInputTokens`

      Tokens read from prompt cache in this request.

    - `long inputTokens`

      Input tokens consumed by this request.

    - `long outputTokens`

      Output tokens generated by this request.

    - `Optional<Speed> speed`

      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.

      - `STANDARD("standard")`

      - `FAST("fast")`

### Beta Managed Agents Span Outcome Evaluation Ongoing Event

- `class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent:`

  Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.

  - `String id`

    Unique identifier for this event.

  - `long iteration`

    0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

  - `String outcomeId`

    The `outc_` ID of the outcome being evaluated.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SPAN_OUTCOME_EVALUATION_ONGOING("span.outcome_evaluation_ongoing")`

### Beta Managed Agents Span Outcome Evaluation Start Event

- `class BetaManagedAgentsSpanOutcomeEvaluationStartEvent:`

  Emitted when an outcome evaluation cycle begins.

  - `String id`

    Unique identifier for this event.

  - `long iteration`

    0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

  - `String outcomeId`

    The `outc_` ID of the outcome being evaluated.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SPAN_OUTCOME_EVALUATION_START("span.outcome_evaluation_start")`

### Beta Managed Agents Stream Session Events

- `class BetaManagedAgentsStreamSessionEvents: A class that can be one of several variants.union`

  Server-sent event in the session stream.

  - `class BetaManagedAgentsUserMessageEvent:`

    A user message event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Array of content blocks comprising the user message.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

        - `Source source`

          Union type for image source variants.

          - `class BetaManagedAgentsBase64ImageSource:`

            Base64-encoded image data.

            - `String data`

              Base64-encoded image data.

            - `String mediaType`

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsUrlImageSource:`

            Image referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the image to fetch.

          - `class BetaManagedAgentsFileImageSource:`

            Image referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `IMAGE("image")`

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `Source source`

          Union type for document source variants.

          - `class BetaManagedAgentsBase64DocumentSource:`

            Base64-encoded document data.

            - `String data`

              Base64-encoded document data.

            - `String mediaType`

              MIME type of the document (e.g., "application/pdf").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsPlainTextDocumentSource:`

            Plain text document content.

            - `String data`

              The plain text content.

            - `MediaType mediaType`

              MIME type of the text content. Must be "text/plain".

              - `TEXT_PLAIN("text/plain")`

            - `Type type`

              - `TEXT("text")`

          - `class BetaManagedAgentsUrlDocumentSource:`

            Document referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the document to fetch.

          - `class BetaManagedAgentsFileDocumentSource:`

            Document referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `DOCUMENT("document")`

        - `Optional<String> context`

          Additional context about the document for the model.

        - `Optional<String> title`

          The title of the document.

    - `Type type`

      - `USER_MESSAGE("user.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsUserInterruptEvent:`

    An interrupt event that pauses agent execution and returns control to the user.

    - `String id`

      Unique identifier for this event.

    - `Type type`

      - `USER_INTERRUPT("user.interrupt")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

  - `class BetaManagedAgentsUserToolConfirmationEvent:`

    A tool confirmation event that approves or denies a pending tool execution.

    - `String id`

      Unique identifier for this event.

    - `Result result`

      UserToolConfirmationResult enum

      - `ALLOW("allow")`

      - `DENY("deny")`

    - `String toolUseId`

      The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

    - `Optional<String> denyMessage`

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

  - `class BetaManagedAgentsUserCustomToolResultEvent:`

    Event sent by the client providing the result of a custom tool execution.

    - `String id`

      Unique identifier for this event.

    - `String customToolUseId`

      The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

        - `BetaManagedAgentsSearchResultCitations citations`

          Citation settings for a search result.

          - `boolean enabled`

            Whether citations are enabled for this search result.

        - `List<BetaManagedAgentsSearchResultContent> content`

          Array of text content blocks from the search result.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `String source`

          The URL source of the search result.

        - `String title`

          The title of the search result.

        - `Type type`

          - `SEARCH_RESULT("search_result")`

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsAgentCustomToolUseEvent:`

    Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the custom tool being called.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.

  - `class BetaManagedAgentsAgentMessageEvent:`

    An agent response event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsTextBlock> content`

      Array of text blocks comprising the agent response.

      - `String text`

        The text content.

      - `Type type`

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MESSAGE("agent.message")`

  - `class BetaManagedAgentsAgentThinkingEvent:`

    Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THINKING("agent.thinking")`

  - `class BetaManagedAgentsAgentMcpToolUseEvent:`

    Event emitted when the agent invokes a tool provided by an MCP server.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String mcpServerName`

      Name of the MCP server providing the tool.

    - `String name`

      Name of the MCP tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentMcpToolResultEvent:`

    Event representing the result of an MCP tool execution.

    - `String id`

      Unique identifier for this event.

    - `String mcpToolUseId`

      The id of the `agent.mcp_tool_use` event this result corresponds to.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentToolUseEvent:`

    Event emitted when the agent invokes a built-in agent tool.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the agent tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_TOOL_USE("agent.tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentToolResultEvent:`

    Event representing the result of an agent tool execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to.

    - `Type type`

      - `AGENT_TOOL_RESULT("agent.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentThreadMessageReceivedEvent:`

    Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `String fromSessionThreadId`

      Public `sthr_` ID of the thread that sent the message.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_MESSAGE_RECEIVED("agent.thread_message_received")`

    - `Optional<String> fromAgentName`

      Name of the callable agent this message came from. Absent when received from the primary agent.

  - `class BetaManagedAgentsAgentThreadMessageSentEvent:`

    Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toSessionThreadId`

      Public `sthr_` ID of the thread the message was sent to.

    - `Type type`

      - `AGENT_THREAD_MESSAGE_SENT("agent.thread_message_sent")`

    - `Optional<String> toAgentName`

      Name of the callable agent this message was sent to. Absent when sent to the primary agent.

  - `class BetaManagedAgentsAgentThreadContextCompactedEvent:`

    Indicates that context compaction (summarization) occurred during the session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")`

  - `class BetaManagedAgentsSessionErrorEvent:`

    An error event indicating a problem occurred during session execution.

    - `String id`

      Unique identifier for this event.

    - `Error error`

      An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

      - `class BetaManagedAgentsUnknownError:`

        An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

            - `Type type`

              - `RETRYING("retrying")`

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            - `Type type`

              - `EXHAUSTED("exhausted")`

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

            - `Type type`

              - `TERMINAL("terminal")`

        - `Type type`

          - `UNKNOWN_ERROR("unknown_error")`

      - `class BetaManagedAgentsModelOverloadedError:`

        The model is currently overloaded. Emitted after automatic retries are exhausted.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_OVERLOADED_ERROR("model_overloaded_error")`

      - `class BetaManagedAgentsModelRateLimitedError:`

        The model request was rate-limited.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")`

      - `class BetaManagedAgentsModelRequestFailedError:`

        A model request failed for a reason other than overload or rate-limiting.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")`

      - `class BetaManagedAgentsMcpConnectionFailedError:`

        Failed to connect to an MCP server.

        - `String mcpServerName`

          Name of the MCP server that failed to connect.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")`

      - `class BetaManagedAgentsMcpAuthenticationFailedError:`

        Authentication to an MCP server failed.

        - `String mcpServerName`

          Name of the MCP server that failed authentication.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")`

      - `class BetaManagedAgentsBillingError:`

        The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `BILLING_ERROR("billing_error")`

      - `class BetaManagedAgentsCredentialHostUnreachableError:`

        An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

        - `String credentialId`

          ID of the affected credential.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `CREDENTIAL_HOST_UNREACHABLE_ERROR("credential_host_unreachable_error")`

        - `String vaultId`

          ID of the vault containing the affected credential.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_ERROR("session.error")`

  - `class BetaManagedAgentsSessionStatusRescheduledEvent:`

    Indicates the session is recovering from an error state and is rescheduled for execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

  - `class BetaManagedAgentsSessionStatusRunningEvent:`

    Indicates the session is actively running and the agent is working.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RUNNING("session.status_running")`

  - `class BetaManagedAgentsSessionStatusIdleEvent:`

    Indicates the agent has paused and is awaiting user input.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

        - `Type type`

          - `END_TURN("end_turn")`

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

        - `List<String> eventIds`

          The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

        - `Type type`

          - `REQUIRES_ACTION("requires_action")`

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

        - `Type type`

          - `RETRIES_EXHAUSTED("retries_exhausted")`

    - `Type type`

      - `SESSION_STATUS_IDLE("session.status_idle")`

  - `class BetaManagedAgentsSessionStatusTerminatedEvent:`

    Indicates the session has terminated, either due to an error or completion.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_TERMINATED("session.status_terminated")`

  - `class BetaManagedAgentsSessionThreadCreatedEvent:`

    Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the callable agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public `sthr_` ID of the newly created thread.

    - `Type type`

      - `SESSION_THREAD_CREATED("session.thread_created")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationStartEvent:`

    Emitted when an outcome evaluation cycle begins.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_START("span.outcome_evaluation_start")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationEndEvent:`

    Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.

    - `String id`

      Unique identifier for this event.

    - `String explanation`

      Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeEvaluationStartId`

      The id of the corresponding `span.outcome_evaluation_start` event.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String result`

      Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_END("span.outcome_evaluation_end")`

    - `BetaManagedAgentsSpanModelUsage usage`

      Token usage for a single model request.

      - `long cacheCreationInputTokens`

        Tokens used to create prompt cache in this request.

      - `long cacheReadInputTokens`

        Tokens read from prompt cache in this request.

      - `long inputTokens`

        Input tokens consumed by this request.

      - `long outputTokens`

        Output tokens generated by this request.

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `class BetaManagedAgentsSpanModelRequestStartEvent:`

    Emitted when a model request is initiated by the agent.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_START("span.model_request_start")`

  - `class BetaManagedAgentsSpanModelRequestEndEvent:`

    Emitted when a model request completes.

    - `String id`

      Unique identifier for this event.

    - `Optional<Boolean> isError`

      Whether the model request resulted in an error.

    - `String modelRequestStartId`

      The id of the corresponding `span.model_request_start` event.

    - `BetaManagedAgentsSpanModelUsage modelUsage`

      Token usage for a single model request.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_END("span.model_request_end")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent:`

    Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_ONGOING("span.outcome_evaluation_ongoing")`

  - `class BetaManagedAgentsUserDefineOutcomeEvent:`

    Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

    - `String id`

      Unique identifier for this event.

    - `String description`

      What the agent should produce. Copied from the input event.

    - `Optional<Long> maxIterations`

      Evaluate-then-revise cycles before giving up. Default 3, max 20.

    - `String outcomeId`

      Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Rubric rubric`

      Rubric for grading the quality of an outcome.

      - `class BetaManagedAgentsFileRubric:`

        Rubric referenced by a file uploaded via the Files API.

        - `String fileId`

          ID of the rubric file.

        - `Type type`

          - `FILE("file")`

      - `class BetaManagedAgentsTextRubric:`

        Rubric content provided inline as text.

        - `String content`

          Rubric content. Plain text or markdown — the grader treats it as freeform text.

        - `Type type`

          - `TEXT("text")`

    - `Type type`

      - `USER_DEFINE_OUTCOME("user.define_outcome")`

  - `class BetaManagedAgentsSessionDeletedEvent:`

    Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_DELETED("session.deleted")`

  - `class BetaManagedAgentsSessionThreadStatusRunningEvent:`

    A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that started running.

    - `Type type`

      - `SESSION_THREAD_STATUS_RUNNING("session.thread_status_running")`

  - `class BetaManagedAgentsSessionThreadStatusIdleEvent:`

    A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that went idle.

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

    - `Type type`

      - `SESSION_THREAD_STATUS_IDLE("session.thread_status_idle")`

  - `class BetaManagedAgentsSessionThreadStatusTerminatedEvent:`

    A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that terminated.

    - `Type type`

      - `SESSION_THREAD_STATUS_TERMINATED("session.thread_status_terminated")`

  - `class BetaManagedAgentsUserToolResultEvent:`

    Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

    - `String id`

      Unique identifier for this event.

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_RESULT("user.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsSessionThreadStatusRescheduledEvent:`

    A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that is retrying.

    - `Type type`

      - `SESSION_THREAD_STATUS_RESCHEDULED("session.thread_status_rescheduled")`

  - `class BetaManagedAgentsSessionUpdatedEvent:`

    Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_UPDATED("session.updated")`

    - `Optional<BetaManagedAgentsSessionAgent> agent`

      Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

      - `String id`

      - `Optional<String> description`

      - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

        - `String name`

        - `Type type`

          - `URL("url")`

        - `String url`

      - `BetaManagedAgentsModelConfig model`

        Model identifier and configuration.

        - `BetaManagedAgentsModel id`

          The model that will power your agent.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Most intelligent model for building agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

        - `Optional<Speed> speed`

          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.

          - `STANDARD("standard")`

          - `FAST("fast")`

      - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

        Resolved coordinator topology with full agent definitions for each roster member.

        - `List<BetaManagedAgentsSessionThreadAgent> agents`

          Full `agent` definitions the coordinator may spawn as session threads.

          - `String id`

          - `Optional<String> description`

          - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

            - `String name`

            - `Type type`

            - `String url`

          - `BetaManagedAgentsModelConfig model`

            Model identifier and configuration.

          - `String name`

          - `List<Skill> skills`

            - `class BetaManagedAgentsAnthropicSkill:`

              A resolved Anthropic-managed skill.

              - `String skillId`

              - `Type type`

                - `ANTHROPIC("anthropic")`

              - `String version`

            - `class BetaManagedAgentsCustomSkill:`

              A resolved user-created custom skill.

              - `String skillId`

              - `Type type`

                - `CUSTOM("custom")`

              - `String version`

          - `Optional<String> system`

          - `List<Tool> tools`

            - `class BetaManagedAgentsAgentToolset20260401:`

              - `List<BetaManagedAgentsAgentToolConfig> configs`

                - `boolean enabled`

                - `Name name`

                  Built-in agent tool identifier.

                  - `BASH("bash")`

                  - `EDIT("edit")`

                  - `READ("read")`

                  - `WRITE("write")`

                  - `GLOB("glob")`

                  - `GREP("grep")`

                  - `WEB_FETCH("web_fetch")`

                  - `WEB_SEARCH("web_search")`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                    - `Type type`

                      - `ALWAYS_ALLOW("always_allow")`

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

                    - `Type type`

                      - `ALWAYS_ASK("always_ask")`

              - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

                Resolved default configuration for agent tools.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `Type type`

                - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

            - `class BetaManagedAgentsMcpToolset:`

              - `List<BetaManagedAgentsMcpToolConfig> configs`

                - `boolean enabled`

                - `String name`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

                Resolved default configuration for all tools from an MCP server.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `String mcpServerName`

              - `Type type`

                - `MCP_TOOLSET("mcp_toolset")`

            - `class BetaManagedAgentsCustomTool:`

              A custom tool as returned in API responses.

              - `String description`

              - `BetaManagedAgentsCustomToolInputSchema inputSchema`

                JSON Schema for custom tool input parameters.

                - `JsonValue; type "object"constant`

                  - `OBJECT("object")`

                - `Optional<Properties> properties`

                - `Optional<List<String>> required`

              - `String name`

              - `Type type`

                - `CUSTOM("custom")`

          - `Type type`

            - `AGENT("agent")`

          - `long version`

        - `Type type`

          - `COORDINATOR("coordinator")`

      - `String name`

      - `List<Skill> skills`

        - `class BetaManagedAgentsAnthropicSkill:`

          A resolved Anthropic-managed skill.

        - `class BetaManagedAgentsCustomSkill:`

          A resolved user-created custom skill.

      - `Optional<String> system`

      - `List<Tool> tools`

        - `class BetaManagedAgentsAgentToolset20260401:`

        - `class BetaManagedAgentsMcpToolset:`

        - `class BetaManagedAgentsCustomTool:`

          A custom tool as returned in API responses.

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Optional<Metadata> metadata`

      The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.

    - `Optional<String> title`

      The session's new title. Present only when the update changed it.

  - `class BetaManagedAgentsSystemMessageEvent:`

    A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsSystemContentBlock> content`

      System content blocks. Text-only.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `Type type`

      - `SYSTEM_MESSAGE("system.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

### Beta Managed Agents System Message Event Params

- `class BetaManagedAgentsSystemMessageEventParams:`

  Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages.

  - `List<BetaManagedAgentsSystemContentBlock> content`

    System content blocks to append. Text-only.

    - `String text`

      The text content.

    - `Type type`

      - `TEXT("text")`

  - `Type type`

    - `SYSTEM_MESSAGE("system.message")`

### Beta Managed Agents Text Block

- `class BetaManagedAgentsTextBlock:`

  Regular text content.

  - `String text`

    The text content.

  - `Type type`

    - `TEXT("text")`

### Beta Managed Agents Text Rubric

- `class BetaManagedAgentsTextRubric:`

  Rubric content provided inline as text.

  - `String content`

    Rubric content. Plain text or markdown — the grader treats it as freeform text.

  - `Type type`

    - `TEXT("text")`

### Beta Managed Agents Text Rubric Params

- `class BetaManagedAgentsTextRubricParams:`

  Rubric content provided inline as text.

  - `String content`

    Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

  - `Type type`

    - `TEXT("text")`

### Beta Managed Agents Unknown Error

- `class BetaManagedAgentsUnknownError:`

  An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

  - `String message`

    Human-readable error description.

  - `RetryStatus retryStatus`

    What the client should do next in response to this error.

    - `class BetaManagedAgentsRetryStatusRetrying:`

      The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

      - `Type type`

        - `RETRYING("retrying")`

    - `class BetaManagedAgentsRetryStatusExhausted:`

      This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

      - `Type type`

        - `EXHAUSTED("exhausted")`

    - `class BetaManagedAgentsRetryStatusTerminal:`

      The session encountered a terminal error and will transition to `terminated` state.

      - `Type type`

        - `TERMINAL("terminal")`

  - `Type type`

    - `UNKNOWN_ERROR("unknown_error")`

### Beta Managed Agents URL Document Source

- `class BetaManagedAgentsUrlDocumentSource:`

  Document referenced by URL.

  - `Type type`

    - `URL("url")`

  - `String url`

    URL of the document to fetch.

### Beta Managed Agents URL Image Source

- `class BetaManagedAgentsUrlImageSource:`

  Image referenced by URL.

  - `Type type`

    - `URL("url")`

  - `String url`

    URL of the image to fetch.

### Beta Managed Agents User Custom Tool Result Event

- `class BetaManagedAgentsUserCustomToolResultEvent:`

  Event sent by the client providing the result of a custom tool execution.

  - `String id`

    Unique identifier for this event.

  - `String customToolUseId`

    The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

  - `Type type`

    - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

  - `Optional<List<Content>> content`

    The result content returned by the tool.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

    - `class BetaManagedAgentsSearchResultBlock:`

      A block containing a web search result.

      - `BetaManagedAgentsSearchResultCitations citations`

        Citation settings for a search result.

        - `boolean enabled`

          Whether citations are enabled for this search result.

      - `List<BetaManagedAgentsSearchResultContent> content`

        Array of text content blocks from the search result.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `String source`

        The URL source of the search result.

      - `String title`

        The title of the search result.

      - `Type type`

        - `SEARCH_RESULT("search_result")`

  - `Optional<Boolean> isError`

    Whether the tool execution resulted in an error.

  - `Optional<LocalDateTime> processedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> sessionThreadId`

    Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

### Beta Managed Agents User Custom Tool Result Event Params

- `class BetaManagedAgentsUserCustomToolResultEventParams:`

  Parameters for providing the result of a custom tool execution.

  - `String customToolUseId`

    The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

  - `Type type`

    - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

  - `Optional<List<Content>> content`

    The result content returned by the tool.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

    - `class BetaManagedAgentsSearchResultBlock:`

      A block containing a web search result.

      - `BetaManagedAgentsSearchResultCitations citations`

        Citation settings for a search result.

        - `boolean enabled`

          Whether citations are enabled for this search result.

      - `List<BetaManagedAgentsSearchResultContent> content`

        Array of text content blocks from the search result.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `String source`

        The URL source of the search result.

      - `String title`

        The title of the search result.

      - `Type type`

        - `SEARCH_RESULT("search_result")`

  - `Optional<Boolean> isError`

    Whether the tool execution resulted in an error.

### Beta Managed Agents User Define Outcome Event

- `class BetaManagedAgentsUserDefineOutcomeEvent:`

  Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

  - `String id`

    Unique identifier for this event.

  - `String description`

    What the agent should produce. Copied from the input event.

  - `Optional<Long> maxIterations`

    Evaluate-then-revise cycles before giving up. Default 3, max 20.

  - `String outcomeId`

    Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

  - `LocalDateTime processedAt`

    A timestamp in RFC 3339 format

  - `Rubric rubric`

    Rubric for grading the quality of an outcome.

    - `class BetaManagedAgentsFileRubric:`

      Rubric referenced by a file uploaded via the Files API.

      - `String fileId`

        ID of the rubric file.

      - `Type type`

        - `FILE("file")`

    - `class BetaManagedAgentsTextRubric:`

      Rubric content provided inline as text.

      - `String content`

        Rubric content. Plain text or markdown — the grader treats it as freeform text.

      - `Type type`

        - `TEXT("text")`

  - `Type type`

    - `USER_DEFINE_OUTCOME("user.define_outcome")`

### Beta Managed Agents User Define Outcome Event Params

- `class BetaManagedAgentsUserDefineOutcomeEventParams:`

  Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

  - `String description`

    What the agent should produce. This is the task specification.

  - `Rubric rubric`

    Rubric for grading the quality of an outcome.

    - `class BetaManagedAgentsFileRubricParams:`

      Rubric referenced by a file uploaded via the Files API.

      - `String fileId`

        ID of the rubric file.

      - `Type type`

        - `FILE("file")`

    - `class BetaManagedAgentsTextRubricParams:`

      Rubric content provided inline as text.

      - `String content`

        Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

      - `Type type`

        - `TEXT("text")`

  - `Type type`

    - `USER_DEFINE_OUTCOME("user.define_outcome")`

  - `Optional<Long> maxIterations`

    Eval→revision cycles before giving up. Default 3, max 20.

### Beta Managed Agents User Interrupt Event

- `class BetaManagedAgentsUserInterruptEvent:`

  An interrupt event that pauses agent execution and returns control to the user.

  - `String id`

    Unique identifier for this event.

  - `Type type`

    - `USER_INTERRUPT("user.interrupt")`

  - `Optional<LocalDateTime> processedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> sessionThreadId`

    If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

### Beta Managed Agents User Interrupt Event Params

- `class BetaManagedAgentsUserInterruptEventParams:`

  Parameters for sending an interrupt to pause the agent.

  - `Type type`

    - `USER_INTERRUPT("user.interrupt")`

  - `Optional<String> sessionThreadId`

    If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

### Beta Managed Agents User Message Event

- `class BetaManagedAgentsUserMessageEvent:`

  A user message event in the session conversation.

  - `String id`

    Unique identifier for this event.

  - `List<Content> content`

    Array of content blocks comprising the user message.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

  - `Type type`

    - `USER_MESSAGE("user.message")`

  - `Optional<LocalDateTime> processedAt`

    A timestamp in RFC 3339 format

### Beta Managed Agents User Message Event Params

- `class BetaManagedAgentsUserMessageEventParams:`

  Parameters for sending a user message to the session.

  - `List<Content> content`

    Array of content blocks for the user message.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

  - `Type type`

    - `USER_MESSAGE("user.message")`

### Beta Managed Agents User Tool Confirmation Event

- `class BetaManagedAgentsUserToolConfirmationEvent:`

  A tool confirmation event that approves or denies a pending tool execution.

  - `String id`

    Unique identifier for this event.

  - `Result result`

    UserToolConfirmationResult enum

    - `ALLOW("allow")`

    - `DENY("deny")`

  - `String toolUseId`

    The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

  - `Type type`

    - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

  - `Optional<String> denyMessage`

    Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

  - `Optional<LocalDateTime> processedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> sessionThreadId`

    When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

### Beta Managed Agents User Tool Confirmation Event Params

- `class BetaManagedAgentsUserToolConfirmationEventParams:`

  Parameters for confirming or denying a tool execution request.

  - `Result result`

    UserToolConfirmationResult enum

    - `ALLOW("allow")`

    - `DENY("deny")`

  - `String toolUseId`

    The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

  - `Type type`

    - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

  - `Optional<String> denyMessage`

    Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

### Beta Managed Agents User Tool Result Event Params

- `class BetaManagedAgentsUserToolResultEventParams:`

  Parameters for providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

  - `String toolUseId`

    The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

  - `Type type`

    - `USER_TOOL_RESULT("user.tool_result")`

  - `Optional<List<Content>> content`

    The result content returned by the tool.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

    - `class BetaManagedAgentsSearchResultBlock:`

      A block containing a web search result.

      - `BetaManagedAgentsSearchResultCitations citations`

        Citation settings for a search result.

        - `boolean enabled`

          Whether citations are enabled for this search result.

      - `List<BetaManagedAgentsSearchResultContent> content`

        Array of text content blocks from the search result.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `String source`

        The URL source of the search result.

      - `String title`

        The title of the search result.

      - `Type type`

        - `SEARCH_RESULT("search_result")`

  - `Optional<Boolean> isError`

    Whether the tool execution resulted in an error.

# Resources

## Add Session Resource

`BetaManagedAgentsFileResource beta().sessions().resources().add(ResourceAddParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/sessions/{session_id}/resources`

Add Session Resource

### Parameters

- `ResourceAddParams params`

  - `Optional<String> sessionId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `BetaManagedAgentsFileResourceParams betaManagedAgentsFileResourceParams`

    Mount a file uploaded via the Files API into the session.

### Returns

- `class BetaManagedAgentsFileResource:`

  - `String id`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String fileId`

  - `String mountPath`

  - `Type type`

    - `FILE("file")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.BetaManagedAgentsFileResourceParams;
import com.anthropic.models.beta.sessions.resources.BetaManagedAgentsFileResource;
import com.anthropic.models.beta.sessions.resources.ResourceAddParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        ResourceAddParams params = ResourceAddParams.builder()
            .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7")
            .betaManagedAgentsFileResourceParams(BetaManagedAgentsFileResourceParams.builder()
                .fileId("file_011CNha8iCJcU1wXNR6q4V8w")
                .type(BetaManagedAgentsFileResourceParams.Type.FILE)
                .build())
            .build();
        BetaManagedAgentsFileResource betaManagedAgentsFileResource = client.beta().sessions().resources().add(params);
    }
}
```

#### Response

```json
{
  "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
  "created_at": "2026-03-15T10:00:00Z",
  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "mount_path": "/uploads/receipt.pdf",
  "type": "file",
  "updated_at": "2026-03-15T10:00:00Z"
}
```

## List Session Resources

`ResourceListPage beta().sessions().resources().list(ResourceListParamsparams = ResourceListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/sessions/{session_id}/resources`

List Session Resources

### Parameters

- `ResourceListParams params`

  - `Optional<String> sessionId`

  - `Optional<Long> limit`

    Maximum number of resources to return per page (max 1000). If omitted, returns all resources.

  - `Optional<String> page`

    Opaque cursor from a previous response's next_page field.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsSessionResource: A class that can be one of several variants.union`

  A memory store attached to an agent session.

  - `class BetaManagedAgentsGitHubRepositoryResource:`

    - `String id`

    - `LocalDateTime createdAt`

      A timestamp in RFC 3339 format

    - `String mountPath`

    - `Type type`

      - `GITHUB_REPOSITORY("github_repository")`

    - `LocalDateTime updatedAt`

      A timestamp in RFC 3339 format

    - `String url`

    - `Optional<Checkout> checkout`

      - `class BetaManagedAgentsBranchCheckout:`

        - `String name`

          Branch name to check out.

        - `Type type`

          - `BRANCH("branch")`

      - `class BetaManagedAgentsCommitCheckout:`

        - `String sha`

          Full commit SHA to check out.

        - `Type type`

          - `COMMIT("commit")`

  - `class BetaManagedAgentsFileResource:`

    - `String id`

    - `LocalDateTime createdAt`

      A timestamp in RFC 3339 format

    - `String fileId`

    - `String mountPath`

    - `Type type`

      - `FILE("file")`

    - `LocalDateTime updatedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsMemoryStoreResource:`

    A memory store attached to an agent session.

    - `String memoryStoreId`

      The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

    - `Type type`

      - `MEMORY_STORE("memory_store")`

    - `Optional<Access> access`

      Access mode for an attached memory store.

      - `READ_WRITE("read_write")`

      - `READ_ONLY("read_only")`

    - `Optional<String> description`

      Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

    - `Optional<String> instructions`

      Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

    - `Optional<String> mountPath`

      Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

    - `Optional<String> name`

      Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.resources.ResourceListPage;
import com.anthropic.models.beta.sessions.resources.ResourceListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        ResourceListPage page = client.beta().sessions().resources().list("sesn_011CZkZAtmR3yMPDzynEDxu7");
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
      "created_at": "2026-03-15T10:00:00Z",
      "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
      "mount_path": "/uploads/receipt.pdf",
      "type": "file",
      "updated_at": "2026-03-15T10:00:00Z"
    },
    {
      "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
      "created_at": "2026-03-15T10:00:00Z",
      "mount_path": "/workspace/example-repo",
      "type": "github_repository",
      "updated_at": "2026-03-15T10:00:00Z",
      "url": "https://github.com/example-org/example-repo",
      "checkout": {
        "name": "main",
        "type": "branch"
      }
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```

## Get Session Resource

`ResourceRetrieveResponse beta().sessions().resources().retrieve(ResourceRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/sessions/{session_id}/resources/{resource_id}`

Get Session Resource

### Parameters

- `ResourceRetrieveParams params`

  - `String sessionId`

  - `Optional<String> resourceId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class ResourceRetrieveResponse: A class that can be one of several variants.union`

  The requested session resource.

  - `class BetaManagedAgentsGitHubRepositoryResource:`

    - `String id`

    - `LocalDateTime createdAt`

      A timestamp in RFC 3339 format

    - `String mountPath`

    - `Type type`

      - `GITHUB_REPOSITORY("github_repository")`

    - `LocalDateTime updatedAt`

      A timestamp in RFC 3339 format

    - `String url`

    - `Optional<Checkout> checkout`

      - `class BetaManagedAgentsBranchCheckout:`

        - `String name`

          Branch name to check out.

        - `Type type`

          - `BRANCH("branch")`

      - `class BetaManagedAgentsCommitCheckout:`

        - `String sha`

          Full commit SHA to check out.

        - `Type type`

          - `COMMIT("commit")`

  - `class BetaManagedAgentsFileResource:`

    - `String id`

    - `LocalDateTime createdAt`

      A timestamp in RFC 3339 format

    - `String fileId`

    - `String mountPath`

    - `Type type`

      - `FILE("file")`

    - `LocalDateTime updatedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsMemoryStoreResource:`

    A memory store attached to an agent session.

    - `String memoryStoreId`

      The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

    - `Type type`

      - `MEMORY_STORE("memory_store")`

    - `Optional<Access> access`

      Access mode for an attached memory store.

      - `READ_WRITE("read_write")`

      - `READ_ONLY("read_only")`

    - `Optional<String> description`

      Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

    - `Optional<String> instructions`

      Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

    - `Optional<String> mountPath`

      Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

    - `Optional<String> name`

      Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.resources.ResourceRetrieveParams;
import com.anthropic.models.beta.sessions.resources.ResourceRetrieveResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        ResourceRetrieveParams params = ResourceRetrieveParams.builder()
            .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7")
            .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht")
            .build();
        ResourceRetrieveResponse resource = client.beta().sessions().resources().retrieve(params);
    }
}
```

#### Response

```json
{
  "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
  "created_at": "2026-03-15T10:00:00Z",
  "mount_path": "/workspace/example-repo",
  "type": "github_repository",
  "updated_at": "2026-03-15T10:00:00Z",
  "url": "https://github.com/example-org/example-repo",
  "checkout": {
    "name": "main",
    "type": "branch"
  }
}
```

## Update Session Resource

`ResourceUpdateResponse beta().sessions().resources().update(ResourceUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/sessions/{session_id}/resources/{resource_id}`

Update Session Resource

### Parameters

- `ResourceUpdateParams params`

  - `String sessionId`

  - `Optional<String> resourceId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `String authorizationToken`

    New authorization token for the resource. Currently only `github_repository` resources support token rotation.

### Returns

- `class ResourceUpdateResponse: A class that can be one of several variants.union`

  The updated session resource.

  - `class BetaManagedAgentsGitHubRepositoryResource:`

    - `String id`

    - `LocalDateTime createdAt`

      A timestamp in RFC 3339 format

    - `String mountPath`

    - `Type type`

      - `GITHUB_REPOSITORY("github_repository")`

    - `LocalDateTime updatedAt`

      A timestamp in RFC 3339 format

    - `String url`

    - `Optional<Checkout> checkout`

      - `class BetaManagedAgentsBranchCheckout:`

        - `String name`

          Branch name to check out.

        - `Type type`

          - `BRANCH("branch")`

      - `class BetaManagedAgentsCommitCheckout:`

        - `String sha`

          Full commit SHA to check out.

        - `Type type`

          - `COMMIT("commit")`

  - `class BetaManagedAgentsFileResource:`

    - `String id`

    - `LocalDateTime createdAt`

      A timestamp in RFC 3339 format

    - `String fileId`

    - `String mountPath`

    - `Type type`

      - `FILE("file")`

    - `LocalDateTime updatedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsMemoryStoreResource:`

    A memory store attached to an agent session.

    - `String memoryStoreId`

      The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

    - `Type type`

      - `MEMORY_STORE("memory_store")`

    - `Optional<Access> access`

      Access mode for an attached memory store.

      - `READ_WRITE("read_write")`

      - `READ_ONLY("read_only")`

    - `Optional<String> description`

      Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

    - `Optional<String> instructions`

      Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

    - `Optional<String> mountPath`

      Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

    - `Optional<String> name`

      Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.resources.ResourceUpdateParams;
import com.anthropic.models.beta.sessions.resources.ResourceUpdateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        ResourceUpdateParams params = ResourceUpdateParams.builder()
            .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7")
            .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht")
            .authorizationToken("ghp_exampletoken")
            .build();
        ResourceUpdateResponse resource = client.beta().sessions().resources().update(params);
    }
}
```

#### Response

```json
{
  "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
  "created_at": "2026-03-15T10:00:00Z",
  "mount_path": "/workspace/example-repo",
  "type": "github_repository",
  "updated_at": "2026-03-15T10:00:00Z",
  "url": "https://github.com/example-org/example-repo",
  "checkout": {
    "name": "main",
    "type": "branch"
  }
}
```

## Delete Session Resource

`BetaManagedAgentsDeleteSessionResource beta().sessions().resources().delete(ResourceDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/sessions/{session_id}/resources/{resource_id}`

Delete Session Resource

### Parameters

- `ResourceDeleteParams params`

  - `String sessionId`

  - `Optional<String> resourceId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeleteSessionResource:`

  Confirmation of resource deletion.

  - `String id`

  - `Type type`

    - `SESSION_RESOURCE_DELETED("session_resource_deleted")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.resources.BetaManagedAgentsDeleteSessionResource;
import com.anthropic.models.beta.sessions.resources.ResourceDeleteParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        ResourceDeleteParams params = ResourceDeleteParams.builder()
            .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7")
            .resourceId("sesrsc_011CZkZBJq5dWxk9fVLNcPht")
            .build();
        BetaManagedAgentsDeleteSessionResource betaManagedAgentsDeleteSessionResource = client.beta().sessions().resources().delete(params);
    }
}
```

#### Response

```json
{
  "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
  "type": "session_resource_deleted"
}
```

## Domain Types

### Beta Managed Agents Delete Session Resource

- `class BetaManagedAgentsDeleteSessionResource:`

  Confirmation of resource deletion.

  - `String id`

  - `Type type`

    - `SESSION_RESOURCE_DELETED("session_resource_deleted")`

### Beta Managed Agents File Resource

- `class BetaManagedAgentsFileResource:`

  - `String id`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String fileId`

  - `String mountPath`

  - `Type type`

    - `FILE("file")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

### Beta Managed Agents GitHub Repository Resource

- `class BetaManagedAgentsGitHubRepositoryResource:`

  - `String id`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String mountPath`

  - `Type type`

    - `GITHUB_REPOSITORY("github_repository")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `String url`

  - `Optional<Checkout> checkout`

    - `class BetaManagedAgentsBranchCheckout:`

      - `String name`

        Branch name to check out.

      - `Type type`

        - `BRANCH("branch")`

    - `class BetaManagedAgentsCommitCheckout:`

      - `String sha`

        Full commit SHA to check out.

      - `Type type`

        - `COMMIT("commit")`

### Beta Managed Agents Memory Store Resource

- `class BetaManagedAgentsMemoryStoreResource:`

  A memory store attached to an agent session.

  - `String memoryStoreId`

    The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

  - `Type type`

    - `MEMORY_STORE("memory_store")`

  - `Optional<Access> access`

    Access mode for an attached memory store.

    - `READ_WRITE("read_write")`

    - `READ_ONLY("read_only")`

  - `Optional<String> description`

    Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

  - `Optional<String> instructions`

    Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<String> mountPath`

    Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

  - `Optional<String> name`

    Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

### Beta Managed Agents Session Resource

- `class BetaManagedAgentsSessionResource: A class that can be one of several variants.union`

  A memory store attached to an agent session.

  - `class BetaManagedAgentsGitHubRepositoryResource:`

    - `String id`

    - `LocalDateTime createdAt`

      A timestamp in RFC 3339 format

    - `String mountPath`

    - `Type type`

      - `GITHUB_REPOSITORY("github_repository")`

    - `LocalDateTime updatedAt`

      A timestamp in RFC 3339 format

    - `String url`

    - `Optional<Checkout> checkout`

      - `class BetaManagedAgentsBranchCheckout:`

        - `String name`

          Branch name to check out.

        - `Type type`

          - `BRANCH("branch")`

      - `class BetaManagedAgentsCommitCheckout:`

        - `String sha`

          Full commit SHA to check out.

        - `Type type`

          - `COMMIT("commit")`

  - `class BetaManagedAgentsFileResource:`

    - `String id`

    - `LocalDateTime createdAt`

      A timestamp in RFC 3339 format

    - `String fileId`

    - `String mountPath`

    - `Type type`

      - `FILE("file")`

    - `LocalDateTime updatedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsMemoryStoreResource:`

    A memory store attached to an agent session.

    - `String memoryStoreId`

      The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

    - `Type type`

      - `MEMORY_STORE("memory_store")`

    - `Optional<Access> access`

      Access mode for an attached memory store.

      - `READ_WRITE("read_write")`

      - `READ_ONLY("read_only")`

    - `Optional<String> description`

      Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.

    - `Optional<String> instructions`

      Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

    - `Optional<String> mountPath`

      Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.

    - `Optional<String> name`

      Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

# Threads

## List Session Threads

`ThreadListPage beta().sessions().threads().list(ThreadListParamsparams = ThreadListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/sessions/{session_id}/threads`

List Session Threads

### Parameters

- `ThreadListParams params`

  - `Optional<String> sessionId`

  - `Optional<Long> limit`

    Maximum results per page. Defaults to 1000.

  - `Optional<String> page`

    Opaque pagination cursor from a previous response's next_page. Forward-only.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsSessionThread:`

  An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator.

  - `String id`

    Unique identifier for this thread.

  - `BetaManagedAgentsSessionThreadAgent agent`

    Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

        - `String skillId`

        - `Type type`

          - `ANTHROPIC("anthropic")`

        - `String version`

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

        - `String skillId`

        - `Type type`

          - `CUSTOM("custom")`

        - `String version`

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

        - `List<BetaManagedAgentsAgentToolConfig> configs`

          - `boolean enabled`

          - `Name name`

            Built-in agent tool identifier.

            - `BASH("bash")`

            - `EDIT("edit")`

            - `READ("read")`

            - `WRITE("write")`

            - `GLOB("glob")`

            - `GREP("grep")`

            - `WEB_FETCH("web_fetch")`

            - `WEB_SEARCH("web_search")`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

              - `Type type`

                - `ALWAYS_ALLOW("always_allow")`

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

              - `Type type`

                - `ALWAYS_ASK("always_ask")`

        - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

          Resolved default configuration for agent tools.

          - `boolean enabled`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `Type type`

          - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

      - `class BetaManagedAgentsMcpToolset:`

        - `List<BetaManagedAgentsMcpToolConfig> configs`

          - `boolean enabled`

          - `String name`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

          Resolved default configuration for all tools from an MCP server.

          - `boolean enabled`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `String mcpServerName`

        - `Type type`

          - `MCP_TOOLSET("mcp_toolset")`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

        - `String description`

        - `BetaManagedAgentsCustomToolInputSchema inputSchema`

          JSON Schema for custom tool input parameters.

          - `JsonValue; type "object"constant`

            - `OBJECT("object")`

          - `Optional<Properties> properties`

          - `Optional<List<String>> required`

        - `String name`

        - `Type type`

          - `CUSTOM("custom")`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> parentThreadId`

    Parent thread that spawned this thread. Null for the primary thread.

  - `String sessionId`

    The session this thread belongs to.

  - `Optional<BetaManagedAgentsSessionThreadStats> stats`

    Timing statistics for a session thread.

    - `Optional<Double> activeSeconds`

      Cumulative time in seconds the thread spent actively running. Excludes idle time.

    - `Optional<Double> durationSeconds`

      Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

    - `Optional<Double> startupSeconds`

      Time in seconds for the thread to begin running. Zero for child threads, which start immediately.

  - `BetaManagedAgentsSessionThreadStatus status`

    SessionThreadStatus enum

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `RESCHEDULING("rescheduling")`

    - `TERMINATED("terminated")`

  - `Type type`

    - `SESSION_THREAD("session_thread")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsSessionThreadUsage> usage`

    Cumulative token usage for a session thread across all turns.

    - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

      Prompt-cache creation token usage broken down by cache lifetime.

      - `Optional<Long> ephemeral1hInputTokens`

        Tokens used to create 1-hour ephemeral cache entries.

      - `Optional<Long> ephemeral5mInputTokens`

        Tokens used to create 5-minute ephemeral cache entries.

    - `Optional<Long> cacheReadInputTokens`

      Total tokens read from prompt cache.

    - `Optional<Long> inputTokens`

      Total input tokens consumed across all turns.

    - `Optional<Long> outputTokens`

      Total output tokens generated across all turns.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.threads.ThreadListPage;
import com.anthropic.models.beta.sessions.threads.ThreadListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        ThreadListPage page = client.beta().sessions().threads().list("sesn_011CZkZAtmR3yMPDzynEDxu7");
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "sthr_011CZkZVWa6oIjw0rgXZpnBt",
      "agent": {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "description": "A focused research subagent.",
        "mcp_servers": [
          {
            "name": "example-mcp",
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse"
          }
        ],
        "model": {
          "id": "claude-sonnet-4-6",
          "speed": "standard"
        },
        "name": "Researcher",
        "skills": [
          {
            "skill_id": "xlsx",
            "type": "anthropic",
            "version": "1"
          }
        ],
        "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
        "tools": [
          {
            "configs": [
              {
                "enabled": true,
                "name": "bash",
                "permission_policy": {
                  "type": "always_allow"
                }
              }
            ],
            "default_config": {
              "enabled": true,
              "permission_policy": {
                "type": "always_ask"
              }
            },
            "type": "agent_toolset_20260401"
          }
        ],
        "type": "agent",
        "version": 1
      },
      "archived_at": null,
      "created_at": "2026-03-15T10:00:00Z",
      "parent_thread_id": null,
      "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
      "stats": {
        "active_seconds": 0,
        "duration_seconds": 0,
        "startup_seconds": 0
      },
      "status": "idle",
      "type": "session_thread",
      "updated_at": "2026-03-15T10:00:00Z",
      "usage": {
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 0
        },
        "cache_read_input_tokens": 0,
        "input_tokens": 0,
        "output_tokens": 0
      }
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```

## Get Session Thread

`BetaManagedAgentsSessionThread beta().sessions().threads().retrieve(ThreadRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/sessions/{session_id}/threads/{thread_id}`

Get Session Thread

### Parameters

- `ThreadRetrieveParams params`

  - `String sessionId`

  - `Optional<String> threadId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsSessionThread:`

  An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator.

  - `String id`

    Unique identifier for this thread.

  - `BetaManagedAgentsSessionThreadAgent agent`

    Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

        - `String skillId`

        - `Type type`

          - `ANTHROPIC("anthropic")`

        - `String version`

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

        - `String skillId`

        - `Type type`

          - `CUSTOM("custom")`

        - `String version`

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

        - `List<BetaManagedAgentsAgentToolConfig> configs`

          - `boolean enabled`

          - `Name name`

            Built-in agent tool identifier.

            - `BASH("bash")`

            - `EDIT("edit")`

            - `READ("read")`

            - `WRITE("write")`

            - `GLOB("glob")`

            - `GREP("grep")`

            - `WEB_FETCH("web_fetch")`

            - `WEB_SEARCH("web_search")`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

              - `Type type`

                - `ALWAYS_ALLOW("always_allow")`

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

              - `Type type`

                - `ALWAYS_ASK("always_ask")`

        - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

          Resolved default configuration for agent tools.

          - `boolean enabled`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `Type type`

          - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

      - `class BetaManagedAgentsMcpToolset:`

        - `List<BetaManagedAgentsMcpToolConfig> configs`

          - `boolean enabled`

          - `String name`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

          Resolved default configuration for all tools from an MCP server.

          - `boolean enabled`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `String mcpServerName`

        - `Type type`

          - `MCP_TOOLSET("mcp_toolset")`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

        - `String description`

        - `BetaManagedAgentsCustomToolInputSchema inputSchema`

          JSON Schema for custom tool input parameters.

          - `JsonValue; type "object"constant`

            - `OBJECT("object")`

          - `Optional<Properties> properties`

          - `Optional<List<String>> required`

        - `String name`

        - `Type type`

          - `CUSTOM("custom")`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> parentThreadId`

    Parent thread that spawned this thread. Null for the primary thread.

  - `String sessionId`

    The session this thread belongs to.

  - `Optional<BetaManagedAgentsSessionThreadStats> stats`

    Timing statistics for a session thread.

    - `Optional<Double> activeSeconds`

      Cumulative time in seconds the thread spent actively running. Excludes idle time.

    - `Optional<Double> durationSeconds`

      Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

    - `Optional<Double> startupSeconds`

      Time in seconds for the thread to begin running. Zero for child threads, which start immediately.

  - `BetaManagedAgentsSessionThreadStatus status`

    SessionThreadStatus enum

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `RESCHEDULING("rescheduling")`

    - `TERMINATED("terminated")`

  - `Type type`

    - `SESSION_THREAD("session_thread")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsSessionThreadUsage> usage`

    Cumulative token usage for a session thread across all turns.

    - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

      Prompt-cache creation token usage broken down by cache lifetime.

      - `Optional<Long> ephemeral1hInputTokens`

        Tokens used to create 1-hour ephemeral cache entries.

      - `Optional<Long> ephemeral5mInputTokens`

        Tokens used to create 5-minute ephemeral cache entries.

    - `Optional<Long> cacheReadInputTokens`

      Total tokens read from prompt cache.

    - `Optional<Long> inputTokens`

      Total input tokens consumed across all turns.

    - `Optional<Long> outputTokens`

      Total output tokens generated across all turns.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.threads.BetaManagedAgentsSessionThread;
import com.anthropic.models.beta.sessions.threads.ThreadRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        ThreadRetrieveParams params = ThreadRetrieveParams.builder()
            .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7")
            .threadId("sthr_011CZkZVWa6oIjw0rgXZpnBt")
            .build();
        BetaManagedAgentsSessionThread betaManagedAgentsSessionThread = client.beta().sessions().threads().retrieve(params);
    }
}
```

#### Response

```json
{
  "id": "sthr_011CZkZVWa6oIjw0rgXZpnBt",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "description": "A focused research subagent.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-sonnet-4-6",
      "speed": "standard"
    },
    "name": "Researcher",
    "skills": [
      {
        "skill_id": "xlsx",
        "type": "anthropic",
        "version": "1"
      }
    ],
    "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            }
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "parent_thread_id": null,
  "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0,
    "startup_seconds": 0
  },
  "status": "idle",
  "type": "session_thread",
  "updated_at": "2026-03-15T10:00:00Z",
  "usage": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  }
}
```

## Archive Session Thread

`BetaManagedAgentsSessionThread beta().sessions().threads().archive(ThreadArchiveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/sessions/{session_id}/threads/{thread_id}/archive`

Archive Session Thread

### Parameters

- `ThreadArchiveParams params`

  - `String sessionId`

  - `Optional<String> threadId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsSessionThread:`

  An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator.

  - `String id`

    Unique identifier for this thread.

  - `BetaManagedAgentsSessionThreadAgent agent`

    Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

        - `String skillId`

        - `Type type`

          - `ANTHROPIC("anthropic")`

        - `String version`

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

        - `String skillId`

        - `Type type`

          - `CUSTOM("custom")`

        - `String version`

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

        - `List<BetaManagedAgentsAgentToolConfig> configs`

          - `boolean enabled`

          - `Name name`

            Built-in agent tool identifier.

            - `BASH("bash")`

            - `EDIT("edit")`

            - `READ("read")`

            - `WRITE("write")`

            - `GLOB("glob")`

            - `GREP("grep")`

            - `WEB_FETCH("web_fetch")`

            - `WEB_SEARCH("web_search")`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

              - `Type type`

                - `ALWAYS_ALLOW("always_allow")`

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

              - `Type type`

                - `ALWAYS_ASK("always_ask")`

        - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

          Resolved default configuration for agent tools.

          - `boolean enabled`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `Type type`

          - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

      - `class BetaManagedAgentsMcpToolset:`

        - `List<BetaManagedAgentsMcpToolConfig> configs`

          - `boolean enabled`

          - `String name`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

          Resolved default configuration for all tools from an MCP server.

          - `boolean enabled`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `String mcpServerName`

        - `Type type`

          - `MCP_TOOLSET("mcp_toolset")`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

        - `String description`

        - `BetaManagedAgentsCustomToolInputSchema inputSchema`

          JSON Schema for custom tool input parameters.

          - `JsonValue; type "object"constant`

            - `OBJECT("object")`

          - `Optional<Properties> properties`

          - `Optional<List<String>> required`

        - `String name`

        - `Type type`

          - `CUSTOM("custom")`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> parentThreadId`

    Parent thread that spawned this thread. Null for the primary thread.

  - `String sessionId`

    The session this thread belongs to.

  - `Optional<BetaManagedAgentsSessionThreadStats> stats`

    Timing statistics for a session thread.

    - `Optional<Double> activeSeconds`

      Cumulative time in seconds the thread spent actively running. Excludes idle time.

    - `Optional<Double> durationSeconds`

      Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

    - `Optional<Double> startupSeconds`

      Time in seconds for the thread to begin running. Zero for child threads, which start immediately.

  - `BetaManagedAgentsSessionThreadStatus status`

    SessionThreadStatus enum

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `RESCHEDULING("rescheduling")`

    - `TERMINATED("terminated")`

  - `Type type`

    - `SESSION_THREAD("session_thread")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsSessionThreadUsage> usage`

    Cumulative token usage for a session thread across all turns.

    - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

      Prompt-cache creation token usage broken down by cache lifetime.

      - `Optional<Long> ephemeral1hInputTokens`

        Tokens used to create 1-hour ephemeral cache entries.

      - `Optional<Long> ephemeral5mInputTokens`

        Tokens used to create 5-minute ephemeral cache entries.

    - `Optional<Long> cacheReadInputTokens`

      Total tokens read from prompt cache.

    - `Optional<Long> inputTokens`

      Total input tokens consumed across all turns.

    - `Optional<Long> outputTokens`

      Total output tokens generated across all turns.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.threads.BetaManagedAgentsSessionThread;
import com.anthropic.models.beta.sessions.threads.ThreadArchiveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        ThreadArchiveParams params = ThreadArchiveParams.builder()
            .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7")
            .threadId("sthr_011CZkZVWa6oIjw0rgXZpnBt")
            .build();
        BetaManagedAgentsSessionThread betaManagedAgentsSessionThread = client.beta().sessions().threads().archive(params);
    }
}
```

#### Response

```json
{
  "id": "sthr_011CZkZVWa6oIjw0rgXZpnBt",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "description": "A focused research subagent.",
    "mcp_servers": [
      {
        "name": "example-mcp",
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "model": {
      "id": "claude-sonnet-4-6",
      "speed": "standard"
    },
    "name": "Researcher",
    "skills": [
      {
        "skill_id": "xlsx",
        "type": "anthropic",
        "version": "1"
      }
    ],
    "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.",
    "tools": [
      {
        "configs": [
          {
            "enabled": true,
            "name": "bash",
            "permission_policy": {
              "type": "always_allow"
            }
          }
        ],
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "type": "agent_toolset_20260401"
      }
    ],
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "parent_thread_id": null,
  "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0,
    "startup_seconds": 0
  },
  "status": "idle",
  "type": "session_thread",
  "updated_at": "2026-03-15T10:00:00Z",
  "usage": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  }
}
```

## Domain Types

### Beta Managed Agents Session Thread

- `class BetaManagedAgentsSessionThread:`

  An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator.

  - `String id`

    Unique identifier for this thread.

  - `BetaManagedAgentsSessionThreadAgent agent`

    Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.

    - `String id`

    - `Optional<String> description`

    - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

      - `String name`

      - `Type type`

        - `URL("url")`

      - `String url`

    - `BetaManagedAgentsModelConfig model`

      Model identifier and configuration.

      - `BetaManagedAgentsModel id`

        The model that will power your agent.

        See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

        - `CLAUDE_FABLE_5("claude-fable-5")`

          Next generation of intelligence for the hardest knowledge work and coding problems

        - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

          Frontier intelligence for long-running agents and coding

        - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

          Most intelligent model for building agents and coding

        - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

          Best combination of speed and intelligence

        - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

          Fastest model with near-frontier intelligence

        - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

          Premium model combining maximum intelligence with practical performance

        - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

          High-performance model for agents and coding

        - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

          High-performance model for agents and coding

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

    - `String name`

    - `List<Skill> skills`

      - `class BetaManagedAgentsAnthropicSkill:`

        A resolved Anthropic-managed skill.

        - `String skillId`

        - `Type type`

          - `ANTHROPIC("anthropic")`

        - `String version`

      - `class BetaManagedAgentsCustomSkill:`

        A resolved user-created custom skill.

        - `String skillId`

        - `Type type`

          - `CUSTOM("custom")`

        - `String version`

    - `Optional<String> system`

    - `List<Tool> tools`

      - `class BetaManagedAgentsAgentToolset20260401:`

        - `List<BetaManagedAgentsAgentToolConfig> configs`

          - `boolean enabled`

          - `Name name`

            Built-in agent tool identifier.

            - `BASH("bash")`

            - `EDIT("edit")`

            - `READ("read")`

            - `WRITE("write")`

            - `GLOB("glob")`

            - `GREP("grep")`

            - `WEB_FETCH("web_fetch")`

            - `WEB_SEARCH("web_search")`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

              - `Type type`

                - `ALWAYS_ALLOW("always_allow")`

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

              - `Type type`

                - `ALWAYS_ASK("always_ask")`

        - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

          Resolved default configuration for agent tools.

          - `boolean enabled`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `Type type`

          - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

      - `class BetaManagedAgentsMcpToolset:`

        - `List<BetaManagedAgentsMcpToolConfig> configs`

          - `boolean enabled`

          - `String name`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

          Resolved default configuration for all tools from an MCP server.

          - `boolean enabled`

          - `PermissionPolicy permissionPolicy`

            Permission policy for tool execution.

            - `class BetaManagedAgentsAlwaysAllowPolicy:`

              Tool calls are automatically approved without user confirmation.

            - `class BetaManagedAgentsAlwaysAskPolicy:`

              Tool calls require user confirmation before execution.

        - `String mcpServerName`

        - `Type type`

          - `MCP_TOOLSET("mcp_toolset")`

      - `class BetaManagedAgentsCustomTool:`

        A custom tool as returned in API responses.

        - `String description`

        - `BetaManagedAgentsCustomToolInputSchema inputSchema`

          JSON Schema for custom tool input parameters.

          - `JsonValue; type "object"constant`

            - `OBJECT("object")`

          - `Optional<Properties> properties`

          - `Optional<List<String>> required`

        - `String name`

        - `Type type`

          - `CUSTOM("custom")`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> parentThreadId`

    Parent thread that spawned this thread. Null for the primary thread.

  - `String sessionId`

    The session this thread belongs to.

  - `Optional<BetaManagedAgentsSessionThreadStats> stats`

    Timing statistics for a session thread.

    - `Optional<Double> activeSeconds`

      Cumulative time in seconds the thread spent actively running. Excludes idle time.

    - `Optional<Double> durationSeconds`

      Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

    - `Optional<Double> startupSeconds`

      Time in seconds for the thread to begin running. Zero for child threads, which start immediately.

  - `BetaManagedAgentsSessionThreadStatus status`

    SessionThreadStatus enum

    - `RUNNING("running")`

    - `IDLE("idle")`

    - `RESCHEDULING("rescheduling")`

    - `TERMINATED("terminated")`

  - `Type type`

    - `SESSION_THREAD("session_thread")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsSessionThreadUsage> usage`

    Cumulative token usage for a session thread across all turns.

    - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

      Prompt-cache creation token usage broken down by cache lifetime.

      - `Optional<Long> ephemeral1hInputTokens`

        Tokens used to create 1-hour ephemeral cache entries.

      - `Optional<Long> ephemeral5mInputTokens`

        Tokens used to create 5-minute ephemeral cache entries.

    - `Optional<Long> cacheReadInputTokens`

      Total tokens read from prompt cache.

    - `Optional<Long> inputTokens`

      Total input tokens consumed across all turns.

    - `Optional<Long> outputTokens`

      Total output tokens generated across all turns.

### Beta Managed Agents Session Thread Stats

- `class BetaManagedAgentsSessionThreadStats:`

  Timing statistics for a session thread.

  - `Optional<Double> activeSeconds`

    Cumulative time in seconds the thread spent actively running. Excludes idle time.

  - `Optional<Double> durationSeconds`

    Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

  - `Optional<Double> startupSeconds`

    Time in seconds for the thread to begin running. Zero for child threads, which start immediately.

### Beta Managed Agents Session Thread Status

- `enum BetaManagedAgentsSessionThreadStatus:`

  SessionThreadStatus enum

  - `RUNNING("running")`

  - `IDLE("idle")`

  - `RESCHEDULING("rescheduling")`

  - `TERMINATED("terminated")`

### Beta Managed Agents Session Thread Usage

- `class BetaManagedAgentsSessionThreadUsage:`

  Cumulative token usage for a session thread across all turns.

  - `Optional<BetaManagedAgentsCacheCreationUsage> cacheCreation`

    Prompt-cache creation token usage broken down by cache lifetime.

    - `Optional<Long> ephemeral1hInputTokens`

      Tokens used to create 1-hour ephemeral cache entries.

    - `Optional<Long> ephemeral5mInputTokens`

      Tokens used to create 5-minute ephemeral cache entries.

  - `Optional<Long> cacheReadInputTokens`

    Total tokens read from prompt cache.

  - `Optional<Long> inputTokens`

    Total input tokens consumed across all turns.

  - `Optional<Long> outputTokens`

    Total output tokens generated across all turns.

### Beta Managed Agents Stream Session Thread Events

- `class BetaManagedAgentsStreamSessionThreadEvents: A class that can be one of several variants.union`

  Server-sent event in a single thread's stream.

  - `class BetaManagedAgentsUserMessageEvent:`

    A user message event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Array of content blocks comprising the user message.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

        - `Source source`

          Union type for image source variants.

          - `class BetaManagedAgentsBase64ImageSource:`

            Base64-encoded image data.

            - `String data`

              Base64-encoded image data.

            - `String mediaType`

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsUrlImageSource:`

            Image referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the image to fetch.

          - `class BetaManagedAgentsFileImageSource:`

            Image referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `IMAGE("image")`

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `Source source`

          Union type for document source variants.

          - `class BetaManagedAgentsBase64DocumentSource:`

            Base64-encoded document data.

            - `String data`

              Base64-encoded document data.

            - `String mediaType`

              MIME type of the document (e.g., "application/pdf").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsPlainTextDocumentSource:`

            Plain text document content.

            - `String data`

              The plain text content.

            - `MediaType mediaType`

              MIME type of the text content. Must be "text/plain".

              - `TEXT_PLAIN("text/plain")`

            - `Type type`

              - `TEXT("text")`

          - `class BetaManagedAgentsUrlDocumentSource:`

            Document referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the document to fetch.

          - `class BetaManagedAgentsFileDocumentSource:`

            Document referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `DOCUMENT("document")`

        - `Optional<String> context`

          Additional context about the document for the model.

        - `Optional<String> title`

          The title of the document.

    - `Type type`

      - `USER_MESSAGE("user.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsUserInterruptEvent:`

    An interrupt event that pauses agent execution and returns control to the user.

    - `String id`

      Unique identifier for this event.

    - `Type type`

      - `USER_INTERRUPT("user.interrupt")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

  - `class BetaManagedAgentsUserToolConfirmationEvent:`

    A tool confirmation event that approves or denies a pending tool execution.

    - `String id`

      Unique identifier for this event.

    - `Result result`

      UserToolConfirmationResult enum

      - `ALLOW("allow")`

      - `DENY("deny")`

    - `String toolUseId`

      The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

    - `Optional<String> denyMessage`

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

  - `class BetaManagedAgentsUserCustomToolResultEvent:`

    Event sent by the client providing the result of a custom tool execution.

    - `String id`

      Unique identifier for this event.

    - `String customToolUseId`

      The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

        - `BetaManagedAgentsSearchResultCitations citations`

          Citation settings for a search result.

          - `boolean enabled`

            Whether citations are enabled for this search result.

        - `List<BetaManagedAgentsSearchResultContent> content`

          Array of text content blocks from the search result.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `String source`

          The URL source of the search result.

        - `String title`

          The title of the search result.

        - `Type type`

          - `SEARCH_RESULT("search_result")`

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsAgentCustomToolUseEvent:`

    Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the custom tool being called.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.

  - `class BetaManagedAgentsAgentMessageEvent:`

    An agent response event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsTextBlock> content`

      Array of text blocks comprising the agent response.

      - `String text`

        The text content.

      - `Type type`

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MESSAGE("agent.message")`

  - `class BetaManagedAgentsAgentThinkingEvent:`

    Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THINKING("agent.thinking")`

  - `class BetaManagedAgentsAgentMcpToolUseEvent:`

    Event emitted when the agent invokes a tool provided by an MCP server.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String mcpServerName`

      Name of the MCP server providing the tool.

    - `String name`

      Name of the MCP tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentMcpToolResultEvent:`

    Event representing the result of an MCP tool execution.

    - `String id`

      Unique identifier for this event.

    - `String mcpToolUseId`

      The id of the `agent.mcp_tool_use` event this result corresponds to.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentToolUseEvent:`

    Event emitted when the agent invokes a built-in agent tool.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the agent tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_TOOL_USE("agent.tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentToolResultEvent:`

    Event representing the result of an agent tool execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to.

    - `Type type`

      - `AGENT_TOOL_RESULT("agent.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentThreadMessageReceivedEvent:`

    Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `String fromSessionThreadId`

      Public `sthr_` ID of the thread that sent the message.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_MESSAGE_RECEIVED("agent.thread_message_received")`

    - `Optional<String> fromAgentName`

      Name of the callable agent this message came from. Absent when received from the primary agent.

  - `class BetaManagedAgentsAgentThreadMessageSentEvent:`

    Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toSessionThreadId`

      Public `sthr_` ID of the thread the message was sent to.

    - `Type type`

      - `AGENT_THREAD_MESSAGE_SENT("agent.thread_message_sent")`

    - `Optional<String> toAgentName`

      Name of the callable agent this message was sent to. Absent when sent to the primary agent.

  - `class BetaManagedAgentsAgentThreadContextCompactedEvent:`

    Indicates that context compaction (summarization) occurred during the session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")`

  - `class BetaManagedAgentsSessionErrorEvent:`

    An error event indicating a problem occurred during session execution.

    - `String id`

      Unique identifier for this event.

    - `Error error`

      An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

      - `class BetaManagedAgentsUnknownError:`

        An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

            - `Type type`

              - `RETRYING("retrying")`

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            - `Type type`

              - `EXHAUSTED("exhausted")`

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

            - `Type type`

              - `TERMINAL("terminal")`

        - `Type type`

          - `UNKNOWN_ERROR("unknown_error")`

      - `class BetaManagedAgentsModelOverloadedError:`

        The model is currently overloaded. Emitted after automatic retries are exhausted.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_OVERLOADED_ERROR("model_overloaded_error")`

      - `class BetaManagedAgentsModelRateLimitedError:`

        The model request was rate-limited.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")`

      - `class BetaManagedAgentsModelRequestFailedError:`

        A model request failed for a reason other than overload or rate-limiting.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")`

      - `class BetaManagedAgentsMcpConnectionFailedError:`

        Failed to connect to an MCP server.

        - `String mcpServerName`

          Name of the MCP server that failed to connect.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")`

      - `class BetaManagedAgentsMcpAuthenticationFailedError:`

        Authentication to an MCP server failed.

        - `String mcpServerName`

          Name of the MCP server that failed authentication.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")`

      - `class BetaManagedAgentsBillingError:`

        The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `BILLING_ERROR("billing_error")`

      - `class BetaManagedAgentsCredentialHostUnreachableError:`

        An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

        - `String credentialId`

          ID of the affected credential.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `CREDENTIAL_HOST_UNREACHABLE_ERROR("credential_host_unreachable_error")`

        - `String vaultId`

          ID of the vault containing the affected credential.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_ERROR("session.error")`

  - `class BetaManagedAgentsSessionStatusRescheduledEvent:`

    Indicates the session is recovering from an error state and is rescheduled for execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

  - `class BetaManagedAgentsSessionStatusRunningEvent:`

    Indicates the session is actively running and the agent is working.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RUNNING("session.status_running")`

  - `class BetaManagedAgentsSessionStatusIdleEvent:`

    Indicates the agent has paused and is awaiting user input.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

        - `Type type`

          - `END_TURN("end_turn")`

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

        - `List<String> eventIds`

          The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

        - `Type type`

          - `REQUIRES_ACTION("requires_action")`

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

        - `Type type`

          - `RETRIES_EXHAUSTED("retries_exhausted")`

    - `Type type`

      - `SESSION_STATUS_IDLE("session.status_idle")`

  - `class BetaManagedAgentsSessionStatusTerminatedEvent:`

    Indicates the session has terminated, either due to an error or completion.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_TERMINATED("session.status_terminated")`

  - `class BetaManagedAgentsSessionThreadCreatedEvent:`

    Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the callable agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public `sthr_` ID of the newly created thread.

    - `Type type`

      - `SESSION_THREAD_CREATED("session.thread_created")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationStartEvent:`

    Emitted when an outcome evaluation cycle begins.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_START("span.outcome_evaluation_start")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationEndEvent:`

    Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.

    - `String id`

      Unique identifier for this event.

    - `String explanation`

      Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeEvaluationStartId`

      The id of the corresponding `span.outcome_evaluation_start` event.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String result`

      Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_END("span.outcome_evaluation_end")`

    - `BetaManagedAgentsSpanModelUsage usage`

      Token usage for a single model request.

      - `long cacheCreationInputTokens`

        Tokens used to create prompt cache in this request.

      - `long cacheReadInputTokens`

        Tokens read from prompt cache in this request.

      - `long inputTokens`

        Input tokens consumed by this request.

      - `long outputTokens`

        Output tokens generated by this request.

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `class BetaManagedAgentsSpanModelRequestStartEvent:`

    Emitted when a model request is initiated by the agent.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_START("span.model_request_start")`

  - `class BetaManagedAgentsSpanModelRequestEndEvent:`

    Emitted when a model request completes.

    - `String id`

      Unique identifier for this event.

    - `Optional<Boolean> isError`

      Whether the model request resulted in an error.

    - `String modelRequestStartId`

      The id of the corresponding `span.model_request_start` event.

    - `BetaManagedAgentsSpanModelUsage modelUsage`

      Token usage for a single model request.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_END("span.model_request_end")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent:`

    Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_ONGOING("span.outcome_evaluation_ongoing")`

  - `class BetaManagedAgentsUserDefineOutcomeEvent:`

    Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

    - `String id`

      Unique identifier for this event.

    - `String description`

      What the agent should produce. Copied from the input event.

    - `Optional<Long> maxIterations`

      Evaluate-then-revise cycles before giving up. Default 3, max 20.

    - `String outcomeId`

      Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Rubric rubric`

      Rubric for grading the quality of an outcome.

      - `class BetaManagedAgentsFileRubric:`

        Rubric referenced by a file uploaded via the Files API.

        - `String fileId`

          ID of the rubric file.

        - `Type type`

          - `FILE("file")`

      - `class BetaManagedAgentsTextRubric:`

        Rubric content provided inline as text.

        - `String content`

          Rubric content. Plain text or markdown — the grader treats it as freeform text.

        - `Type type`

          - `TEXT("text")`

    - `Type type`

      - `USER_DEFINE_OUTCOME("user.define_outcome")`

  - `class BetaManagedAgentsSessionDeletedEvent:`

    Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_DELETED("session.deleted")`

  - `class BetaManagedAgentsSessionThreadStatusRunningEvent:`

    A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that started running.

    - `Type type`

      - `SESSION_THREAD_STATUS_RUNNING("session.thread_status_running")`

  - `class BetaManagedAgentsSessionThreadStatusIdleEvent:`

    A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that went idle.

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

    - `Type type`

      - `SESSION_THREAD_STATUS_IDLE("session.thread_status_idle")`

  - `class BetaManagedAgentsSessionThreadStatusTerminatedEvent:`

    A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that terminated.

    - `Type type`

      - `SESSION_THREAD_STATUS_TERMINATED("session.thread_status_terminated")`

  - `class BetaManagedAgentsUserToolResultEvent:`

    Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

    - `String id`

      Unique identifier for this event.

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_RESULT("user.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsSessionThreadStatusRescheduledEvent:`

    A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that is retrying.

    - `Type type`

      - `SESSION_THREAD_STATUS_RESCHEDULED("session.thread_status_rescheduled")`

  - `class BetaManagedAgentsSessionUpdatedEvent:`

    Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_UPDATED("session.updated")`

    - `Optional<BetaManagedAgentsSessionAgent> agent`

      Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

      - `String id`

      - `Optional<String> description`

      - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

        - `String name`

        - `Type type`

          - `URL("url")`

        - `String url`

      - `BetaManagedAgentsModelConfig model`

        Model identifier and configuration.

        - `BetaManagedAgentsModel id`

          The model that will power your agent.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Most intelligent model for building agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

        - `Optional<Speed> speed`

          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.

          - `STANDARD("standard")`

          - `FAST("fast")`

      - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

        Resolved coordinator topology with full agent definitions for each roster member.

        - `List<BetaManagedAgentsSessionThreadAgent> agents`

          Full `agent` definitions the coordinator may spawn as session threads.

          - `String id`

          - `Optional<String> description`

          - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

            - `String name`

            - `Type type`

            - `String url`

          - `BetaManagedAgentsModelConfig model`

            Model identifier and configuration.

          - `String name`

          - `List<Skill> skills`

            - `class BetaManagedAgentsAnthropicSkill:`

              A resolved Anthropic-managed skill.

              - `String skillId`

              - `Type type`

                - `ANTHROPIC("anthropic")`

              - `String version`

            - `class BetaManagedAgentsCustomSkill:`

              A resolved user-created custom skill.

              - `String skillId`

              - `Type type`

                - `CUSTOM("custom")`

              - `String version`

          - `Optional<String> system`

          - `List<Tool> tools`

            - `class BetaManagedAgentsAgentToolset20260401:`

              - `List<BetaManagedAgentsAgentToolConfig> configs`

                - `boolean enabled`

                - `Name name`

                  Built-in agent tool identifier.

                  - `BASH("bash")`

                  - `EDIT("edit")`

                  - `READ("read")`

                  - `WRITE("write")`

                  - `GLOB("glob")`

                  - `GREP("grep")`

                  - `WEB_FETCH("web_fetch")`

                  - `WEB_SEARCH("web_search")`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                    - `Type type`

                      - `ALWAYS_ALLOW("always_allow")`

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

                    - `Type type`

                      - `ALWAYS_ASK("always_ask")`

              - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

                Resolved default configuration for agent tools.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `Type type`

                - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

            - `class BetaManagedAgentsMcpToolset:`

              - `List<BetaManagedAgentsMcpToolConfig> configs`

                - `boolean enabled`

                - `String name`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

                Resolved default configuration for all tools from an MCP server.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `String mcpServerName`

              - `Type type`

                - `MCP_TOOLSET("mcp_toolset")`

            - `class BetaManagedAgentsCustomTool:`

              A custom tool as returned in API responses.

              - `String description`

              - `BetaManagedAgentsCustomToolInputSchema inputSchema`

                JSON Schema for custom tool input parameters.

                - `JsonValue; type "object"constant`

                  - `OBJECT("object")`

                - `Optional<Properties> properties`

                - `Optional<List<String>> required`

              - `String name`

              - `Type type`

                - `CUSTOM("custom")`

          - `Type type`

            - `AGENT("agent")`

          - `long version`

        - `Type type`

          - `COORDINATOR("coordinator")`

      - `String name`

      - `List<Skill> skills`

        - `class BetaManagedAgentsAnthropicSkill:`

          A resolved Anthropic-managed skill.

        - `class BetaManagedAgentsCustomSkill:`

          A resolved user-created custom skill.

      - `Optional<String> system`

      - `List<Tool> tools`

        - `class BetaManagedAgentsAgentToolset20260401:`

        - `class BetaManagedAgentsMcpToolset:`

        - `class BetaManagedAgentsCustomTool:`

          A custom tool as returned in API responses.

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Optional<Metadata> metadata`

      The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.

    - `Optional<String> title`

      The session's new title. Present only when the update changed it.

  - `class BetaManagedAgentsSystemMessageEvent:`

    A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsSystemContentBlock> content`

      System content blocks. Text-only.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `Type type`

      - `SYSTEM_MESSAGE("system.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

# Events

## List Session Thread Events

`EventListPage beta().sessions().threads().events().list(EventListParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/sessions/{session_id}/threads/{thread_id}/events`

List Session Thread Events

### Parameters

- `EventListParams params`

  - `String sessionId`

  - `Optional<String> threadId`

  - `Optional<Long> limit`

    Query parameter for limit

  - `Optional<String> page`

    Query parameter for page

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsSessionEvent: A class that can be one of several variants.union`

  Union type for all event types in a session.

  - `class BetaManagedAgentsUserMessageEvent:`

    A user message event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Array of content blocks comprising the user message.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

        - `Source source`

          Union type for image source variants.

          - `class BetaManagedAgentsBase64ImageSource:`

            Base64-encoded image data.

            - `String data`

              Base64-encoded image data.

            - `String mediaType`

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsUrlImageSource:`

            Image referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the image to fetch.

          - `class BetaManagedAgentsFileImageSource:`

            Image referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `IMAGE("image")`

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `Source source`

          Union type for document source variants.

          - `class BetaManagedAgentsBase64DocumentSource:`

            Base64-encoded document data.

            - `String data`

              Base64-encoded document data.

            - `String mediaType`

              MIME type of the document (e.g., "application/pdf").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsPlainTextDocumentSource:`

            Plain text document content.

            - `String data`

              The plain text content.

            - `MediaType mediaType`

              MIME type of the text content. Must be "text/plain".

              - `TEXT_PLAIN("text/plain")`

            - `Type type`

              - `TEXT("text")`

          - `class BetaManagedAgentsUrlDocumentSource:`

            Document referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the document to fetch.

          - `class BetaManagedAgentsFileDocumentSource:`

            Document referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `DOCUMENT("document")`

        - `Optional<String> context`

          Additional context about the document for the model.

        - `Optional<String> title`

          The title of the document.

    - `Type type`

      - `USER_MESSAGE("user.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsUserInterruptEvent:`

    An interrupt event that pauses agent execution and returns control to the user.

    - `String id`

      Unique identifier for this event.

    - `Type type`

      - `USER_INTERRUPT("user.interrupt")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

  - `class BetaManagedAgentsUserToolConfirmationEvent:`

    A tool confirmation event that approves or denies a pending tool execution.

    - `String id`

      Unique identifier for this event.

    - `Result result`

      UserToolConfirmationResult enum

      - `ALLOW("allow")`

      - `DENY("deny")`

    - `String toolUseId`

      The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

    - `Optional<String> denyMessage`

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

  - `class BetaManagedAgentsUserCustomToolResultEvent:`

    Event sent by the client providing the result of a custom tool execution.

    - `String id`

      Unique identifier for this event.

    - `String customToolUseId`

      The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

        - `BetaManagedAgentsSearchResultCitations citations`

          Citation settings for a search result.

          - `boolean enabled`

            Whether citations are enabled for this search result.

        - `List<BetaManagedAgentsSearchResultContent> content`

          Array of text content blocks from the search result.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `String source`

          The URL source of the search result.

        - `String title`

          The title of the search result.

        - `Type type`

          - `SEARCH_RESULT("search_result")`

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsAgentCustomToolUseEvent:`

    Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the custom tool being called.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.

  - `class BetaManagedAgentsAgentMessageEvent:`

    An agent response event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsTextBlock> content`

      Array of text blocks comprising the agent response.

      - `String text`

        The text content.

      - `Type type`

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MESSAGE("agent.message")`

  - `class BetaManagedAgentsAgentThinkingEvent:`

    Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THINKING("agent.thinking")`

  - `class BetaManagedAgentsAgentMcpToolUseEvent:`

    Event emitted when the agent invokes a tool provided by an MCP server.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String mcpServerName`

      Name of the MCP server providing the tool.

    - `String name`

      Name of the MCP tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentMcpToolResultEvent:`

    Event representing the result of an MCP tool execution.

    - `String id`

      Unique identifier for this event.

    - `String mcpToolUseId`

      The id of the `agent.mcp_tool_use` event this result corresponds to.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentToolUseEvent:`

    Event emitted when the agent invokes a built-in agent tool.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the agent tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_TOOL_USE("agent.tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentToolResultEvent:`

    Event representing the result of an agent tool execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to.

    - `Type type`

      - `AGENT_TOOL_RESULT("agent.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentThreadMessageReceivedEvent:`

    Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `String fromSessionThreadId`

      Public `sthr_` ID of the thread that sent the message.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_MESSAGE_RECEIVED("agent.thread_message_received")`

    - `Optional<String> fromAgentName`

      Name of the callable agent this message came from. Absent when received from the primary agent.

  - `class BetaManagedAgentsAgentThreadMessageSentEvent:`

    Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toSessionThreadId`

      Public `sthr_` ID of the thread the message was sent to.

    - `Type type`

      - `AGENT_THREAD_MESSAGE_SENT("agent.thread_message_sent")`

    - `Optional<String> toAgentName`

      Name of the callable agent this message was sent to. Absent when sent to the primary agent.

  - `class BetaManagedAgentsAgentThreadContextCompactedEvent:`

    Indicates that context compaction (summarization) occurred during the session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")`

  - `class BetaManagedAgentsSessionErrorEvent:`

    An error event indicating a problem occurred during session execution.

    - `String id`

      Unique identifier for this event.

    - `Error error`

      An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

      - `class BetaManagedAgentsUnknownError:`

        An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

            - `Type type`

              - `RETRYING("retrying")`

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            - `Type type`

              - `EXHAUSTED("exhausted")`

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

            - `Type type`

              - `TERMINAL("terminal")`

        - `Type type`

          - `UNKNOWN_ERROR("unknown_error")`

      - `class BetaManagedAgentsModelOverloadedError:`

        The model is currently overloaded. Emitted after automatic retries are exhausted.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_OVERLOADED_ERROR("model_overloaded_error")`

      - `class BetaManagedAgentsModelRateLimitedError:`

        The model request was rate-limited.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")`

      - `class BetaManagedAgentsModelRequestFailedError:`

        A model request failed for a reason other than overload or rate-limiting.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")`

      - `class BetaManagedAgentsMcpConnectionFailedError:`

        Failed to connect to an MCP server.

        - `String mcpServerName`

          Name of the MCP server that failed to connect.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")`

      - `class BetaManagedAgentsMcpAuthenticationFailedError:`

        Authentication to an MCP server failed.

        - `String mcpServerName`

          Name of the MCP server that failed authentication.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")`

      - `class BetaManagedAgentsBillingError:`

        The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `BILLING_ERROR("billing_error")`

      - `class BetaManagedAgentsCredentialHostUnreachableError:`

        An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

        - `String credentialId`

          ID of the affected credential.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `CREDENTIAL_HOST_UNREACHABLE_ERROR("credential_host_unreachable_error")`

        - `String vaultId`

          ID of the vault containing the affected credential.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_ERROR("session.error")`

  - `class BetaManagedAgentsSessionStatusRescheduledEvent:`

    Indicates the session is recovering from an error state and is rescheduled for execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

  - `class BetaManagedAgentsSessionStatusRunningEvent:`

    Indicates the session is actively running and the agent is working.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RUNNING("session.status_running")`

  - `class BetaManagedAgentsSessionStatusIdleEvent:`

    Indicates the agent has paused and is awaiting user input.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

        - `Type type`

          - `END_TURN("end_turn")`

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

        - `List<String> eventIds`

          The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

        - `Type type`

          - `REQUIRES_ACTION("requires_action")`

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

        - `Type type`

          - `RETRIES_EXHAUSTED("retries_exhausted")`

    - `Type type`

      - `SESSION_STATUS_IDLE("session.status_idle")`

  - `class BetaManagedAgentsSessionStatusTerminatedEvent:`

    Indicates the session has terminated, either due to an error or completion.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_TERMINATED("session.status_terminated")`

  - `class BetaManagedAgentsSessionThreadCreatedEvent:`

    Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the callable agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public `sthr_` ID of the newly created thread.

    - `Type type`

      - `SESSION_THREAD_CREATED("session.thread_created")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationStartEvent:`

    Emitted when an outcome evaluation cycle begins.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_START("span.outcome_evaluation_start")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationEndEvent:`

    Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.

    - `String id`

      Unique identifier for this event.

    - `String explanation`

      Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeEvaluationStartId`

      The id of the corresponding `span.outcome_evaluation_start` event.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String result`

      Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_END("span.outcome_evaluation_end")`

    - `BetaManagedAgentsSpanModelUsage usage`

      Token usage for a single model request.

      - `long cacheCreationInputTokens`

        Tokens used to create prompt cache in this request.

      - `long cacheReadInputTokens`

        Tokens read from prompt cache in this request.

      - `long inputTokens`

        Input tokens consumed by this request.

      - `long outputTokens`

        Output tokens generated by this request.

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `class BetaManagedAgentsSpanModelRequestStartEvent:`

    Emitted when a model request is initiated by the agent.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_START("span.model_request_start")`

  - `class BetaManagedAgentsSpanModelRequestEndEvent:`

    Emitted when a model request completes.

    - `String id`

      Unique identifier for this event.

    - `Optional<Boolean> isError`

      Whether the model request resulted in an error.

    - `String modelRequestStartId`

      The id of the corresponding `span.model_request_start` event.

    - `BetaManagedAgentsSpanModelUsage modelUsage`

      Token usage for a single model request.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_END("span.model_request_end")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent:`

    Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_ONGOING("span.outcome_evaluation_ongoing")`

  - `class BetaManagedAgentsUserDefineOutcomeEvent:`

    Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

    - `String id`

      Unique identifier for this event.

    - `String description`

      What the agent should produce. Copied from the input event.

    - `Optional<Long> maxIterations`

      Evaluate-then-revise cycles before giving up. Default 3, max 20.

    - `String outcomeId`

      Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Rubric rubric`

      Rubric for grading the quality of an outcome.

      - `class BetaManagedAgentsFileRubric:`

        Rubric referenced by a file uploaded via the Files API.

        - `String fileId`

          ID of the rubric file.

        - `Type type`

          - `FILE("file")`

      - `class BetaManagedAgentsTextRubric:`

        Rubric content provided inline as text.

        - `String content`

          Rubric content. Plain text or markdown — the grader treats it as freeform text.

        - `Type type`

          - `TEXT("text")`

    - `Type type`

      - `USER_DEFINE_OUTCOME("user.define_outcome")`

  - `class BetaManagedAgentsSessionDeletedEvent:`

    Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_DELETED("session.deleted")`

  - `class BetaManagedAgentsSessionThreadStatusRunningEvent:`

    A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that started running.

    - `Type type`

      - `SESSION_THREAD_STATUS_RUNNING("session.thread_status_running")`

  - `class BetaManagedAgentsSessionThreadStatusIdleEvent:`

    A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that went idle.

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

    - `Type type`

      - `SESSION_THREAD_STATUS_IDLE("session.thread_status_idle")`

  - `class BetaManagedAgentsSessionThreadStatusTerminatedEvent:`

    A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that terminated.

    - `Type type`

      - `SESSION_THREAD_STATUS_TERMINATED("session.thread_status_terminated")`

  - `class BetaManagedAgentsUserToolResultEvent:`

    Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

    - `String id`

      Unique identifier for this event.

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_RESULT("user.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsSessionThreadStatusRescheduledEvent:`

    A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that is retrying.

    - `Type type`

      - `SESSION_THREAD_STATUS_RESCHEDULED("session.thread_status_rescheduled")`

  - `class BetaManagedAgentsSessionUpdatedEvent:`

    Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_UPDATED("session.updated")`

    - `Optional<BetaManagedAgentsSessionAgent> agent`

      Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

      - `String id`

      - `Optional<String> description`

      - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

        - `String name`

        - `Type type`

          - `URL("url")`

        - `String url`

      - `BetaManagedAgentsModelConfig model`

        Model identifier and configuration.

        - `BetaManagedAgentsModel id`

          The model that will power your agent.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Most intelligent model for building agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

        - `Optional<Speed> speed`

          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.

          - `STANDARD("standard")`

          - `FAST("fast")`

      - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

        Resolved coordinator topology with full agent definitions for each roster member.

        - `List<BetaManagedAgentsSessionThreadAgent> agents`

          Full `agent` definitions the coordinator may spawn as session threads.

          - `String id`

          - `Optional<String> description`

          - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

            - `String name`

            - `Type type`

            - `String url`

          - `BetaManagedAgentsModelConfig model`

            Model identifier and configuration.

          - `String name`

          - `List<Skill> skills`

            - `class BetaManagedAgentsAnthropicSkill:`

              A resolved Anthropic-managed skill.

              - `String skillId`

              - `Type type`

                - `ANTHROPIC("anthropic")`

              - `String version`

            - `class BetaManagedAgentsCustomSkill:`

              A resolved user-created custom skill.

              - `String skillId`

              - `Type type`

                - `CUSTOM("custom")`

              - `String version`

          - `Optional<String> system`

          - `List<Tool> tools`

            - `class BetaManagedAgentsAgentToolset20260401:`

              - `List<BetaManagedAgentsAgentToolConfig> configs`

                - `boolean enabled`

                - `Name name`

                  Built-in agent tool identifier.

                  - `BASH("bash")`

                  - `EDIT("edit")`

                  - `READ("read")`

                  - `WRITE("write")`

                  - `GLOB("glob")`

                  - `GREP("grep")`

                  - `WEB_FETCH("web_fetch")`

                  - `WEB_SEARCH("web_search")`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                    - `Type type`

                      - `ALWAYS_ALLOW("always_allow")`

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

                    - `Type type`

                      - `ALWAYS_ASK("always_ask")`

              - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

                Resolved default configuration for agent tools.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `Type type`

                - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

            - `class BetaManagedAgentsMcpToolset:`

              - `List<BetaManagedAgentsMcpToolConfig> configs`

                - `boolean enabled`

                - `String name`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

                Resolved default configuration for all tools from an MCP server.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `String mcpServerName`

              - `Type type`

                - `MCP_TOOLSET("mcp_toolset")`

            - `class BetaManagedAgentsCustomTool:`

              A custom tool as returned in API responses.

              - `String description`

              - `BetaManagedAgentsCustomToolInputSchema inputSchema`

                JSON Schema for custom tool input parameters.

                - `JsonValue; type "object"constant`

                  - `OBJECT("object")`

                - `Optional<Properties> properties`

                - `Optional<List<String>> required`

              - `String name`

              - `Type type`

                - `CUSTOM("custom")`

          - `Type type`

            - `AGENT("agent")`

          - `long version`

        - `Type type`

          - `COORDINATOR("coordinator")`

      - `String name`

      - `List<Skill> skills`

        - `class BetaManagedAgentsAnthropicSkill:`

          A resolved Anthropic-managed skill.

        - `class BetaManagedAgentsCustomSkill:`

          A resolved user-created custom skill.

      - `Optional<String> system`

      - `List<Tool> tools`

        - `class BetaManagedAgentsAgentToolset20260401:`

        - `class BetaManagedAgentsMcpToolset:`

        - `class BetaManagedAgentsCustomTool:`

          A custom tool as returned in API responses.

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Optional<Metadata> metadata`

      The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.

    - `Optional<String> title`

      The session's new title. Present only when the update changed it.

  - `class BetaManagedAgentsSystemMessageEvent:`

    A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsSystemContentBlock> content`

      System content blocks. Text-only.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `Type type`

      - `SYSTEM_MESSAGE("system.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.sessions.threads.events.EventListPage;
import com.anthropic.models.beta.sessions.threads.events.EventListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        EventListParams params = EventListParams.builder()
            .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7")
            .threadId("sthr_011CZkZVWa6oIjw0rgXZpnBt")
            .build();
        EventListPage page = client.beta().sessions().threads().events().list(params);
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message",
      "processed_at": "2026-03-15T10:00:00Z"
    }
  ],
  "next_page": "next_page"
}
```

## Stream Session Thread Events

`BetaManagedAgentsStreamSessionThreadEvents beta().sessions().threads().events().streamStreaming(EventStreamParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/sessions/{session_id}/threads/{thread_id}/stream`

Stream Session Thread Events

### Parameters

- `EventStreamParams params`

  - `String sessionId`

  - `Optional<String> threadId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsStreamSessionThreadEvents: A class that can be one of several variants.union`

  Server-sent event in a single thread's stream.

  - `class BetaManagedAgentsUserMessageEvent:`

    A user message event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Array of content blocks comprising the user message.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

        - `Source source`

          Union type for image source variants.

          - `class BetaManagedAgentsBase64ImageSource:`

            Base64-encoded image data.

            - `String data`

              Base64-encoded image data.

            - `String mediaType`

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsUrlImageSource:`

            Image referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the image to fetch.

          - `class BetaManagedAgentsFileImageSource:`

            Image referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `IMAGE("image")`

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `Source source`

          Union type for document source variants.

          - `class BetaManagedAgentsBase64DocumentSource:`

            Base64-encoded document data.

            - `String data`

              Base64-encoded document data.

            - `String mediaType`

              MIME type of the document (e.g., "application/pdf").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsPlainTextDocumentSource:`

            Plain text document content.

            - `String data`

              The plain text content.

            - `MediaType mediaType`

              MIME type of the text content. Must be "text/plain".

              - `TEXT_PLAIN("text/plain")`

            - `Type type`

              - `TEXT("text")`

          - `class BetaManagedAgentsUrlDocumentSource:`

            Document referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the document to fetch.

          - `class BetaManagedAgentsFileDocumentSource:`

            Document referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `DOCUMENT("document")`

        - `Optional<String> context`

          Additional context about the document for the model.

        - `Optional<String> title`

          The title of the document.

    - `Type type`

      - `USER_MESSAGE("user.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

  - `class BetaManagedAgentsUserInterruptEvent:`

    An interrupt event that pauses agent execution and returns control to the user.

    - `String id`

      Unique identifier for this event.

    - `Type type`

      - `USER_INTERRUPT("user.interrupt")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

  - `class BetaManagedAgentsUserToolConfirmationEvent:`

    A tool confirmation event that approves or denies a pending tool execution.

    - `String id`

      Unique identifier for this event.

    - `Result result`

      UserToolConfirmationResult enum

      - `ALLOW("allow")`

      - `DENY("deny")`

    - `String toolUseId`

      The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_CONFIRMATION("user.tool_confirmation")`

    - `Optional<String> denyMessage`

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

  - `class BetaManagedAgentsUserCustomToolResultEvent:`

    Event sent by the client providing the result of a custom tool execution.

    - `String id`

      Unique identifier for this event.

    - `String customToolUseId`

      The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_CUSTOM_TOOL_RESULT("user.custom_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

        - `BetaManagedAgentsSearchResultCitations citations`

          Citation settings for a search result.

          - `boolean enabled`

            Whether citations are enabled for this search result.

        - `List<BetaManagedAgentsSearchResultContent> content`

          Array of text content blocks from the search result.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `String source`

          The URL source of the search result.

        - `String title`

          The title of the search result.

        - `Type type`

          - `SEARCH_RESULT("search_result")`

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsAgentCustomToolUseEvent:`

    Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the custom tool being called.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_CUSTOM_TOOL_USE("agent.custom_tool_use")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.

  - `class BetaManagedAgentsAgentMessageEvent:`

    An agent response event in the session conversation.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsTextBlock> content`

      Array of text blocks comprising the agent response.

      - `String text`

        The text content.

      - `Type type`

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MESSAGE("agent.message")`

  - `class BetaManagedAgentsAgentThinkingEvent:`

    Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THINKING("agent.thinking")`

  - `class BetaManagedAgentsAgentMcpToolUseEvent:`

    Event emitted when the agent invokes a tool provided by an MCP server.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String mcpServerName`

      Name of the MCP server providing the tool.

    - `String name`

      Name of the MCP tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_USE("agent.mcp_tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentMcpToolResultEvent:`

    Event representing the result of an MCP tool execution.

    - `String id`

      Unique identifier for this event.

    - `String mcpToolUseId`

      The id of the `agent.mcp_tool_use` event this result corresponds to.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_MCP_TOOL_RESULT("agent.mcp_tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentToolUseEvent:`

    Event emitted when the agent invokes a built-in agent tool.

    - `String id`

      Unique identifier for this event.

    - `Input input`

      Input parameters for the tool call.

    - `String name`

      Name of the agent tool being used.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_TOOL_USE("agent.tool_use")`

    - `Optional<EvaluatedPermission> evaluatedPermission`

      AgentEvaluatedPermission enum

      - `ALLOW("allow")`

      - `ASK("ask")`

      - `DENY("deny")`

    - `Optional<String> sessionThreadId`

      When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

  - `class BetaManagedAgentsAgentToolResultEvent:`

    Event representing the result of an agent tool execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to.

    - `Type type`

      - `AGENT_TOOL_RESULT("agent.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

  - `class BetaManagedAgentsAgentThreadMessageReceivedEvent:`

    Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `String fromSessionThreadId`

      Public `sthr_` ID of the thread that sent the message.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_MESSAGE_RECEIVED("agent.thread_message_received")`

    - `Optional<String> fromAgentName`

      Name of the callable agent this message came from. Absent when received from the primary agent.

  - `class BetaManagedAgentsAgentThreadMessageSentEvent:`

    Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

    - `String id`

      Unique identifier for this event.

    - `List<Content> content`

      Message content blocks.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String toSessionThreadId`

      Public `sthr_` ID of the thread the message was sent to.

    - `Type type`

      - `AGENT_THREAD_MESSAGE_SENT("agent.thread_message_sent")`

    - `Optional<String> toAgentName`

      Name of the callable agent this message was sent to. Absent when sent to the primary agent.

  - `class BetaManagedAgentsAgentThreadContextCompactedEvent:`

    Indicates that context compaction (summarization) occurred during the session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `AGENT_THREAD_CONTEXT_COMPACTED("agent.thread_context_compacted")`

  - `class BetaManagedAgentsSessionErrorEvent:`

    An error event indicating a problem occurred during session execution.

    - `String id`

      Unique identifier for this event.

    - `Error error`

      An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

      - `class BetaManagedAgentsUnknownError:`

        An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

            - `Type type`

              - `RETRYING("retrying")`

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            - `Type type`

              - `EXHAUSTED("exhausted")`

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

            - `Type type`

              - `TERMINAL("terminal")`

        - `Type type`

          - `UNKNOWN_ERROR("unknown_error")`

      - `class BetaManagedAgentsModelOverloadedError:`

        The model is currently overloaded. Emitted after automatic retries are exhausted.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_OVERLOADED_ERROR("model_overloaded_error")`

      - `class BetaManagedAgentsModelRateLimitedError:`

        The model request was rate-limited.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_RATE_LIMITED_ERROR("model_rate_limited_error")`

      - `class BetaManagedAgentsModelRequestFailedError:`

        A model request failed for a reason other than overload or rate-limiting.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MODEL_REQUEST_FAILED_ERROR("model_request_failed_error")`

      - `class BetaManagedAgentsMcpConnectionFailedError:`

        Failed to connect to an MCP server.

        - `String mcpServerName`

          Name of the MCP server that failed to connect.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_CONNECTION_FAILED_ERROR("mcp_connection_failed_error")`

      - `class BetaManagedAgentsMcpAuthenticationFailedError:`

        Authentication to an MCP server failed.

        - `String mcpServerName`

          Name of the MCP server that failed authentication.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `MCP_AUTHENTICATION_FAILED_ERROR("mcp_authentication_failed_error")`

      - `class BetaManagedAgentsBillingError:`

        The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `BILLING_ERROR("billing_error")`

      - `class BetaManagedAgentsCredentialHostUnreachableError:`

        An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

        - `String credentialId`

          ID of the affected credential.

        - `String message`

          Human-readable error description.

        - `RetryStatus retryStatus`

          What the client should do next in response to this error.

          - `class BetaManagedAgentsRetryStatusRetrying:`

            The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

          - `class BetaManagedAgentsRetryStatusExhausted:`

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          - `class BetaManagedAgentsRetryStatusTerminal:`

            The session encountered a terminal error and will transition to `terminated` state.

        - `Type type`

          - `CREDENTIAL_HOST_UNREACHABLE_ERROR("credential_host_unreachable_error")`

        - `String vaultId`

          ID of the vault containing the affected credential.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_ERROR("session.error")`

  - `class BetaManagedAgentsSessionStatusRescheduledEvent:`

    Indicates the session is recovering from an error state and is rescheduled for execution.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

  - `class BetaManagedAgentsSessionStatusRunningEvent:`

    Indicates the session is actively running and the agent is working.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_RUNNING("session.status_running")`

  - `class BetaManagedAgentsSessionStatusIdleEvent:`

    Indicates the agent has paused and is awaiting user input.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

        - `Type type`

          - `END_TURN("end_turn")`

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

        - `List<String> eventIds`

          The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

        - `Type type`

          - `REQUIRES_ACTION("requires_action")`

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

        - `Type type`

          - `RETRIES_EXHAUSTED("retries_exhausted")`

    - `Type type`

      - `SESSION_STATUS_IDLE("session.status_idle")`

  - `class BetaManagedAgentsSessionStatusTerminatedEvent:`

    Indicates the session has terminated, either due to an error or completion.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_STATUS_TERMINATED("session.status_terminated")`

  - `class BetaManagedAgentsSessionThreadCreatedEvent:`

    Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the callable agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public `sthr_` ID of the newly created thread.

    - `Type type`

      - `SESSION_THREAD_CREATED("session.thread_created")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationStartEvent:`

    Emitted when an outcome evaluation cycle begins.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_START("span.outcome_evaluation_start")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationEndEvent:`

    Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.

    - `String id`

      Unique identifier for this event.

    - `String explanation`

      Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeEvaluationStartId`

      The id of the corresponding `span.outcome_evaluation_start` event.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String result`

      Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_END("span.outcome_evaluation_end")`

    - `BetaManagedAgentsSpanModelUsage usage`

      Token usage for a single model request.

      - `long cacheCreationInputTokens`

        Tokens used to create prompt cache in this request.

      - `long cacheReadInputTokens`

        Tokens read from prompt cache in this request.

      - `long inputTokens`

        Input tokens consumed by this request.

      - `long outputTokens`

        Output tokens generated by this request.

      - `Optional<Speed> speed`

        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.

        - `STANDARD("standard")`

        - `FAST("fast")`

  - `class BetaManagedAgentsSpanModelRequestStartEvent:`

    Emitted when a model request is initiated by the agent.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_START("span.model_request_start")`

  - `class BetaManagedAgentsSpanModelRequestEndEvent:`

    Emitted when a model request completes.

    - `String id`

      Unique identifier for this event.

    - `Optional<Boolean> isError`

      Whether the model request resulted in an error.

    - `String modelRequestStartId`

      The id of the corresponding `span.model_request_start` event.

    - `BetaManagedAgentsSpanModelUsage modelUsage`

      Token usage for a single model request.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_MODEL_REQUEST_END("span.model_request_end")`

  - `class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent:`

    Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.

    - `String id`

      Unique identifier for this event.

    - `long iteration`

      0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

    - `String outcomeId`

      The `outc_` ID of the outcome being evaluated.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SPAN_OUTCOME_EVALUATION_ONGOING("span.outcome_evaluation_ongoing")`

  - `class BetaManagedAgentsUserDefineOutcomeEvent:`

    Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

    - `String id`

      Unique identifier for this event.

    - `String description`

      What the agent should produce. Copied from the input event.

    - `Optional<Long> maxIterations`

      Evaluate-then-revise cycles before giving up. Default 3, max 20.

    - `String outcomeId`

      Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Rubric rubric`

      Rubric for grading the quality of an outcome.

      - `class BetaManagedAgentsFileRubric:`

        Rubric referenced by a file uploaded via the Files API.

        - `String fileId`

          ID of the rubric file.

        - `Type type`

          - `FILE("file")`

      - `class BetaManagedAgentsTextRubric:`

        Rubric content provided inline as text.

        - `String content`

          Rubric content. Plain text or markdown — the grader treats it as freeform text.

        - `Type type`

          - `TEXT("text")`

    - `Type type`

      - `USER_DEFINE_OUTCOME("user.define_outcome")`

  - `class BetaManagedAgentsSessionDeletedEvent:`

    Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_DELETED("session.deleted")`

  - `class BetaManagedAgentsSessionThreadStatusRunningEvent:`

    A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that started running.

    - `Type type`

      - `SESSION_THREAD_STATUS_RUNNING("session.thread_status_running")`

  - `class BetaManagedAgentsSessionThreadStatusIdleEvent:`

    A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that went idle.

    - `StopReason stopReason`

      The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionEndTurn:`

        The agent completed its turn naturally and is ready for the next user message.

      - `class BetaManagedAgentsSessionRequiresAction:`

        The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

      - `class BetaManagedAgentsSessionRetriesExhausted:`

        The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`).

    - `Type type`

      - `SESSION_THREAD_STATUS_IDLE("session.thread_status_idle")`

  - `class BetaManagedAgentsSessionThreadStatusTerminatedEvent:`

    A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that terminated.

    - `Type type`

      - `SESSION_THREAD_STATUS_TERMINATED("session.thread_status_terminated")`

  - `class BetaManagedAgentsUserToolResultEvent:`

    Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

    - `String id`

      Unique identifier for this event.

    - `String toolUseId`

      The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

    - `Type type`

      - `USER_TOOL_RESULT("user.tool_result")`

    - `Optional<List<Content>> content`

      The result content returned by the tool.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `class BetaManagedAgentsSearchResultBlock:`

        A block containing a web search result.

    - `Optional<Boolean> isError`

      Whether the tool execution resulted in an error.

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> sessionThreadId`

      Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

  - `class BetaManagedAgentsSessionThreadStatusRescheduledEvent:`

    A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

    - `String id`

      Unique identifier for this event.

    - `String agentName`

      Name of the agent the thread runs.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `String sessionThreadId`

      Public sthr_ ID of the thread that is retrying.

    - `Type type`

      - `SESSION_THREAD_STATUS_RESCHEDULED("session.thread_status_rescheduled")`

  - `class BetaManagedAgentsSessionUpdatedEvent:`

    Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

    - `String id`

      Unique identifier for this event.

    - `LocalDateTime processedAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SESSION_UPDATED("session.updated")`

    - `Optional<BetaManagedAgentsSessionAgent> agent`

      Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

      - `String id`

      - `Optional<String> description`

      - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

        - `String name`

        - `Type type`

          - `URL("url")`

        - `String url`

      - `BetaManagedAgentsModelConfig model`

        Model identifier and configuration.

        - `BetaManagedAgentsModel id`

          The model that will power your agent.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `CLAUDE_FABLE_5("claude-fable-5")`

            Next generation of intelligence for the hardest knowledge work and coding problems

          - `CLAUDE_OPUS_4_8("claude-opus-4-8")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_7("claude-opus-4-7")`

            Frontier intelligence for long-running agents and coding

          - `CLAUDE_OPUS_4_6("claude-opus-4-6")`

            Most intelligent model for building agents and coding

          - `CLAUDE_SONNET_4_6("claude-sonnet-4-6")`

            Best combination of speed and intelligence

          - `CLAUDE_HAIKU_4_5("claude-haiku-4-5")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_HAIKU_4_5_20251001("claude-haiku-4-5-20251001")`

            Fastest model with near-frontier intelligence

          - `CLAUDE_OPUS_4_5("claude-opus-4-5")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_OPUS_4_5_20251101("claude-opus-4-5-20251101")`

            Premium model combining maximum intelligence with practical performance

          - `CLAUDE_SONNET_4_5("claude-sonnet-4-5")`

            High-performance model for agents and coding

          - `CLAUDE_SONNET_4_5_20250929("claude-sonnet-4-5-20250929")`

            High-performance model for agents and coding

        - `Optional<Speed> speed`

          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.

          - `STANDARD("standard")`

          - `FAST("fast")`

      - `Optional<BetaManagedAgentsSessionMultiagentCoordinator> multiagent`

        Resolved coordinator topology with full agent definitions for each roster member.

        - `List<BetaManagedAgentsSessionThreadAgent> agents`

          Full `agent` definitions the coordinator may spawn as session threads.

          - `String id`

          - `Optional<String> description`

          - `List<BetaManagedAgentsMcpServerUrlDefinition> mcpServers`

            - `String name`

            - `Type type`

            - `String url`

          - `BetaManagedAgentsModelConfig model`

            Model identifier and configuration.

          - `String name`

          - `List<Skill> skills`

            - `class BetaManagedAgentsAnthropicSkill:`

              A resolved Anthropic-managed skill.

              - `String skillId`

              - `Type type`

                - `ANTHROPIC("anthropic")`

              - `String version`

            - `class BetaManagedAgentsCustomSkill:`

              A resolved user-created custom skill.

              - `String skillId`

              - `Type type`

                - `CUSTOM("custom")`

              - `String version`

          - `Optional<String> system`

          - `List<Tool> tools`

            - `class BetaManagedAgentsAgentToolset20260401:`

              - `List<BetaManagedAgentsAgentToolConfig> configs`

                - `boolean enabled`

                - `Name name`

                  Built-in agent tool identifier.

                  - `BASH("bash")`

                  - `EDIT("edit")`

                  - `READ("read")`

                  - `WRITE("write")`

                  - `GLOB("glob")`

                  - `GREP("grep")`

                  - `WEB_FETCH("web_fetch")`

                  - `WEB_SEARCH("web_search")`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                    - `Type type`

                      - `ALWAYS_ALLOW("always_allow")`

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

                    - `Type type`

                      - `ALWAYS_ASK("always_ask")`

              - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig`

                Resolved default configuration for agent tools.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `Type type`

                - `AGENT_TOOLSET_20260401("agent_toolset_20260401")`

            - `class BetaManagedAgentsMcpToolset:`

              - `List<BetaManagedAgentsMcpToolConfig> configs`

                - `boolean enabled`

                - `String name`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `BetaManagedAgentsMcpToolsetDefaultConfig defaultConfig`

                Resolved default configuration for all tools from an MCP server.

                - `boolean enabled`

                - `PermissionPolicy permissionPolicy`

                  Permission policy for tool execution.

                  - `class BetaManagedAgentsAlwaysAllowPolicy:`

                    Tool calls are automatically approved without user confirmation.

                  - `class BetaManagedAgentsAlwaysAskPolicy:`

                    Tool calls require user confirmation before execution.

              - `String mcpServerName`

              - `Type type`

                - `MCP_TOOLSET("mcp_toolset")`

            - `class BetaManagedAgentsCustomTool:`

              A custom tool as returned in API responses.

              - `String description`

              - `BetaManagedAgentsCustomToolInputSchema inputSchema`

                JSON Schema for custom tool input parameters.

                - `JsonValue; type "object"constant`

                  - `OBJECT("object")`

                - `Optional<Properties> properties`

                - `Optional<List<String>> required`

              - `String name`

              - `Type type`

                - `CUSTOM("custom")`

          - `Type type`

            - `AGENT("agent")`

          - `long version`

        - `Type type`

          - `COORDINATOR("coordinator")`

      - `String name`

      - `List<Skill> skills`

        - `class BetaManagedAgentsAnthropicSkill:`

          A resolved Anthropic-managed skill.

        - `class BetaManagedAgentsCustomSkill:`

          A resolved user-created custom skill.

      - `Optional<String> system`

      - `List<Tool> tools`

        - `class BetaManagedAgentsAgentToolset20260401:`

        - `class BetaManagedAgentsMcpToolset:`

        - `class BetaManagedAgentsCustomTool:`

          A custom tool as returned in API responses.

      - `Type type`

        - `AGENT("agent")`

      - `long version`

    - `Optional<Metadata> metadata`

      The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.

    - `Optional<String> title`

      The session's new title. Present only when the update changed it.

  - `class BetaManagedAgentsSystemMessageEvent:`

    A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

    - `String id`

      Unique identifier for this event.

    - `List<BetaManagedAgentsSystemContentBlock> content`

      System content blocks. Text-only.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `Type type`

      - `SYSTEM_MESSAGE("system.message")`

    - `Optional<LocalDateTime> processedAt`

      A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.beta.sessions.threads.BetaManagedAgentsStreamSessionThreadEvents;
import com.anthropic.models.beta.sessions.threads.events.EventStreamParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        EventStreamParams params = EventStreamParams.builder()
            .sessionId("sesn_011CZkZAtmR3yMPDzynEDxu7")
            .threadId("sthr_011CZkZVWa6oIjw0rgXZpnBt")
            .build();
        StreamResponse<BetaManagedAgentsStreamSessionThreadEvents> betaManagedAgentsStreamSessionThreadEvents = client.beta().sessions().threads().events().streamStreaming(params);
    }
}
```

#### Response

```json
{
  "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
  "content": [
    {
      "text": "Where is my order #1234?",
      "type": "text"
    }
  ],
  "type": "user.message",
  "processed_at": "2026-03-15T10:00:00Z"
}
```

# Deployments

## Create Deployment

`BetaManagedAgentsDeployment beta().deployments().create(DeploymentCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/deployments`

Create Deployment

### Parameters

- `DeploymentCreateParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Agent agent`

    Agent to deploy. Accepts the `agent` ID string, which pins the latest version, or an `agent` object with both id and version specified. The agent must exist and not be archived.

    - `String`

    - `class BetaManagedAgentsAgentParams:`

      Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version

      - `String id`

        The `agent` ID.

      - `Type type`

        - `AGENT("agent")`

      - `Optional<Long> version`

        The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.

  - `String environmentId`

    ID of the `environment` defining the container configuration for sessions created from this deployment.

  - `List<BetaManagedAgentsDeploymentInitialEventParams> initialEvents`

    Events to send to each session immediately after creation. At least 1, maximum 50.

    - `class BetaManagedAgentsUserMessageEventParams:`

      Parameters for sending a user message to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsUserDefineOutcomeEventParams:`

      Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubricParams:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubricParams:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsSystemMessageEventParams:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

  - `String name`

    Human-readable name for the deployment.

  - `Optional<String> description`

    Description of what the deployment does.

  - `Optional<Metadata> metadata`

    Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

  - `Optional<List<Resource>> resources`

    Resources (e.g. repositories, files) to mount into each session's container. Maximum 500.

    - `class BetaManagedAgentsGitHubRepositoryResourceParams:`

      Mount a GitHub repository into the session's container.

      - `String authorizationToken`

        GitHub authorization token used to clone the repository.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceParams:`

      Mount a file uploaded via the Files API into the session.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceParam:`

      Parameters for attaching a memory store to an agent session.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<BetaManagedAgentsScheduleParams> schedule`

    5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.

  - `Optional<List<String>> vaultIds`

    Vault IDs for stored credentials the agent can use during sessions created from this deployment. Maximum 50.

### Returns

- `class BetaManagedAgentsDeployment:`

  A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

  - `String id`

    Unique identifier for this deployment.

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Description of what the deployment does.

  - `String environmentId`

    ID of the `environment` where sessions run.

  - `List<BetaManagedAgentsDeploymentInitialEvent> initialEvents`

    Events sent to each session immediately after creation.

    - `class BetaManagedAgentsDeploymentUserMessageEvent:`

      A user message sent to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsDeploymentUserDefineOutcomeEvent:`

      An outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubric:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubric:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsDeploymentSystemMessageEvent:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs.

  - `String name`

    Human-readable name.

  - `Optional<BetaManagedAgentsDeploymentPausedReason> pausedReason`

    Why a deployment is paused. Non-null exactly when `status` is `paused`.

    - `class BetaManagedAgentsManualDeploymentPausedReason:`

      The caller invoked the pause endpoint on the deployment.

      - `Type type`

        - `MANUAL("manual")`

    - `class BetaManagedAgentsErrorDeploymentPausedReason:`

      A scheduled fire recorded a failed run whose error auto-pauses the deployment.

      - `BetaManagedAgentsDeploymentPausedReasonError error`

        The error that triggered an auto-pause. Matches the failed run's `error.type`.

        - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

          The deployment's environment was archived.

          - `Type type`

            - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

        - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

          The deployment's agent was archived.

          - `Type type`

            - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

        - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

          The deployment's environment no longer exists.

          - `Type type`

            - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

        - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

          A vault referenced by the deployment no longer exists.

          - `Type type`

            - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

        - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

          A file resource referenced by the deployment no longer exists.

          - `Type type`

            - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

        - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

          A referenced resource no longer exists and its kind was not reported.

          - `Type type`

            - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

        - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

          The deployment's workspace was archived.

          - `Type type`

            - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

        - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

          The deployment's organization is disabled.

          - `Type type`

            - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

        - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

          A memory store referenced by the deployment is archived.

          - `Type type`

            - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

        - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

          A skill referenced by the deployment's agent no longer exists.

          - `Type type`

            - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

        - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

          A vault referenced by the deployment is archived.

          - `Type type`

            - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

        - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

          An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

          - `Type type`

            - `UNKNOWN_ERROR("unknown_error")`

        - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

          The deployment configures resources, but its environment is self-hosted and cannot mount them.

          - `Type type`

            - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

        - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

          An MCP server host used by the deployment's agent is blocked by the environment's network policy.

          - `Type type`

            - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

      - `Type type`

        - `ERROR("error")`

  - `List<BetaManagedAgentsSessionResourceConfig> resources`

    Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

    - `class BetaManagedAgentsGitHubRepositoryResourceConfig:`

      A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceConfig:`

      A file mounted into each session's container.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceConfig:`

      A memory store attached to each session created from this deployment.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<BetaManagedAgentsSchedule> schedule`

    5-field POSIX cron schedule with computed runtime timestamps.

    - `String expression`

      5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

    - `String timezone`

      IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").

    - `Type type`

      - `CRON("cron")`

    - `Optional<LocalDateTime> lastRunAt`

      A timestamp in RFC 3339 format

    - `Optional<List<LocalDateTime>> upcomingRunsAt`

      Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.

  - `BetaManagedAgentsDeploymentStatus status`

    Lifecycle status of a deployment.

    - `ACTIVE("active")`

    - `PAUSED("paused")`

  - `Type type`

    - `DEPLOYMENT("deployment")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `List<String> vaultIds`

    Vault IDs supplying stored credentials for sessions created from this deployment.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.deployments.BetaManagedAgentsDeployment;
import com.anthropic.models.beta.deployments.DeploymentCreateParams;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsTextBlock;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams;
import java.util.List;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        DeploymentCreateParams params = DeploymentCreateParams.builder()
            .agent("string")
            .environmentId("x")
            .addUserMessageInitialEvent(List.of(BetaManagedAgentsUserMessageEventParams.Content.ofText(BetaManagedAgentsTextBlock.builder()
                .text("Where is my order #1234?")
                .type(BetaManagedAgentsTextBlock.Type.TEXT)
                .build())))
            .name("x")
            .build();
        BetaManagedAgentsDeployment betaManagedAgentsDeployment = client.beta().deployments().create(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "type": "agent",
    "version": 1
  },
  "archived_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "environment_id": "environment_id",
  "initial_events": [
    {
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message"
    }
  ],
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "paused_reason": {
    "type": "manual"
  },
  "resources": [
    {
      "type": "github_repository",
      "url": "url",
      "checkout": {
        "name": "main",
        "type": "branch"
      },
      "mount_path": "mount_path"
    }
  ],
  "schedule": {
    "expression": "x",
    "timezone": "x",
    "type": "cron",
    "last_run_at": "2019-12-27T18:11:19.117Z",
    "upcoming_runs_at": [
      "2019-12-27T18:11:19.117Z"
    ]
  },
  "status": "active",
  "type": "deployment",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "vault_ids": [
    "string"
  ]
}
```

## List Deployments

`DeploymentListPage beta().deployments().list(DeploymentListParamsparams = DeploymentListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/deployments`

List Deployments

### Parameters

- `DeploymentListParams params`

  - `Optional<String> agentId`

    Filter by agent ID.

  - `Optional<LocalDateTime> createdAtGte`

    Return deployments created at or after this time (inclusive).

  - `Optional<LocalDateTime> createdAtLte`

    Return deployments created at or before this time (inclusive).

  - `Optional<Boolean> includeArchived`

    When true, includes archived deployments. Default: false (exclude archived).

  - `Optional<Long> limit`

    Maximum results per page. Default 20, maximum 100.

  - `Optional<String> page`

    Opaque pagination cursor.

  - `Optional<BetaManagedAgentsDeploymentStatus> status`

    Filter by status: active or paused. Omit for both. To include archived deployments, use include_archived instead; the two cannot be combined.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeployment:`

  A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

  - `String id`

    Unique identifier for this deployment.

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Description of what the deployment does.

  - `String environmentId`

    ID of the `environment` where sessions run.

  - `List<BetaManagedAgentsDeploymentInitialEvent> initialEvents`

    Events sent to each session immediately after creation.

    - `class BetaManagedAgentsDeploymentUserMessageEvent:`

      A user message sent to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsDeploymentUserDefineOutcomeEvent:`

      An outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubric:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubric:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsDeploymentSystemMessageEvent:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs.

  - `String name`

    Human-readable name.

  - `Optional<BetaManagedAgentsDeploymentPausedReason> pausedReason`

    Why a deployment is paused. Non-null exactly when `status` is `paused`.

    - `class BetaManagedAgentsManualDeploymentPausedReason:`

      The caller invoked the pause endpoint on the deployment.

      - `Type type`

        - `MANUAL("manual")`

    - `class BetaManagedAgentsErrorDeploymentPausedReason:`

      A scheduled fire recorded a failed run whose error auto-pauses the deployment.

      - `BetaManagedAgentsDeploymentPausedReasonError error`

        The error that triggered an auto-pause. Matches the failed run's `error.type`.

        - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

          The deployment's environment was archived.

          - `Type type`

            - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

        - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

          The deployment's agent was archived.

          - `Type type`

            - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

        - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

          The deployment's environment no longer exists.

          - `Type type`

            - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

        - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

          A vault referenced by the deployment no longer exists.

          - `Type type`

            - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

        - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

          A file resource referenced by the deployment no longer exists.

          - `Type type`

            - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

        - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

          A referenced resource no longer exists and its kind was not reported.

          - `Type type`

            - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

        - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

          The deployment's workspace was archived.

          - `Type type`

            - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

        - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

          The deployment's organization is disabled.

          - `Type type`

            - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

        - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

          A memory store referenced by the deployment is archived.

          - `Type type`

            - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

        - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

          A skill referenced by the deployment's agent no longer exists.

          - `Type type`

            - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

        - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

          A vault referenced by the deployment is archived.

          - `Type type`

            - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

        - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

          An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

          - `Type type`

            - `UNKNOWN_ERROR("unknown_error")`

        - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

          The deployment configures resources, but its environment is self-hosted and cannot mount them.

          - `Type type`

            - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

        - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

          An MCP server host used by the deployment's agent is blocked by the environment's network policy.

          - `Type type`

            - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

      - `Type type`

        - `ERROR("error")`

  - `List<BetaManagedAgentsSessionResourceConfig> resources`

    Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

    - `class BetaManagedAgentsGitHubRepositoryResourceConfig:`

      A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceConfig:`

      A file mounted into each session's container.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceConfig:`

      A memory store attached to each session created from this deployment.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<BetaManagedAgentsSchedule> schedule`

    5-field POSIX cron schedule with computed runtime timestamps.

    - `String expression`

      5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

    - `String timezone`

      IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").

    - `Type type`

      - `CRON("cron")`

    - `Optional<LocalDateTime> lastRunAt`

      A timestamp in RFC 3339 format

    - `Optional<List<LocalDateTime>> upcomingRunsAt`

      Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.

  - `BetaManagedAgentsDeploymentStatus status`

    Lifecycle status of a deployment.

    - `ACTIVE("active")`

    - `PAUSED("paused")`

  - `Type type`

    - `DEPLOYMENT("deployment")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `List<String> vaultIds`

    Vault IDs supplying stored credentials for sessions created from this deployment.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.deployments.DeploymentListPage;
import com.anthropic.models.beta.deployments.DeploymentListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        DeploymentListPage page = client.beta().deployments().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "id",
      "agent": {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "type": "agent",
        "version": 1
      },
      "archived_at": "2019-12-27T18:11:19.117Z",
      "created_at": "2019-12-27T18:11:19.117Z",
      "description": "description",
      "environment_id": "environment_id",
      "initial_events": [
        {
          "content": [
            {
              "text": "Where is my order #1234?",
              "type": "text"
            }
          ],
          "type": "user.message"
        }
      ],
      "metadata": {
        "foo": "string"
      },
      "name": "name",
      "paused_reason": {
        "type": "manual"
      },
      "resources": [
        {
          "type": "github_repository",
          "url": "url",
          "checkout": {
            "name": "main",
            "type": "branch"
          },
          "mount_path": "mount_path"
        }
      ],
      "schedule": {
        "expression": "x",
        "timezone": "x",
        "type": "cron",
        "last_run_at": "2019-12-27T18:11:19.117Z",
        "upcoming_runs_at": [
          "2019-12-27T18:11:19.117Z"
        ]
      },
      "status": "active",
      "type": "deployment",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "vault_ids": [
        "string"
      ]
    }
  ],
  "next_page": "next_page"
}
```

## Get Deployment

`BetaManagedAgentsDeployment beta().deployments().retrieve(DeploymentRetrieveParamsparams = DeploymentRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/deployments/{deployment_id}`

Get Deployment

### Parameters

- `DeploymentRetrieveParams params`

  - `Optional<String> deploymentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeployment:`

  A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

  - `String id`

    Unique identifier for this deployment.

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Description of what the deployment does.

  - `String environmentId`

    ID of the `environment` where sessions run.

  - `List<BetaManagedAgentsDeploymentInitialEvent> initialEvents`

    Events sent to each session immediately after creation.

    - `class BetaManagedAgentsDeploymentUserMessageEvent:`

      A user message sent to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsDeploymentUserDefineOutcomeEvent:`

      An outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubric:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubric:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsDeploymentSystemMessageEvent:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs.

  - `String name`

    Human-readable name.

  - `Optional<BetaManagedAgentsDeploymentPausedReason> pausedReason`

    Why a deployment is paused. Non-null exactly when `status` is `paused`.

    - `class BetaManagedAgentsManualDeploymentPausedReason:`

      The caller invoked the pause endpoint on the deployment.

      - `Type type`

        - `MANUAL("manual")`

    - `class BetaManagedAgentsErrorDeploymentPausedReason:`

      A scheduled fire recorded a failed run whose error auto-pauses the deployment.

      - `BetaManagedAgentsDeploymentPausedReasonError error`

        The error that triggered an auto-pause. Matches the failed run's `error.type`.

        - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

          The deployment's environment was archived.

          - `Type type`

            - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

        - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

          The deployment's agent was archived.

          - `Type type`

            - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

        - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

          The deployment's environment no longer exists.

          - `Type type`

            - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

        - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

          A vault referenced by the deployment no longer exists.

          - `Type type`

            - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

        - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

          A file resource referenced by the deployment no longer exists.

          - `Type type`

            - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

        - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

          A referenced resource no longer exists and its kind was not reported.

          - `Type type`

            - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

        - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

          The deployment's workspace was archived.

          - `Type type`

            - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

        - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

          The deployment's organization is disabled.

          - `Type type`

            - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

        - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

          A memory store referenced by the deployment is archived.

          - `Type type`

            - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

        - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

          A skill referenced by the deployment's agent no longer exists.

          - `Type type`

            - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

        - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

          A vault referenced by the deployment is archived.

          - `Type type`

            - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

        - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

          An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

          - `Type type`

            - `UNKNOWN_ERROR("unknown_error")`

        - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

          The deployment configures resources, but its environment is self-hosted and cannot mount them.

          - `Type type`

            - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

        - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

          An MCP server host used by the deployment's agent is blocked by the environment's network policy.

          - `Type type`

            - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

      - `Type type`

        - `ERROR("error")`

  - `List<BetaManagedAgentsSessionResourceConfig> resources`

    Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

    - `class BetaManagedAgentsGitHubRepositoryResourceConfig:`

      A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceConfig:`

      A file mounted into each session's container.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceConfig:`

      A memory store attached to each session created from this deployment.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<BetaManagedAgentsSchedule> schedule`

    5-field POSIX cron schedule with computed runtime timestamps.

    - `String expression`

      5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

    - `String timezone`

      IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").

    - `Type type`

      - `CRON("cron")`

    - `Optional<LocalDateTime> lastRunAt`

      A timestamp in RFC 3339 format

    - `Optional<List<LocalDateTime>> upcomingRunsAt`

      Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.

  - `BetaManagedAgentsDeploymentStatus status`

    Lifecycle status of a deployment.

    - `ACTIVE("active")`

    - `PAUSED("paused")`

  - `Type type`

    - `DEPLOYMENT("deployment")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `List<String> vaultIds`

    Vault IDs supplying stored credentials for sessions created from this deployment.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.deployments.BetaManagedAgentsDeployment;
import com.anthropic.models.beta.deployments.DeploymentRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsDeployment betaManagedAgentsDeployment = client.beta().deployments().retrieve("deployment_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "type": "agent",
    "version": 1
  },
  "archived_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "environment_id": "environment_id",
  "initial_events": [
    {
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message"
    }
  ],
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "paused_reason": {
    "type": "manual"
  },
  "resources": [
    {
      "type": "github_repository",
      "url": "url",
      "checkout": {
        "name": "main",
        "type": "branch"
      },
      "mount_path": "mount_path"
    }
  ],
  "schedule": {
    "expression": "x",
    "timezone": "x",
    "type": "cron",
    "last_run_at": "2019-12-27T18:11:19.117Z",
    "upcoming_runs_at": [
      "2019-12-27T18:11:19.117Z"
    ]
  },
  "status": "active",
  "type": "deployment",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "vault_ids": [
    "string"
  ]
}
```

## Update Deployment

`BetaManagedAgentsDeployment beta().deployments().update(DeploymentUpdateParamsparams = DeploymentUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/deployments/{deployment_id}`

Update Deployment

### Parameters

- `DeploymentUpdateParams params`

  - `Optional<String> deploymentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<Agent> agent`

    Agent to deploy. Accepts the `agent` ID string, which re-pins to the latest version, or an `agent` object with both id and version specified. Omit to preserve. Cannot be cleared.

    - `String`

    - `class BetaManagedAgentsAgentParams:`

      Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version

      - `String id`

        The `agent` ID.

      - `Type type`

        - `AGENT("agent")`

      - `Optional<Long> version`

        The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.

  - `Optional<String> description`

    Description. Omit to preserve; send empty string or null to clear.

  - `Optional<String> environmentId`

    ID of the `environment` where sessions run. Omit to preserve. Cannot be cleared.

  - `Optional<List<BetaManagedAgentsDeploymentInitialEventParams>> initialEvents`

    Initial events. Full replacement. Omit to preserve. Cannot be cleared. At least 1, maximum 50.

    - `class BetaManagedAgentsUserMessageEventParams:`

      Parameters for sending a user message to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsUserDefineOutcomeEventParams:`

      Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubricParams:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubricParams:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsSystemMessageEventParams:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

  - `Optional<Metadata> metadata`

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars.

  - `Optional<String> name`

    Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.

  - `Optional<List<Resource>> resources`

    Session resources. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 500.

    - `class BetaManagedAgentsGitHubRepositoryResourceParams:`

      Mount a GitHub repository into the session's container.

      - `String authorizationToken`

        GitHub authorization token used to clone the repository.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceParams:`

      Mount a file uploaded via the Files API into the session.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceParam:`

      Parameters for attaching a memory store to an agent session.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<BetaManagedAgentsScheduleParams> schedule`

    5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.

  - `Optional<List<String>> vaultIds`

    Vault IDs. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 50.

### Returns

- `class BetaManagedAgentsDeployment:`

  A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

  - `String id`

    Unique identifier for this deployment.

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Description of what the deployment does.

  - `String environmentId`

    ID of the `environment` where sessions run.

  - `List<BetaManagedAgentsDeploymentInitialEvent> initialEvents`

    Events sent to each session immediately after creation.

    - `class BetaManagedAgentsDeploymentUserMessageEvent:`

      A user message sent to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsDeploymentUserDefineOutcomeEvent:`

      An outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubric:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubric:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsDeploymentSystemMessageEvent:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs.

  - `String name`

    Human-readable name.

  - `Optional<BetaManagedAgentsDeploymentPausedReason> pausedReason`

    Why a deployment is paused. Non-null exactly when `status` is `paused`.

    - `class BetaManagedAgentsManualDeploymentPausedReason:`

      The caller invoked the pause endpoint on the deployment.

      - `Type type`

        - `MANUAL("manual")`

    - `class BetaManagedAgentsErrorDeploymentPausedReason:`

      A scheduled fire recorded a failed run whose error auto-pauses the deployment.

      - `BetaManagedAgentsDeploymentPausedReasonError error`

        The error that triggered an auto-pause. Matches the failed run's `error.type`.

        - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

          The deployment's environment was archived.

          - `Type type`

            - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

        - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

          The deployment's agent was archived.

          - `Type type`

            - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

        - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

          The deployment's environment no longer exists.

          - `Type type`

            - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

        - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

          A vault referenced by the deployment no longer exists.

          - `Type type`

            - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

        - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

          A file resource referenced by the deployment no longer exists.

          - `Type type`

            - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

        - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

          A referenced resource no longer exists and its kind was not reported.

          - `Type type`

            - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

        - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

          The deployment's workspace was archived.

          - `Type type`

            - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

        - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

          The deployment's organization is disabled.

          - `Type type`

            - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

        - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

          A memory store referenced by the deployment is archived.

          - `Type type`

            - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

        - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

          A skill referenced by the deployment's agent no longer exists.

          - `Type type`

            - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

        - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

          A vault referenced by the deployment is archived.

          - `Type type`

            - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

        - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

          An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

          - `Type type`

            - `UNKNOWN_ERROR("unknown_error")`

        - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

          The deployment configures resources, but its environment is self-hosted and cannot mount them.

          - `Type type`

            - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

        - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

          An MCP server host used by the deployment's agent is blocked by the environment's network policy.

          - `Type type`

            - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

      - `Type type`

        - `ERROR("error")`

  - `List<BetaManagedAgentsSessionResourceConfig> resources`

    Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

    - `class BetaManagedAgentsGitHubRepositoryResourceConfig:`

      A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceConfig:`

      A file mounted into each session's container.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceConfig:`

      A memory store attached to each session created from this deployment.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<BetaManagedAgentsSchedule> schedule`

    5-field POSIX cron schedule with computed runtime timestamps.

    - `String expression`

      5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

    - `String timezone`

      IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").

    - `Type type`

      - `CRON("cron")`

    - `Optional<LocalDateTime> lastRunAt`

      A timestamp in RFC 3339 format

    - `Optional<List<LocalDateTime>> upcomingRunsAt`

      Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.

  - `BetaManagedAgentsDeploymentStatus status`

    Lifecycle status of a deployment.

    - `ACTIVE("active")`

    - `PAUSED("paused")`

  - `Type type`

    - `DEPLOYMENT("deployment")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `List<String> vaultIds`

    Vault IDs supplying stored credentials for sessions created from this deployment.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.deployments.BetaManagedAgentsDeployment;
import com.anthropic.models.beta.deployments.DeploymentUpdateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsDeployment betaManagedAgentsDeployment = client.beta().deployments().update("deployment_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "type": "agent",
    "version": 1
  },
  "archived_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "environment_id": "environment_id",
  "initial_events": [
    {
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message"
    }
  ],
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "paused_reason": {
    "type": "manual"
  },
  "resources": [
    {
      "type": "github_repository",
      "url": "url",
      "checkout": {
        "name": "main",
        "type": "branch"
      },
      "mount_path": "mount_path"
    }
  ],
  "schedule": {
    "expression": "x",
    "timezone": "x",
    "type": "cron",
    "last_run_at": "2019-12-27T18:11:19.117Z",
    "upcoming_runs_at": [
      "2019-12-27T18:11:19.117Z"
    ]
  },
  "status": "active",
  "type": "deployment",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "vault_ids": [
    "string"
  ]
}
```

## Archive Deployment

`BetaManagedAgentsDeployment beta().deployments().archive(DeploymentArchiveParamsparams = DeploymentArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/deployments/{deployment_id}/archive`

Archive Deployment

### Parameters

- `DeploymentArchiveParams params`

  - `Optional<String> deploymentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeployment:`

  A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

  - `String id`

    Unique identifier for this deployment.

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Description of what the deployment does.

  - `String environmentId`

    ID of the `environment` where sessions run.

  - `List<BetaManagedAgentsDeploymentInitialEvent> initialEvents`

    Events sent to each session immediately after creation.

    - `class BetaManagedAgentsDeploymentUserMessageEvent:`

      A user message sent to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsDeploymentUserDefineOutcomeEvent:`

      An outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubric:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubric:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsDeploymentSystemMessageEvent:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs.

  - `String name`

    Human-readable name.

  - `Optional<BetaManagedAgentsDeploymentPausedReason> pausedReason`

    Why a deployment is paused. Non-null exactly when `status` is `paused`.

    - `class BetaManagedAgentsManualDeploymentPausedReason:`

      The caller invoked the pause endpoint on the deployment.

      - `Type type`

        - `MANUAL("manual")`

    - `class BetaManagedAgentsErrorDeploymentPausedReason:`

      A scheduled fire recorded a failed run whose error auto-pauses the deployment.

      - `BetaManagedAgentsDeploymentPausedReasonError error`

        The error that triggered an auto-pause. Matches the failed run's `error.type`.

        - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

          The deployment's environment was archived.

          - `Type type`

            - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

        - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

          The deployment's agent was archived.

          - `Type type`

            - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

        - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

          The deployment's environment no longer exists.

          - `Type type`

            - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

        - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

          A vault referenced by the deployment no longer exists.

          - `Type type`

            - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

        - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

          A file resource referenced by the deployment no longer exists.

          - `Type type`

            - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

        - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

          A referenced resource no longer exists and its kind was not reported.

          - `Type type`

            - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

        - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

          The deployment's workspace was archived.

          - `Type type`

            - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

        - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

          The deployment's organization is disabled.

          - `Type type`

            - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

        - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

          A memory store referenced by the deployment is archived.

          - `Type type`

            - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

        - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

          A skill referenced by the deployment's agent no longer exists.

          - `Type type`

            - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

        - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

          A vault referenced by the deployment is archived.

          - `Type type`

            - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

        - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

          An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

          - `Type type`

            - `UNKNOWN_ERROR("unknown_error")`

        - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

          The deployment configures resources, but its environment is self-hosted and cannot mount them.

          - `Type type`

            - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

        - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

          An MCP server host used by the deployment's agent is blocked by the environment's network policy.

          - `Type type`

            - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

      - `Type type`

        - `ERROR("error")`

  - `List<BetaManagedAgentsSessionResourceConfig> resources`

    Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

    - `class BetaManagedAgentsGitHubRepositoryResourceConfig:`

      A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceConfig:`

      A file mounted into each session's container.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceConfig:`

      A memory store attached to each session created from this deployment.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<BetaManagedAgentsSchedule> schedule`

    5-field POSIX cron schedule with computed runtime timestamps.

    - `String expression`

      5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

    - `String timezone`

      IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").

    - `Type type`

      - `CRON("cron")`

    - `Optional<LocalDateTime> lastRunAt`

      A timestamp in RFC 3339 format

    - `Optional<List<LocalDateTime>> upcomingRunsAt`

      Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.

  - `BetaManagedAgentsDeploymentStatus status`

    Lifecycle status of a deployment.

    - `ACTIVE("active")`

    - `PAUSED("paused")`

  - `Type type`

    - `DEPLOYMENT("deployment")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `List<String> vaultIds`

    Vault IDs supplying stored credentials for sessions created from this deployment.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.deployments.BetaManagedAgentsDeployment;
import com.anthropic.models.beta.deployments.DeploymentArchiveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsDeployment betaManagedAgentsDeployment = client.beta().deployments().archive("deployment_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "type": "agent",
    "version": 1
  },
  "archived_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "environment_id": "environment_id",
  "initial_events": [
    {
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message"
    }
  ],
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "paused_reason": {
    "type": "manual"
  },
  "resources": [
    {
      "type": "github_repository",
      "url": "url",
      "checkout": {
        "name": "main",
        "type": "branch"
      },
      "mount_path": "mount_path"
    }
  ],
  "schedule": {
    "expression": "x",
    "timezone": "x",
    "type": "cron",
    "last_run_at": "2019-12-27T18:11:19.117Z",
    "upcoming_runs_at": [
      "2019-12-27T18:11:19.117Z"
    ]
  },
  "status": "active",
  "type": "deployment",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "vault_ids": [
    "string"
  ]
}
```

## Run Deployment Now

`BetaManagedAgentsDeploymentRun beta().deployments().run(DeploymentRunParamsparams = DeploymentRunParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/deployments/{deployment_id}/run`

Run Deployment Now

### Parameters

- `DeploymentRunParams params`

  - `Optional<String> deploymentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeploymentRun:`

  A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.

  - `String id`

    Unique identifier for this run (`drun_...`).

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String deploymentId`

    ID of the deployment that produced this run.

  - `Optional<Error> error`

    Why the run failed to create a session. The type identifies the failure; message is human-readable detail.

    - `class BetaManagedAgentsEnvironmentArchivedRunError:`

      The deployment's environment was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

    - `class BetaManagedAgentsAgentArchivedRunError:`

      The deployment's agent was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

    - `class BetaManagedAgentsEnvironmentNotFoundRunError:`

      The deployment's environment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

    - `class BetaManagedAgentsVaultNotFoundRunError:`

      A vault referenced by the deployment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

    - `class BetaManagedAgentsVaultArchivedRunError:`

      A vault referenced by the deployment is archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

    - `class BetaManagedAgentsFileNotFoundRunError:`

      A file resource referenced by the deployment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

    - `class BetaManagedAgentsMemoryStoreArchivedRunError:`

      A memory store referenced by the deployment is archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

    - `class BetaManagedAgentsSkillNotFoundRunError:`

      A skill referenced by the deployment's agent no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

    - `class BetaManagedAgentsSessionResourceNotFoundRunError:`

      A referenced resource no longer exists and its kind was not reported.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

    - `class BetaManagedAgentsWorkspaceArchivedRunError:`

      The deployment's workspace was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

    - `class BetaManagedAgentsOrganizationDisabledRunError:`

      The deployment's organization is disabled.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

    - `class BetaManagedAgentsSessionRateLimitedRunError:`

      Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_RATE_LIMITED_ERROR("session_rate_limited_error")`

    - `class BetaManagedAgentsSessionCreationRejectedRunError:`

      The session create request was rejected with a non-retryable validation error.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_CREATION_REJECTED_ERROR("session_creation_rejected_error")`

    - `class BetaManagedAgentsUnknownRunError:`

      An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `UNKNOWN_ERROR("unknown_error")`

    - `class BetaManagedAgentsSelfHostedResourcesUnsupportedRunError:`

      The deployment configures resources, but its environment is self-hosted and cannot mount them.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

    - `class BetaManagedAgentsMcpEgressBlockedRunError:`

      An MCP server host used by the deployment's agent is blocked by the environment's network policy.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

  - `Optional<String> sessionId`

    Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.

  - `BetaManagedAgentsTriggerContext triggerContext`

    Describes what triggered a deployment run, with trigger-specific metadata.

    - `class BetaManagedAgentsScheduleTriggerContext:`

      The run was fired by the deployment's cron schedule.

      - `LocalDateTime scheduledAt`

        A timestamp in RFC 3339 format

      - `Type type`

        - `SCHEDULE("schedule")`

    - `class BetaManagedAgentsManualTriggerContext:`

      The run was started manually by creating a session directly against the deployment.

      - `Type type`

        - `MANUAL("manual")`

  - `Type type`

    - `DEPLOYMENT_RUN("deployment_run")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.deploymentruns.BetaManagedAgentsDeploymentRun;
import com.anthropic.models.beta.deployments.DeploymentRunParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsDeploymentRun betaManagedAgentsDeploymentRun = client.beta().deployments().run("deployment_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "type": "agent",
    "version": 1
  },
  "created_at": "2019-12-27T18:11:19.117Z",
  "deployment_id": "deployment_id",
  "error": {
    "message": "message",
    "type": "environment_archived_error"
  },
  "session_id": "session_id",
  "trigger_context": {
    "scheduled_at": "2019-12-27T18:11:19.117Z",
    "type": "schedule"
  },
  "type": "deployment_run"
}
```

## Pause Deployment

`BetaManagedAgentsDeployment beta().deployments().pause(DeploymentPauseParamsparams = DeploymentPauseParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/deployments/{deployment_id}/pause`

Pause Deployment

### Parameters

- `DeploymentPauseParams params`

  - `Optional<String> deploymentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeployment:`

  A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

  - `String id`

    Unique identifier for this deployment.

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Description of what the deployment does.

  - `String environmentId`

    ID of the `environment` where sessions run.

  - `List<BetaManagedAgentsDeploymentInitialEvent> initialEvents`

    Events sent to each session immediately after creation.

    - `class BetaManagedAgentsDeploymentUserMessageEvent:`

      A user message sent to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsDeploymentUserDefineOutcomeEvent:`

      An outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubric:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubric:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsDeploymentSystemMessageEvent:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs.

  - `String name`

    Human-readable name.

  - `Optional<BetaManagedAgentsDeploymentPausedReason> pausedReason`

    Why a deployment is paused. Non-null exactly when `status` is `paused`.

    - `class BetaManagedAgentsManualDeploymentPausedReason:`

      The caller invoked the pause endpoint on the deployment.

      - `Type type`

        - `MANUAL("manual")`

    - `class BetaManagedAgentsErrorDeploymentPausedReason:`

      A scheduled fire recorded a failed run whose error auto-pauses the deployment.

      - `BetaManagedAgentsDeploymentPausedReasonError error`

        The error that triggered an auto-pause. Matches the failed run's `error.type`.

        - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

          The deployment's environment was archived.

          - `Type type`

            - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

        - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

          The deployment's agent was archived.

          - `Type type`

            - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

        - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

          The deployment's environment no longer exists.

          - `Type type`

            - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

        - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

          A vault referenced by the deployment no longer exists.

          - `Type type`

            - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

        - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

          A file resource referenced by the deployment no longer exists.

          - `Type type`

            - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

        - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

          A referenced resource no longer exists and its kind was not reported.

          - `Type type`

            - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

        - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

          The deployment's workspace was archived.

          - `Type type`

            - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

        - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

          The deployment's organization is disabled.

          - `Type type`

            - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

        - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

          A memory store referenced by the deployment is archived.

          - `Type type`

            - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

        - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

          A skill referenced by the deployment's agent no longer exists.

          - `Type type`

            - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

        - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

          A vault referenced by the deployment is archived.

          - `Type type`

            - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

        - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

          An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

          - `Type type`

            - `UNKNOWN_ERROR("unknown_error")`

        - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

          The deployment configures resources, but its environment is self-hosted and cannot mount them.

          - `Type type`

            - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

        - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

          An MCP server host used by the deployment's agent is blocked by the environment's network policy.

          - `Type type`

            - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

      - `Type type`

        - `ERROR("error")`

  - `List<BetaManagedAgentsSessionResourceConfig> resources`

    Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

    - `class BetaManagedAgentsGitHubRepositoryResourceConfig:`

      A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceConfig:`

      A file mounted into each session's container.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceConfig:`

      A memory store attached to each session created from this deployment.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<BetaManagedAgentsSchedule> schedule`

    5-field POSIX cron schedule with computed runtime timestamps.

    - `String expression`

      5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

    - `String timezone`

      IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").

    - `Type type`

      - `CRON("cron")`

    - `Optional<LocalDateTime> lastRunAt`

      A timestamp in RFC 3339 format

    - `Optional<List<LocalDateTime>> upcomingRunsAt`

      Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.

  - `BetaManagedAgentsDeploymentStatus status`

    Lifecycle status of a deployment.

    - `ACTIVE("active")`

    - `PAUSED("paused")`

  - `Type type`

    - `DEPLOYMENT("deployment")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `List<String> vaultIds`

    Vault IDs supplying stored credentials for sessions created from this deployment.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.deployments.BetaManagedAgentsDeployment;
import com.anthropic.models.beta.deployments.DeploymentPauseParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsDeployment betaManagedAgentsDeployment = client.beta().deployments().pause("deployment_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "type": "agent",
    "version": 1
  },
  "archived_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "environment_id": "environment_id",
  "initial_events": [
    {
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message"
    }
  ],
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "paused_reason": {
    "type": "manual"
  },
  "resources": [
    {
      "type": "github_repository",
      "url": "url",
      "checkout": {
        "name": "main",
        "type": "branch"
      },
      "mount_path": "mount_path"
    }
  ],
  "schedule": {
    "expression": "x",
    "timezone": "x",
    "type": "cron",
    "last_run_at": "2019-12-27T18:11:19.117Z",
    "upcoming_runs_at": [
      "2019-12-27T18:11:19.117Z"
    ]
  },
  "status": "active",
  "type": "deployment",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "vault_ids": [
    "string"
  ]
}
```

## Unpause Deployment

`BetaManagedAgentsDeployment beta().deployments().unpause(DeploymentUnpauseParamsparams = DeploymentUnpauseParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/deployments/{deployment_id}/unpause`

Unpause Deployment

### Parameters

- `DeploymentUnpauseParams params`

  - `Optional<String> deploymentId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeployment:`

  A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

  - `String id`

    Unique identifier for this deployment.

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Description of what the deployment does.

  - `String environmentId`

    ID of the `environment` where sessions run.

  - `List<BetaManagedAgentsDeploymentInitialEvent> initialEvents`

    Events sent to each session immediately after creation.

    - `class BetaManagedAgentsDeploymentUserMessageEvent:`

      A user message sent to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsDeploymentUserDefineOutcomeEvent:`

      An outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubric:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubric:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsDeploymentSystemMessageEvent:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs.

  - `String name`

    Human-readable name.

  - `Optional<BetaManagedAgentsDeploymentPausedReason> pausedReason`

    Why a deployment is paused. Non-null exactly when `status` is `paused`.

    - `class BetaManagedAgentsManualDeploymentPausedReason:`

      The caller invoked the pause endpoint on the deployment.

      - `Type type`

        - `MANUAL("manual")`

    - `class BetaManagedAgentsErrorDeploymentPausedReason:`

      A scheduled fire recorded a failed run whose error auto-pauses the deployment.

      - `BetaManagedAgentsDeploymentPausedReasonError error`

        The error that triggered an auto-pause. Matches the failed run's `error.type`.

        - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

          The deployment's environment was archived.

          - `Type type`

            - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

        - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

          The deployment's agent was archived.

          - `Type type`

            - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

        - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

          The deployment's environment no longer exists.

          - `Type type`

            - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

        - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

          A vault referenced by the deployment no longer exists.

          - `Type type`

            - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

        - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

          A file resource referenced by the deployment no longer exists.

          - `Type type`

            - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

        - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

          A referenced resource no longer exists and its kind was not reported.

          - `Type type`

            - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

        - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

          The deployment's workspace was archived.

          - `Type type`

            - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

        - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

          The deployment's organization is disabled.

          - `Type type`

            - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

        - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

          A memory store referenced by the deployment is archived.

          - `Type type`

            - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

        - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

          A skill referenced by the deployment's agent no longer exists.

          - `Type type`

            - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

        - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

          A vault referenced by the deployment is archived.

          - `Type type`

            - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

        - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

          An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

          - `Type type`

            - `UNKNOWN_ERROR("unknown_error")`

        - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

          The deployment configures resources, but its environment is self-hosted and cannot mount them.

          - `Type type`

            - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

        - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

          An MCP server host used by the deployment's agent is blocked by the environment's network policy.

          - `Type type`

            - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

      - `Type type`

        - `ERROR("error")`

  - `List<BetaManagedAgentsSessionResourceConfig> resources`

    Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

    - `class BetaManagedAgentsGitHubRepositoryResourceConfig:`

      A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceConfig:`

      A file mounted into each session's container.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceConfig:`

      A memory store attached to each session created from this deployment.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<BetaManagedAgentsSchedule> schedule`

    5-field POSIX cron schedule with computed runtime timestamps.

    - `String expression`

      5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

    - `String timezone`

      IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").

    - `Type type`

      - `CRON("cron")`

    - `Optional<LocalDateTime> lastRunAt`

      A timestamp in RFC 3339 format

    - `Optional<List<LocalDateTime>> upcomingRunsAt`

      Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.

  - `BetaManagedAgentsDeploymentStatus status`

    Lifecycle status of a deployment.

    - `ACTIVE("active")`

    - `PAUSED("paused")`

  - `Type type`

    - `DEPLOYMENT("deployment")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `List<String> vaultIds`

    Vault IDs supplying stored credentials for sessions created from this deployment.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.deployments.BetaManagedAgentsDeployment;
import com.anthropic.models.beta.deployments.DeploymentUnpauseParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsDeployment betaManagedAgentsDeployment = client.beta().deployments().unpause("deployment_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "type": "agent",
    "version": 1
  },
  "archived_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "environment_id": "environment_id",
  "initial_events": [
    {
      "content": [
        {
          "text": "Where is my order #1234?",
          "type": "text"
        }
      ],
      "type": "user.message"
    }
  ],
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "paused_reason": {
    "type": "manual"
  },
  "resources": [
    {
      "type": "github_repository",
      "url": "url",
      "checkout": {
        "name": "main",
        "type": "branch"
      },
      "mount_path": "mount_path"
    }
  ],
  "schedule": {
    "expression": "x",
    "timezone": "x",
    "type": "cron",
    "last_run_at": "2019-12-27T18:11:19.117Z",
    "upcoming_runs_at": [
      "2019-12-27T18:11:19.117Z"
    ]
  },
  "status": "active",
  "type": "deployment",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "vault_ids": [
    "string"
  ]
}
```

## Domain Types

### Beta Managed Agents Agent Archived Deployment Paused Reason Error

- `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

  The deployment's agent was archived.

  - `Type type`

    - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

### Beta Managed Agents Cron Schedule

- `class BetaManagedAgentsCronSchedule:`

  5-field POSIX cron schedule with computed runtime timestamps.

  - `String expression`

    5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

  - `String timezone`

    IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").

  - `Type type`

    - `CRON("cron")`

  - `Optional<LocalDateTime> lastRunAt`

    A timestamp in RFC 3339 format

  - `Optional<List<LocalDateTime>> upcomingRunsAt`

    Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.

### Beta Managed Agents Cron Schedule Params

- `class BetaManagedAgentsCronScheduleParams:`

  5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.

  - `String expression`

    5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

  - `String timezone`

    Required. IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Validated against the IANA timezone database.

  - `Type type`

    - `CRON("cron")`

### Beta Managed Agents Deployment

- `class BetaManagedAgentsDeployment:`

  A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.

  - `String id`

    Unique identifier for this deployment.

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Description of what the deployment does.

  - `String environmentId`

    ID of the `environment` where sessions run.

  - `List<BetaManagedAgentsDeploymentInitialEvent> initialEvents`

    Events sent to each session immediately after creation.

    - `class BetaManagedAgentsDeploymentUserMessageEvent:`

      A user message sent to the session.

      - `List<Content> content`

        Array of content blocks for the user message.

        - `class BetaManagedAgentsTextBlock:`

          Regular text content.

          - `String text`

            The text content.

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsImageBlock:`

          Image content specified directly as base64 data or as a reference via a URL.

          - `Source source`

            Union type for image source variants.

            - `class BetaManagedAgentsBase64ImageSource:`

              Base64-encoded image data.

              - `String data`

                Base64-encoded image data.

              - `String mediaType`

                MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsUrlImageSource:`

              Image referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the image to fetch.

            - `class BetaManagedAgentsFileImageSource:`

              Image referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `IMAGE("image")`

        - `class BetaManagedAgentsDocumentBlock:`

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          - `Source source`

            Union type for document source variants.

            - `class BetaManagedAgentsBase64DocumentSource:`

              Base64-encoded document data.

              - `String data`

                Base64-encoded document data.

              - `String mediaType`

                MIME type of the document (e.g., "application/pdf").

              - `Type type`

                - `BASE64("base64")`

            - `class BetaManagedAgentsPlainTextDocumentSource:`

              Plain text document content.

              - `String data`

                The plain text content.

              - `MediaType mediaType`

                MIME type of the text content. Must be "text/plain".

                - `TEXT_PLAIN("text/plain")`

              - `Type type`

                - `TEXT("text")`

            - `class BetaManagedAgentsUrlDocumentSource:`

              Document referenced by URL.

              - `Type type`

                - `URL("url")`

              - `String url`

                URL of the document to fetch.

            - `class BetaManagedAgentsFileDocumentSource:`

              Document referenced by file ID.

              - `String fileId`

                ID of a previously uploaded file.

              - `Type type`

                - `FILE("file")`

          - `Type type`

            - `DOCUMENT("document")`

          - `Optional<String> context`

            Additional context about the document for the model.

          - `Optional<String> title`

            The title of the document.

      - `Type type`

        - `USER_MESSAGE("user.message")`

    - `class BetaManagedAgentsDeploymentUserDefineOutcomeEvent:`

      An outcome the agent should work toward. The agent begins work on receipt.

      - `String description`

        What the agent should produce. This is the task specification.

      - `Rubric rubric`

        Rubric for grading the quality of an outcome.

        - `class BetaManagedAgentsFileRubric:`

          Rubric referenced by a file uploaded via the Files API.

          - `String fileId`

            ID of the rubric file.

          - `Type type`

            - `FILE("file")`

        - `class BetaManagedAgentsTextRubric:`

          Rubric content provided inline as text.

          - `String content`

            Rubric content. Plain text or markdown — the grader treats it as freeform text.

          - `Type type`

            - `TEXT("text")`

      - `Type type`

        - `USER_DEFINE_OUTCOME("user.define_outcome")`

      - `Optional<Long> maxIterations`

        Eval→revision cycles before giving up. Default 3, max 20.

    - `class BetaManagedAgentsDeploymentSystemMessageEvent:`

      Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

      - `List<BetaManagedAgentsSystemContentBlock> content`

        System content blocks to append. Text-only.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `Type type`

        - `SYSTEM_MESSAGE("system.message")`

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs.

  - `String name`

    Human-readable name.

  - `Optional<BetaManagedAgentsDeploymentPausedReason> pausedReason`

    Why a deployment is paused. Non-null exactly when `status` is `paused`.

    - `class BetaManagedAgentsManualDeploymentPausedReason:`

      The caller invoked the pause endpoint on the deployment.

      - `Type type`

        - `MANUAL("manual")`

    - `class BetaManagedAgentsErrorDeploymentPausedReason:`

      A scheduled fire recorded a failed run whose error auto-pauses the deployment.

      - `BetaManagedAgentsDeploymentPausedReasonError error`

        The error that triggered an auto-pause. Matches the failed run's `error.type`.

        - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

          The deployment's environment was archived.

          - `Type type`

            - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

        - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

          The deployment's agent was archived.

          - `Type type`

            - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

        - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

          The deployment's environment no longer exists.

          - `Type type`

            - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

        - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

          A vault referenced by the deployment no longer exists.

          - `Type type`

            - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

        - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

          A file resource referenced by the deployment no longer exists.

          - `Type type`

            - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

        - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

          A referenced resource no longer exists and its kind was not reported.

          - `Type type`

            - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

        - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

          The deployment's workspace was archived.

          - `Type type`

            - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

        - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

          The deployment's organization is disabled.

          - `Type type`

            - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

        - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

          A memory store referenced by the deployment is archived.

          - `Type type`

            - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

        - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

          A skill referenced by the deployment's agent no longer exists.

          - `Type type`

            - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

        - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

          A vault referenced by the deployment is archived.

          - `Type type`

            - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

        - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

          An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

          - `Type type`

            - `UNKNOWN_ERROR("unknown_error")`

        - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

          The deployment configures resources, but its environment is self-hosted and cannot mount them.

          - `Type type`

            - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

        - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

          An MCP server host used by the deployment's agent is blocked by the environment's network policy.

          - `Type type`

            - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

      - `Type type`

        - `ERROR("error")`

  - `List<BetaManagedAgentsSessionResourceConfig> resources`

    Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.

    - `class BetaManagedAgentsGitHubRepositoryResourceConfig:`

      A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.

      - `Type type`

        - `GITHUB_REPOSITORY("github_repository")`

      - `String url`

        Github URL of the repository

      - `Optional<Checkout> checkout`

        Branch or commit to check out. Defaults to the repository's default branch.

        - `class BetaManagedAgentsBranchCheckout:`

          - `String name`

            Branch name to check out.

          - `Type type`

            - `BRANCH("branch")`

        - `class BetaManagedAgentsCommitCheckout:`

          - `String sha`

            Full commit SHA to check out.

          - `Type type`

            - `COMMIT("commit")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/workspace/<repo-name>`.

    - `class BetaManagedAgentsFileResourceConfig:`

      A file mounted into each session's container.

      - `String fileId`

        ID of a previously uploaded file.

      - `Type type`

        - `FILE("file")`

      - `Optional<String> mountPath`

        Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

    - `class BetaManagedAgentsMemoryStoreResourceConfig:`

      A memory store attached to each session created from this deployment.

      - `String memoryStoreId`

        The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

      - `Type type`

        - `MEMORY_STORE("memory_store")`

      - `Optional<Access> access`

        Access mode for an attached memory store.

        - `READ_WRITE("read_write")`

        - `READ_ONLY("read_only")`

      - `Optional<String> instructions`

        Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

  - `Optional<BetaManagedAgentsSchedule> schedule`

    5-field POSIX cron schedule with computed runtime timestamps.

    - `String expression`

      5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

    - `String timezone`

      IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").

    - `Type type`

      - `CRON("cron")`

    - `Optional<LocalDateTime> lastRunAt`

      A timestamp in RFC 3339 format

    - `Optional<List<LocalDateTime>> upcomingRunsAt`

      Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.

  - `BetaManagedAgentsDeploymentStatus status`

    Lifecycle status of a deployment.

    - `ACTIVE("active")`

    - `PAUSED("paused")`

  - `Type type`

    - `DEPLOYMENT("deployment")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `List<String> vaultIds`

    Vault IDs supplying stored credentials for sessions created from this deployment.

### Beta Managed Agents Deployment Initial Event

- `class BetaManagedAgentsDeploymentInitialEvent: A class that can be one of several variants.union`

  An event sent to a session immediately after it is created. Supports `user.message`, `user.define_outcome`, and `system.message`.

  - `class BetaManagedAgentsDeploymentUserMessageEvent:`

    A user message sent to the session.

    - `List<Content> content`

      Array of content blocks for the user message.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

        - `Source source`

          Union type for image source variants.

          - `class BetaManagedAgentsBase64ImageSource:`

            Base64-encoded image data.

            - `String data`

              Base64-encoded image data.

            - `String mediaType`

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsUrlImageSource:`

            Image referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the image to fetch.

          - `class BetaManagedAgentsFileImageSource:`

            Image referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `IMAGE("image")`

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `Source source`

          Union type for document source variants.

          - `class BetaManagedAgentsBase64DocumentSource:`

            Base64-encoded document data.

            - `String data`

              Base64-encoded document data.

            - `String mediaType`

              MIME type of the document (e.g., "application/pdf").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsPlainTextDocumentSource:`

            Plain text document content.

            - `String data`

              The plain text content.

            - `MediaType mediaType`

              MIME type of the text content. Must be "text/plain".

              - `TEXT_PLAIN("text/plain")`

            - `Type type`

              - `TEXT("text")`

          - `class BetaManagedAgentsUrlDocumentSource:`

            Document referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the document to fetch.

          - `class BetaManagedAgentsFileDocumentSource:`

            Document referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `DOCUMENT("document")`

        - `Optional<String> context`

          Additional context about the document for the model.

        - `Optional<String> title`

          The title of the document.

    - `Type type`

      - `USER_MESSAGE("user.message")`

  - `class BetaManagedAgentsDeploymentUserDefineOutcomeEvent:`

    An outcome the agent should work toward. The agent begins work on receipt.

    - `String description`

      What the agent should produce. This is the task specification.

    - `Rubric rubric`

      Rubric for grading the quality of an outcome.

      - `class BetaManagedAgentsFileRubric:`

        Rubric referenced by a file uploaded via the Files API.

        - `String fileId`

          ID of the rubric file.

        - `Type type`

          - `FILE("file")`

      - `class BetaManagedAgentsTextRubric:`

        Rubric content provided inline as text.

        - `String content`

          Rubric content. Plain text or markdown — the grader treats it as freeform text.

        - `Type type`

          - `TEXT("text")`

    - `Type type`

      - `USER_DEFINE_OUTCOME("user.define_outcome")`

    - `Optional<Long> maxIterations`

      Eval→revision cycles before giving up. Default 3, max 20.

  - `class BetaManagedAgentsDeploymentSystemMessageEvent:`

    Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

    - `List<BetaManagedAgentsSystemContentBlock> content`

      System content blocks to append. Text-only.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `Type type`

      - `SYSTEM_MESSAGE("system.message")`

### Beta Managed Agents Deployment Initial Event Params

- `class BetaManagedAgentsDeploymentInitialEventParams: A class that can be one of several variants.union`

  An event sent to a session immediately after it is created. Supports `user.message`, `user.define_outcome`, and `system.message`.

  - `class BetaManagedAgentsUserMessageEventParams:`

    Parameters for sending a user message to the session.

    - `List<Content> content`

      Array of content blocks for the user message.

      - `class BetaManagedAgentsTextBlock:`

        Regular text content.

        - `String text`

          The text content.

        - `Type type`

          - `TEXT("text")`

      - `class BetaManagedAgentsImageBlock:`

        Image content specified directly as base64 data or as a reference via a URL.

        - `Source source`

          Union type for image source variants.

          - `class BetaManagedAgentsBase64ImageSource:`

            Base64-encoded image data.

            - `String data`

              Base64-encoded image data.

            - `String mediaType`

              MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsUrlImageSource:`

            Image referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the image to fetch.

          - `class BetaManagedAgentsFileImageSource:`

            Image referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `IMAGE("image")`

      - `class BetaManagedAgentsDocumentBlock:`

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        - `Source source`

          Union type for document source variants.

          - `class BetaManagedAgentsBase64DocumentSource:`

            Base64-encoded document data.

            - `String data`

              Base64-encoded document data.

            - `String mediaType`

              MIME type of the document (e.g., "application/pdf").

            - `Type type`

              - `BASE64("base64")`

          - `class BetaManagedAgentsPlainTextDocumentSource:`

            Plain text document content.

            - `String data`

              The plain text content.

            - `MediaType mediaType`

              MIME type of the text content. Must be "text/plain".

              - `TEXT_PLAIN("text/plain")`

            - `Type type`

              - `TEXT("text")`

          - `class BetaManagedAgentsUrlDocumentSource:`

            Document referenced by URL.

            - `Type type`

              - `URL("url")`

            - `String url`

              URL of the document to fetch.

          - `class BetaManagedAgentsFileDocumentSource:`

            Document referenced by file ID.

            - `String fileId`

              ID of a previously uploaded file.

            - `Type type`

              - `FILE("file")`

        - `Type type`

          - `DOCUMENT("document")`

        - `Optional<String> context`

          Additional context about the document for the model.

        - `Optional<String> title`

          The title of the document.

    - `Type type`

      - `USER_MESSAGE("user.message")`

  - `class BetaManagedAgentsUserDefineOutcomeEventParams:`

    Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

    - `String description`

      What the agent should produce. This is the task specification.

    - `Rubric rubric`

      Rubric for grading the quality of an outcome.

      - `class BetaManagedAgentsFileRubricParams:`

        Rubric referenced by a file uploaded via the Files API.

        - `String fileId`

          ID of the rubric file.

        - `Type type`

          - `FILE("file")`

      - `class BetaManagedAgentsTextRubricParams:`

        Rubric content provided inline as text.

        - `String content`

          Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.

        - `Type type`

          - `TEXT("text")`

    - `Type type`

      - `USER_DEFINE_OUTCOME("user.define_outcome")`

    - `Optional<Long> maxIterations`

      Eval→revision cycles before giving up. Default 3, max 20.

  - `class BetaManagedAgentsSystemMessageEventParams:`

    Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages.

    - `List<BetaManagedAgentsSystemContentBlock> content`

      System content blocks to append. Text-only.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `Type type`

      - `SYSTEM_MESSAGE("system.message")`

### Beta Managed Agents Deployment Paused Reason

- `class BetaManagedAgentsDeploymentPausedReason: A class that can be one of several variants.union`

  Why a deployment is paused. Non-null exactly when `status` is `paused`.

  - `class BetaManagedAgentsManualDeploymentPausedReason:`

    The caller invoked the pause endpoint on the deployment.

    - `Type type`

      - `MANUAL("manual")`

  - `class BetaManagedAgentsErrorDeploymentPausedReason:`

    A scheduled fire recorded a failed run whose error auto-pauses the deployment.

    - `BetaManagedAgentsDeploymentPausedReasonError error`

      The error that triggered an auto-pause. Matches the failed run's `error.type`.

      - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

        The deployment's environment was archived.

        - `Type type`

          - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

      - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

        The deployment's agent was archived.

        - `Type type`

          - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

      - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

        The deployment's environment no longer exists.

        - `Type type`

          - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

      - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

        A vault referenced by the deployment no longer exists.

        - `Type type`

          - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

      - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

        A file resource referenced by the deployment no longer exists.

        - `Type type`

          - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

      - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

        A referenced resource no longer exists and its kind was not reported.

        - `Type type`

          - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

      - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

        The deployment's workspace was archived.

        - `Type type`

          - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

      - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

        The deployment's organization is disabled.

        - `Type type`

          - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

      - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

        A memory store referenced by the deployment is archived.

        - `Type type`

          - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

      - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

        A skill referenced by the deployment's agent no longer exists.

        - `Type type`

          - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

      - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

        A vault referenced by the deployment is archived.

        - `Type type`

          - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

      - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

        An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

        - `Type type`

          - `UNKNOWN_ERROR("unknown_error")`

      - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

        The deployment configures resources, but its environment is self-hosted and cannot mount them.

        - `Type type`

          - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

      - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

        An MCP server host used by the deployment's agent is blocked by the environment's network policy.

        - `Type type`

          - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

    - `Type type`

      - `ERROR("error")`

### Beta Managed Agents Deployment Paused Reason Error

- `class BetaManagedAgentsDeploymentPausedReasonError: A class that can be one of several variants.union`

  The error that triggered an auto-pause. Matches the failed run's `error.type`.

  - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

    The deployment's environment was archived.

    - `Type type`

      - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

  - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

    The deployment's agent was archived.

    - `Type type`

      - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

  - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

    The deployment's environment no longer exists.

    - `Type type`

      - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

  - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

    A vault referenced by the deployment no longer exists.

    - `Type type`

      - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

  - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

    A file resource referenced by the deployment no longer exists.

    - `Type type`

      - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

  - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

    A referenced resource no longer exists and its kind was not reported.

    - `Type type`

      - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

  - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

    The deployment's workspace was archived.

    - `Type type`

      - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

  - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

    The deployment's organization is disabled.

    - `Type type`

      - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

  - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

    A memory store referenced by the deployment is archived.

    - `Type type`

      - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

  - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

    A skill referenced by the deployment's agent no longer exists.

    - `Type type`

      - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

  - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

    A vault referenced by the deployment is archived.

    - `Type type`

      - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

  - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

    An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

    - `Type type`

      - `UNKNOWN_ERROR("unknown_error")`

  - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

    The deployment configures resources, but its environment is self-hosted and cannot mount them.

    - `Type type`

      - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

  - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

    An MCP server host used by the deployment's agent is blocked by the environment's network policy.

    - `Type type`

      - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

### Beta Managed Agents Deployment Status

- `enum BetaManagedAgentsDeploymentStatus:`

  Lifecycle status of a deployment.

  - `ACTIVE("active")`

  - `PAUSED("paused")`

### Beta Managed Agents Deployment System Message Event

- `class BetaManagedAgentsDeploymentSystemMessageEvent:`

  Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.

  - `List<BetaManagedAgentsSystemContentBlock> content`

    System content blocks to append. Text-only.

    - `String text`

      The text content.

    - `Type type`

      - `TEXT("text")`

  - `Type type`

    - `SYSTEM_MESSAGE("system.message")`

### Beta Managed Agents Deployment User Define Outcome Event

- `class BetaManagedAgentsDeploymentUserDefineOutcomeEvent:`

  An outcome the agent should work toward. The agent begins work on receipt.

  - `String description`

    What the agent should produce. This is the task specification.

  - `Rubric rubric`

    Rubric for grading the quality of an outcome.

    - `class BetaManagedAgentsFileRubric:`

      Rubric referenced by a file uploaded via the Files API.

      - `String fileId`

        ID of the rubric file.

      - `Type type`

        - `FILE("file")`

    - `class BetaManagedAgentsTextRubric:`

      Rubric content provided inline as text.

      - `String content`

        Rubric content. Plain text or markdown — the grader treats it as freeform text.

      - `Type type`

        - `TEXT("text")`

  - `Type type`

    - `USER_DEFINE_OUTCOME("user.define_outcome")`

  - `Optional<Long> maxIterations`

    Eval→revision cycles before giving up. Default 3, max 20.

### Beta Managed Agents Deployment User Message Event

- `class BetaManagedAgentsDeploymentUserMessageEvent:`

  A user message sent to the session.

  - `List<Content> content`

    Array of content blocks for the user message.

    - `class BetaManagedAgentsTextBlock:`

      Regular text content.

      - `String text`

        The text content.

      - `Type type`

        - `TEXT("text")`

    - `class BetaManagedAgentsImageBlock:`

      Image content specified directly as base64 data or as a reference via a URL.

      - `Source source`

        Union type for image source variants.

        - `class BetaManagedAgentsBase64ImageSource:`

          Base64-encoded image data.

          - `String data`

            Base64-encoded image data.

          - `String mediaType`

            MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsUrlImageSource:`

          Image referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the image to fetch.

        - `class BetaManagedAgentsFileImageSource:`

          Image referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `IMAGE("image")`

    - `class BetaManagedAgentsDocumentBlock:`

      Document content, either specified directly as base64 data, as text, or as a reference via a URL.

      - `Source source`

        Union type for document source variants.

        - `class BetaManagedAgentsBase64DocumentSource:`

          Base64-encoded document data.

          - `String data`

            Base64-encoded document data.

          - `String mediaType`

            MIME type of the document (e.g., "application/pdf").

          - `Type type`

            - `BASE64("base64")`

        - `class BetaManagedAgentsPlainTextDocumentSource:`

          Plain text document content.

          - `String data`

            The plain text content.

          - `MediaType mediaType`

            MIME type of the text content. Must be "text/plain".

            - `TEXT_PLAIN("text/plain")`

          - `Type type`

            - `TEXT("text")`

        - `class BetaManagedAgentsUrlDocumentSource:`

          Document referenced by URL.

          - `Type type`

            - `URL("url")`

          - `String url`

            URL of the document to fetch.

        - `class BetaManagedAgentsFileDocumentSource:`

          Document referenced by file ID.

          - `String fileId`

            ID of a previously uploaded file.

          - `Type type`

            - `FILE("file")`

      - `Type type`

        - `DOCUMENT("document")`

      - `Optional<String> context`

        Additional context about the document for the model.

      - `Optional<String> title`

        The title of the document.

  - `Type type`

    - `USER_MESSAGE("user.message")`

### Beta Managed Agents Environment Archived Deployment Paused Reason Error

- `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

  The deployment's environment was archived.

  - `Type type`

    - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

### Beta Managed Agents Environment Not Found Deployment Paused Reason Error

- `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

  The deployment's environment no longer exists.

  - `Type type`

    - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

### Beta Managed Agents Error Deployment Paused Reason

- `class BetaManagedAgentsErrorDeploymentPausedReason:`

  A scheduled fire recorded a failed run whose error auto-pauses the deployment.

  - `BetaManagedAgentsDeploymentPausedReasonError error`

    The error that triggered an auto-pause. Matches the failed run's `error.type`.

    - `class BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError:`

      The deployment's environment was archived.

      - `Type type`

        - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

    - `class BetaManagedAgentsAgentArchivedDeploymentPausedReasonError:`

      The deployment's agent was archived.

      - `Type type`

        - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

    - `class BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError:`

      The deployment's environment no longer exists.

      - `Type type`

        - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

    - `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

      A vault referenced by the deployment no longer exists.

      - `Type type`

        - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

    - `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

      A file resource referenced by the deployment no longer exists.

      - `Type type`

        - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

    - `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

      A referenced resource no longer exists and its kind was not reported.

      - `Type type`

        - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

    - `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

      The deployment's workspace was archived.

      - `Type type`

        - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

    - `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

      The deployment's organization is disabled.

      - `Type type`

        - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

    - `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

      A memory store referenced by the deployment is archived.

      - `Type type`

        - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

    - `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

      A skill referenced by the deployment's agent no longer exists.

      - `Type type`

        - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

    - `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

      A vault referenced by the deployment is archived.

      - `Type type`

        - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

    - `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

      An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

      - `Type type`

        - `UNKNOWN_ERROR("unknown_error")`

    - `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

      The deployment configures resources, but its environment is self-hosted and cannot mount them.

      - `Type type`

        - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

    - `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

      An MCP server host used by the deployment's agent is blocked by the environment's network policy.

      - `Type type`

        - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

  - `Type type`

    - `ERROR("error")`

### Beta Managed Agents File Not Found Deployment Paused Reason Error

- `class BetaManagedAgentsFileNotFoundDeploymentPausedReasonError:`

  A file resource referenced by the deployment no longer exists.

  - `Type type`

    - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

### Beta Managed Agents File Resource Config

- `class BetaManagedAgentsFileResourceConfig:`

  A file mounted into each session's container.

  - `String fileId`

    ID of a previously uploaded file.

  - `Type type`

    - `FILE("file")`

  - `Optional<String> mountPath`

    Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

### Beta Managed Agents GitHub Repository Resource Config

- `class BetaManagedAgentsGitHubRepositoryResourceConfig:`

  A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.

  - `Type type`

    - `GITHUB_REPOSITORY("github_repository")`

  - `String url`

    Github URL of the repository

  - `Optional<Checkout> checkout`

    Branch or commit to check out. Defaults to the repository's default branch.

    - `class BetaManagedAgentsBranchCheckout:`

      - `String name`

        Branch name to check out.

      - `Type type`

        - `BRANCH("branch")`

    - `class BetaManagedAgentsCommitCheckout:`

      - `String sha`

        Full commit SHA to check out.

      - `Type type`

        - `COMMIT("commit")`

  - `Optional<String> mountPath`

    Mount path in the container. Defaults to `/workspace/<repo-name>`.

### Beta Managed Agents Manual Deployment Paused Reason

- `class BetaManagedAgentsManualDeploymentPausedReason:`

  The caller invoked the pause endpoint on the deployment.

  - `Type type`

    - `MANUAL("manual")`

### Beta Managed Agents MCP Egress Blocked Deployment Paused Reason Error

- `class BetaManagedAgentsMcpEgressBlockedDeploymentPausedReasonError:`

  An MCP server host used by the deployment's agent is blocked by the environment's network policy.

  - `Type type`

    - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

### Beta Managed Agents Memory Store Archived Deployment Paused Reason Error

- `class BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError:`

  A memory store referenced by the deployment is archived.

  - `Type type`

    - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

### Beta Managed Agents Memory Store Resource Config

- `class BetaManagedAgentsMemoryStoreResourceConfig:`

  A memory store attached to each session created from this deployment.

  - `String memoryStoreId`

    The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

  - `Type type`

    - `MEMORY_STORE("memory_store")`

  - `Optional<Access> access`

    Access mode for an attached memory store.

    - `READ_WRITE("read_write")`

    - `READ_ONLY("read_only")`

  - `Optional<String> instructions`

    Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

### Beta Managed Agents Organization Disabled Deployment Paused Reason Error

- `class BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError:`

  The deployment's organization is disabled.

  - `Type type`

    - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

### Beta Managed Agents Schedule

- `class BetaManagedAgentsSchedule:`

  5-field POSIX cron schedule with computed runtime timestamps.

  - `String expression`

    5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

  - `String timezone`

    IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").

  - `Type type`

    - `CRON("cron")`

  - `Optional<LocalDateTime> lastRunAt`

    A timestamp in RFC 3339 format

  - `Optional<List<LocalDateTime>> upcomingRunsAt`

    Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.

### Beta Managed Agents Schedule Params

- `class BetaManagedAgentsScheduleParams:`

  5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.

  - `String expression`

    5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).

  - `String timezone`

    Required. IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Validated against the IANA timezone database.

  - `Type type`

    - `CRON("cron")`

### Beta Managed Agents Self Hosted Resources Unsupported Deployment Paused Reason Error

- `class BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError:`

  The deployment configures resources, but its environment is self-hosted and cannot mount them.

  - `Type type`

    - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

### Beta Managed Agents Session Resource Config

- `class BetaManagedAgentsSessionResourceConfig: A class that can be one of several variants.union`

  A configured session resource. Echoes the input minus write-only credentials.

  - `class BetaManagedAgentsGitHubRepositoryResourceConfig:`

    A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.

    - `Type type`

      - `GITHUB_REPOSITORY("github_repository")`

    - `String url`

      Github URL of the repository

    - `Optional<Checkout> checkout`

      Branch or commit to check out. Defaults to the repository's default branch.

      - `class BetaManagedAgentsBranchCheckout:`

        - `String name`

          Branch name to check out.

        - `Type type`

          - `BRANCH("branch")`

      - `class BetaManagedAgentsCommitCheckout:`

        - `String sha`

          Full commit SHA to check out.

        - `Type type`

          - `COMMIT("commit")`

    - `Optional<String> mountPath`

      Mount path in the container. Defaults to `/workspace/<repo-name>`.

  - `class BetaManagedAgentsFileResourceConfig:`

    A file mounted into each session's container.

    - `String fileId`

      ID of a previously uploaded file.

    - `Type type`

      - `FILE("file")`

    - `Optional<String> mountPath`

      Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

  - `class BetaManagedAgentsMemoryStoreResourceConfig:`

    A memory store attached to each session created from this deployment.

    - `String memoryStoreId`

      The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

    - `Type type`

      - `MEMORY_STORE("memory_store")`

    - `Optional<Access> access`

      Access mode for an attached memory store.

      - `READ_WRITE("read_write")`

      - `READ_ONLY("read_only")`

    - `Optional<String> instructions`

      Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

### Beta Managed Agents Session Resource Not Found Deployment Paused Reason Error

- `class BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError:`

  A referenced resource no longer exists and its kind was not reported.

  - `Type type`

    - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

### Beta Managed Agents Skill Not Found Deployment Paused Reason Error

- `class BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError:`

  A skill referenced by the deployment's agent no longer exists.

  - `Type type`

    - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

### Beta Managed Agents Unknown Deployment Paused Reason Error

- `class BetaManagedAgentsUnknownDeploymentPausedReasonError:`

  An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.

  - `Type type`

    - `UNKNOWN_ERROR("unknown_error")`

### Beta Managed Agents Vault Archived Deployment Paused Reason Error

- `class BetaManagedAgentsVaultArchivedDeploymentPausedReasonError:`

  A vault referenced by the deployment is archived.

  - `Type type`

    - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

### Beta Managed Agents Vault Not Found Deployment Paused Reason Error

- `class BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError:`

  A vault referenced by the deployment no longer exists.

  - `Type type`

    - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

### Beta Managed Agents Workspace Archived Deployment Paused Reason Error

- `class BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError:`

  The deployment's workspace was archived.

  - `Type type`

    - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

# Deployment Runs

## List Deployment Runs

`DeploymentRunListPage beta().deploymentRuns().list(DeploymentRunListParamsparams = DeploymentRunListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/deployment_runs`

List Deployment Runs

### Parameters

- `DeploymentRunListParams params`

  - `Optional<LocalDateTime> createdAtGt`

    Return runs created strictly after this time (exclusive).

  - `Optional<LocalDateTime> createdAtGte`

    Return runs created at or after this time (inclusive).

  - `Optional<LocalDateTime> createdAtLt`

    Return runs created strictly before this time (exclusive).

  - `Optional<LocalDateTime> createdAtLte`

    Return runs created at or before this time (inclusive).

  - `Optional<String> deploymentId`

    Filter to a specific deployment. Omit to list across all deployments in the workspace. Filtering by a non-existent deployment_id returns 200 with empty data.

  - `Optional<Boolean> hasError`

    Filter: true for runs with non-null error, false for runs with non-null session_id. Omit for all.

  - `Optional<Long> limit`

    Maximum results per page. Default 20, maximum 1000.

  - `Optional<String> page`

    Opaque pagination cursor. Pass next_page from the previous response. Invalid or expired cursors return 400.

  - `Optional<BetaManagedAgentsTriggerType> triggerType`

    Filter runs by what triggered them. Omit to return all runs.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeploymentRun:`

  A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.

  - `String id`

    Unique identifier for this run (`drun_...`).

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String deploymentId`

    ID of the deployment that produced this run.

  - `Optional<Error> error`

    Why the run failed to create a session. The type identifies the failure; message is human-readable detail.

    - `class BetaManagedAgentsEnvironmentArchivedRunError:`

      The deployment's environment was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

    - `class BetaManagedAgentsAgentArchivedRunError:`

      The deployment's agent was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

    - `class BetaManagedAgentsEnvironmentNotFoundRunError:`

      The deployment's environment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

    - `class BetaManagedAgentsVaultNotFoundRunError:`

      A vault referenced by the deployment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

    - `class BetaManagedAgentsVaultArchivedRunError:`

      A vault referenced by the deployment is archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

    - `class BetaManagedAgentsFileNotFoundRunError:`

      A file resource referenced by the deployment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

    - `class BetaManagedAgentsMemoryStoreArchivedRunError:`

      A memory store referenced by the deployment is archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

    - `class BetaManagedAgentsSkillNotFoundRunError:`

      A skill referenced by the deployment's agent no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

    - `class BetaManagedAgentsSessionResourceNotFoundRunError:`

      A referenced resource no longer exists and its kind was not reported.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

    - `class BetaManagedAgentsWorkspaceArchivedRunError:`

      The deployment's workspace was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

    - `class BetaManagedAgentsOrganizationDisabledRunError:`

      The deployment's organization is disabled.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

    - `class BetaManagedAgentsSessionRateLimitedRunError:`

      Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_RATE_LIMITED_ERROR("session_rate_limited_error")`

    - `class BetaManagedAgentsSessionCreationRejectedRunError:`

      The session create request was rejected with a non-retryable validation error.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_CREATION_REJECTED_ERROR("session_creation_rejected_error")`

    - `class BetaManagedAgentsUnknownRunError:`

      An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `UNKNOWN_ERROR("unknown_error")`

    - `class BetaManagedAgentsSelfHostedResourcesUnsupportedRunError:`

      The deployment configures resources, but its environment is self-hosted and cannot mount them.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

    - `class BetaManagedAgentsMcpEgressBlockedRunError:`

      An MCP server host used by the deployment's agent is blocked by the environment's network policy.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

  - `Optional<String> sessionId`

    Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.

  - `BetaManagedAgentsTriggerContext triggerContext`

    Describes what triggered a deployment run, with trigger-specific metadata.

    - `class BetaManagedAgentsScheduleTriggerContext:`

      The run was fired by the deployment's cron schedule.

      - `LocalDateTime scheduledAt`

        A timestamp in RFC 3339 format

      - `Type type`

        - `SCHEDULE("schedule")`

    - `class BetaManagedAgentsManualTriggerContext:`

      The run was started manually by creating a session directly against the deployment.

      - `Type type`

        - `MANUAL("manual")`

  - `Type type`

    - `DEPLOYMENT_RUN("deployment_run")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.deploymentruns.DeploymentRunListPage;
import com.anthropic.models.beta.deploymentruns.DeploymentRunListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        DeploymentRunListPage page = client.beta().deploymentRuns().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "id",
      "agent": {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "type": "agent",
        "version": 1
      },
      "created_at": "2019-12-27T18:11:19.117Z",
      "deployment_id": "deployment_id",
      "error": {
        "message": "message",
        "type": "environment_archived_error"
      },
      "session_id": "session_id",
      "trigger_context": {
        "scheduled_at": "2019-12-27T18:11:19.117Z",
        "type": "schedule"
      },
      "type": "deployment_run"
    }
  ],
  "next_page": "next_page"
}
```

## Get Deployment Run

`BetaManagedAgentsDeploymentRun beta().deploymentRuns().retrieve(DeploymentRunRetrieveParamsparams = DeploymentRunRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/deployment_runs/{deployment_run_id}`

Get Deployment Run

### Parameters

- `DeploymentRunRetrieveParams params`

  - `Optional<String> deploymentRunId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeploymentRun:`

  A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.

  - `String id`

    Unique identifier for this run (`drun_...`).

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String deploymentId`

    ID of the deployment that produced this run.

  - `Optional<Error> error`

    Why the run failed to create a session. The type identifies the failure; message is human-readable detail.

    - `class BetaManagedAgentsEnvironmentArchivedRunError:`

      The deployment's environment was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

    - `class BetaManagedAgentsAgentArchivedRunError:`

      The deployment's agent was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

    - `class BetaManagedAgentsEnvironmentNotFoundRunError:`

      The deployment's environment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

    - `class BetaManagedAgentsVaultNotFoundRunError:`

      A vault referenced by the deployment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

    - `class BetaManagedAgentsVaultArchivedRunError:`

      A vault referenced by the deployment is archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

    - `class BetaManagedAgentsFileNotFoundRunError:`

      A file resource referenced by the deployment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

    - `class BetaManagedAgentsMemoryStoreArchivedRunError:`

      A memory store referenced by the deployment is archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

    - `class BetaManagedAgentsSkillNotFoundRunError:`

      A skill referenced by the deployment's agent no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

    - `class BetaManagedAgentsSessionResourceNotFoundRunError:`

      A referenced resource no longer exists and its kind was not reported.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

    - `class BetaManagedAgentsWorkspaceArchivedRunError:`

      The deployment's workspace was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

    - `class BetaManagedAgentsOrganizationDisabledRunError:`

      The deployment's organization is disabled.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

    - `class BetaManagedAgentsSessionRateLimitedRunError:`

      Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_RATE_LIMITED_ERROR("session_rate_limited_error")`

    - `class BetaManagedAgentsSessionCreationRejectedRunError:`

      The session create request was rejected with a non-retryable validation error.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_CREATION_REJECTED_ERROR("session_creation_rejected_error")`

    - `class BetaManagedAgentsUnknownRunError:`

      An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `UNKNOWN_ERROR("unknown_error")`

    - `class BetaManagedAgentsSelfHostedResourcesUnsupportedRunError:`

      The deployment configures resources, but its environment is self-hosted and cannot mount them.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

    - `class BetaManagedAgentsMcpEgressBlockedRunError:`

      An MCP server host used by the deployment's agent is blocked by the environment's network policy.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

  - `Optional<String> sessionId`

    Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.

  - `BetaManagedAgentsTriggerContext triggerContext`

    Describes what triggered a deployment run, with trigger-specific metadata.

    - `class BetaManagedAgentsScheduleTriggerContext:`

      The run was fired by the deployment's cron schedule.

      - `LocalDateTime scheduledAt`

        A timestamp in RFC 3339 format

      - `Type type`

        - `SCHEDULE("schedule")`

    - `class BetaManagedAgentsManualTriggerContext:`

      The run was started manually by creating a session directly against the deployment.

      - `Type type`

        - `MANUAL("manual")`

  - `Type type`

    - `DEPLOYMENT_RUN("deployment_run")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.deploymentruns.BetaManagedAgentsDeploymentRun;
import com.anthropic.models.beta.deploymentruns.DeploymentRunRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsDeploymentRun betaManagedAgentsDeploymentRun = client.beta().deploymentRuns().retrieve("deployment_run_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "agent": {
    "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
    "type": "agent",
    "version": 1
  },
  "created_at": "2019-12-27T18:11:19.117Z",
  "deployment_id": "deployment_id",
  "error": {
    "message": "message",
    "type": "environment_archived_error"
  },
  "session_id": "session_id",
  "trigger_context": {
    "scheduled_at": "2019-12-27T18:11:19.117Z",
    "type": "schedule"
  },
  "type": "deployment_run"
}
```

## Domain Types

### Beta Managed Agents Agent Archived Run Error

- `class BetaManagedAgentsAgentArchivedRunError:`

  The deployment's agent was archived.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

### Beta Managed Agents Deployment Run

- `class BetaManagedAgentsDeploymentRun:`

  A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.

  - `String id`

    Unique identifier for this run (`drun_...`).

  - `BetaManagedAgentsAgentReference agent`

    A resolved agent reference with a concrete version.

    - `String id`

    - `Type type`

      - `AGENT("agent")`

    - `long version`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String deploymentId`

    ID of the deployment that produced this run.

  - `Optional<Error> error`

    Why the run failed to create a session. The type identifies the failure; message is human-readable detail.

    - `class BetaManagedAgentsEnvironmentArchivedRunError:`

      The deployment's environment was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

    - `class BetaManagedAgentsAgentArchivedRunError:`

      The deployment's agent was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `AGENT_ARCHIVED_ERROR("agent_archived_error")`

    - `class BetaManagedAgentsEnvironmentNotFoundRunError:`

      The deployment's environment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

    - `class BetaManagedAgentsVaultNotFoundRunError:`

      A vault referenced by the deployment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

    - `class BetaManagedAgentsVaultArchivedRunError:`

      A vault referenced by the deployment is archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

    - `class BetaManagedAgentsFileNotFoundRunError:`

      A file resource referenced by the deployment no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

    - `class BetaManagedAgentsMemoryStoreArchivedRunError:`

      A memory store referenced by the deployment is archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

    - `class BetaManagedAgentsSkillNotFoundRunError:`

      A skill referenced by the deployment's agent no longer exists.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

    - `class BetaManagedAgentsSessionResourceNotFoundRunError:`

      A referenced resource no longer exists and its kind was not reported.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

    - `class BetaManagedAgentsWorkspaceArchivedRunError:`

      The deployment's workspace was archived.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

    - `class BetaManagedAgentsOrganizationDisabledRunError:`

      The deployment's organization is disabled.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

    - `class BetaManagedAgentsSessionRateLimitedRunError:`

      Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_RATE_LIMITED_ERROR("session_rate_limited_error")`

    - `class BetaManagedAgentsSessionCreationRejectedRunError:`

      The session create request was rejected with a non-retryable validation error.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SESSION_CREATION_REJECTED_ERROR("session_creation_rejected_error")`

    - `class BetaManagedAgentsUnknownRunError:`

      An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `UNKNOWN_ERROR("unknown_error")`

    - `class BetaManagedAgentsSelfHostedResourcesUnsupportedRunError:`

      The deployment configures resources, but its environment is self-hosted and cannot mount them.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

    - `class BetaManagedAgentsMcpEgressBlockedRunError:`

      An MCP server host used by the deployment's agent is blocked by the environment's network policy.

      - `String message`

        Human-readable error description.

      - `Type type`

        - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

  - `Optional<String> sessionId`

    Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.

  - `BetaManagedAgentsTriggerContext triggerContext`

    Describes what triggered a deployment run, with trigger-specific metadata.

    - `class BetaManagedAgentsScheduleTriggerContext:`

      The run was fired by the deployment's cron schedule.

      - `LocalDateTime scheduledAt`

        A timestamp in RFC 3339 format

      - `Type type`

        - `SCHEDULE("schedule")`

    - `class BetaManagedAgentsManualTriggerContext:`

      The run was started manually by creating a session directly against the deployment.

      - `Type type`

        - `MANUAL("manual")`

  - `Type type`

    - `DEPLOYMENT_RUN("deployment_run")`

### Beta Managed Agents Environment Archived Run Error

- `class BetaManagedAgentsEnvironmentArchivedRunError:`

  The deployment's environment was archived.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `ENVIRONMENT_ARCHIVED_ERROR("environment_archived_error")`

### Beta Managed Agents Environment Not Found Run Error

- `class BetaManagedAgentsEnvironmentNotFoundRunError:`

  The deployment's environment no longer exists.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `ENVIRONMENT_NOT_FOUND_ERROR("environment_not_found_error")`

### Beta Managed Agents File Not Found Run Error

- `class BetaManagedAgentsFileNotFoundRunError:`

  A file resource referenced by the deployment no longer exists.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `FILE_NOT_FOUND_ERROR("file_not_found_error")`

### Beta Managed Agents Manual Trigger Context

- `class BetaManagedAgentsManualTriggerContext:`

  The run was started manually by creating a session directly against the deployment.

  - `Type type`

    - `MANUAL("manual")`

### Beta Managed Agents MCP Egress Blocked Run Error

- `class BetaManagedAgentsMcpEgressBlockedRunError:`

  An MCP server host used by the deployment's agent is blocked by the environment's network policy.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `MCP_EGRESS_BLOCKED_ERROR("mcp_egress_blocked_error")`

### Beta Managed Agents Memory Store Archived Run Error

- `class BetaManagedAgentsMemoryStoreArchivedRunError:`

  A memory store referenced by the deployment is archived.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `MEMORY_STORE_ARCHIVED_ERROR("memory_store_archived_error")`

### Beta Managed Agents Organization Disabled Run Error

- `class BetaManagedAgentsOrganizationDisabledRunError:`

  The deployment's organization is disabled.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `ORGANIZATION_DISABLED_ERROR("organization_disabled_error")`

### Beta Managed Agents Schedule Trigger Context

- `class BetaManagedAgentsScheduleTriggerContext:`

  The run was fired by the deployment's cron schedule.

  - `LocalDateTime scheduledAt`

    A timestamp in RFC 3339 format

  - `Type type`

    - `SCHEDULE("schedule")`

### Beta Managed Agents Self Hosted Resources Unsupported Run Error

- `class BetaManagedAgentsSelfHostedResourcesUnsupportedRunError:`

  The deployment configures resources, but its environment is self-hosted and cannot mount them.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `SELF_HOSTED_RESOURCES_UNSUPPORTED_ERROR("self_hosted_resources_unsupported_error")`

### Beta Managed Agents Session Creation Rejected Run Error

- `class BetaManagedAgentsSessionCreationRejectedRunError:`

  The session create request was rejected with a non-retryable validation error.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `SESSION_CREATION_REJECTED_ERROR("session_creation_rejected_error")`

### Beta Managed Agents Session Rate Limited Run Error

- `class BetaManagedAgentsSessionRateLimitedRunError:`

  Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `SESSION_RATE_LIMITED_ERROR("session_rate_limited_error")`

### Beta Managed Agents Session Resource Not Found Run Error

- `class BetaManagedAgentsSessionResourceNotFoundRunError:`

  A referenced resource no longer exists and its kind was not reported.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `SESSION_RESOURCE_NOT_FOUND_ERROR("session_resource_not_found_error")`

### Beta Managed Agents Skill Not Found Run Error

- `class BetaManagedAgentsSkillNotFoundRunError:`

  A skill referenced by the deployment's agent no longer exists.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `SKILL_NOT_FOUND_ERROR("skill_not_found_error")`

### Beta Managed Agents Trigger Context

- `class BetaManagedAgentsTriggerContext: A class that can be one of several variants.union`

  Describes what triggered a deployment run, with trigger-specific metadata.

  - `class BetaManagedAgentsScheduleTriggerContext:`

    The run was fired by the deployment's cron schedule.

    - `LocalDateTime scheduledAt`

      A timestamp in RFC 3339 format

    - `Type type`

      - `SCHEDULE("schedule")`

  - `class BetaManagedAgentsManualTriggerContext:`

    The run was started manually by creating a session directly against the deployment.

    - `Type type`

      - `MANUAL("manual")`

### Beta Managed Agents Trigger Type

- `enum BetaManagedAgentsTriggerType:`

  What triggered a deployment run.

  - `SCHEDULE("schedule")`

  - `MANUAL("manual")`

### Beta Managed Agents Unknown Run Error

- `class BetaManagedAgentsUnknownRunError:`

  An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `UNKNOWN_ERROR("unknown_error")`

### Beta Managed Agents Vault Archived Run Error

- `class BetaManagedAgentsVaultArchivedRunError:`

  A vault referenced by the deployment is archived.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `VAULT_ARCHIVED_ERROR("vault_archived_error")`

### Beta Managed Agents Vault Not Found Run Error

- `class BetaManagedAgentsVaultNotFoundRunError:`

  A vault referenced by the deployment no longer exists.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `VAULT_NOT_FOUND_ERROR("vault_not_found_error")`

### Beta Managed Agents Workspace Archived Run Error

- `class BetaManagedAgentsWorkspaceArchivedRunError:`

  The deployment's workspace was archived.

  - `String message`

    Human-readable error description.

  - `Type type`

    - `WORKSPACE_ARCHIVED_ERROR("workspace_archived_error")`

# Vaults

## Create Vault

`BetaManagedAgentsVault beta().vaults().create(VaultCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/vaults`

Create Vault

### Parameters

- `VaultCreateParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `String displayName`

    Human-readable name for the vault. 1-255 characters.

  - `Optional<Metadata> metadata`

    Arbitrary key-value metadata to attach to the vault. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

### Returns

- `class BetaManagedAgentsVault:`

  A vault that stores credentials for use by agents during sessions.

  - `String id`

    Unique identifier for the vault.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String displayName`

    Human-readable name for the vault.

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the vault.

  - `Type type`

    - `VAULT("vault")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.BetaManagedAgentsVault;
import com.anthropic.models.beta.vaults.VaultCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        VaultCreateParams params = VaultCreateParams.builder()
            .displayName("Example vault")
            .build();
        BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().create(params);
    }
}
```

#### Response

```json
{
  "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "display_name": "Example vault",
  "metadata": {
    "environment": "production"
  },
  "type": "vault",
  "updated_at": "2026-03-15T10:00:00Z"
}
```

## List Vaults

`VaultListPage beta().vaults().list(VaultListParamsparams = VaultListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/vaults`

List Vaults

### Parameters

- `VaultListParams params`

  - `Optional<Boolean> includeArchived`

    Whether to include archived vaults in the results.

  - `Optional<Long> limit`

    Maximum number of vaults to return per page. Defaults to 20, maximum 100.

  - `Optional<String> page`

    Opaque pagination token from a previous `list_vaults` response.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsVault:`

  A vault that stores credentials for use by agents during sessions.

  - `String id`

    Unique identifier for the vault.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String displayName`

    Human-readable name for the vault.

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the vault.

  - `Type type`

    - `VAULT("vault")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.VaultListPage;
import com.anthropic.models.beta.vaults.VaultListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        VaultListPage page = client.beta().vaults().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
      "archived_at": null,
      "created_at": "2026-03-15T10:00:00Z",
      "display_name": "Example vault",
      "metadata": {
        "environment": "production"
      },
      "type": "vault",
      "updated_at": "2026-03-15T10:00:00Z"
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```

## Get Vault

`BetaManagedAgentsVault beta().vaults().retrieve(VaultRetrieveParamsparams = VaultRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/vaults/{vault_id}`

Get Vault

### Parameters

- `VaultRetrieveParams params`

  - `Optional<String> vaultId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsVault:`

  A vault that stores credentials for use by agents during sessions.

  - `String id`

    Unique identifier for the vault.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String displayName`

    Human-readable name for the vault.

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the vault.

  - `Type type`

    - `VAULT("vault")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.BetaManagedAgentsVault;
import com.anthropic.models.beta.vaults.VaultRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().retrieve("vlt_011CZkZDLs7fYzm1hXNPeRjv");
    }
}
```

#### Response

```json
{
  "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "display_name": "Example vault",
  "metadata": {
    "environment": "production"
  },
  "type": "vault",
  "updated_at": "2026-03-15T10:00:00Z"
}
```

## Update Vault

`BetaManagedAgentsVault beta().vaults().update(VaultUpdateParamsparams = VaultUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/vaults/{vault_id}`

Update Vault

### Parameters

- `VaultUpdateParams params`

  - `Optional<String> vaultId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<String> displayName`

    Updated human-readable name for the vault. 1-255 characters.

  - `Optional<Metadata> metadata`

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved.

### Returns

- `class BetaManagedAgentsVault:`

  A vault that stores credentials for use by agents during sessions.

  - `String id`

    Unique identifier for the vault.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String displayName`

    Human-readable name for the vault.

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the vault.

  - `Type type`

    - `VAULT("vault")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.BetaManagedAgentsVault;
import com.anthropic.models.beta.vaults.VaultUpdateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().update("vlt_011CZkZDLs7fYzm1hXNPeRjv");
    }
}
```

#### Response

```json
{
  "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "display_name": "Example vault",
  "metadata": {
    "environment": "production"
  },
  "type": "vault",
  "updated_at": "2026-03-15T10:00:00Z"
}
```

## Delete Vault

`BetaManagedAgentsDeletedVault beta().vaults().delete(VaultDeleteParamsparams = VaultDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/vaults/{vault_id}`

Delete Vault

### Parameters

- `VaultDeleteParams params`

  - `Optional<String> vaultId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeletedVault:`

  Confirmation of a deleted vault.

  - `String id`

    Unique identifier of the deleted vault.

  - `Type type`

    - `VAULT_DELETED("vault_deleted")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.BetaManagedAgentsDeletedVault;
import com.anthropic.models.beta.vaults.VaultDeleteParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsDeletedVault betaManagedAgentsDeletedVault = client.beta().vaults().delete("vlt_011CZkZDLs7fYzm1hXNPeRjv");
    }
}
```

#### Response

```json
{
  "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
  "type": "vault_deleted"
}
```

## Archive Vault

`BetaManagedAgentsVault beta().vaults().archive(VaultArchiveParamsparams = VaultArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/vaults/{vault_id}/archive`

Archive Vault

### Parameters

- `VaultArchiveParams params`

  - `Optional<String> vaultId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsVault:`

  A vault that stores credentials for use by agents during sessions.

  - `String id`

    Unique identifier for the vault.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String displayName`

    Human-readable name for the vault.

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the vault.

  - `Type type`

    - `VAULT("vault")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.BetaManagedAgentsVault;
import com.anthropic.models.beta.vaults.VaultArchiveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsVault betaManagedAgentsVault = client.beta().vaults().archive("vlt_011CZkZDLs7fYzm1hXNPeRjv");
    }
}
```

#### Response

```json
{
  "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
  "archived_at": null,
  "created_at": "2026-03-15T10:00:00Z",
  "display_name": "Example vault",
  "metadata": {
    "environment": "production"
  },
  "type": "vault",
  "updated_at": "2026-03-15T10:00:00Z"
}
```

## Domain Types

### Beta Managed Agents Deleted Vault

- `class BetaManagedAgentsDeletedVault:`

  Confirmation of a deleted vault.

  - `String id`

    Unique identifier of the deleted vault.

  - `Type type`

    - `VAULT_DELETED("vault_deleted")`

### Beta Managed Agents Vault

- `class BetaManagedAgentsVault:`

  A vault that stores credentials for use by agents during sessions.

  - `String id`

    Unique identifier for the vault.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String displayName`

    Human-readable name for the vault.

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the vault.

  - `Type type`

    - `VAULT("vault")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

# Credentials

## Create Credential

`BetaManagedAgentsCredential beta().vaults().credentials().create(CredentialCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/vaults/{vault_id}/credentials`

Create Credential

### Parameters

- `CredentialCreateParams params`

  - `Optional<String> vaultId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Auth auth`

    Authentication details for creating a credential.

    - `class BetaManagedAgentsMcpOAuthCreateParams:`

      Parameters for creating an MCP OAuth credential.

      - `String accessToken`

        OAuth access token.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `MCP_OAUTH("mcp_oauth")`

      - `Optional<LocalDateTime> expiresAt`

        A timestamp in RFC 3339 format

      - `Optional<BetaManagedAgentsMcpOAuthRefreshParams> refresh`

        OAuth refresh token parameters for creating a credential with refresh support.

        - `String clientId`

          OAuth client ID.

        - `String refreshToken`

          OAuth refresh token.

        - `String tokenEndpoint`

          Token endpoint URL used to refresh the access token.

        - `TokenEndpointAuth tokenEndpointAuth`

          Token endpoint requires no client authentication.

          - `class BetaManagedAgentsTokenEndpointAuthNoneParam:`

            Token endpoint requires no client authentication.

            - `Type type`

              - `NONE("none")`

          - `class BetaManagedAgentsTokenEndpointAuthBasicParam:`

            Token endpoint uses HTTP Basic authentication with client credentials.

            - `String clientSecret`

              OAuth client secret.

            - `Type type`

              - `CLIENT_SECRET_BASIC("client_secret_basic")`

          - `class BetaManagedAgentsTokenEndpointAuthPostParam:`

            Token endpoint uses POST body authentication with client credentials.

            - `String clientSecret`

              OAuth client secret.

            - `Type type`

              - `CLIENT_SECRET_POST("client_secret_post")`

        - `Optional<String> resource`

          OAuth resource indicator.

        - `Optional<String> scope`

          OAuth scope for the refresh request.

    - `class BetaManagedAgentsStaticBearerCreateParams:`

      Parameters for creating a static bearer token credential.

      - `String token`

        Static bearer token value.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `STATIC_BEARER("static_bearer")`

    - `class BetaManagedAgentsEnvironmentVariableCreateParams:`

      Parameters for creating an environment variable credential.

      - `BetaManagedAgentsCredentialNetworkingParams networking`

        Outbound hosts the secret value is substituted on.

        - `class BetaManagedAgentsUnrestrictedCredentialNetworkingParams:`

          Substitute the secret on any host the session's Environment network policy permits egress to. The Environment's network policy is the only boundary on where the secret can reach.

          - `Type type`

            - `UNRESTRICTED("unrestricted")`

        - `class BetaManagedAgentsLimitedCredentialNetworkingParams:`

          Substitute the secret only on requests to the listed hosts.

          - `List<String> allowedHosts`

            Hostnames on which the secret will be substituted. Each entry is a bare hostname (`api.example.com`), an IPv4 address (`192.0.2.1`), or a `*.`-prefixed wildcard (`*.example.com`). URLs, ports, paths, and IPv6 addresses are not accepted. At most 16 entries.

          - `Type type`

            - `LIMITED("limited")`

      - `String secretName`

        Name of the environment variable. Immutable after create.

      - `String secretValue`

        Secret value. Write-only; never returned in responses.

      - `Type type`

        - `ENVIRONMENT_VARIABLE("environment_variable")`

  - `Optional<String> displayName`

    Human-readable name for the credential. Up to 255 characters.

  - `Optional<Metadata> metadata`

    Arbitrary key-value metadata to attach to the credential. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

### Returns

- `class BetaManagedAgentsCredential:`

  A credential stored in a vault. Sensitive fields are never returned in responses.

  - `String id`

    Unique identifier for the credential.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Auth auth`

    Authentication details for a credential.

    - `class BetaManagedAgentsMcpOAuthAuthResponse:`

      OAuth credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `MCP_OAUTH("mcp_oauth")`

      - `Optional<LocalDateTime> expiresAt`

        A timestamp in RFC 3339 format

      - `Optional<BetaManagedAgentsMcpOAuthRefreshResponse> refresh`

        OAuth refresh token configuration returned in credential responses.

        - `String clientId`

          OAuth client ID.

        - `String tokenEndpoint`

          Token endpoint URL used to refresh the access token.

        - `TokenEndpointAuth tokenEndpointAuth`

          Token endpoint requires no client authentication.

          - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:`

            Token endpoint requires no client authentication.

            - `Type type`

              - `NONE("none")`

          - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:`

            Token endpoint uses HTTP Basic authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_BASIC("client_secret_basic")`

          - `class BetaManagedAgentsTokenEndpointAuthPostResponse:`

            Token endpoint uses POST body authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_POST("client_secret_post")`

        - `Optional<String> resource`

          OAuth resource indicator.

        - `Optional<String> scope`

          OAuth scope for the refresh request.

    - `class BetaManagedAgentsStaticBearerAuthResponse:`

      Static bearer token credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `STATIC_BEARER("static_bearer")`

    - `class BetaManagedAgentsEnvironmentVariableAuthResponse:`

      Environment variable credential details. The secret value is never returned.

      - `Networking networking`

        Outbound hosts the secret value is substituted on.

        - `class BetaManagedAgentsUnrestrictedCredentialNetworkingResponse:`

          The secret is substituted on any host the session's Environment network policy permits egress to.

          - `Type type`

            - `UNRESTRICTED("unrestricted")`

        - `class BetaManagedAgentsLimitedCredentialNetworkingResponse:`

          The secret is substituted only on requests to the listed hosts.

          - `List<String> allowedHosts`

            Hostnames on which the secret will be substituted. An entry matches the request host exactly; a `*.`-prefixed entry matches any subdomain of the named domain but not the domain itself.

          - `Type type`

            - `LIMITED("limited")`

      - `String secretName`

        Name of the environment variable.

      - `Type type`

        - `ENVIRONMENT_VARIABLE("environment_variable")`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the credential.

  - `Type type`

    - `VAULT_CREDENTIAL("vault_credential")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `String vaultId`

    Identifier of the vault this credential belongs to.

  - `Optional<String> displayName`

    Human-readable name for the credential.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential;
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsStaticBearerCreateParams;
import com.anthropic.models.beta.vaults.credentials.CredentialCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        CredentialCreateParams params = CredentialCreateParams.builder()
            .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv")
            .auth(BetaManagedAgentsStaticBearerCreateParams.builder()
                .token("bearer_exampletoken")
                .mcpServerUrl("https://example-server.modelcontextprotocol.io/sse")
                .type(BetaManagedAgentsStaticBearerCreateParams.Type.STATIC_BEARER)
                .build())
            .build();
        BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().create(params);
    }
}
```

#### Response

```json
{
  "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw",
  "archived_at": null,
  "auth": {
    "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse",
    "type": "static_bearer"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "metadata": {
    "environment": "production"
  },
  "type": "vault_credential",
  "updated_at": "2026-03-15T10:00:00Z",
  "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
  "display_name": "Example credential"
}
```

## List Credentials

`CredentialListPage beta().vaults().credentials().list(CredentialListParamsparams = CredentialListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/vaults/{vault_id}/credentials`

List Credentials

### Parameters

- `CredentialListParams params`

  - `Optional<String> vaultId`

  - `Optional<Boolean> includeArchived`

    Whether to include archived credentials in the results.

  - `Optional<Long> limit`

    Maximum number of credentials to return per page. Defaults to 20, maximum 100.

  - `Optional<String> page`

    Opaque pagination token from a previous `list_credentials` response.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsCredential:`

  A credential stored in a vault. Sensitive fields are never returned in responses.

  - `String id`

    Unique identifier for the credential.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Auth auth`

    Authentication details for a credential.

    - `class BetaManagedAgentsMcpOAuthAuthResponse:`

      OAuth credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `MCP_OAUTH("mcp_oauth")`

      - `Optional<LocalDateTime> expiresAt`

        A timestamp in RFC 3339 format

      - `Optional<BetaManagedAgentsMcpOAuthRefreshResponse> refresh`

        OAuth refresh token configuration returned in credential responses.

        - `String clientId`

          OAuth client ID.

        - `String tokenEndpoint`

          Token endpoint URL used to refresh the access token.

        - `TokenEndpointAuth tokenEndpointAuth`

          Token endpoint requires no client authentication.

          - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:`

            Token endpoint requires no client authentication.

            - `Type type`

              - `NONE("none")`

          - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:`

            Token endpoint uses HTTP Basic authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_BASIC("client_secret_basic")`

          - `class BetaManagedAgentsTokenEndpointAuthPostResponse:`

            Token endpoint uses POST body authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_POST("client_secret_post")`

        - `Optional<String> resource`

          OAuth resource indicator.

        - `Optional<String> scope`

          OAuth scope for the refresh request.

    - `class BetaManagedAgentsStaticBearerAuthResponse:`

      Static bearer token credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `STATIC_BEARER("static_bearer")`

    - `class BetaManagedAgentsEnvironmentVariableAuthResponse:`

      Environment variable credential details. The secret value is never returned.

      - `Networking networking`

        Outbound hosts the secret value is substituted on.

        - `class BetaManagedAgentsUnrestrictedCredentialNetworkingResponse:`

          The secret is substituted on any host the session's Environment network policy permits egress to.

          - `Type type`

            - `UNRESTRICTED("unrestricted")`

        - `class BetaManagedAgentsLimitedCredentialNetworkingResponse:`

          The secret is substituted only on requests to the listed hosts.

          - `List<String> allowedHosts`

            Hostnames on which the secret will be substituted. An entry matches the request host exactly; a `*.`-prefixed entry matches any subdomain of the named domain but not the domain itself.

          - `Type type`

            - `LIMITED("limited")`

      - `String secretName`

        Name of the environment variable.

      - `Type type`

        - `ENVIRONMENT_VARIABLE("environment_variable")`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the credential.

  - `Type type`

    - `VAULT_CREDENTIAL("vault_credential")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `String vaultId`

    Identifier of the vault this credential belongs to.

  - `Optional<String> displayName`

    Human-readable name for the credential.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.credentials.CredentialListPage;
import com.anthropic.models.beta.vaults.credentials.CredentialListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        CredentialListPage page = client.beta().vaults().credentials().list("vlt_011CZkZDLs7fYzm1hXNPeRjv");
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw",
      "archived_at": null,
      "auth": {
        "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse",
        "type": "static_bearer"
      },
      "created_at": "2026-03-15T10:00:00Z",
      "metadata": {
        "environment": "production"
      },
      "type": "vault_credential",
      "updated_at": "2026-03-15T10:00:00Z",
      "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
      "display_name": "Example credential"
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```

## Get Credential

`BetaManagedAgentsCredential beta().vaults().credentials().retrieve(CredentialRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/vaults/{vault_id}/credentials/{credential_id}`

Get Credential

### Parameters

- `CredentialRetrieveParams params`

  - `String vaultId`

  - `Optional<String> credentialId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsCredential:`

  A credential stored in a vault. Sensitive fields are never returned in responses.

  - `String id`

    Unique identifier for the credential.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Auth auth`

    Authentication details for a credential.

    - `class BetaManagedAgentsMcpOAuthAuthResponse:`

      OAuth credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `MCP_OAUTH("mcp_oauth")`

      - `Optional<LocalDateTime> expiresAt`

        A timestamp in RFC 3339 format

      - `Optional<BetaManagedAgentsMcpOAuthRefreshResponse> refresh`

        OAuth refresh token configuration returned in credential responses.

        - `String clientId`

          OAuth client ID.

        - `String tokenEndpoint`

          Token endpoint URL used to refresh the access token.

        - `TokenEndpointAuth tokenEndpointAuth`

          Token endpoint requires no client authentication.

          - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:`

            Token endpoint requires no client authentication.

            - `Type type`

              - `NONE("none")`

          - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:`

            Token endpoint uses HTTP Basic authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_BASIC("client_secret_basic")`

          - `class BetaManagedAgentsTokenEndpointAuthPostResponse:`

            Token endpoint uses POST body authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_POST("client_secret_post")`

        - `Optional<String> resource`

          OAuth resource indicator.

        - `Optional<String> scope`

          OAuth scope for the refresh request.

    - `class BetaManagedAgentsStaticBearerAuthResponse:`

      Static bearer token credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `STATIC_BEARER("static_bearer")`

    - `class BetaManagedAgentsEnvironmentVariableAuthResponse:`

      Environment variable credential details. The secret value is never returned.

      - `Networking networking`

        Outbound hosts the secret value is substituted on.

        - `class BetaManagedAgentsUnrestrictedCredentialNetworkingResponse:`

          The secret is substituted on any host the session's Environment network policy permits egress to.

          - `Type type`

            - `UNRESTRICTED("unrestricted")`

        - `class BetaManagedAgentsLimitedCredentialNetworkingResponse:`

          The secret is substituted only on requests to the listed hosts.

          - `List<String> allowedHosts`

            Hostnames on which the secret will be substituted. An entry matches the request host exactly; a `*.`-prefixed entry matches any subdomain of the named domain but not the domain itself.

          - `Type type`

            - `LIMITED("limited")`

      - `String secretName`

        Name of the environment variable.

      - `Type type`

        - `ENVIRONMENT_VARIABLE("environment_variable")`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the credential.

  - `Type type`

    - `VAULT_CREDENTIAL("vault_credential")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `String vaultId`

    Identifier of the vault this credential belongs to.

  - `Optional<String> displayName`

    Human-readable name for the credential.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential;
import com.anthropic.models.beta.vaults.credentials.CredentialRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        CredentialRetrieveParams params = CredentialRetrieveParams.builder()
            .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv")
            .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw")
            .build();
        BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().retrieve(params);
    }
}
```

#### Response

```json
{
  "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw",
  "archived_at": null,
  "auth": {
    "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse",
    "type": "static_bearer"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "metadata": {
    "environment": "production"
  },
  "type": "vault_credential",
  "updated_at": "2026-03-15T10:00:00Z",
  "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
  "display_name": "Example credential"
}
```

## Update Credential

`BetaManagedAgentsCredential beta().vaults().credentials().update(CredentialUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/vaults/{vault_id}/credentials/{credential_id}`

Update Credential

### Parameters

- `CredentialUpdateParams params`

  - `String vaultId`

  - `Optional<String> credentialId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<Auth> auth`

    Updated authentication details for a credential.

    - `class BetaManagedAgentsMcpOAuthUpdateParams:`

      Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable.

      - `Type type`

        - `MCP_OAUTH("mcp_oauth")`

      - `Optional<String> accessToken`

        Updated OAuth access token.

      - `Optional<LocalDateTime> expiresAt`

        A timestamp in RFC 3339 format

      - `Optional<BetaManagedAgentsMcpOAuthRefreshUpdateParams> refresh`

        Parameters for updating OAuth refresh token configuration.

        - `Optional<String> refreshToken`

          Updated OAuth refresh token.

        - `Optional<String> scope`

          Updated OAuth scope for the refresh request.

        - `Optional<TokenEndpointAuth> tokenEndpointAuth`

          Updated HTTP Basic authentication parameters for the token endpoint.

          - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:`

            Updated HTTP Basic authentication parameters for the token endpoint.

            - `Type type`

              - `CLIENT_SECRET_BASIC("client_secret_basic")`

            - `Optional<String> clientSecret`

              Updated OAuth client secret.

          - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:`

            Updated POST body authentication parameters for the token endpoint.

            - `Type type`

              - `CLIENT_SECRET_POST("client_secret_post")`

            - `Optional<String> clientSecret`

              Updated OAuth client secret.

    - `class BetaManagedAgentsStaticBearerUpdateParams:`

      Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable.

      - `Type type`

        - `STATIC_BEARER("static_bearer")`

      - `Optional<String> token`

        Updated static bearer token value.

    - `class BetaManagedAgentsEnvironmentVariableUpdateParams:`

      Parameters for updating an environment variable credential. `secret_name` is immutable.

      - `Type type`

        - `ENVIRONMENT_VARIABLE("environment_variable")`

      - `Optional<BetaManagedAgentsCredentialNetworkingParams> networking`

        Updated networking scope. Full replacement.

        - `class BetaManagedAgentsUnrestrictedCredentialNetworkingParams:`

          Substitute the secret on any host the session's Environment network policy permits egress to. The Environment's network policy is the only boundary on where the secret can reach.

          - `Type type`

            - `UNRESTRICTED("unrestricted")`

        - `class BetaManagedAgentsLimitedCredentialNetworkingParams:`

          Substitute the secret only on requests to the listed hosts.

          - `List<String> allowedHosts`

            Hostnames on which the secret will be substituted. Each entry is a bare hostname (`api.example.com`), an IPv4 address (`192.0.2.1`), or a `*.`-prefixed wildcard (`*.example.com`). URLs, ports, paths, and IPv6 addresses are not accepted. At most 16 entries.

          - `Type type`

            - `LIMITED("limited")`

      - `Optional<String> secretValue`

        Updated secret value.

  - `Optional<String> displayName`

    Updated human-readable name for the credential. 1-255 characters.

  - `Optional<Metadata> metadata`

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved.

### Returns

- `class BetaManagedAgentsCredential:`

  A credential stored in a vault. Sensitive fields are never returned in responses.

  - `String id`

    Unique identifier for the credential.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Auth auth`

    Authentication details for a credential.

    - `class BetaManagedAgentsMcpOAuthAuthResponse:`

      OAuth credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `MCP_OAUTH("mcp_oauth")`

      - `Optional<LocalDateTime> expiresAt`

        A timestamp in RFC 3339 format

      - `Optional<BetaManagedAgentsMcpOAuthRefreshResponse> refresh`

        OAuth refresh token configuration returned in credential responses.

        - `String clientId`

          OAuth client ID.

        - `String tokenEndpoint`

          Token endpoint URL used to refresh the access token.

        - `TokenEndpointAuth tokenEndpointAuth`

          Token endpoint requires no client authentication.

          - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:`

            Token endpoint requires no client authentication.

            - `Type type`

              - `NONE("none")`

          - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:`

            Token endpoint uses HTTP Basic authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_BASIC("client_secret_basic")`

          - `class BetaManagedAgentsTokenEndpointAuthPostResponse:`

            Token endpoint uses POST body authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_POST("client_secret_post")`

        - `Optional<String> resource`

          OAuth resource indicator.

        - `Optional<String> scope`

          OAuth scope for the refresh request.

    - `class BetaManagedAgentsStaticBearerAuthResponse:`

      Static bearer token credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `STATIC_BEARER("static_bearer")`

    - `class BetaManagedAgentsEnvironmentVariableAuthResponse:`

      Environment variable credential details. The secret value is never returned.

      - `Networking networking`

        Outbound hosts the secret value is substituted on.

        - `class BetaManagedAgentsUnrestrictedCredentialNetworkingResponse:`

          The secret is substituted on any host the session's Environment network policy permits egress to.

          - `Type type`

            - `UNRESTRICTED("unrestricted")`

        - `class BetaManagedAgentsLimitedCredentialNetworkingResponse:`

          The secret is substituted only on requests to the listed hosts.

          - `List<String> allowedHosts`

            Hostnames on which the secret will be substituted. An entry matches the request host exactly; a `*.`-prefixed entry matches any subdomain of the named domain but not the domain itself.

          - `Type type`

            - `LIMITED("limited")`

      - `String secretName`

        Name of the environment variable.

      - `Type type`

        - `ENVIRONMENT_VARIABLE("environment_variable")`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the credential.

  - `Type type`

    - `VAULT_CREDENTIAL("vault_credential")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `String vaultId`

    Identifier of the vault this credential belongs to.

  - `Optional<String> displayName`

    Human-readable name for the credential.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential;
import com.anthropic.models.beta.vaults.credentials.CredentialUpdateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        CredentialUpdateParams params = CredentialUpdateParams.builder()
            .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv")
            .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw")
            .build();
        BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().update(params);
    }
}
```

#### Response

```json
{
  "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw",
  "archived_at": null,
  "auth": {
    "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse",
    "type": "static_bearer"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "metadata": {
    "environment": "production"
  },
  "type": "vault_credential",
  "updated_at": "2026-03-15T10:00:00Z",
  "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
  "display_name": "Example credential"
}
```

## Delete Credential

`BetaManagedAgentsDeletedCredential beta().vaults().credentials().delete(CredentialDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/vaults/{vault_id}/credentials/{credential_id}`

Delete Credential

### Parameters

- `CredentialDeleteParams params`

  - `String vaultId`

  - `Optional<String> credentialId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeletedCredential:`

  Confirmation of a deleted credential.

  - `String id`

    Unique identifier of the deleted credential.

  - `Type type`

    - `VAULT_CREDENTIAL_DELETED("vault_credential_deleted")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsDeletedCredential;
import com.anthropic.models.beta.vaults.credentials.CredentialDeleteParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        CredentialDeleteParams params = CredentialDeleteParams.builder()
            .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv")
            .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw")
            .build();
        BetaManagedAgentsDeletedCredential betaManagedAgentsDeletedCredential = client.beta().vaults().credentials().delete(params);
    }
}
```

#### Response

```json
{
  "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw",
  "type": "vault_credential_deleted"
}
```

## Archive Credential

`BetaManagedAgentsCredential beta().vaults().credentials().archive(CredentialArchiveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive`

Archive Credential

### Parameters

- `CredentialArchiveParams params`

  - `String vaultId`

  - `Optional<String> credentialId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsCredential:`

  A credential stored in a vault. Sensitive fields are never returned in responses.

  - `String id`

    Unique identifier for the credential.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Auth auth`

    Authentication details for a credential.

    - `class BetaManagedAgentsMcpOAuthAuthResponse:`

      OAuth credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `MCP_OAUTH("mcp_oauth")`

      - `Optional<LocalDateTime> expiresAt`

        A timestamp in RFC 3339 format

      - `Optional<BetaManagedAgentsMcpOAuthRefreshResponse> refresh`

        OAuth refresh token configuration returned in credential responses.

        - `String clientId`

          OAuth client ID.

        - `String tokenEndpoint`

          Token endpoint URL used to refresh the access token.

        - `TokenEndpointAuth tokenEndpointAuth`

          Token endpoint requires no client authentication.

          - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:`

            Token endpoint requires no client authentication.

            - `Type type`

              - `NONE("none")`

          - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:`

            Token endpoint uses HTTP Basic authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_BASIC("client_secret_basic")`

          - `class BetaManagedAgentsTokenEndpointAuthPostResponse:`

            Token endpoint uses POST body authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_POST("client_secret_post")`

        - `Optional<String> resource`

          OAuth resource indicator.

        - `Optional<String> scope`

          OAuth scope for the refresh request.

    - `class BetaManagedAgentsStaticBearerAuthResponse:`

      Static bearer token credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `STATIC_BEARER("static_bearer")`

    - `class BetaManagedAgentsEnvironmentVariableAuthResponse:`

      Environment variable credential details. The secret value is never returned.

      - `Networking networking`

        Outbound hosts the secret value is substituted on.

        - `class BetaManagedAgentsUnrestrictedCredentialNetworkingResponse:`

          The secret is substituted on any host the session's Environment network policy permits egress to.

          - `Type type`

            - `UNRESTRICTED("unrestricted")`

        - `class BetaManagedAgentsLimitedCredentialNetworkingResponse:`

          The secret is substituted only on requests to the listed hosts.

          - `List<String> allowedHosts`

            Hostnames on which the secret will be substituted. An entry matches the request host exactly; a `*.`-prefixed entry matches any subdomain of the named domain but not the domain itself.

          - `Type type`

            - `LIMITED("limited")`

      - `String secretName`

        Name of the environment variable.

      - `Type type`

        - `ENVIRONMENT_VARIABLE("environment_variable")`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the credential.

  - `Type type`

    - `VAULT_CREDENTIAL("vault_credential")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `String vaultId`

    Identifier of the vault this credential belongs to.

  - `Optional<String> displayName`

    Human-readable name for the credential.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredential;
import com.anthropic.models.beta.vaults.credentials.CredentialArchiveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        CredentialArchiveParams params = CredentialArchiveParams.builder()
            .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv")
            .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw")
            .build();
        BetaManagedAgentsCredential betaManagedAgentsCredential = client.beta().vaults().credentials().archive(params);
    }
}
```

#### Response

```json
{
  "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw",
  "archived_at": null,
  "auth": {
    "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse",
    "type": "static_bearer"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "metadata": {
    "environment": "production"
  },
  "type": "vault_credential",
  "updated_at": "2026-03-15T10:00:00Z",
  "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
  "display_name": "Example credential"
}
```

## Validate Credential

`BetaManagedAgentsCredentialValidation beta().vaults().credentials().mcpOAuthValidate(CredentialMcpOAuthValidateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate`

Validate Credential

### Parameters

- `CredentialMcpOAuthValidateParams params`

  - `String vaultId`

  - `Optional<String> credentialId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsCredentialValidation:`

  Result of live-probing a credential against its configured MCP server.

  - `String credentialId`

    Unique identifier of the credential that was validated.

  - `boolean hasRefreshToken`

    Whether the credential has a refresh token configured.

  - `Optional<BetaManagedAgentsMcpProbe> mcpProbe`

    The failing step of an MCP validation probe.

    - `Optional<BetaManagedAgentsRefreshHttpResponse> httpResponse`

      An HTTP response captured during a credential validation probe.

      - `String body`

        Response body. May be truncated and has sensitive values scrubbed.

      - `boolean bodyTruncated`

        Whether `body` was truncated.

      - `String contentType`

        Value of the `Content-Type` response header.

      - `long statusCode`

        HTTP status code.

    - `String method`

      The MCP method that failed (for example `initialize` or `tools/list`).

  - `Optional<BetaManagedAgentsRefreshObject> refresh`

    Outcome of a refresh-token exchange attempted during credential validation.

    - `Optional<BetaManagedAgentsRefreshHttpResponse> httpResponse`

      An HTTP response captured during a credential validation probe.

    - `Status status`

      Outcome of a refresh-token exchange attempted during credential validation.

      - `SUCCEEDED("succeeded")`

      - `FAILED("failed")`

      - `CONNECT_ERROR("connect_error")`

      - `NO_REFRESH_TOKEN("no_refresh_token")`

  - `BetaManagedAgentsCredentialValidationStatus status`

    Overall verdict of a credential validation probe.

    - `VALID("valid")`

    - `INVALID("invalid")`

    - `UNKNOWN("unknown")`

  - `Type type`

    - `VAULT_CREDENTIAL_VALIDATION("vault_credential_validation")`

  - `LocalDateTime validatedAt`

    A timestamp in RFC 3339 format

  - `String vaultId`

    Identifier of the vault containing the credential.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsCredentialValidation;
import com.anthropic.models.beta.vaults.credentials.CredentialMcpOAuthValidateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        CredentialMcpOAuthValidateParams params = CredentialMcpOAuthValidateParams.builder()
            .vaultId("vlt_011CZkZDLs7fYzm1hXNPeRjv")
            .credentialId("vcrd_011CZkZEMt8gZan2iYOQfSkw")
            .build();
        BetaManagedAgentsCredentialValidation betaManagedAgentsCredentialValidation = client.beta().vaults().credentials().mcpOAuthValidate(params);
    }
}
```

#### Response

```json
{
  "credential_id": "vcrd_011CZkZEMt8gZan2iYOQfSkw",
  "has_refresh_token": true,
  "mcp_probe": {
    "http_response": {
      "body": "body",
      "body_truncated": true,
      "content_type": "content_type",
      "status_code": 0
    },
    "method": "method"
  },
  "refresh": {
    "http_response": {
      "body": "body",
      "body_truncated": true,
      "content_type": "content_type",
      "status_code": 0
    },
    "status": "succeeded"
  },
  "status": "valid",
  "type": "vault_credential_validation",
  "validated_at": "2026-03-15T10:00:00Z",
  "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv"
}
```

## Domain Types

### Beta Managed Agents Credential

- `class BetaManagedAgentsCredential:`

  A credential stored in a vault. Sensitive fields are never returned in responses.

  - `String id`

    Unique identifier for the credential.

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Auth auth`

    Authentication details for a credential.

    - `class BetaManagedAgentsMcpOAuthAuthResponse:`

      OAuth credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `MCP_OAUTH("mcp_oauth")`

      - `Optional<LocalDateTime> expiresAt`

        A timestamp in RFC 3339 format

      - `Optional<BetaManagedAgentsMcpOAuthRefreshResponse> refresh`

        OAuth refresh token configuration returned in credential responses.

        - `String clientId`

          OAuth client ID.

        - `String tokenEndpoint`

          Token endpoint URL used to refresh the access token.

        - `TokenEndpointAuth tokenEndpointAuth`

          Token endpoint requires no client authentication.

          - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:`

            Token endpoint requires no client authentication.

            - `Type type`

              - `NONE("none")`

          - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:`

            Token endpoint uses HTTP Basic authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_BASIC("client_secret_basic")`

          - `class BetaManagedAgentsTokenEndpointAuthPostResponse:`

            Token endpoint uses POST body authentication with client credentials.

            - `Type type`

              - `CLIENT_SECRET_POST("client_secret_post")`

        - `Optional<String> resource`

          OAuth resource indicator.

        - `Optional<String> scope`

          OAuth scope for the refresh request.

    - `class BetaManagedAgentsStaticBearerAuthResponse:`

      Static bearer token credential details for an MCP server.

      - `String mcpServerUrl`

        URL of the MCP server this credential authenticates against.

      - `Type type`

        - `STATIC_BEARER("static_bearer")`

    - `class BetaManagedAgentsEnvironmentVariableAuthResponse:`

      Environment variable credential details. The secret value is never returned.

      - `Networking networking`

        Outbound hosts the secret value is substituted on.

        - `class BetaManagedAgentsUnrestrictedCredentialNetworkingResponse:`

          The secret is substituted on any host the session's Environment network policy permits egress to.

          - `Type type`

            - `UNRESTRICTED("unrestricted")`

        - `class BetaManagedAgentsLimitedCredentialNetworkingResponse:`

          The secret is substituted only on requests to the listed hosts.

          - `List<String> allowedHosts`

            Hostnames on which the secret will be substituted. An entry matches the request host exactly; a `*.`-prefixed entry matches any subdomain of the named domain but not the domain itself.

          - `Type type`

            - `LIMITED("limited")`

      - `String secretName`

        Name of the environment variable.

      - `Type type`

        - `ENVIRONMENT_VARIABLE("environment_variable")`

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata attached to the credential.

  - `Type type`

    - `VAULT_CREDENTIAL("vault_credential")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `String vaultId`

    Identifier of the vault this credential belongs to.

  - `Optional<String> displayName`

    Human-readable name for the credential.

### Beta Managed Agents Credential Networking Params

- `class BetaManagedAgentsCredentialNetworkingParams: A class that can be one of several variants.union`

  Substitute the secret on any host the session's Environment network policy permits egress to. The Environment's network policy is the only boundary on where the secret can reach.

  - `class BetaManagedAgentsUnrestrictedCredentialNetworkingParams:`

    Substitute the secret on any host the session's Environment network policy permits egress to. The Environment's network policy is the only boundary on where the secret can reach.

    - `Type type`

      - `UNRESTRICTED("unrestricted")`

  - `class BetaManagedAgentsLimitedCredentialNetworkingParams:`

    Substitute the secret only on requests to the listed hosts.

    - `List<String> allowedHosts`

      Hostnames on which the secret will be substituted. Each entry is a bare hostname (`api.example.com`), an IPv4 address (`192.0.2.1`), or a `*.`-prefixed wildcard (`*.example.com`). URLs, ports, paths, and IPv6 addresses are not accepted. At most 16 entries.

    - `Type type`

      - `LIMITED("limited")`

### Beta Managed Agents Credential Validation

- `class BetaManagedAgentsCredentialValidation:`

  Result of live-probing a credential against its configured MCP server.

  - `String credentialId`

    Unique identifier of the credential that was validated.

  - `boolean hasRefreshToken`

    Whether the credential has a refresh token configured.

  - `Optional<BetaManagedAgentsMcpProbe> mcpProbe`

    The failing step of an MCP validation probe.

    - `Optional<BetaManagedAgentsRefreshHttpResponse> httpResponse`

      An HTTP response captured during a credential validation probe.

      - `String body`

        Response body. May be truncated and has sensitive values scrubbed.

      - `boolean bodyTruncated`

        Whether `body` was truncated.

      - `String contentType`

        Value of the `Content-Type` response header.

      - `long statusCode`

        HTTP status code.

    - `String method`

      The MCP method that failed (for example `initialize` or `tools/list`).

  - `Optional<BetaManagedAgentsRefreshObject> refresh`

    Outcome of a refresh-token exchange attempted during credential validation.

    - `Optional<BetaManagedAgentsRefreshHttpResponse> httpResponse`

      An HTTP response captured during a credential validation probe.

    - `Status status`

      Outcome of a refresh-token exchange attempted during credential validation.

      - `SUCCEEDED("succeeded")`

      - `FAILED("failed")`

      - `CONNECT_ERROR("connect_error")`

      - `NO_REFRESH_TOKEN("no_refresh_token")`

  - `BetaManagedAgentsCredentialValidationStatus status`

    Overall verdict of a credential validation probe.

    - `VALID("valid")`

    - `INVALID("invalid")`

    - `UNKNOWN("unknown")`

  - `Type type`

    - `VAULT_CREDENTIAL_VALIDATION("vault_credential_validation")`

  - `LocalDateTime validatedAt`

    A timestamp in RFC 3339 format

  - `String vaultId`

    Identifier of the vault containing the credential.

### Beta Managed Agents Credential Validation Status

- `enum BetaManagedAgentsCredentialValidationStatus:`

  Overall verdict of a credential validation probe.

  - `VALID("valid")`

  - `INVALID("invalid")`

  - `UNKNOWN("unknown")`

### Beta Managed Agents Deleted Credential

- `class BetaManagedAgentsDeletedCredential:`

  Confirmation of a deleted credential.

  - `String id`

    Unique identifier of the deleted credential.

  - `Type type`

    - `VAULT_CREDENTIAL_DELETED("vault_credential_deleted")`

### Beta Managed Agents Environment Variable Auth Response

- `class BetaManagedAgentsEnvironmentVariableAuthResponse:`

  Environment variable credential details. The secret value is never returned.

  - `Networking networking`

    Outbound hosts the secret value is substituted on.

    - `class BetaManagedAgentsUnrestrictedCredentialNetworkingResponse:`

      The secret is substituted on any host the session's Environment network policy permits egress to.

      - `Type type`

        - `UNRESTRICTED("unrestricted")`

    - `class BetaManagedAgentsLimitedCredentialNetworkingResponse:`

      The secret is substituted only on requests to the listed hosts.

      - `List<String> allowedHosts`

        Hostnames on which the secret will be substituted. An entry matches the request host exactly; a `*.`-prefixed entry matches any subdomain of the named domain but not the domain itself.

      - `Type type`

        - `LIMITED("limited")`

  - `String secretName`

    Name of the environment variable.

  - `Type type`

    - `ENVIRONMENT_VARIABLE("environment_variable")`

### Beta Managed Agents Environment Variable Create Params

- `class BetaManagedAgentsEnvironmentVariableCreateParams:`

  Parameters for creating an environment variable credential.

  - `BetaManagedAgentsCredentialNetworkingParams networking`

    Outbound hosts the secret value is substituted on.

    - `class BetaManagedAgentsUnrestrictedCredentialNetworkingParams:`

      Substitute the secret on any host the session's Environment network policy permits egress to. The Environment's network policy is the only boundary on where the secret can reach.

      - `Type type`

        - `UNRESTRICTED("unrestricted")`

    - `class BetaManagedAgentsLimitedCredentialNetworkingParams:`

      Substitute the secret only on requests to the listed hosts.

      - `List<String> allowedHosts`

        Hostnames on which the secret will be substituted. Each entry is a bare hostname (`api.example.com`), an IPv4 address (`192.0.2.1`), or a `*.`-prefixed wildcard (`*.example.com`). URLs, ports, paths, and IPv6 addresses are not accepted. At most 16 entries.

      - `Type type`

        - `LIMITED("limited")`

  - `String secretName`

    Name of the environment variable. Immutable after create.

  - `String secretValue`

    Secret value. Write-only; never returned in responses.

  - `Type type`

    - `ENVIRONMENT_VARIABLE("environment_variable")`

### Beta Managed Agents Environment Variable Update Params

- `class BetaManagedAgentsEnvironmentVariableUpdateParams:`

  Parameters for updating an environment variable credential. `secret_name` is immutable.

  - `Type type`

    - `ENVIRONMENT_VARIABLE("environment_variable")`

  - `Optional<BetaManagedAgentsCredentialNetworkingParams> networking`

    Updated networking scope. Full replacement.

    - `class BetaManagedAgentsUnrestrictedCredentialNetworkingParams:`

      Substitute the secret on any host the session's Environment network policy permits egress to. The Environment's network policy is the only boundary on where the secret can reach.

      - `Type type`

        - `UNRESTRICTED("unrestricted")`

    - `class BetaManagedAgentsLimitedCredentialNetworkingParams:`

      Substitute the secret only on requests to the listed hosts.

      - `List<String> allowedHosts`

        Hostnames on which the secret will be substituted. Each entry is a bare hostname (`api.example.com`), an IPv4 address (`192.0.2.1`), or a `*.`-prefixed wildcard (`*.example.com`). URLs, ports, paths, and IPv6 addresses are not accepted. At most 16 entries.

      - `Type type`

        - `LIMITED("limited")`

  - `Optional<String> secretValue`

    Updated secret value.

### Beta Managed Agents Limited Credential Networking Params

- `class BetaManagedAgentsLimitedCredentialNetworkingParams:`

  Substitute the secret only on requests to the listed hosts.

  - `List<String> allowedHosts`

    Hostnames on which the secret will be substituted. Each entry is a bare hostname (`api.example.com`), an IPv4 address (`192.0.2.1`), or a `*.`-prefixed wildcard (`*.example.com`). URLs, ports, paths, and IPv6 addresses are not accepted. At most 16 entries.

  - `Type type`

    - `LIMITED("limited")`

### Beta Managed Agents Limited Credential Networking Response

- `class BetaManagedAgentsLimitedCredentialNetworkingResponse:`

  The secret is substituted only on requests to the listed hosts.

  - `List<String> allowedHosts`

    Hostnames on which the secret will be substituted. An entry matches the request host exactly; a `*.`-prefixed entry matches any subdomain of the named domain but not the domain itself.

  - `Type type`

    - `LIMITED("limited")`

### Beta Managed Agents MCP OAuth Auth Response

- `class BetaManagedAgentsMcpOAuthAuthResponse:`

  OAuth credential details for an MCP server.

  - `String mcpServerUrl`

    URL of the MCP server this credential authenticates against.

  - `Type type`

    - `MCP_OAUTH("mcp_oauth")`

  - `Optional<LocalDateTime> expiresAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsMcpOAuthRefreshResponse> refresh`

    OAuth refresh token configuration returned in credential responses.

    - `String clientId`

      OAuth client ID.

    - `String tokenEndpoint`

      Token endpoint URL used to refresh the access token.

    - `TokenEndpointAuth tokenEndpointAuth`

      Token endpoint requires no client authentication.

      - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:`

        Token endpoint requires no client authentication.

        - `Type type`

          - `NONE("none")`

      - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:`

        Token endpoint uses HTTP Basic authentication with client credentials.

        - `Type type`

          - `CLIENT_SECRET_BASIC("client_secret_basic")`

      - `class BetaManagedAgentsTokenEndpointAuthPostResponse:`

        Token endpoint uses POST body authentication with client credentials.

        - `Type type`

          - `CLIENT_SECRET_POST("client_secret_post")`

    - `Optional<String> resource`

      OAuth resource indicator.

    - `Optional<String> scope`

      OAuth scope for the refresh request.

### Beta Managed Agents MCP OAuth Create Params

- `class BetaManagedAgentsMcpOAuthCreateParams:`

  Parameters for creating an MCP OAuth credential.

  - `String accessToken`

    OAuth access token.

  - `String mcpServerUrl`

    URL of the MCP server this credential authenticates against.

  - `Type type`

    - `MCP_OAUTH("mcp_oauth")`

  - `Optional<LocalDateTime> expiresAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsMcpOAuthRefreshParams> refresh`

    OAuth refresh token parameters for creating a credential with refresh support.

    - `String clientId`

      OAuth client ID.

    - `String refreshToken`

      OAuth refresh token.

    - `String tokenEndpoint`

      Token endpoint URL used to refresh the access token.

    - `TokenEndpointAuth tokenEndpointAuth`

      Token endpoint requires no client authentication.

      - `class BetaManagedAgentsTokenEndpointAuthNoneParam:`

        Token endpoint requires no client authentication.

        - `Type type`

          - `NONE("none")`

      - `class BetaManagedAgentsTokenEndpointAuthBasicParam:`

        Token endpoint uses HTTP Basic authentication with client credentials.

        - `String clientSecret`

          OAuth client secret.

        - `Type type`

          - `CLIENT_SECRET_BASIC("client_secret_basic")`

      - `class BetaManagedAgentsTokenEndpointAuthPostParam:`

        Token endpoint uses POST body authentication with client credentials.

        - `String clientSecret`

          OAuth client secret.

        - `Type type`

          - `CLIENT_SECRET_POST("client_secret_post")`

    - `Optional<String> resource`

      OAuth resource indicator.

    - `Optional<String> scope`

      OAuth scope for the refresh request.

### Beta Managed Agents MCP OAuth Refresh Params

- `class BetaManagedAgentsMcpOAuthRefreshParams:`

  OAuth refresh token parameters for creating a credential with refresh support.

  - `String clientId`

    OAuth client ID.

  - `String refreshToken`

    OAuth refresh token.

  - `String tokenEndpoint`

    Token endpoint URL used to refresh the access token.

  - `TokenEndpointAuth tokenEndpointAuth`

    Token endpoint requires no client authentication.

    - `class BetaManagedAgentsTokenEndpointAuthNoneParam:`

      Token endpoint requires no client authentication.

      - `Type type`

        - `NONE("none")`

    - `class BetaManagedAgentsTokenEndpointAuthBasicParam:`

      Token endpoint uses HTTP Basic authentication with client credentials.

      - `String clientSecret`

        OAuth client secret.

      - `Type type`

        - `CLIENT_SECRET_BASIC("client_secret_basic")`

    - `class BetaManagedAgentsTokenEndpointAuthPostParam:`

      Token endpoint uses POST body authentication with client credentials.

      - `String clientSecret`

        OAuth client secret.

      - `Type type`

        - `CLIENT_SECRET_POST("client_secret_post")`

  - `Optional<String> resource`

    OAuth resource indicator.

  - `Optional<String> scope`

    OAuth scope for the refresh request.

### Beta Managed Agents MCP OAuth Refresh Response

- `class BetaManagedAgentsMcpOAuthRefreshResponse:`

  OAuth refresh token configuration returned in credential responses.

  - `String clientId`

    OAuth client ID.

  - `String tokenEndpoint`

    Token endpoint URL used to refresh the access token.

  - `TokenEndpointAuth tokenEndpointAuth`

    Token endpoint requires no client authentication.

    - `class BetaManagedAgentsTokenEndpointAuthNoneResponse:`

      Token endpoint requires no client authentication.

      - `Type type`

        - `NONE("none")`

    - `class BetaManagedAgentsTokenEndpointAuthBasicResponse:`

      Token endpoint uses HTTP Basic authentication with client credentials.

      - `Type type`

        - `CLIENT_SECRET_BASIC("client_secret_basic")`

    - `class BetaManagedAgentsTokenEndpointAuthPostResponse:`

      Token endpoint uses POST body authentication with client credentials.

      - `Type type`

        - `CLIENT_SECRET_POST("client_secret_post")`

  - `Optional<String> resource`

    OAuth resource indicator.

  - `Optional<String> scope`

    OAuth scope for the refresh request.

### Beta Managed Agents MCP OAuth Refresh Update Params

- `class BetaManagedAgentsMcpOAuthRefreshUpdateParams:`

  Parameters for updating OAuth refresh token configuration.

  - `Optional<String> refreshToken`

    Updated OAuth refresh token.

  - `Optional<String> scope`

    Updated OAuth scope for the refresh request.

  - `Optional<TokenEndpointAuth> tokenEndpointAuth`

    Updated HTTP Basic authentication parameters for the token endpoint.

    - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:`

      Updated HTTP Basic authentication parameters for the token endpoint.

      - `Type type`

        - `CLIENT_SECRET_BASIC("client_secret_basic")`

      - `Optional<String> clientSecret`

        Updated OAuth client secret.

    - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:`

      Updated POST body authentication parameters for the token endpoint.

      - `Type type`

        - `CLIENT_SECRET_POST("client_secret_post")`

      - `Optional<String> clientSecret`

        Updated OAuth client secret.

### Beta Managed Agents MCP OAuth Update Params

- `class BetaManagedAgentsMcpOAuthUpdateParams:`

  Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable.

  - `Type type`

    - `MCP_OAUTH("mcp_oauth")`

  - `Optional<String> accessToken`

    Updated OAuth access token.

  - `Optional<LocalDateTime> expiresAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsMcpOAuthRefreshUpdateParams> refresh`

    Parameters for updating OAuth refresh token configuration.

    - `Optional<String> refreshToken`

      Updated OAuth refresh token.

    - `Optional<String> scope`

      Updated OAuth scope for the refresh request.

    - `Optional<TokenEndpointAuth> tokenEndpointAuth`

      Updated HTTP Basic authentication parameters for the token endpoint.

      - `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:`

        Updated HTTP Basic authentication parameters for the token endpoint.

        - `Type type`

          - `CLIENT_SECRET_BASIC("client_secret_basic")`

        - `Optional<String> clientSecret`

          Updated OAuth client secret.

      - `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:`

        Updated POST body authentication parameters for the token endpoint.

        - `Type type`

          - `CLIENT_SECRET_POST("client_secret_post")`

        - `Optional<String> clientSecret`

          Updated OAuth client secret.

### Beta Managed Agents MCP Probe

- `class BetaManagedAgentsMcpProbe:`

  The failing step of an MCP validation probe.

  - `Optional<BetaManagedAgentsRefreshHttpResponse> httpResponse`

    An HTTP response captured during a credential validation probe.

    - `String body`

      Response body. May be truncated and has sensitive values scrubbed.

    - `boolean bodyTruncated`

      Whether `body` was truncated.

    - `String contentType`

      Value of the `Content-Type` response header.

    - `long statusCode`

      HTTP status code.

  - `String method`

    The MCP method that failed (for example `initialize` or `tools/list`).

### Beta Managed Agents Refresh HTTP Response

- `class BetaManagedAgentsRefreshHttpResponse:`

  An HTTP response captured during a credential validation probe.

  - `String body`

    Response body. May be truncated and has sensitive values scrubbed.

  - `boolean bodyTruncated`

    Whether `body` was truncated.

  - `String contentType`

    Value of the `Content-Type` response header.

  - `long statusCode`

    HTTP status code.

### Beta Managed Agents Refresh Object

- `class BetaManagedAgentsRefreshObject:`

  Outcome of a refresh-token exchange attempted during credential validation.

  - `Optional<BetaManagedAgentsRefreshHttpResponse> httpResponse`

    An HTTP response captured during a credential validation probe.

    - `String body`

      Response body. May be truncated and has sensitive values scrubbed.

    - `boolean bodyTruncated`

      Whether `body` was truncated.

    - `String contentType`

      Value of the `Content-Type` response header.

    - `long statusCode`

      HTTP status code.

  - `Status status`

    Outcome of a refresh-token exchange attempted during credential validation.

    - `SUCCEEDED("succeeded")`

    - `FAILED("failed")`

    - `CONNECT_ERROR("connect_error")`

    - `NO_REFRESH_TOKEN("no_refresh_token")`

### Beta Managed Agents Static Bearer Auth Response

- `class BetaManagedAgentsStaticBearerAuthResponse:`

  Static bearer token credential details for an MCP server.

  - `String mcpServerUrl`

    URL of the MCP server this credential authenticates against.

  - `Type type`

    - `STATIC_BEARER("static_bearer")`

### Beta Managed Agents Static Bearer Create Params

- `class BetaManagedAgentsStaticBearerCreateParams:`

  Parameters for creating a static bearer token credential.

  - `String token`

    Static bearer token value.

  - `String mcpServerUrl`

    URL of the MCP server this credential authenticates against.

  - `Type type`

    - `STATIC_BEARER("static_bearer")`

### Beta Managed Agents Static Bearer Update Params

- `class BetaManagedAgentsStaticBearerUpdateParams:`

  Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable.

  - `Type type`

    - `STATIC_BEARER("static_bearer")`

  - `Optional<String> token`

    Updated static bearer token value.

### Beta Managed Agents Token Endpoint Auth Basic Param

- `class BetaManagedAgentsTokenEndpointAuthBasicParam:`

  Token endpoint uses HTTP Basic authentication with client credentials.

  - `String clientSecret`

    OAuth client secret.

  - `Type type`

    - `CLIENT_SECRET_BASIC("client_secret_basic")`

### Beta Managed Agents Token Endpoint Auth Basic Response

- `class BetaManagedAgentsTokenEndpointAuthBasicResponse:`

  Token endpoint uses HTTP Basic authentication with client credentials.

  - `Type type`

    - `CLIENT_SECRET_BASIC("client_secret_basic")`

### Beta Managed Agents Token Endpoint Auth Basic Update Param

- `class BetaManagedAgentsTokenEndpointAuthBasicUpdateParam:`

  Updated HTTP Basic authentication parameters for the token endpoint.

  - `Type type`

    - `CLIENT_SECRET_BASIC("client_secret_basic")`

  - `Optional<String> clientSecret`

    Updated OAuth client secret.

### Beta Managed Agents Token Endpoint Auth None Param

- `class BetaManagedAgentsTokenEndpointAuthNoneParam:`

  Token endpoint requires no client authentication.

  - `Type type`

    - `NONE("none")`

### Beta Managed Agents Token Endpoint Auth None Response

- `class BetaManagedAgentsTokenEndpointAuthNoneResponse:`

  Token endpoint requires no client authentication.

  - `Type type`

    - `NONE("none")`

### Beta Managed Agents Token Endpoint Auth Post Param

- `class BetaManagedAgentsTokenEndpointAuthPostParam:`

  Token endpoint uses POST body authentication with client credentials.

  - `String clientSecret`

    OAuth client secret.

  - `Type type`

    - `CLIENT_SECRET_POST("client_secret_post")`

### Beta Managed Agents Token Endpoint Auth Post Response

- `class BetaManagedAgentsTokenEndpointAuthPostResponse:`

  Token endpoint uses POST body authentication with client credentials.

  - `Type type`

    - `CLIENT_SECRET_POST("client_secret_post")`

### Beta Managed Agents Token Endpoint Auth Post Update Param

- `class BetaManagedAgentsTokenEndpointAuthPostUpdateParam:`

  Updated POST body authentication parameters for the token endpoint.

  - `Type type`

    - `CLIENT_SECRET_POST("client_secret_post")`

  - `Optional<String> clientSecret`

    Updated OAuth client secret.

### Beta Managed Agents Unrestricted Credential Networking Params

- `class BetaManagedAgentsUnrestrictedCredentialNetworkingParams:`

  Substitute the secret on any host the session's Environment network policy permits egress to. The Environment's network policy is the only boundary on where the secret can reach.

  - `Type type`

    - `UNRESTRICTED("unrestricted")`

### Beta Managed Agents Unrestricted Credential Networking Response

- `class BetaManagedAgentsUnrestrictedCredentialNetworkingResponse:`

  The secret is substituted on any host the session's Environment network policy permits egress to.

  - `Type type`

    - `UNRESTRICTED("unrestricted")`

# Memory Stores

## Create a memory store

`BetaManagedAgentsMemoryStore beta().memoryStores().create(MemoryStoreCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/memory_stores`

Create a memory store

### Parameters

- `MemoryStoreCreateParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `String name`

    Human-readable name for the store. Required; 1–255 characters; no control characters. The mount-path slug under `/mnt/memory/` is derived from this name (lowercased, non-alphanumeric runs collapsed to a hyphen). Names need not be unique within a workspace.

  - `Optional<String> description`

    Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent.

  - `Optional<Metadata> metadata`

    Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Not visible to the agent.

### Returns

- `class BetaManagedAgentsMemoryStore:`

  A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write.

  - `String id`

    Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String name`

    Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name.

  - `Type type`

    - `MEMORY_STORE("memory_store")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset.

  - `Optional<Metadata> metadata`

    Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.BetaManagedAgentsMemoryStore;
import com.anthropic.models.beta.memorystores.MemoryStoreCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MemoryStoreCreateParams params = MemoryStoreCreateParams.builder()
            .name("x")
            .build();
        BetaManagedAgentsMemoryStore betaManagedAgentsMemoryStore = client.beta().memoryStores().create(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "name": "name",
  "type": "memory_store",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "metadata": {
    "foo": "string"
  }
}
```

## List memory stores

`MemoryStoreListPage beta().memoryStores().list(MemoryStoreListParamsparams = MemoryStoreListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/memory_stores`

List memory stores

### Parameters

- `MemoryStoreListParams params`

  - `Optional<LocalDateTime> createdAtGte`

    Return only stores whose `created_at` is at or after this time (inclusive). Sent on the wire as `created_at[gte]`.

  - `Optional<LocalDateTime> createdAtLte`

    Return only stores whose `created_at` is at or before this time (inclusive). Sent on the wire as `created_at[lte]`.

  - `Optional<Boolean> includeArchived`

    When `true`, archived stores are included in the results. Defaults to `false` (archived stores are excluded).

  - `Optional<Long> limit`

    Maximum number of stores to return per page. Must be between 1 and 100. Defaults to 20 when omitted.

  - `Optional<String> page`

    Opaque pagination cursor (a `page_...` value). Pass the `next_page` value from a previous response to fetch the next page; omit for the first page.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsMemoryStore:`

  A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write.

  - `String id`

    Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String name`

    Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name.

  - `Type type`

    - `MEMORY_STORE("memory_store")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset.

  - `Optional<Metadata> metadata`

    Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.MemoryStoreListPage;
import com.anthropic.models.beta.memorystores.MemoryStoreListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MemoryStoreListPage page = client.beta().memoryStores().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "type": "memory_store",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "archived_at": "2019-12-27T18:11:19.117Z",
      "description": "description",
      "metadata": {
        "foo": "string"
      }
    }
  ],
  "next_page": "next_page"
}
```

## Retrieve a memory store

`BetaManagedAgentsMemoryStore beta().memoryStores().retrieve(MemoryStoreRetrieveParamsparams = MemoryStoreRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/memory_stores/{memory_store_id}`

Retrieve a memory store

### Parameters

- `MemoryStoreRetrieveParams params`

  - `Optional<String> memoryStoreId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsMemoryStore:`

  A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write.

  - `String id`

    Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String name`

    Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name.

  - `Type type`

    - `MEMORY_STORE("memory_store")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset.

  - `Optional<Metadata> metadata`

    Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.BetaManagedAgentsMemoryStore;
import com.anthropic.models.beta.memorystores.MemoryStoreRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsMemoryStore betaManagedAgentsMemoryStore = client.beta().memoryStores().retrieve("memory_store_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "name": "name",
  "type": "memory_store",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "metadata": {
    "foo": "string"
  }
}
```

## Update a memory store

`BetaManagedAgentsMemoryStore beta().memoryStores().update(MemoryStoreUpdateParamsparams = MemoryStoreUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/memory_stores/{memory_store_id}`

Update a memory store

### Parameters

- `MemoryStoreUpdateParams params`

  - `Optional<String> memoryStoreId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<String> description`

    New description for the store, up to 1024 characters. Pass an empty string to clear it.

  - `Optional<Metadata> metadata`

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars.

  - `Optional<String> name`

    New human-readable name for the store. 1–255 characters; no control characters. Renaming changes the slug used for the store's `mount_path` in sessions created after the update.

### Returns

- `class BetaManagedAgentsMemoryStore:`

  A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write.

  - `String id`

    Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String name`

    Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name.

  - `Type type`

    - `MEMORY_STORE("memory_store")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset.

  - `Optional<Metadata> metadata`

    Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.BetaManagedAgentsMemoryStore;
import com.anthropic.models.beta.memorystores.MemoryStoreUpdateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsMemoryStore betaManagedAgentsMemoryStore = client.beta().memoryStores().update("memory_store_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "name": "name",
  "type": "memory_store",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "metadata": {
    "foo": "string"
  }
}
```

## Delete a memory store

`BetaManagedAgentsDeletedMemoryStore beta().memoryStores().delete(MemoryStoreDeleteParamsparams = MemoryStoreDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/memory_stores/{memory_store_id}`

Delete a memory store

### Parameters

- `MemoryStoreDeleteParams params`

  - `Optional<String> memoryStoreId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeletedMemoryStore:`

  Confirmation that a `memory_store` was deleted.

  - `String id`

    ID of the deleted memory store (a `memstore_...` identifier). The store and all its memories and versions are no longer retrievable.

  - `Type type`

    - `MEMORY_STORE_DELETED("memory_store_deleted")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.BetaManagedAgentsDeletedMemoryStore;
import com.anthropic.models.beta.memorystores.MemoryStoreDeleteParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsDeletedMemoryStore betaManagedAgentsDeletedMemoryStore = client.beta().memoryStores().delete("memory_store_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "type": "memory_store_deleted"
}
```

## Archive a memory store

`BetaManagedAgentsMemoryStore beta().memoryStores().archive(MemoryStoreArchiveParamsparams = MemoryStoreArchiveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/memory_stores/{memory_store_id}/archive`

Archive a memory store

### Parameters

- `MemoryStoreArchiveParams params`

  - `Optional<String> memoryStoreId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsMemoryStore:`

  A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write.

  - `String id`

    Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String name`

    Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name.

  - `Type type`

    - `MEMORY_STORE("memory_store")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset.

  - `Optional<Metadata> metadata`

    Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.BetaManagedAgentsMemoryStore;
import com.anthropic.models.beta.memorystores.MemoryStoreArchiveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaManagedAgentsMemoryStore betaManagedAgentsMemoryStore = client.beta().memoryStores().archive("memory_store_id");
    }
}
```

#### Response

```json
{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "name": "name",
  "type": "memory_store",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "metadata": {
    "foo": "string"
  }
}
```

## Domain Types

### Beta Managed Agents Deleted Memory Store

- `class BetaManagedAgentsDeletedMemoryStore:`

  Confirmation that a `memory_store` was deleted.

  - `String id`

    ID of the deleted memory store (a `memstore_...` identifier). The store and all its memories and versions are no longer retrievable.

  - `Type type`

    - `MEMORY_STORE_DELETED("memory_store_deleted")`

### Beta Managed Agents Memory Store

- `class BetaManagedAgentsMemoryStore:`

  A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write.

  - `String id`

    Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String name`

    Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name.

  - `Type type`

    - `MEMORY_STORE("memory_store")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<LocalDateTime> archivedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> description`

    Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset.

  - `Optional<Metadata> metadata`

    Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable.

# Memories

## Create a memory

`BetaManagedAgentsMemory beta().memoryStores().memories().create(MemoryCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/memory_stores/{memory_store_id}/memories`

Create a memory

### Parameters

- `MemoryCreateParams params`

  - `Optional<String> memoryStoreId`

  - `Optional<BetaManagedAgentsMemoryView> view`

    Query parameter for view

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<String> content`

    UTF-8 text content for the new memory. Maximum 100 kB (102,400 bytes). Required; pass `""` explicitly to create an empty memory.

  - `String path`

    Hierarchical path for the new memory, e.g. `/projects/foo/notes.md`. Must start with `/`, contain at least one non-empty segment, and be at most 1,024 bytes. Must not contain empty segments, `.` or `..` segments, control or format characters, and must be NFC-normalized. Paths are case-sensitive.

### Returns

- `class BetaManagedAgentsMemory:`

  A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update.

  - `String id`

    Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory.

  - `String contentSha256`

    Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`.

  - `long contentSizeBytes`

    Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String memoryStoreId`

    ID of the memory store this memory belongs to (a `memstore_...` value).

  - `String memoryVersionId`

    ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list).

  - `String path`

    Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes.

  - `Type type`

    - `MEMORY("memory")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> content`

    The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes).

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.memories.BetaManagedAgentsMemory;
import com.anthropic.models.beta.memorystores.memories.MemoryCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MemoryCreateParams params = MemoryCreateParams.builder()
            .memoryStoreId("memory_store_id")
            .content("content")
            .path("xx")
            .build();
        BetaManagedAgentsMemory betaManagedAgentsMemory = client.beta().memoryStores().memories().create(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "content_sha256": "content_sha256",
  "content_size_bytes": 0,
  "created_at": "2019-12-27T18:11:19.117Z",
  "memory_store_id": "memory_store_id",
  "memory_version_id": "memory_version_id",
  "path": "path",
  "type": "memory",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "content": "content"
}
```

## List memories

`MemoryListPage beta().memoryStores().memories().list(MemoryListParamsparams = MemoryListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/memory_stores/{memory_store_id}/memories`

List memories

### Parameters

- `MemoryListParams params`

  - `Optional<String> memoryStoreId`

  - `Optional<Long> depth`

    Query parameter for depth

  - `Optional<Long> limit`

    Query parameter for limit

  - `Optional<Order> order`

    Query parameter for order

    - `ASC("asc")`

    - `DESC("desc")`

  - `Optional<String> orderBy`

    Query parameter for order_by

  - `Optional<String> page`

    Query parameter for page

  - `Optional<String> pathPrefix`

    Optional path prefix filter (raw string-prefix match; include a trailing slash for directory-scoped lists). This value appears in request URLs. Do not include secrets or personally identifiable information.

  - `Optional<BetaManagedAgentsMemoryView> view`

    Query parameter for view

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsMemoryListItem: A class that can be one of several variants.union`

  One item in a [List memories](/docs/en/api/beta/memory_stores/memories/list) response: either a `memory` object or, when `depth` is set, a `memory_prefix` rollup marker.

  - `class BetaManagedAgentsMemory:`

    A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update.

    - `String id`

      Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory.

    - `String contentSha256`

      Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`.

    - `long contentSizeBytes`

      Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`.

    - `LocalDateTime createdAt`

      A timestamp in RFC 3339 format

    - `String memoryStoreId`

      ID of the memory store this memory belongs to (a `memstore_...` value).

    - `String memoryVersionId`

      ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list).

    - `String path`

      Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes.

    - `Type type`

      - `MEMORY("memory")`

    - `LocalDateTime updatedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> content`

      The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes).

  - `class BetaManagedAgentsMemoryPrefix:`

    A rolled-up directory marker returned by [List memories](/docs/en/api/beta/memory_stores/memories/list) when `depth` is set. Indicates that one or more memories exist deeper than the requested depth under this prefix. This is a list-time rollup, not a stored resource; it has no ID and no lifecycle. Each prefix counts toward the page `limit` and interleaves with `memory` items in path order.

    - `String path`

      The rolled-up path prefix, including a trailing `/` (e.g. `/projects/foo/`). Pass this value as `path_prefix` on a subsequent list call to drill into the directory.

    - `Type type`

      - `MEMORY_PREFIX("memory_prefix")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.memories.MemoryListPage;
import com.anthropic.models.beta.memorystores.memories.MemoryListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MemoryListPage page = client.beta().memoryStores().memories().list("memory_store_id");
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "id",
      "content_sha256": "content_sha256",
      "content_size_bytes": 0,
      "created_at": "2019-12-27T18:11:19.117Z",
      "memory_store_id": "memory_store_id",
      "memory_version_id": "memory_version_id",
      "path": "path",
      "type": "memory",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "content": "content"
    }
  ],
  "next_page": "next_page"
}
```

## Retrieve a memory

`BetaManagedAgentsMemory beta().memoryStores().memories().retrieve(MemoryRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`

Retrieve a memory

### Parameters

- `MemoryRetrieveParams params`

  - `String memoryStoreId`

  - `Optional<String> memoryId`

  - `Optional<BetaManagedAgentsMemoryView> view`

    Query parameter for view

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsMemory:`

  A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update.

  - `String id`

    Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory.

  - `String contentSha256`

    Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`.

  - `long contentSizeBytes`

    Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String memoryStoreId`

    ID of the memory store this memory belongs to (a `memstore_...` value).

  - `String memoryVersionId`

    ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list).

  - `String path`

    Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes.

  - `Type type`

    - `MEMORY("memory")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> content`

    The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes).

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.memories.BetaManagedAgentsMemory;
import com.anthropic.models.beta.memorystores.memories.MemoryRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MemoryRetrieveParams params = MemoryRetrieveParams.builder()
            .memoryStoreId("memory_store_id")
            .memoryId("memory_id")
            .build();
        BetaManagedAgentsMemory betaManagedAgentsMemory = client.beta().memoryStores().memories().retrieve(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "content_sha256": "content_sha256",
  "content_size_bytes": 0,
  "created_at": "2019-12-27T18:11:19.117Z",
  "memory_store_id": "memory_store_id",
  "memory_version_id": "memory_version_id",
  "path": "path",
  "type": "memory",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "content": "content"
}
```

## Update a memory

`BetaManagedAgentsMemory beta().memoryStores().memories().update(MemoryUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`

Update a memory

### Parameters

- `MemoryUpdateParams params`

  - `String memoryStoreId`

  - `Optional<String> memoryId`

  - `Optional<BetaManagedAgentsMemoryView> view`

    Query parameter for view

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<String> content`

    New UTF-8 text content for the memory. Maximum 100 kB (102,400 bytes). Omit to leave the content unchanged (e.g., for a rename-only update).

  - `Optional<String> path`

    New path for the memory (a rename). Must start with `/`, contain at least one non-empty segment, and be at most 1,024 bytes. Must not contain empty segments, `.` or `..` segments, control or format characters, and must be NFC-normalized. Paths are case-sensitive. The memory's `id` is preserved across renames. Omit to leave the path unchanged.

  - `Optional<BetaManagedAgentsPrecondition> precondition`

    Optimistic-concurrency precondition: the update applies only if the memory's stored `content_sha256` equals the supplied value. On mismatch, the request returns `memory_precondition_failed_error` (HTTP 409); re-read the memory and retry against the fresh state. If the precondition fails but the stored state already exactly matches the requested `content` and `path`, the server returns 200 instead of 409.

### Returns

- `class BetaManagedAgentsMemory:`

  A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update.

  - `String id`

    Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory.

  - `String contentSha256`

    Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`.

  - `long contentSizeBytes`

    Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String memoryStoreId`

    ID of the memory store this memory belongs to (a `memstore_...` value).

  - `String memoryVersionId`

    ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list).

  - `String path`

    Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes.

  - `Type type`

    - `MEMORY("memory")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> content`

    The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes).

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.memories.BetaManagedAgentsMemory;
import com.anthropic.models.beta.memorystores.memories.MemoryUpdateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MemoryUpdateParams params = MemoryUpdateParams.builder()
            .memoryStoreId("memory_store_id")
            .memoryId("memory_id")
            .build();
        BetaManagedAgentsMemory betaManagedAgentsMemory = client.beta().memoryStores().memories().update(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "content_sha256": "content_sha256",
  "content_size_bytes": 0,
  "created_at": "2019-12-27T18:11:19.117Z",
  "memory_store_id": "memory_store_id",
  "memory_version_id": "memory_version_id",
  "path": "path",
  "type": "memory",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "content": "content"
}
```

## Delete a memory

`BetaManagedAgentsDeletedMemory beta().memoryStores().memories().delete(MemoryDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`

Delete a memory

### Parameters

- `MemoryDeleteParams params`

  - `String memoryStoreId`

  - `Optional<String> memoryId`

  - `Optional<String> expectedContentSha256`

    Query parameter for expected_content_sha256

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsDeletedMemory:`

  Tombstone returned by [Delete a memory](/docs/en/api/beta/memory_stores/memories/delete). The memory's version history persists and remains listable via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) until the store itself is deleted.

  - `String id`

    ID of the deleted memory (a `mem_...` value).

  - `Type type`

    - `MEMORY_DELETED("memory_deleted")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.memories.BetaManagedAgentsDeletedMemory;
import com.anthropic.models.beta.memorystores.memories.MemoryDeleteParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MemoryDeleteParams params = MemoryDeleteParams.builder()
            .memoryStoreId("memory_store_id")
            .memoryId("memory_id")
            .build();
        BetaManagedAgentsDeletedMemory betaManagedAgentsDeletedMemory = client.beta().memoryStores().memories().delete(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "type": "memory_deleted"
}
```

## Domain Types

### Beta Managed Agents Conflict Error

- `class BetaManagedAgentsConflictError:`

  - `Type type`

    - `CONFLICT_ERROR("conflict_error")`

  - `Optional<String> message`

### Beta Managed Agents Content Sha256 Precondition

- `class BetaManagedAgentsContentSha256Precondition:`

  Optimistic-concurrency precondition: the update applies only if the memory's stored `content_sha256` equals the supplied value. On mismatch, the request returns `memory_precondition_failed_error` (HTTP 409); re-read the memory and retry against the fresh state. If the precondition fails but the stored state already exactly matches the requested `content` and `path`, the server returns 200 instead of 409.

  - `Type type`

    - `CONTENT_SHA256("content_sha256")`

  - `Optional<String> contentSha256`

    Expected `content_sha256` of the stored memory (64 lowercase hexadecimal characters). Typically the `content_sha256` returned by a prior read or list call. Because the server applies no content normalization, clients can also compute this locally as the SHA-256 of the UTF-8 content bytes.

### Beta Managed Agents Deleted Memory

- `class BetaManagedAgentsDeletedMemory:`

  Tombstone returned by [Delete a memory](/docs/en/api/beta/memory_stores/memories/delete). The memory's version history persists and remains listable via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) until the store itself is deleted.

  - `String id`

    ID of the deleted memory (a `mem_...` value).

  - `Type type`

    - `MEMORY_DELETED("memory_deleted")`

### Beta Managed Agents Error

- `class BetaManagedAgentsError: A class that can be one of several variants.union`

  - `class BetaInvalidRequestError:`

    - `String message`

    - `JsonValue; type "invalid_request_error"constant`

      - `INVALID_REQUEST_ERROR("invalid_request_error")`

  - `class BetaAuthenticationError:`

    - `String message`

    - `JsonValue; type "authentication_error"constant`

      - `AUTHENTICATION_ERROR("authentication_error")`

  - `class BetaBillingError:`

    - `String message`

    - `JsonValue; type "billing_error"constant`

      - `BILLING_ERROR("billing_error")`

  - `class BetaPermissionError:`

    - `String message`

    - `JsonValue; type "permission_error"constant`

      - `PERMISSION_ERROR("permission_error")`

  - `class BetaNotFoundError:`

    - `String message`

    - `JsonValue; type "not_found_error"constant`

      - `NOT_FOUND_ERROR("not_found_error")`

  - `class BetaRateLimitError:`

    - `String message`

    - `JsonValue; type "rate_limit_error"constant`

      - `RATE_LIMIT_ERROR("rate_limit_error")`

  - `class BetaGatewayTimeoutError:`

    - `String message`

    - `JsonValue; type "timeout_error"constant`

      - `TIMEOUT_ERROR("timeout_error")`

  - `class BetaApiError:`

    - `String message`

    - `JsonValue; type "api_error"constant`

      - `API_ERROR("api_error")`

  - `class BetaOverloadedError:`

    - `String message`

    - `JsonValue; type "overloaded_error"constant`

      - `OVERLOADED_ERROR("overloaded_error")`

  - `class BetaManagedAgentsMemoryPreconditionFailedError:`

    - `Type type`

      - `MEMORY_PRECONDITION_FAILED_ERROR("memory_precondition_failed_error")`

    - `Optional<String> message`

  - `class BetaManagedAgentsMemoryPathConflictError:`

    - `Type type`

      - `MEMORY_PATH_CONFLICT_ERROR("memory_path_conflict_error")`

    - `Optional<String> conflictingMemoryId`

    - `Optional<String> conflictingPath`

    - `Optional<String> message`

  - `class BetaManagedAgentsConflictError:`

    - `Type type`

      - `CONFLICT_ERROR("conflict_error")`

    - `Optional<String> message`

### Beta Managed Agents Memory

- `class BetaManagedAgentsMemory:`

  A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update.

  - `String id`

    Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory.

  - `String contentSha256`

    Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`.

  - `long contentSizeBytes`

    Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String memoryStoreId`

    ID of the memory store this memory belongs to (a `memstore_...` value).

  - `String memoryVersionId`

    ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list).

  - `String path`

    Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes.

  - `Type type`

    - `MEMORY("memory")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> content`

    The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes).

### Beta Managed Agents Memory List Item

- `class BetaManagedAgentsMemoryListItem: A class that can be one of several variants.union`

  One item in a [List memories](/docs/en/api/beta/memory_stores/memories/list) response: either a `memory` object or, when `depth` is set, a `memory_prefix` rollup marker.

  - `class BetaManagedAgentsMemory:`

    A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update.

    - `String id`

      Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory.

    - `String contentSha256`

      Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`.

    - `long contentSizeBytes`

      Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`.

    - `LocalDateTime createdAt`

      A timestamp in RFC 3339 format

    - `String memoryStoreId`

      ID of the memory store this memory belongs to (a `memstore_...` value).

    - `String memoryVersionId`

      ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list).

    - `String path`

      Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes.

    - `Type type`

      - `MEMORY("memory")`

    - `LocalDateTime updatedAt`

      A timestamp in RFC 3339 format

    - `Optional<String> content`

      The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes).

  - `class BetaManagedAgentsMemoryPrefix:`

    A rolled-up directory marker returned by [List memories](/docs/en/api/beta/memory_stores/memories/list) when `depth` is set. Indicates that one or more memories exist deeper than the requested depth under this prefix. This is a list-time rollup, not a stored resource; it has no ID and no lifecycle. Each prefix counts toward the page `limit` and interleaves with `memory` items in path order.

    - `String path`

      The rolled-up path prefix, including a trailing `/` (e.g. `/projects/foo/`). Pass this value as `path_prefix` on a subsequent list call to drill into the directory.

    - `Type type`

      - `MEMORY_PREFIX("memory_prefix")`

### Beta Managed Agents Memory Path Conflict Error

- `class BetaManagedAgentsMemoryPathConflictError:`

  - `Type type`

    - `MEMORY_PATH_CONFLICT_ERROR("memory_path_conflict_error")`

  - `Optional<String> conflictingMemoryId`

  - `Optional<String> conflictingPath`

  - `Optional<String> message`

### Beta Managed Agents Memory Precondition Failed Error

- `class BetaManagedAgentsMemoryPreconditionFailedError:`

  - `Type type`

    - `MEMORY_PRECONDITION_FAILED_ERROR("memory_precondition_failed_error")`

  - `Optional<String> message`

### Beta Managed Agents Memory Prefix

- `class BetaManagedAgentsMemoryPrefix:`

  A rolled-up directory marker returned by [List memories](/docs/en/api/beta/memory_stores/memories/list) when `depth` is set. Indicates that one or more memories exist deeper than the requested depth under this prefix. This is a list-time rollup, not a stored resource; it has no ID and no lifecycle. Each prefix counts toward the page `limit` and interleaves with `memory` items in path order.

  - `String path`

    The rolled-up path prefix, including a trailing `/` (e.g. `/projects/foo/`). Pass this value as `path_prefix` on a subsequent list call to drill into the directory.

  - `Type type`

    - `MEMORY_PREFIX("memory_prefix")`

### Beta Managed Agents Memory View

- `enum BetaManagedAgentsMemoryView:`

  Selects which projection of a `memory` or `memory_version` the server returns. `basic` returns the object with `content` set to `null`; `full` populates `content`. When omitted, the default is endpoint-specific: retrieve operations default to `full`; list, create, and update operations default to `basic`. Listing with `view=full` caps `limit` at 20.

  - `BASIC("basic")`

  - `FULL("full")`

### Beta Managed Agents Precondition

- `class BetaManagedAgentsPrecondition:`

  Optimistic-concurrency precondition: the update applies only if the memory's stored `content_sha256` equals the supplied value. On mismatch, the request returns `memory_precondition_failed_error` (HTTP 409); re-read the memory and retry against the fresh state. If the precondition fails but the stored state already exactly matches the requested `content` and `path`, the server returns 200 instead of 409.

  - `Type type`

    - `CONTENT_SHA256("content_sha256")`

  - `Optional<String> contentSha256`

    Expected `content_sha256` of the stored memory (64 lowercase hexadecimal characters). Typically the `content_sha256` returned by a prior read or list call. Because the server applies no content normalization, clients can also compute this locally as the SHA-256 of the UTF-8 content bytes.

# Memory Versions

## List memory versions

`MemoryVersionListPage beta().memoryStores().memoryVersions().list(MemoryVersionListParamsparams = MemoryVersionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/memory_stores/{memory_store_id}/memory_versions`

List memory versions

### Parameters

- `MemoryVersionListParams params`

  - `Optional<String> memoryStoreId`

  - `Optional<String> apiKeyId`

    Query parameter for api_key_id

  - `Optional<LocalDateTime> createdAtGte`

    Return versions created at or after this time (inclusive).

  - `Optional<LocalDateTime> createdAtLte`

    Return versions created at or before this time (inclusive).

  - `Optional<Long> limit`

    Query parameter for limit

  - `Optional<String> memoryId`

    Query parameter for memory_id

  - `Optional<BetaManagedAgentsMemoryVersionOperation> operation`

    Query parameter for operation

  - `Optional<String> page`

    Query parameter for page

  - `Optional<String> sessionId`

    Query parameter for session_id

  - `Optional<BetaManagedAgentsMemoryView> view`

    Query parameter for view

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsMemoryVersion:`

  A `memory_version` object: one immutable, attributed row in a memory's append-only history. Every non-no-op mutation to a memory produces a new version. Versions belong to the store (not the individual memory) and persist after the memory is deleted. Retrieving a redacted version returns 200 with `content`, `path`, `content_size_bytes`, and `content_sha256` set to `null`; branch on `redacted_at`, not HTTP status.

  - `String id`

    Unique identifier for this version (a `memver_...` value).

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String memoryId`

    ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) to retrieve the full lineage including the `deleted` row.

  - `String memoryStoreId`

    ID of the memory store this version belongs to (a `memstore_...` value).

  - `BetaManagedAgentsMemoryVersionOperation operation`

    The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values.

    - `CREATED("created")`

    - `MODIFIED("modified")`

    - `DELETED("deleted")`

  - `Type type`

    - `MEMORY_VERSION("memory_version")`

  - `Optional<String> content`

    The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set.

  - `Optional<String> contentSha256`

    Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise.

  - `Optional<Long> contentSizeBytes`

    Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise.

  - `Optional<BetaManagedAgentsActor> createdBy`

    Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve).

    - `class BetaManagedAgentsSessionActor:`

      Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`.

      - `String sessionId`

        ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance.

      - `Type type`

        - `SESSION_ACTOR("session_actor")`

    - `class BetaManagedAgentsApiActor:`

      Attribution for a write made directly via the public API (outside of any session).

      - `String apiKeyId`

        ID of the API key that performed the write. This identifies the key, not the secret.

      - `Type type`

        - `API_ACTOR("api_actor")`

    - `class BetaManagedAgentsUserActor:`

      Attribution for a write made by a human user through the Anthropic Console.

      - `Type type`

        - `USER_ACTOR("user_actor")`

      - `String userId`

        ID of the user who performed the write (a `user_...` value).

  - `Optional<String> path`

    The memory's path at the time of this write. `null` if and only if `redacted_at` is set.

  - `Optional<LocalDateTime> redactedAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsActor> redactedBy`

    Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve).

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.memoryversions.MemoryVersionListPage;
import com.anthropic.models.beta.memorystores.memoryversions.MemoryVersionListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MemoryVersionListPage page = client.beta().memoryStores().memoryVersions().list("memory_store_id");
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "memory_id": "memory_id",
      "memory_store_id": "memory_store_id",
      "operation": "created",
      "type": "memory_version",
      "content": "content",
      "content_sha256": "content_sha256",
      "content_size_bytes": 0,
      "created_by": {
        "session_id": "x",
        "type": "session_actor"
      },
      "path": "path",
      "redacted_at": "2019-12-27T18:11:19.117Z",
      "redacted_by": {
        "session_id": "x",
        "type": "session_actor"
      }
    }
  ],
  "next_page": "next_page"
}
```

## Retrieve a memory version

`BetaManagedAgentsMemoryVersion beta().memoryStores().memoryVersions().retrieve(MemoryVersionRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}`

Retrieve a memory version

### Parameters

- `MemoryVersionRetrieveParams params`

  - `String memoryStoreId`

  - `Optional<String> memoryVersionId`

  - `Optional<BetaManagedAgentsMemoryView> view`

    Query parameter for view

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsMemoryVersion:`

  A `memory_version` object: one immutable, attributed row in a memory's append-only history. Every non-no-op mutation to a memory produces a new version. Versions belong to the store (not the individual memory) and persist after the memory is deleted. Retrieving a redacted version returns 200 with `content`, `path`, `content_size_bytes`, and `content_sha256` set to `null`; branch on `redacted_at`, not HTTP status.

  - `String id`

    Unique identifier for this version (a `memver_...` value).

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String memoryId`

    ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) to retrieve the full lineage including the `deleted` row.

  - `String memoryStoreId`

    ID of the memory store this version belongs to (a `memstore_...` value).

  - `BetaManagedAgentsMemoryVersionOperation operation`

    The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values.

    - `CREATED("created")`

    - `MODIFIED("modified")`

    - `DELETED("deleted")`

  - `Type type`

    - `MEMORY_VERSION("memory_version")`

  - `Optional<String> content`

    The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set.

  - `Optional<String> contentSha256`

    Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise.

  - `Optional<Long> contentSizeBytes`

    Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise.

  - `Optional<BetaManagedAgentsActor> createdBy`

    Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve).

    - `class BetaManagedAgentsSessionActor:`

      Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`.

      - `String sessionId`

        ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance.

      - `Type type`

        - `SESSION_ACTOR("session_actor")`

    - `class BetaManagedAgentsApiActor:`

      Attribution for a write made directly via the public API (outside of any session).

      - `String apiKeyId`

        ID of the API key that performed the write. This identifies the key, not the secret.

      - `Type type`

        - `API_ACTOR("api_actor")`

    - `class BetaManagedAgentsUserActor:`

      Attribution for a write made by a human user through the Anthropic Console.

      - `Type type`

        - `USER_ACTOR("user_actor")`

      - `String userId`

        ID of the user who performed the write (a `user_...` value).

  - `Optional<String> path`

    The memory's path at the time of this write. `null` if and only if `redacted_at` is set.

  - `Optional<LocalDateTime> redactedAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsActor> redactedBy`

    Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve).

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.memoryversions.BetaManagedAgentsMemoryVersion;
import com.anthropic.models.beta.memorystores.memoryversions.MemoryVersionRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MemoryVersionRetrieveParams params = MemoryVersionRetrieveParams.builder()
            .memoryStoreId("memory_store_id")
            .memoryVersionId("memory_version_id")
            .build();
        BetaManagedAgentsMemoryVersion betaManagedAgentsMemoryVersion = client.beta().memoryStores().memoryVersions().retrieve(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "memory_id": "memory_id",
  "memory_store_id": "memory_store_id",
  "operation": "created",
  "type": "memory_version",
  "content": "content",
  "content_sha256": "content_sha256",
  "content_size_bytes": 0,
  "created_by": {
    "session_id": "x",
    "type": "session_actor"
  },
  "path": "path",
  "redacted_at": "2019-12-27T18:11:19.117Z",
  "redacted_by": {
    "session_id": "x",
    "type": "session_actor"
  }
}
```

## Redact a memory version

`BetaManagedAgentsMemoryVersion beta().memoryStores().memoryVersions().redact(MemoryVersionRedactParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}/redact`

Redact a memory version

### Parameters

- `MemoryVersionRedactParams params`

  - `String memoryStoreId`

  - `Optional<String> memoryVersionId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaManagedAgentsMemoryVersion:`

  A `memory_version` object: one immutable, attributed row in a memory's append-only history. Every non-no-op mutation to a memory produces a new version. Versions belong to the store (not the individual memory) and persist after the memory is deleted. Retrieving a redacted version returns 200 with `content`, `path`, `content_size_bytes`, and `content_sha256` set to `null`; branch on `redacted_at`, not HTTP status.

  - `String id`

    Unique identifier for this version (a `memver_...` value).

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String memoryId`

    ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) to retrieve the full lineage including the `deleted` row.

  - `String memoryStoreId`

    ID of the memory store this version belongs to (a `memstore_...` value).

  - `BetaManagedAgentsMemoryVersionOperation operation`

    The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values.

    - `CREATED("created")`

    - `MODIFIED("modified")`

    - `DELETED("deleted")`

  - `Type type`

    - `MEMORY_VERSION("memory_version")`

  - `Optional<String> content`

    The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set.

  - `Optional<String> contentSha256`

    Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise.

  - `Optional<Long> contentSizeBytes`

    Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise.

  - `Optional<BetaManagedAgentsActor> createdBy`

    Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve).

    - `class BetaManagedAgentsSessionActor:`

      Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`.

      - `String sessionId`

        ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance.

      - `Type type`

        - `SESSION_ACTOR("session_actor")`

    - `class BetaManagedAgentsApiActor:`

      Attribution for a write made directly via the public API (outside of any session).

      - `String apiKeyId`

        ID of the API key that performed the write. This identifies the key, not the secret.

      - `Type type`

        - `API_ACTOR("api_actor")`

    - `class BetaManagedAgentsUserActor:`

      Attribution for a write made by a human user through the Anthropic Console.

      - `Type type`

        - `USER_ACTOR("user_actor")`

      - `String userId`

        ID of the user who performed the write (a `user_...` value).

  - `Optional<String> path`

    The memory's path at the time of this write. `null` if and only if `redacted_at` is set.

  - `Optional<LocalDateTime> redactedAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsActor> redactedBy`

    Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve).

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.memorystores.memoryversions.BetaManagedAgentsMemoryVersion;
import com.anthropic.models.beta.memorystores.memoryversions.MemoryVersionRedactParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MemoryVersionRedactParams params = MemoryVersionRedactParams.builder()
            .memoryStoreId("memory_store_id")
            .memoryVersionId("memory_version_id")
            .build();
        BetaManagedAgentsMemoryVersion betaManagedAgentsMemoryVersion = client.beta().memoryStores().memoryVersions().redact(params);
    }
}
```

#### Response

```json
{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "memory_id": "memory_id",
  "memory_store_id": "memory_store_id",
  "operation": "created",
  "type": "memory_version",
  "content": "content",
  "content_sha256": "content_sha256",
  "content_size_bytes": 0,
  "created_by": {
    "session_id": "x",
    "type": "session_actor"
  },
  "path": "path",
  "redacted_at": "2019-12-27T18:11:19.117Z",
  "redacted_by": {
    "session_id": "x",
    "type": "session_actor"
  }
}
```

## Domain Types

### Beta Managed Agents Actor

- `class BetaManagedAgentsActor: A class that can be one of several variants.union`

  Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve).

  - `class BetaManagedAgentsSessionActor:`

    Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`.

    - `String sessionId`

      ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance.

    - `Type type`

      - `SESSION_ACTOR("session_actor")`

  - `class BetaManagedAgentsApiActor:`

    Attribution for a write made directly via the public API (outside of any session).

    - `String apiKeyId`

      ID of the API key that performed the write. This identifies the key, not the secret.

    - `Type type`

      - `API_ACTOR("api_actor")`

  - `class BetaManagedAgentsUserActor:`

    Attribution for a write made by a human user through the Anthropic Console.

    - `Type type`

      - `USER_ACTOR("user_actor")`

    - `String userId`

      ID of the user who performed the write (a `user_...` value).

### Beta Managed Agents API Actor

- `class BetaManagedAgentsApiActor:`

  Attribution for a write made directly via the public API (outside of any session).

  - `String apiKeyId`

    ID of the API key that performed the write. This identifies the key, not the secret.

  - `Type type`

    - `API_ACTOR("api_actor")`

### Beta Managed Agents Memory Version

- `class BetaManagedAgentsMemoryVersion:`

  A `memory_version` object: one immutable, attributed row in a memory's append-only history. Every non-no-op mutation to a memory produces a new version. Versions belong to the store (not the individual memory) and persist after the memory is deleted. Retrieving a redacted version returns 200 with `content`, `path`, `content_size_bytes`, and `content_sha256` set to `null`; branch on `redacted_at`, not HTTP status.

  - `String id`

    Unique identifier for this version (a `memver_...` value).

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `String memoryId`

    ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) to retrieve the full lineage including the `deleted` row.

  - `String memoryStoreId`

    ID of the memory store this version belongs to (a `memstore_...` value).

  - `BetaManagedAgentsMemoryVersionOperation operation`

    The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values.

    - `CREATED("created")`

    - `MODIFIED("modified")`

    - `DELETED("deleted")`

  - `Type type`

    - `MEMORY_VERSION("memory_version")`

  - `Optional<String> content`

    The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set.

  - `Optional<String> contentSha256`

    Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise.

  - `Optional<Long> contentSizeBytes`

    Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise.

  - `Optional<BetaManagedAgentsActor> createdBy`

    Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve).

    - `class BetaManagedAgentsSessionActor:`

      Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`.

      - `String sessionId`

        ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance.

      - `Type type`

        - `SESSION_ACTOR("session_actor")`

    - `class BetaManagedAgentsApiActor:`

      Attribution for a write made directly via the public API (outside of any session).

      - `String apiKeyId`

        ID of the API key that performed the write. This identifies the key, not the secret.

      - `Type type`

        - `API_ACTOR("api_actor")`

    - `class BetaManagedAgentsUserActor:`

      Attribution for a write made by a human user through the Anthropic Console.

      - `Type type`

        - `USER_ACTOR("user_actor")`

      - `String userId`

        ID of the user who performed the write (a `user_...` value).

  - `Optional<String> path`

    The memory's path at the time of this write. `null` if and only if `redacted_at` is set.

  - `Optional<LocalDateTime> redactedAt`

    A timestamp in RFC 3339 format

  - `Optional<BetaManagedAgentsActor> redactedBy`

    Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve).

### Beta Managed Agents Memory Version Operation

- `enum BetaManagedAgentsMemoryVersionOperation:`

  The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values.

  - `CREATED("created")`

  - `MODIFIED("modified")`

  - `DELETED("deleted")`

### Beta Managed Agents Session Actor

- `class BetaManagedAgentsSessionActor:`

  Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`.

  - `String sessionId`

    ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance.

  - `Type type`

    - `SESSION_ACTOR("session_actor")`

### Beta Managed Agents User Actor

- `class BetaManagedAgentsUserActor:`

  Attribution for a write made by a human user through the Anthropic Console.

  - `Type type`

    - `USER_ACTOR("user_actor")`

  - `String userId`

    ID of the user who performed the write (a `user_...` value).

# Files

## Upload File

`FileMetadata beta().files().upload(FileUploadParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/files`

Upload File

### Parameters

- `FileUploadParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `String file`

    The file to upload

### Returns

- `class FileMetadata:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing when the file was created.

  - `String filename`

    Original filename of the uploaded file.

  - `String mimeType`

    MIME type of the file.

  - `long sizeBytes`

    Size of the file in bytes.

  - `JsonValue; type "file"constant`

    Object type.

    For files, this is always `"file"`.

    - `FILE("file")`

  - `Optional<Boolean> downloadable`

    Whether the file can be downloaded.

  - `Optional<BetaFileScope> scope`

    The scope of this file, indicating the context in which it was created (e.g., a session).

    - `String id`

      The ID of the scoping resource (e.g., the session ID).

    - `JsonValue; type "session"constant`

      The type of scope (e.g., `"session"`).

      - `SESSION("session")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileUploadParams;
import java.io.ByteArrayInputStream;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        FileUploadParams params = FileUploadParams.builder()
            .file(new ByteArrayInputStream("Example data".getBytes()))
            .build();
        FileMetadata fileMetadata = client.beta().files().upload(params);
    }
}
```

#### Response

```json
{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "created_at": "2025-04-15T18:37:24.100435Z",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 102400,
  "type": "file",
  "downloadable": false,
  "scope": {
    "id": "id",
    "type": "session"
  }
}
```

## List Files

`FileListPage beta().files().list(FileListParamsparams = FileListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/files`

List Files

### Parameters

- `FileListParams params`

  - `Optional<String> afterId`

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

  - `Optional<String> beforeId`

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

  - `Optional<Long> limit`

    Number of items to return per page.

    Defaults to `20`. Ranges from `1` to `1000`.

  - `Optional<String> scopeId`

    Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID).

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class FileMetadata:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing when the file was created.

  - `String filename`

    Original filename of the uploaded file.

  - `String mimeType`

    MIME type of the file.

  - `long sizeBytes`

    Size of the file in bytes.

  - `JsonValue; type "file"constant`

    Object type.

    For files, this is always `"file"`.

    - `FILE("file")`

  - `Optional<Boolean> downloadable`

    Whether the file can be downloaded.

  - `Optional<BetaFileScope> scope`

    The scope of this file, indicating the context in which it was created (e.g., a session).

    - `String id`

      The ID of the scoping resource (e.g., the session ID).

    - `JsonValue; type "session"constant`

      The type of scope (e.g., `"session"`).

      - `SESSION("session")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.files.FileListPage;
import com.anthropic.models.beta.files.FileListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        FileListPage page = client.beta().files().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "file_011CNha8iCJcU1wXNR6q4V8w",
      "created_at": "2025-04-15T18:37:24.100435Z",
      "filename": "document.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 102400,
      "type": "file",
      "downloadable": false,
      "scope": {
        "id": "id",
        "type": "session"
      }
    }
  ],
  "first_id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "has_more": true,
  "last_id": "file_013Zva2CMHLNnXjNJJKqJ2EF"
}
```

## Download File

`HttpResponse beta().files().download(FileDownloadParamsparams = FileDownloadParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/files/{file_id}/content`

Download File

### Parameters

- `FileDownloadParams params`

  - `Optional<String> fileId`

    ID of the File.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.models.beta.files.FileDownloadParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        HttpResponse response = client.beta().files().download("file_id");
    }
}
```

## Get File Metadata

`FileMetadata beta().files().retrieveMetadata(FileRetrieveMetadataParamsparams = FileRetrieveMetadataParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/files/{file_id}`

Get File Metadata

### Parameters

- `FileRetrieveMetadataParams params`

  - `Optional<String> fileId`

    ID of the File.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class FileMetadata:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing when the file was created.

  - `String filename`

    Original filename of the uploaded file.

  - `String mimeType`

    MIME type of the file.

  - `long sizeBytes`

    Size of the file in bytes.

  - `JsonValue; type "file"constant`

    Object type.

    For files, this is always `"file"`.

    - `FILE("file")`

  - `Optional<Boolean> downloadable`

    Whether the file can be downloaded.

  - `Optional<BetaFileScope> scope`

    The scope of this file, indicating the context in which it was created (e.g., a session).

    - `String id`

      The ID of the scoping resource (e.g., the session ID).

    - `JsonValue; type "session"constant`

      The type of scope (e.g., `"session"`).

      - `SESSION("session")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileRetrieveMetadataParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        FileMetadata fileMetadata = client.beta().files().retrieveMetadata("file_id");
    }
}
```

#### Response

```json
{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "created_at": "2025-04-15T18:37:24.100435Z",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 102400,
  "type": "file",
  "downloadable": false,
  "scope": {
    "id": "id",
    "type": "session"
  }
}
```

## Delete File

`DeletedFile beta().files().delete(FileDeleteParamsparams = FileDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/files/{file_id}`

Delete File

### Parameters

- `FileDeleteParams params`

  - `Optional<String> fileId`

    ID of the File.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class DeletedFile:`

  - `String id`

    ID of the deleted file.

  - `Optional<Type> type`

    Deleted object type.

    For file deletion, this is always `"file_deleted"`.

    - `FILE_DELETED("file_deleted")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.files.DeletedFile;
import com.anthropic.models.beta.files.FileDeleteParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        DeletedFile deletedFile = client.beta().files().delete("file_id");
    }
}
```

#### Response

```json
{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file_deleted"
}
```

## Domain Types

### Beta File Scope

- `class BetaFileScope:`

  - `String id`

    The ID of the scoping resource (e.g., the session ID).

  - `JsonValue; type "session"constant`

    The type of scope (e.g., `"session"`).

    - `SESSION("session")`

### Deleted File

- `class DeletedFile:`

  - `String id`

    ID of the deleted file.

  - `Optional<Type> type`

    Deleted object type.

    For file deletion, this is always `"file_deleted"`.

    - `FILE_DELETED("file_deleted")`

### File Metadata

- `class FileMetadata:`

  - `String id`

    Unique object identifier.

    The format and length of IDs may change over time.

  - `LocalDateTime createdAt`

    RFC 3339 datetime string representing when the file was created.

  - `String filename`

    Original filename of the uploaded file.

  - `String mimeType`

    MIME type of the file.

  - `long sizeBytes`

    Size of the file in bytes.

  - `JsonValue; type "file"constant`

    Object type.

    For files, this is always `"file"`.

    - `FILE("file")`

  - `Optional<Boolean> downloadable`

    Whether the file can be downloaded.

  - `Optional<BetaFileScope> scope`

    The scope of this file, indicating the context in which it was created (e.g., a session).

    - `String id`

      The ID of the scoping resource (e.g., the session ID).

    - `JsonValue; type "session"constant`

      The type of scope (e.g., `"session"`).

      - `SESSION("session")`

# Skills

## Create Skill

`SkillCreateResponse beta().skills().create(SkillCreateParamsparams = SkillCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/skills`

Create Skill

### Parameters

- `SkillCreateParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<String> displayTitle`

    Display title for the skill.

    This is a human-readable label that is not included in the prompt sent to the model.

  - `Optional<List<String>> files`

    Files to upload for the skill.

    All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.

### Returns

- `class SkillCreateResponse:`

  - `String id`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `String createdAt`

    ISO 8601 timestamp of when the skill was created.

  - `Optional<String> displayTitle`

    Display title for the skill.

    This is a human-readable label that is not included in the prompt sent to the model.

  - `Optional<String> latestVersion`

    The latest version identifier for the skill.

    This represents the most recent version of the skill that has been created.

  - `String source`

    Source of the skill.

    This may be one of the following values:

    * `"custom"`: the skill was created by a user
    * `"anthropic"`: the skill was created by Anthropic

  - `String type`

    Object type.

    For Skills, this is always `"skill"`.

  - `String updatedAt`

    ISO 8601 timestamp of when the skill was last updated.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.SkillCreateParams;
import com.anthropic.models.beta.skills.SkillCreateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        SkillCreateResponse skill = client.beta().skills().create();
    }
}
```

#### Response

```json
{
  "id": "skill_01JAbcdefghijklmnopqrstuvw",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "display_title": "My Custom Skill",
  "latest_version": "1759178010641129",
  "source": "custom",
  "type": "type",
  "updated_at": "2024-10-30T23:58:27.427722Z"
}
```

## List Skills

`SkillListPage beta().skills().list(SkillListParamsparams = SkillListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/skills`

List Skills

### Parameters

- `SkillListParams params`

  - `Optional<Long> limit`

    Number of results to return per page.

    Maximum value is 100. Defaults to 20.

  - `Optional<String> page`

    Pagination token for fetching a specific page of results.

    Pass the value from a previous response's `next_page` field to get the next page of results.

  - `Optional<String> source`

    Filter skills by source.

    If provided, only skills from the specified source will be returned:

    * `"custom"`: only return user-created skills
    * `"anthropic"`: only return Anthropic-created skills

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class SkillListResponse:`

  - `String id`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `String createdAt`

    ISO 8601 timestamp of when the skill was created.

  - `Optional<String> displayTitle`

    Display title for the skill.

    This is a human-readable label that is not included in the prompt sent to the model.

  - `Optional<String> latestVersion`

    The latest version identifier for the skill.

    This represents the most recent version of the skill that has been created.

  - `String source`

    Source of the skill.

    This may be one of the following values:

    * `"custom"`: the skill was created by a user
    * `"anthropic"`: the skill was created by Anthropic

  - `String type`

    Object type.

    For Skills, this is always `"skill"`.

  - `String updatedAt`

    ISO 8601 timestamp of when the skill was last updated.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.SkillListPage;
import com.anthropic.models.beta.skills.SkillListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        SkillListPage page = client.beta().skills().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "skill_01JAbcdefghijklmnopqrstuvw",
      "created_at": "2024-10-30T23:58:27.427722Z",
      "display_title": "My Custom Skill",
      "latest_version": "1759178010641129",
      "source": "custom",
      "type": "type",
      "updated_at": "2024-10-30T23:58:27.427722Z"
    }
  ],
  "has_more": true,
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```

## Get Skill

`SkillRetrieveResponse beta().skills().retrieve(SkillRetrieveParamsparams = SkillRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/skills/{skill_id}`

Get Skill

### Parameters

- `SkillRetrieveParams params`

  - `Optional<String> skillId`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class SkillRetrieveResponse:`

  - `String id`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `String createdAt`

    ISO 8601 timestamp of when the skill was created.

  - `Optional<String> displayTitle`

    Display title for the skill.

    This is a human-readable label that is not included in the prompt sent to the model.

  - `Optional<String> latestVersion`

    The latest version identifier for the skill.

    This represents the most recent version of the skill that has been created.

  - `String source`

    Source of the skill.

    This may be one of the following values:

    * `"custom"`: the skill was created by a user
    * `"anthropic"`: the skill was created by Anthropic

  - `String type`

    Object type.

    For Skills, this is always `"skill"`.

  - `String updatedAt`

    ISO 8601 timestamp of when the skill was last updated.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.SkillRetrieveParams;
import com.anthropic.models.beta.skills.SkillRetrieveResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        SkillRetrieveResponse skill = client.beta().skills().retrieve("skill_id");
    }
}
```

#### Response

```json
{
  "id": "skill_01JAbcdefghijklmnopqrstuvw",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "display_title": "My Custom Skill",
  "latest_version": "1759178010641129",
  "source": "custom",
  "type": "type",
  "updated_at": "2024-10-30T23:58:27.427722Z"
}
```

## Delete Skill

`SkillDeleteResponse beta().skills().delete(SkillDeleteParamsparams = SkillDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/skills/{skill_id}`

Delete Skill

### Parameters

- `SkillDeleteParams params`

  - `Optional<String> skillId`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class SkillDeleteResponse:`

  - `String id`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `String type`

    Deleted object type.

    For Skills, this is always `"skill_deleted"`.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.SkillDeleteParams;
import com.anthropic.models.beta.skills.SkillDeleteResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        SkillDeleteResponse skill = client.beta().skills().delete("skill_id");
    }
}
```

#### Response

```json
{
  "id": "skill_01JAbcdefghijklmnopqrstuvw",
  "type": "type"
}
```

# Versions

## Create Skill Version

`VersionCreateResponse beta().skills().versions().create(VersionCreateParamsparams = VersionCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/skills/{skill_id}/versions`

Create Skill Version

### Parameters

- `VersionCreateParams params`

  - `Optional<String> skillId`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<List<String>> files`

    Files to upload for the skill.

    All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory.

### Returns

- `class VersionCreateResponse:`

  - `String id`

    Unique identifier for the skill version.

    The format and length of IDs may change over time.

  - `String createdAt`

    ISO 8601 timestamp of when the skill version was created.

  - `String description`

    Description of the skill version.

    This is extracted from the SKILL.md file in the skill upload.

  - `String directory`

    Directory name of the skill version.

    This is the top-level directory name that was extracted from the uploaded files.

  - `String name`

    Human-readable name of the skill version.

    This is extracted from the SKILL.md file in the skill upload.

  - `String skillId`

    Identifier for the skill that this version belongs to.

  - `String type`

    Object type.

    For Skill Versions, this is always `"skill_version"`.

  - `String version`

    Version identifier for the skill.

    Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.versions.VersionCreateParams;
import com.anthropic.models.beta.skills.versions.VersionCreateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        VersionCreateResponse version = client.beta().skills().versions().create("skill_id");
    }
}
```

#### Response

```json
{
  "id": "skillver_01JAbcdefghijklmnopqrstuvw",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "description": "A custom skill for doing something useful",
  "directory": "my-skill",
  "name": "my-skill",
  "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",
  "type": "type",
  "version": "1759178010641129"
}
```

## List Skill Versions

`VersionListPage beta().skills().versions().list(VersionListParamsparams = VersionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/skills/{skill_id}/versions`

List Skill Versions

### Parameters

- `VersionListParams params`

  - `Optional<String> skillId`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `Optional<Long> limit`

    Number of items to return per page.

    Defaults to `20`. Ranges from `1` to `1000`.

  - `Optional<String> page`

    Optionally set to the `next_page` token from the previous response.

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class VersionListResponse:`

  - `String id`

    Unique identifier for the skill version.

    The format and length of IDs may change over time.

  - `String createdAt`

    ISO 8601 timestamp of when the skill version was created.

  - `String description`

    Description of the skill version.

    This is extracted from the SKILL.md file in the skill upload.

  - `String directory`

    Directory name of the skill version.

    This is the top-level directory name that was extracted from the uploaded files.

  - `String name`

    Human-readable name of the skill version.

    This is extracted from the SKILL.md file in the skill upload.

  - `String skillId`

    Identifier for the skill that this version belongs to.

  - `String type`

    Object type.

    For Skill Versions, this is always `"skill_version"`.

  - `String version`

    Version identifier for the skill.

    Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.versions.VersionListPage;
import com.anthropic.models.beta.skills.versions.VersionListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        VersionListPage page = client.beta().skills().versions().list("skill_id");
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "skillver_01JAbcdefghijklmnopqrstuvw",
      "created_at": "2024-10-30T23:58:27.427722Z",
      "description": "A custom skill for doing something useful",
      "directory": "my-skill",
      "name": "my-skill",
      "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",
      "type": "type",
      "version": "1759178010641129"
    }
  ],
  "has_more": true,
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```

## Download Skill Version Content

`HttpResponse beta().skills().versions().download(VersionDownloadParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/skills/{skill_id}/versions/{version}/content`

Download a skill version's content as a zip archive.

### Parameters

- `VersionDownloadParams params`

  - `String skillId`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `Optional<String> version`

    Version identifier for the skill.

    Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.models.beta.skills.versions.VersionDownloadParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        VersionDownloadParams params = VersionDownloadParams.builder()
            .skillId("skill_id")
            .version("version")
            .build();
        HttpResponse response = client.beta().skills().versions().download(params);
    }
}
```

## Get Skill Version

`VersionRetrieveResponse beta().skills().versions().retrieve(VersionRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/skills/{skill_id}/versions/{version}`

Get Skill Version

### Parameters

- `VersionRetrieveParams params`

  - `String skillId`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `Optional<String> version`

    Version identifier for the skill.

    Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class VersionRetrieveResponse:`

  - `String id`

    Unique identifier for the skill version.

    The format and length of IDs may change over time.

  - `String createdAt`

    ISO 8601 timestamp of when the skill version was created.

  - `String description`

    Description of the skill version.

    This is extracted from the SKILL.md file in the skill upload.

  - `String directory`

    Directory name of the skill version.

    This is the top-level directory name that was extracted from the uploaded files.

  - `String name`

    Human-readable name of the skill version.

    This is extracted from the SKILL.md file in the skill upload.

  - `String skillId`

    Identifier for the skill that this version belongs to.

  - `String type`

    Object type.

    For Skill Versions, this is always `"skill_version"`.

  - `String version`

    Version identifier for the skill.

    Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.versions.VersionRetrieveParams;
import com.anthropic.models.beta.skills.versions.VersionRetrieveResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        VersionRetrieveParams params = VersionRetrieveParams.builder()
            .skillId("skill_id")
            .version("version")
            .build();
        VersionRetrieveResponse version = client.beta().skills().versions().retrieve(params);
    }
}
```

#### Response

```json
{
  "id": "skillver_01JAbcdefghijklmnopqrstuvw",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "description": "A custom skill for doing something useful",
  "directory": "my-skill",
  "name": "my-skill",
  "skill_id": "skill_01JAbcdefghijklmnopqrstuvw",
  "type": "type",
  "version": "1759178010641129"
}
```

## Delete Skill Version

`VersionDeleteResponse beta().skills().versions().delete(VersionDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**delete** `/v1/skills/{skill_id}/versions/{version}`

Delete Skill Version

### Parameters

- `VersionDeleteParams params`

  - `String skillId`

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  - `Optional<String> version`

    Version identifier for the skill.

    Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class VersionDeleteResponse:`

  - `String id`

    Version identifier for the skill.

    Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").

  - `String type`

    Deleted object type.

    For Skill Versions, this is always `"skill_version_deleted"`.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.versions.VersionDeleteParams;
import com.anthropic.models.beta.skills.versions.VersionDeleteResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        VersionDeleteParams params = VersionDeleteParams.builder()
            .skillId("skill_id")
            .version("version")
            .build();
        VersionDeleteResponse version = client.beta().skills().versions().delete(params);
    }
}
```

#### Response

```json
{
  "id": "1759178010641129",
  "type": "type"
}
```

# User Profiles

## Create User Profile

`BetaUserProfile beta().userProfiles().create(UserProfileCreateParamsparams = UserProfileCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/user_profiles`

Create User Profile

### Parameters

- `UserProfileCreateParams params`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<String> externalId`

    Platform's own identifier for this user. Not enforced unique. Maximum 255 characters.

  - `Optional<Metadata> metadata`

    Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings.

  - `Optional<String> name`

    Display name of the entity this profile represents. Required when relationship is `resold` (the resold-to company's name); optional otherwise. Maximum 255 characters.

  - `Optional<Relationship> relationship`

    How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage.

    - `EXTERNAL("external")`

    - `RESOLD("resold")`

    - `INTERNAL("internal")`

### Returns

- `class BetaUserProfile:`

  - `String id`

    Unique identifier for this user profile, prefixed `uprof_`.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

  - `Relationship relationship`

    How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage.

    - `EXTERNAL("external")`

    - `RESOLD("resold")`

    - `INTERNAL("internal")`

  - `TrustGrants trustGrants`

    Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

    - `Status status`

      Status of the trust grant.

      - `ACTIVE("active")`

      - `PENDING("pending")`

      - `REJECTED("rejected")`

  - `Type type`

    Object type. Always `user_profile`.

    - `USER_PROFILE("user_profile")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> externalId`

    Platform's own identifier for this user. Not enforced unique.

  - `Optional<String> name`

    Display name of the entity this profile represents. For `resold` this is the resold-to company's name.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.userprofiles.BetaUserProfile;
import com.anthropic.models.beta.userprofiles.UserProfileCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaUserProfile betaUserProfile = client.beta().userProfiles().create();
    }
}
```

#### Response

```json
{
  "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "created_at": "2026-03-15T10:00:00Z",
  "metadata": {},
  "relationship": "external",
  "trust_grants": {
    "cyber": {
      "status": "active"
    }
  },
  "type": "user_profile",
  "updated_at": "2026-03-15T10:00:00Z",
  "external_id": "user_12345",
  "name": "Example User"
}
```

## List User Profiles

`UserProfileListPage beta().userProfiles().list(UserProfileListParamsparams = UserProfileListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/user_profiles`

List User Profiles

### Parameters

- `UserProfileListParams params`

  - `Optional<Long> limit`

    Query parameter for limit

  - `Optional<Order> order`

    Query parameter for order

    - `ASC("asc")`

    - `DESC("desc")`

  - `Optional<String> page`

    Query parameter for page

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaUserProfile:`

  - `String id`

    Unique identifier for this user profile, prefixed `uprof_`.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

  - `Relationship relationship`

    How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage.

    - `EXTERNAL("external")`

    - `RESOLD("resold")`

    - `INTERNAL("internal")`

  - `TrustGrants trustGrants`

    Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

    - `Status status`

      Status of the trust grant.

      - `ACTIVE("active")`

      - `PENDING("pending")`

      - `REJECTED("rejected")`

  - `Type type`

    Object type. Always `user_profile`.

    - `USER_PROFILE("user_profile")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> externalId`

    Platform's own identifier for this user. Not enforced unique.

  - `Optional<String> name`

    Display name of the entity this profile represents. For `resold` this is the resold-to company's name.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.userprofiles.UserProfileListPage;
import com.anthropic.models.beta.userprofiles.UserProfileListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        UserProfileListPage page = client.beta().userProfiles().list();
    }
}
```

#### Response

```json
{
  "data": [
    {
      "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
      "created_at": "2026-03-15T10:00:00Z",
      "metadata": {},
      "relationship": "external",
      "trust_grants": {
        "cyber": {
          "status": "active"
        }
      },
      "type": "user_profile",
      "updated_at": "2026-03-15T10:00:00Z",
      "external_id": "user_12345",
      "name": "Example User"
    }
  ],
  "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```

## Get User Profile

`BetaUserProfile beta().userProfiles().retrieve(UserProfileRetrieveParamsparams = UserProfileRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/v1/user_profiles/{user_profile_id}`

Get User Profile

### Parameters

- `UserProfileRetrieveParams params`

  - `Optional<String> userProfileId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaUserProfile:`

  - `String id`

    Unique identifier for this user profile, prefixed `uprof_`.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

  - `Relationship relationship`

    How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage.

    - `EXTERNAL("external")`

    - `RESOLD("resold")`

    - `INTERNAL("internal")`

  - `TrustGrants trustGrants`

    Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

    - `Status status`

      Status of the trust grant.

      - `ACTIVE("active")`

      - `PENDING("pending")`

      - `REJECTED("rejected")`

  - `Type type`

    Object type. Always `user_profile`.

    - `USER_PROFILE("user_profile")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> externalId`

    Platform's own identifier for this user. Not enforced unique.

  - `Optional<String> name`

    Display name of the entity this profile represents. For `resold` this is the resold-to company's name.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.userprofiles.BetaUserProfile;
import com.anthropic.models.beta.userprofiles.UserProfileRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaUserProfile betaUserProfile = client.beta().userProfiles().retrieve("uprof_011CZkZCu8hGbp5mYRQgUmz9");
    }
}
```

#### Response

```json
{
  "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "created_at": "2026-03-15T10:00:00Z",
  "metadata": {},
  "relationship": "external",
  "trust_grants": {
    "cyber": {
      "status": "active"
    }
  },
  "type": "user_profile",
  "updated_at": "2026-03-15T10:00:00Z",
  "external_id": "user_12345",
  "name": "Example User"
}
```

## Update User Profile

`BetaUserProfile beta().userProfiles().update(UserProfileUpdateParamsparams = UserProfileUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/user_profiles/{user_profile_id}`

Update User Profile

### Parameters

- `UserProfileUpdateParams params`

  - `Optional<String> userProfileId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

  - `Optional<String> externalId`

    If present, replaces the stored external_id. Omit to leave unchanged. Maximum 255 characters.

  - `Optional<Metadata> metadata`

    Key-value pairs to merge into the stored metadata. Keys provided overwrite existing values. To remove a key, set its value to an empty string. Keys not provided are left unchanged. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters.

  - `Optional<String> name`

    If present, replaces the stored name. Omit to leave unchanged. Maximum 255 characters.

  - `Optional<Relationship> relationship`

    How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage.

    - `EXTERNAL("external")`

    - `RESOLD("resold")`

    - `INTERNAL("internal")`

### Returns

- `class BetaUserProfile:`

  - `String id`

    Unique identifier for this user profile, prefixed `uprof_`.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

  - `Relationship relationship`

    How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage.

    - `EXTERNAL("external")`

    - `RESOLD("resold")`

    - `INTERNAL("internal")`

  - `TrustGrants trustGrants`

    Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

    - `Status status`

      Status of the trust grant.

      - `ACTIVE("active")`

      - `PENDING("pending")`

      - `REJECTED("rejected")`

  - `Type type`

    Object type. Always `user_profile`.

    - `USER_PROFILE("user_profile")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> externalId`

    Platform's own identifier for this user. Not enforced unique.

  - `Optional<String> name`

    Display name of the entity this profile represents. For `resold` this is the resold-to company's name.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.userprofiles.BetaUserProfile;
import com.anthropic.models.beta.userprofiles.UserProfileUpdateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaUserProfile betaUserProfile = client.beta().userProfiles().update("uprof_011CZkZCu8hGbp5mYRQgUmz9");
    }
}
```

#### Response

```json
{
  "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "created_at": "2026-03-15T10:00:00Z",
  "metadata": {},
  "relationship": "external",
  "trust_grants": {
    "cyber": {
      "status": "active"
    }
  },
  "type": "user_profile",
  "updated_at": "2026-03-15T10:00:00Z",
  "external_id": "user_12345",
  "name": "Example User"
}
```

## Create Enrollment URL

`BetaUserProfileEnrollmentUrl beta().userProfiles().createEnrollmentUrl(UserProfileCreateEnrollmentUrlParamsparams = UserProfileCreateEnrollmentUrlParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/v1/user_profiles/{user_profile_id}/enrollment_url`

Create Enrollment URL

### Parameters

- `UserProfileCreateEnrollmentUrlParams params`

  - `Optional<String> userProfileId`

  - `Optional<List<AnthropicBeta>> betas`

    Optional header to specify the beta version(s) you want to use.

    - `MESSAGE_BATCHES_2024_09_24("message-batches-2024-09-24")`

    - `PROMPT_CACHING_2024_07_31("prompt-caching-2024-07-31")`

    - `COMPUTER_USE_2024_10_22("computer-use-2024-10-22")`

    - `COMPUTER_USE_2025_01_24("computer-use-2025-01-24")`

    - `PDFS_2024_09_25("pdfs-2024-09-25")`

    - `TOKEN_COUNTING_2024_11_01("token-counting-2024-11-01")`

    - `TOKEN_EFFICIENT_TOOLS_2025_02_19("token-efficient-tools-2025-02-19")`

    - `OUTPUT_128K_2025_02_19("output-128k-2025-02-19")`

    - `FILES_API_2025_04_14("files-api-2025-04-14")`

    - `MCP_CLIENT_2025_04_04("mcp-client-2025-04-04")`

    - `MCP_CLIENT_2025_11_20("mcp-client-2025-11-20")`

    - `DEV_FULL_THINKING_2025_05_14("dev-full-thinking-2025-05-14")`

    - `INTERLEAVED_THINKING_2025_05_14("interleaved-thinking-2025-05-14")`

    - `CODE_EXECUTION_2025_05_22("code-execution-2025-05-22")`

    - `EXTENDED_CACHE_TTL_2025_04_11("extended-cache-ttl-2025-04-11")`

    - `CONTEXT_1M_2025_08_07("context-1m-2025-08-07")`

    - `CONTEXT_MANAGEMENT_2025_06_27("context-management-2025-06-27")`

    - `MODEL_CONTEXT_WINDOW_EXCEEDED_2025_08_26("model-context-window-exceeded-2025-08-26")`

    - `SKILLS_2025_10_02("skills-2025-10-02")`

    - `FAST_MODE_2026_02_01("fast-mode-2026-02-01")`

    - `OUTPUT_300K_2026_03_24("output-300k-2026-03-24")`

    - `USER_PROFILES_2026_03_24("user-profiles-2026-03-24")`

    - `ADVISOR_TOOL_2026_03_01("advisor-tool-2026-03-01")`

    - `MANAGED_AGENTS_2026_04_01("managed-agents-2026-04-01")`

    - `CACHE_DIAGNOSIS_2026_04_07("cache-diagnosis-2026-04-07")`

    - `THINKING_TOKEN_COUNT_2026_05_13("thinking-token-count-2026-05-13")`

    - `SERVER_SIDE_FALLBACK_2026_06_01("server-side-fallback-2026-06-01")`

    - `FALLBACK_CREDIT_2026_06_01("fallback-credit-2026-06-01")`

### Returns

- `class BetaUserProfileEnrollmentUrl:`

  - `LocalDateTime expiresAt`

    A timestamp in RFC 3339 format

  - `Type type`

    Object type. Always `enrollment_url`.

    - `ENROLLMENT_URL("enrollment_url")`

  - `String url`

    Enrollment URL to send to the end user. Valid until `expires_at`.

### Example

```java
package com.anthropic.example;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.userprofiles.BetaUserProfileEnrollmentUrl;
import com.anthropic.models.beta.userprofiles.UserProfileCreateEnrollmentUrlParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        BetaUserProfileEnrollmentUrl betaUserProfileEnrollmentUrl = client.beta().userProfiles().createEnrollmentUrl("uprof_011CZkZCu8hGbp5mYRQgUmz9");
    }
}
```

#### Response

```json
{
  "expires_at": "2026-03-15T10:15:00Z",
  "type": "enrollment_url",
  "url": "https://platform.claude.com/user-profiles/enrollment/M3J0bGJxZ2ppMnptbnB1"
}
```

## Domain Types

### Beta User Profile

- `class BetaUserProfile:`

  - `String id`

    Unique identifier for this user profile, prefixed `uprof_`.

  - `LocalDateTime createdAt`

    A timestamp in RFC 3339 format

  - `Metadata metadata`

    Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

  - `Relationship relationship`

    How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage.

    - `EXTERNAL("external")`

    - `RESOLD("resold")`

    - `INTERNAL("internal")`

  - `TrustGrants trustGrants`

    Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

    - `Status status`

      Status of the trust grant.

      - `ACTIVE("active")`

      - `PENDING("pending")`

      - `REJECTED("rejected")`

  - `Type type`

    Object type. Always `user_profile`.

    - `USER_PROFILE("user_profile")`

  - `LocalDateTime updatedAt`

    A timestamp in RFC 3339 format

  - `Optional<String> externalId`

    Platform's own identifier for this user. Not enforced unique.

  - `Optional<String> name`

    Display name of the entity this profile represents. For `resold` this is the resold-to company's name.

### Beta User Profile Enrollment URL

- `class BetaUserProfileEnrollmentUrl:`

  - `LocalDateTime expiresAt`

    A timestamp in RFC 3339 format

  - `Type type`

    Object type. Always `enrollment_url`.

    - `ENROLLMENT_URL("enrollment_url")`

  - `String url`

    Enrollment URL to send to the end user. Valid until `expires_at`.

### Beta User Profile Trust Grant

- `class BetaUserProfileTrustGrant:`

  - `Status status`

    Status of the trust grant.

    - `ACTIVE("active")`

    - `PENDING("pending")`

    - `REJECTED("rejected")`

# Webhooks

## Domain Types

### Beta Webhook Event

- `class BetaWebhookEvent:`

  - `String id`

    Unique event identifier for idempotency.

  - `LocalDateTime createdAt`

    RFC 3339 timestamp when the event occurred.

  - `BetaWebhookEventData data`

    - `class BetaWebhookSessionCreatedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.created"constant`

        - `SESSION_CREATED("session.created")`

      - `String workspaceId`

    - `class BetaWebhookSessionPendingEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.pending"constant`

        - `SESSION_PENDING("session.pending")`

      - `String workspaceId`

    - `class BetaWebhookSessionRunningEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.running"constant`

        - `SESSION_RUNNING("session.running")`

      - `String workspaceId`

    - `class BetaWebhookSessionIdledEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.idled"constant`

        - `SESSION_IDLED("session.idled")`

      - `String workspaceId`

    - `class BetaWebhookSessionRequiresActionEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.requires_action"constant`

        - `SESSION_REQUIRES_ACTION("session.requires_action")`

      - `String workspaceId`

    - `class BetaWebhookSessionArchivedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.archived"constant`

        - `SESSION_ARCHIVED("session.archived")`

      - `String workspaceId`

    - `class BetaWebhookSessionDeletedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.deleted"constant`

        - `SESSION_DELETED("session.deleted")`

      - `String workspaceId`

    - `class BetaWebhookSessionStatusRescheduledEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.status_rescheduled"constant`

        - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

      - `String workspaceId`

    - `class BetaWebhookSessionStatusRunStartedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.status_run_started"constant`

        - `SESSION_STATUS_RUN_STARTED("session.status_run_started")`

      - `String workspaceId`

    - `class BetaWebhookSessionStatusIdledEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.status_idled"constant`

        - `SESSION_STATUS_IDLED("session.status_idled")`

      - `String workspaceId`

    - `class BetaWebhookSessionStatusTerminatedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.status_terminated"constant`

        - `SESSION_STATUS_TERMINATED("session.status_terminated")`

      - `String workspaceId`

    - `class BetaWebhookSessionThreadCreatedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `String sessionThreadId`

        ID of the session thread this event refers to.

      - `JsonValue; type "session.thread_created"constant`

        - `SESSION_THREAD_CREATED("session.thread_created")`

      - `String workspaceId`

    - `class BetaWebhookSessionThreadIdledEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `String sessionThreadId`

        ID of the session thread this event refers to.

      - `JsonValue; type "session.thread_idled"constant`

        - `SESSION_THREAD_IDLED("session.thread_idled")`

      - `String workspaceId`

    - `class BetaWebhookSessionThreadTerminatedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `String sessionThreadId`

        ID of the session thread this event refers to.

      - `JsonValue; type "session.thread_terminated"constant`

        - `SESSION_THREAD_TERMINATED("session.thread_terminated")`

      - `String workspaceId`

    - `class BetaWebhookSessionOutcomeEvaluationEndedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.outcome_evaluation_ended"constant`

        - `SESSION_OUTCOME_EVALUATION_ENDED("session.outcome_evaluation_ended")`

      - `String workspaceId`

    - `class BetaWebhookVaultCreatedEventData:`

      - `String id`

        ID of the vault that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault.created"constant`

        - `VAULT_CREATED("vault.created")`

      - `String workspaceId`

    - `class BetaWebhookVaultArchivedEventData:`

      - `String id`

        ID of the vault that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault.archived"constant`

        - `VAULT_ARCHIVED("vault.archived")`

      - `String workspaceId`

    - `class BetaWebhookVaultDeletedEventData:`

      - `String id`

        ID of the vault that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault.deleted"constant`

        - `VAULT_DELETED("vault.deleted")`

      - `String workspaceId`

    - `class BetaWebhookVaultCredentialCreatedEventData:`

      - `String id`

        ID of the vault credential that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault_credential.created"constant`

        - `VAULT_CREDENTIAL_CREATED("vault_credential.created")`

      - `String vaultId`

        ID of the vault that owns this credential.

      - `String workspaceId`

    - `class BetaWebhookVaultCredentialArchivedEventData:`

      - `String id`

        ID of the vault credential that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault_credential.archived"constant`

        - `VAULT_CREDENTIAL_ARCHIVED("vault_credential.archived")`

      - `String vaultId`

        ID of the vault that owns this credential.

      - `String workspaceId`

    - `class BetaWebhookVaultCredentialDeletedEventData:`

      - `String id`

        ID of the vault credential that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault_credential.deleted"constant`

        - `VAULT_CREDENTIAL_DELETED("vault_credential.deleted")`

      - `String vaultId`

        ID of the vault that owns this credential.

      - `String workspaceId`

    - `class BetaWebhookVaultCredentialRefreshFailedEventData:`

      - `String id`

        ID of the vault credential that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault_credential.refresh_failed"constant`

        - `VAULT_CREDENTIAL_REFRESH_FAILED("vault_credential.refresh_failed")`

      - `String vaultId`

        ID of the vault that owns this credential.

      - `String workspaceId`

  - `JsonValue; type "event"constant`

    Object type. Always `event` for webhook payloads.

    - `EVENT("event")`

### Beta Webhook Event Data

- `class BetaWebhookEventData: A class that can be one of several variants.union`

  - `class BetaWebhookSessionCreatedEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.created"constant`

      - `SESSION_CREATED("session.created")`

    - `String workspaceId`

  - `class BetaWebhookSessionPendingEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.pending"constant`

      - `SESSION_PENDING("session.pending")`

    - `String workspaceId`

  - `class BetaWebhookSessionRunningEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.running"constant`

      - `SESSION_RUNNING("session.running")`

    - `String workspaceId`

  - `class BetaWebhookSessionIdledEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.idled"constant`

      - `SESSION_IDLED("session.idled")`

    - `String workspaceId`

  - `class BetaWebhookSessionRequiresActionEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.requires_action"constant`

      - `SESSION_REQUIRES_ACTION("session.requires_action")`

    - `String workspaceId`

  - `class BetaWebhookSessionArchivedEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.archived"constant`

      - `SESSION_ARCHIVED("session.archived")`

    - `String workspaceId`

  - `class BetaWebhookSessionDeletedEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.deleted"constant`

      - `SESSION_DELETED("session.deleted")`

    - `String workspaceId`

  - `class BetaWebhookSessionStatusRescheduledEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.status_rescheduled"constant`

      - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

    - `String workspaceId`

  - `class BetaWebhookSessionStatusRunStartedEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.status_run_started"constant`

      - `SESSION_STATUS_RUN_STARTED("session.status_run_started")`

    - `String workspaceId`

  - `class BetaWebhookSessionStatusIdledEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.status_idled"constant`

      - `SESSION_STATUS_IDLED("session.status_idled")`

    - `String workspaceId`

  - `class BetaWebhookSessionStatusTerminatedEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.status_terminated"constant`

      - `SESSION_STATUS_TERMINATED("session.status_terminated")`

    - `String workspaceId`

  - `class BetaWebhookSessionThreadCreatedEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `String sessionThreadId`

      ID of the session thread this event refers to.

    - `JsonValue; type "session.thread_created"constant`

      - `SESSION_THREAD_CREATED("session.thread_created")`

    - `String workspaceId`

  - `class BetaWebhookSessionThreadIdledEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `String sessionThreadId`

      ID of the session thread this event refers to.

    - `JsonValue; type "session.thread_idled"constant`

      - `SESSION_THREAD_IDLED("session.thread_idled")`

    - `String workspaceId`

  - `class BetaWebhookSessionThreadTerminatedEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `String sessionThreadId`

      ID of the session thread this event refers to.

    - `JsonValue; type "session.thread_terminated"constant`

      - `SESSION_THREAD_TERMINATED("session.thread_terminated")`

    - `String workspaceId`

  - `class BetaWebhookSessionOutcomeEvaluationEndedEventData:`

    - `String id`

      ID of the session that triggered the event.

    - `String organizationId`

    - `JsonValue; type "session.outcome_evaluation_ended"constant`

      - `SESSION_OUTCOME_EVALUATION_ENDED("session.outcome_evaluation_ended")`

    - `String workspaceId`

  - `class BetaWebhookVaultCreatedEventData:`

    - `String id`

      ID of the vault that triggered the event.

    - `String organizationId`

    - `JsonValue; type "vault.created"constant`

      - `VAULT_CREATED("vault.created")`

    - `String workspaceId`

  - `class BetaWebhookVaultArchivedEventData:`

    - `String id`

      ID of the vault that triggered the event.

    - `String organizationId`

    - `JsonValue; type "vault.archived"constant`

      - `VAULT_ARCHIVED("vault.archived")`

    - `String workspaceId`

  - `class BetaWebhookVaultDeletedEventData:`

    - `String id`

      ID of the vault that triggered the event.

    - `String organizationId`

    - `JsonValue; type "vault.deleted"constant`

      - `VAULT_DELETED("vault.deleted")`

    - `String workspaceId`

  - `class BetaWebhookVaultCredentialCreatedEventData:`

    - `String id`

      ID of the vault credential that triggered the event.

    - `String organizationId`

    - `JsonValue; type "vault_credential.created"constant`

      - `VAULT_CREDENTIAL_CREATED("vault_credential.created")`

    - `String vaultId`

      ID of the vault that owns this credential.

    - `String workspaceId`

  - `class BetaWebhookVaultCredentialArchivedEventData:`

    - `String id`

      ID of the vault credential that triggered the event.

    - `String organizationId`

    - `JsonValue; type "vault_credential.archived"constant`

      - `VAULT_CREDENTIAL_ARCHIVED("vault_credential.archived")`

    - `String vaultId`

      ID of the vault that owns this credential.

    - `String workspaceId`

  - `class BetaWebhookVaultCredentialDeletedEventData:`

    - `String id`

      ID of the vault credential that triggered the event.

    - `String organizationId`

    - `JsonValue; type "vault_credential.deleted"constant`

      - `VAULT_CREDENTIAL_DELETED("vault_credential.deleted")`

    - `String vaultId`

      ID of the vault that owns this credential.

    - `String workspaceId`

  - `class BetaWebhookVaultCredentialRefreshFailedEventData:`

    - `String id`

      ID of the vault credential that triggered the event.

    - `String organizationId`

    - `JsonValue; type "vault_credential.refresh_failed"constant`

      - `VAULT_CREDENTIAL_REFRESH_FAILED("vault_credential.refresh_failed")`

    - `String vaultId`

      ID of the vault that owns this credential.

    - `String workspaceId`

### Beta Webhook Session Archived Event Data

- `class BetaWebhookSessionArchivedEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.archived"constant`

    - `SESSION_ARCHIVED("session.archived")`

  - `String workspaceId`

### Beta Webhook Session Created Event Data

- `class BetaWebhookSessionCreatedEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.created"constant`

    - `SESSION_CREATED("session.created")`

  - `String workspaceId`

### Beta Webhook Session Deleted Event Data

- `class BetaWebhookSessionDeletedEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.deleted"constant`

    - `SESSION_DELETED("session.deleted")`

  - `String workspaceId`

### Beta Webhook Session Idled Event Data

- `class BetaWebhookSessionIdledEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.idled"constant`

    - `SESSION_IDLED("session.idled")`

  - `String workspaceId`

### Beta Webhook Session Outcome Evaluation Ended Event Data

- `class BetaWebhookSessionOutcomeEvaluationEndedEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.outcome_evaluation_ended"constant`

    - `SESSION_OUTCOME_EVALUATION_ENDED("session.outcome_evaluation_ended")`

  - `String workspaceId`

### Beta Webhook Session Pending Event Data

- `class BetaWebhookSessionPendingEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.pending"constant`

    - `SESSION_PENDING("session.pending")`

  - `String workspaceId`

### Beta Webhook Session Requires Action Event Data

- `class BetaWebhookSessionRequiresActionEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.requires_action"constant`

    - `SESSION_REQUIRES_ACTION("session.requires_action")`

  - `String workspaceId`

### Beta Webhook Session Running Event Data

- `class BetaWebhookSessionRunningEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.running"constant`

    - `SESSION_RUNNING("session.running")`

  - `String workspaceId`

### Beta Webhook Session Status Idled Event Data

- `class BetaWebhookSessionStatusIdledEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.status_idled"constant`

    - `SESSION_STATUS_IDLED("session.status_idled")`

  - `String workspaceId`

### Beta Webhook Session Status Rescheduled Event Data

- `class BetaWebhookSessionStatusRescheduledEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.status_rescheduled"constant`

    - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

  - `String workspaceId`

### Beta Webhook Session Status Run Started Event Data

- `class BetaWebhookSessionStatusRunStartedEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.status_run_started"constant`

    - `SESSION_STATUS_RUN_STARTED("session.status_run_started")`

  - `String workspaceId`

### Beta Webhook Session Status Terminated Event Data

- `class BetaWebhookSessionStatusTerminatedEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `JsonValue; type "session.status_terminated"constant`

    - `SESSION_STATUS_TERMINATED("session.status_terminated")`

  - `String workspaceId`

### Beta Webhook Session Thread Created Event Data

- `class BetaWebhookSessionThreadCreatedEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `String sessionThreadId`

    ID of the session thread this event refers to.

  - `JsonValue; type "session.thread_created"constant`

    - `SESSION_THREAD_CREATED("session.thread_created")`

  - `String workspaceId`

### Beta Webhook Session Thread Idled Event Data

- `class BetaWebhookSessionThreadIdledEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `String sessionThreadId`

    ID of the session thread this event refers to.

  - `JsonValue; type "session.thread_idled"constant`

    - `SESSION_THREAD_IDLED("session.thread_idled")`

  - `String workspaceId`

### Beta Webhook Session Thread Terminated Event Data

- `class BetaWebhookSessionThreadTerminatedEventData:`

  - `String id`

    ID of the session that triggered the event.

  - `String organizationId`

  - `String sessionThreadId`

    ID of the session thread this event refers to.

  - `JsonValue; type "session.thread_terminated"constant`

    - `SESSION_THREAD_TERMINATED("session.thread_terminated")`

  - `String workspaceId`

### Beta Webhook Vault Archived Event Data

- `class BetaWebhookVaultArchivedEventData:`

  - `String id`

    ID of the vault that triggered the event.

  - `String organizationId`

  - `JsonValue; type "vault.archived"constant`

    - `VAULT_ARCHIVED("vault.archived")`

  - `String workspaceId`

### Beta Webhook Vault Created Event Data

- `class BetaWebhookVaultCreatedEventData:`

  - `String id`

    ID of the vault that triggered the event.

  - `String organizationId`

  - `JsonValue; type "vault.created"constant`

    - `VAULT_CREATED("vault.created")`

  - `String workspaceId`

### Beta Webhook Vault Credential Archived Event Data

- `class BetaWebhookVaultCredentialArchivedEventData:`

  - `String id`

    ID of the vault credential that triggered the event.

  - `String organizationId`

  - `JsonValue; type "vault_credential.archived"constant`

    - `VAULT_CREDENTIAL_ARCHIVED("vault_credential.archived")`

  - `String vaultId`

    ID of the vault that owns this credential.

  - `String workspaceId`

### Beta Webhook Vault Credential Created Event Data

- `class BetaWebhookVaultCredentialCreatedEventData:`

  - `String id`

    ID of the vault credential that triggered the event.

  - `String organizationId`

  - `JsonValue; type "vault_credential.created"constant`

    - `VAULT_CREDENTIAL_CREATED("vault_credential.created")`

  - `String vaultId`

    ID of the vault that owns this credential.

  - `String workspaceId`

### Beta Webhook Vault Credential Deleted Event Data

- `class BetaWebhookVaultCredentialDeletedEventData:`

  - `String id`

    ID of the vault credential that triggered the event.

  - `String organizationId`

  - `JsonValue; type "vault_credential.deleted"constant`

    - `VAULT_CREDENTIAL_DELETED("vault_credential.deleted")`

  - `String vaultId`

    ID of the vault that owns this credential.

  - `String workspaceId`

### Beta Webhook Vault Credential Refresh Failed Event Data

- `class BetaWebhookVaultCredentialRefreshFailedEventData:`

  - `String id`

    ID of the vault credential that triggered the event.

  - `String organizationId`

  - `JsonValue; type "vault_credential.refresh_failed"constant`

    - `VAULT_CREDENTIAL_REFRESH_FAILED("vault_credential.refresh_failed")`

  - `String vaultId`

    ID of the vault that owns this credential.

  - `String workspaceId`

### Beta Webhook Vault Deleted Event Data

- `class BetaWebhookVaultDeletedEventData:`

  - `String id`

    ID of the vault that triggered the event.

  - `String organizationId`

  - `JsonValue; type "vault.deleted"constant`

    - `VAULT_DELETED("vault.deleted")`

  - `String workspaceId`

### Unwrap Webhook Event

- `class UnwrapWebhookEvent:`

  - `String id`

    Unique event identifier for idempotency.

  - `LocalDateTime createdAt`

    RFC 3339 timestamp when the event occurred.

  - `BetaWebhookEventData data`

    - `class BetaWebhookSessionCreatedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.created"constant`

        - `SESSION_CREATED("session.created")`

      - `String workspaceId`

    - `class BetaWebhookSessionPendingEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.pending"constant`

        - `SESSION_PENDING("session.pending")`

      - `String workspaceId`

    - `class BetaWebhookSessionRunningEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.running"constant`

        - `SESSION_RUNNING("session.running")`

      - `String workspaceId`

    - `class BetaWebhookSessionIdledEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.idled"constant`

        - `SESSION_IDLED("session.idled")`

      - `String workspaceId`

    - `class BetaWebhookSessionRequiresActionEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.requires_action"constant`

        - `SESSION_REQUIRES_ACTION("session.requires_action")`

      - `String workspaceId`

    - `class BetaWebhookSessionArchivedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.archived"constant`

        - `SESSION_ARCHIVED("session.archived")`

      - `String workspaceId`

    - `class BetaWebhookSessionDeletedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.deleted"constant`

        - `SESSION_DELETED("session.deleted")`

      - `String workspaceId`

    - `class BetaWebhookSessionStatusRescheduledEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.status_rescheduled"constant`

        - `SESSION_STATUS_RESCHEDULED("session.status_rescheduled")`

      - `String workspaceId`

    - `class BetaWebhookSessionStatusRunStartedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.status_run_started"constant`

        - `SESSION_STATUS_RUN_STARTED("session.status_run_started")`

      - `String workspaceId`

    - `class BetaWebhookSessionStatusIdledEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.status_idled"constant`

        - `SESSION_STATUS_IDLED("session.status_idled")`

      - `String workspaceId`

    - `class BetaWebhookSessionStatusTerminatedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.status_terminated"constant`

        - `SESSION_STATUS_TERMINATED("session.status_terminated")`

      - `String workspaceId`

    - `class BetaWebhookSessionThreadCreatedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `String sessionThreadId`

        ID of the session thread this event refers to.

      - `JsonValue; type "session.thread_created"constant`

        - `SESSION_THREAD_CREATED("session.thread_created")`

      - `String workspaceId`

    - `class BetaWebhookSessionThreadIdledEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `String sessionThreadId`

        ID of the session thread this event refers to.

      - `JsonValue; type "session.thread_idled"constant`

        - `SESSION_THREAD_IDLED("session.thread_idled")`

      - `String workspaceId`

    - `class BetaWebhookSessionThreadTerminatedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `String sessionThreadId`

        ID of the session thread this event refers to.

      - `JsonValue; type "session.thread_terminated"constant`

        - `SESSION_THREAD_TERMINATED("session.thread_terminated")`

      - `String workspaceId`

    - `class BetaWebhookSessionOutcomeEvaluationEndedEventData:`

      - `String id`

        ID of the session that triggered the event.

      - `String organizationId`

      - `JsonValue; type "session.outcome_evaluation_ended"constant`

        - `SESSION_OUTCOME_EVALUATION_ENDED("session.outcome_evaluation_ended")`

      - `String workspaceId`

    - `class BetaWebhookVaultCreatedEventData:`

      - `String id`

        ID of the vault that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault.created"constant`

        - `VAULT_CREATED("vault.created")`

      - `String workspaceId`

    - `class BetaWebhookVaultArchivedEventData:`

      - `String id`

        ID of the vault that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault.archived"constant`

        - `VAULT_ARCHIVED("vault.archived")`

      - `String workspaceId`

    - `class BetaWebhookVaultDeletedEventData:`

      - `String id`

        ID of the vault that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault.deleted"constant`

        - `VAULT_DELETED("vault.deleted")`

      - `String workspaceId`

    - `class BetaWebhookVaultCredentialCreatedEventData:`

      - `String id`

        ID of the vault credential that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault_credential.created"constant`

        - `VAULT_CREDENTIAL_CREATED("vault_credential.created")`

      - `String vaultId`

        ID of the vault that owns this credential.

      - `String workspaceId`

    - `class BetaWebhookVaultCredentialArchivedEventData:`

      - `String id`

        ID of the vault credential that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault_credential.archived"constant`

        - `VAULT_CREDENTIAL_ARCHIVED("vault_credential.archived")`

      - `String vaultId`

        ID of the vault that owns this credential.

      - `String workspaceId`

    - `class BetaWebhookVaultCredentialDeletedEventData:`

      - `String id`

        ID of the vault credential that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault_credential.deleted"constant`

        - `VAULT_CREDENTIAL_DELETED("vault_credential.deleted")`

      - `String vaultId`

        ID of the vault that owns this credential.

      - `String workspaceId`

    - `class BetaWebhookVaultCredentialRefreshFailedEventData:`

      - `String id`

        ID of the vault credential that triggered the event.

      - `String organizationId`

      - `JsonValue; type "vault_credential.refresh_failed"constant`

        - `VAULT_CREDENTIAL_REFRESH_FAILED("vault_credential.refresh_failed")`

      - `String vaultId`

        ID of the vault that owns this credential.

      - `String workspaceId`

  - `JsonValue; type "event"constant`

    Object type. Always `event` for webhook payloads.

    - `EVENT("event")`
