--- title: Beta url: https://platform.claude.com/docs/en/api/cli/beta --- # Beta ## Domain types ### Beta API Error - `beta_api_error: object` - `type: "api_error"` - `message: string` ### Beta Authentication Error - `beta_authentication_error: object` - `type: "authentication_error"` - `message: string` ### Beta Billing Error - `beta_billing_error: object` - `type: "billing_error"` - `message: string` ### Beta Currency - `beta_currency: "USD"` - `"USD"` ### Beta Error - `beta_error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` - `beta_invalid_request_error: object` - `type: "invalid_request_error"` - `message: string` - `beta_authentication_error: object` - `type: "authentication_error"` - `message: string` - `beta_billing_error: object` - `type: "billing_error"` - `message: string` - `beta_permission_error: object` - `type: "permission_error"` - `message: string` - `beta_not_found_error: object` - `type: "not_found_error"` - `message: string` - `beta_rate_limit_error: object` - `type: "rate_limit_error"` - `message: string` - `beta_gateway_timeout_error: object` - `type: "timeout_error"` - `message: string` - `beta_api_error: object` - `type: "api_error"` - `message: string` - `beta_overloaded_error: object` - `type: "overloaded_error"` - `message: string` ### Beta Error Response - `beta_error_response: object` - `type: "error"` - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` - `beta_invalid_request_error: object` - `type: "invalid_request_error"` - `message: string` - `beta_authentication_error: object` - `type: "authentication_error"` - `message: string` - `beta_billing_error: object` - `type: "billing_error"` - `message: string` - `beta_permission_error: object` - `type: "permission_error"` - `message: string` - `beta_not_found_error: object` - `type: "not_found_error"` - `message: string` - `beta_rate_limit_error: object` - `type: "rate_limit_error"` - `message: string` - `beta_gateway_timeout_error: object` - `type: "timeout_error"` - `message: string` - `beta_api_error: object` - `type: "api_error"` - `message: string` - `beta_overloaded_error: object` - `type: "overloaded_error"` - `message: string` - `request_id: string` ### Beta Gateway Timeout Error - `beta_gateway_timeout_error: object` - `type: "timeout_error"` - `message: string` ### Beta Invalid Request Error - `beta_invalid_request_error: object` - `type: "invalid_request_error"` - `message: string` ### Beta Monetary Amount - `beta_monetary_amount: object` A monetary amount in a specific currency. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. ### Beta Not Found Error - `beta_not_found_error: object` - `type: "not_found_error"` - `message: string` ### Beta Overloaded Error - `beta_overloaded_error: object` - `type: "overloaded_error"` - `message: string` ### Beta Permission Error - `beta_permission_error: object` - `type: "permission_error"` - `message: string` ### Beta Rate Limit Error - `beta_rate_limit_error: object` - `type: "rate_limit_error"` - `message: string` ## Beta › Models ### List Models `$ ant beta:models list` **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 - `--after-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - `--before-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - `--lifecycle: optional array of "active" or "deprecated" or "retired"` (query parameter) Filter the list to models in any of the given lifecycle stages (`active`, `deprecated`, or `retired`). Up to 3 values. When omitted, the list contains the `active` and `deprecated` models; `retired` models appear only when `retired` is requested explicitly. maxItems: 3 - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaListResponse_ModelInfo_: object` - `data: array of BetaModelInfo` - `type: "model"` Object type. For Models, this is always `"model"`. - `id: string` Unique model identifier. - `allowed_fallback_models: array of string` 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. - `capabilities: object` Object mapping capability names to their support details. Keys are always present for all known capabilities. - `batch: object` Whether the model supports the Batch API. - `supported: boolean` Whether this capability is supported by the model. - `citations: object` Whether the model supports citation generation. - `supported: boolean` Whether this capability is supported by the model. - `code_execution: object` Whether code that the model runs in the code execution tool can call the request's other tools, as in programmatic tool calling and dynamic filtering for web search and web fetch. Support for the code execution tool itself is in `server_tools.code_execution`. - `supported: boolean` Whether this capability is supported by the model. - `compaction: object` Server-side compaction support (the top-level `compaction` parameter) and the accepted `compaction.type` values. - `summarize: object` Whether the summarize compaction type is supported. - `supported: boolean` Whether this capability is supported by the model. - `supported: boolean` Whether this capability is supported by the model. - `context_management: object` Context management support and available strategies. - `clear_thinking_20251015: object` Whether the clear_thinking_20251015 strategy is supported. - `supported: boolean` Whether this capability is supported by the model. - `clear_tool_uses_20250919: object` Whether the clear_tool_uses_20250919 strategy is supported. - `supported: boolean` Whether this capability is supported by the model. - `compact_20260112: object` Whether the compact_20260112 strategy is supported. - `supported: boolean` Whether this capability is supported by the model. - `supported: boolean` Whether this capability is supported by the model. - `effort: object` Effort (reasoning_effort) support and available levels. - `high: object` Whether the model supports high effort level. - `supported: boolean` Whether this capability is supported by the model. - `low: object` Whether the model supports low effort level. - `supported: boolean` Whether this capability is supported by the model. - `max: object` Whether the model supports max effort level. - `supported: boolean` Whether this capability is supported by the model. - `medium: object` Whether the model supports medium effort level. - `supported: boolean` Whether this capability is supported by the model. - `supported: boolean` Whether this capability is supported by the model. - `xhigh: object` Whether the model supports xhigh effort level. - `supported: boolean` Whether this capability is supported by the model. - `image_input: object` Whether the model accepts image content blocks. - `supported: boolean` Whether this capability is supported by the model. - `pdf_input: object` Whether the model accepts PDF content blocks. - `supported: boolean` Whether this capability is supported by the model. - `server_tools: object` Whether this model supports the web search and code execution server tools. `supported` is true when the model supports at least one of the tools. A supported tool can still be rejected for your organization, for example when an admin has turned web search off. - `code_execution: object` Whether the model supports the code execution tool: true when the model supports at least one version of the tool, not necessarily every version. - `supported: boolean` Whether this capability is supported by the model. - `supported: boolean` Whether this capability is supported by the model. - `web_search: object` Whether the model supports the web search tool: true when the model supports at least one version of the tool, not necessarily every version. - `supported: boolean` Whether this capability is supported by the model. - `structured_outputs: object` Whether the model supports structured output / JSON mode / strict tool schemas. - `supported: boolean` Whether this capability is supported by the model. - `thinking: object` Thinking capability and supported type configurations. - `supported: boolean` Whether this capability is supported by the model. - `types: object` Supported thinking type configurations. - `adaptive: object` Whether the model accepts thinking with type 'adaptive' (the model decides whether and how much to think). - `supported: boolean` Whether this capability is supported by the model. - `between_tools: object` Whether the model accepts thinking with type 'between_tools' (thinking turned off, and any short progress updates the model writes between tool calls come back as thinking blocks). False exactly when a request that sends it gets a 400 from this model. A request that sends 'between_tools' can still be rejected for another reason, such as an effort level the model does not allow with thinking off. - `supported: boolean` Whether this capability is supported by the model. - `disabled: object` Whether the model accepts thinking with type 'disabled' (thinking turned off). False exactly when a request that sends it gets a 400 from this model. True on a model that does not support thinking. A request that sends 'disabled' can still be rejected for another reason, such as an effort level the model does not allow with thinking off. - `supported: boolean` Whether this capability is supported by the model. - `enabled: object` Whether the model accepts thinking with type 'enabled' (extended thinking with a caller-set `budget_tokens`). - `supported: boolean` Whether this capability is supported by the model. - `created_at: string` 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. format: date-time - `deprecated_at: string` RFC 3339 datetime string representing the time of the model's most recent deprecation. Populated for `deprecated` and `retired` models; `null` while the model is `active`. format: date-time - `display_name: string` A human-readable name for the model. - `lifecycle: "active" or "deprecated" or "retired"` The model's current lifecycle stage. - `active`: The model is available for use, open to new adopters, and not scheduled for retirement. - `deprecated`: The model remains callable for organizations with existing access, but is headed for retirement and closed to new adopters. - `retired`: The model is no longer available for use; inference requests naming it fail. It remains in the catalogue as the historical record of its retirement. - `"active"` - `"deprecated"` - `"retired"` - `line: "haiku" or "sonnet" or "opus" or 2 more` The model line this model belongs to, such as `opus` for both Claude Opus 4.5 and Claude Opus 4.6. More lines may be added. `null` when the model belongs to no line; do not infer a line from the `id`. - `"haiku"` - `"sonnet"` - `"opus"` - `"fable"` - `"mythos"` - `max_input_tokens: number` Maximum input context window size in tokens for this model. - `max_tokens: number` Maximum value for the `max_tokens` parameter when using this model. - `retires_at: string` RFC 3339 datetime string representing the model's currently scheduled retirement date. The schedule can be revised until retirement occurs; `null` while the model is `active` or while no retirement is scheduled. A past date on a `deprecated` model means retirement is overdue, not that it has occurred: `lifecycle` is the retirement signal. format: date-time - `first_id: string` First ID in the `data` list. Can be used as the `before_id` for the previous page. - `has_more: boolean` Indicates if there are more results in the requested page direction. - `last_id: string` Last ID in the `data` list. Can be used as the `after_id` for the next page. #### Example ```bash ant beta:models list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "claude-opus-5-5", "allowed_fallback_models": [ "string" ], "capabilities": { "batch": { "supported": true }, "citations": { "supported": true }, "code_execution": { "supported": true }, "compaction": { "summarize": { "supported": true }, "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 }, "server_tools": { "code_execution": { "supported": true }, "supported": true, "web_search": { "supported": true } }, "structured_outputs": { "supported": true }, "thinking": { "supported": true, "types": { "adaptive": { "supported": true }, "between_tools": { "supported": true }, "disabled": { "supported": true }, "enabled": { "supported": true } } } }, "created_at": "2026-09-21T00:00:00Z", "deprecated_at": "2019-12-27T18:11:19.117Z", "display_name": "Claude Opus 5.5", "lifecycle": "active", "line": "haiku", "max_input_tokens": 0, "max_tokens": 0, "retires_at": "2019-12-27T18:11:19.117Z", "type": "model" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ### Get a Model `$ ant beta:models retrieve` **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 - `--model-id: string` (path parameter) Model identifier or alias. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_model_info: object` - `type: "model"` Object type. For Models, this is always `"model"`. - `id: string` Unique model identifier. - `allowed_fallback_models: array of string` 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. - `capabilities: object` Object mapping capability names to their support details. Keys are always present for all known capabilities. - `batch: object` Whether the model supports the Batch API. - `supported: boolean` Whether this capability is supported by the model. - `citations: object` Whether the model supports citation generation. - `supported: boolean` Whether this capability is supported by the model. - `code_execution: object` Whether code that the model runs in the code execution tool can call the request's other tools, as in programmatic tool calling and dynamic filtering for web search and web fetch. Support for the code execution tool itself is in `server_tools.code_execution`. - `supported: boolean` Whether this capability is supported by the model. - `compaction: object` Server-side compaction support (the top-level `compaction` parameter) and the accepted `compaction.type` values. - `summarize: object` Whether the summarize compaction type is supported. - `supported: boolean` Whether this capability is supported by the model. - `supported: boolean` Whether this capability is supported by the model. - `context_management: object` Context management support and available strategies. - `clear_thinking_20251015: object` Whether the clear_thinking_20251015 strategy is supported. - `supported: boolean` Whether this capability is supported by the model. - `clear_tool_uses_20250919: object` Whether the clear_tool_uses_20250919 strategy is supported. - `supported: boolean` Whether this capability is supported by the model. - `compact_20260112: object` Whether the compact_20260112 strategy is supported. - `supported: boolean` Whether this capability is supported by the model. - `supported: boolean` Whether this capability is supported by the model. - `effort: object` Effort (reasoning_effort) support and available levels. - `high: object` Whether the model supports high effort level. - `supported: boolean` Whether this capability is supported by the model. - `low: object` Whether the model supports low effort level. - `supported: boolean` Whether this capability is supported by the model. - `max: object` Whether the model supports max effort level. - `supported: boolean` Whether this capability is supported by the model. - `medium: object` Whether the model supports medium effort level. - `supported: boolean` Whether this capability is supported by the model. - `supported: boolean` Whether this capability is supported by the model. - `xhigh: object` Whether the model supports xhigh effort level. - `supported: boolean` Whether this capability is supported by the model. - `image_input: object` Whether the model accepts image content blocks. - `supported: boolean` Whether this capability is supported by the model. - `pdf_input: object` Whether the model accepts PDF content blocks. - `supported: boolean` Whether this capability is supported by the model. - `server_tools: object` Whether this model supports the web search and code execution server tools. `supported` is true when the model supports at least one of the tools. A supported tool can still be rejected for your organization, for example when an admin has turned web search off. - `code_execution: object` Whether the model supports the code execution tool: true when the model supports at least one version of the tool, not necessarily every version. - `supported: boolean` Whether this capability is supported by the model. - `supported: boolean` Whether this capability is supported by the model. - `web_search: object` Whether the model supports the web search tool: true when the model supports at least one version of the tool, not necessarily every version. - `supported: boolean` Whether this capability is supported by the model. - `structured_outputs: object` Whether the model supports structured output / JSON mode / strict tool schemas. - `supported: boolean` Whether this capability is supported by the model. - `thinking: object` Thinking capability and supported type configurations. - `supported: boolean` Whether this capability is supported by the model. - `types: object` Supported thinking type configurations. - `adaptive: object` Whether the model accepts thinking with type 'adaptive' (the model decides whether and how much to think). - `supported: boolean` Whether this capability is supported by the model. - `between_tools: object` Whether the model accepts thinking with type 'between_tools' (thinking turned off, and any short progress updates the model writes between tool calls come back as thinking blocks). False exactly when a request that sends it gets a 400 from this model. A request that sends 'between_tools' can still be rejected for another reason, such as an effort level the model does not allow with thinking off. - `supported: boolean` Whether this capability is supported by the model. - `disabled: object` Whether the model accepts thinking with type 'disabled' (thinking turned off). False exactly when a request that sends it gets a 400 from this model. True on a model that does not support thinking. A request that sends 'disabled' can still be rejected for another reason, such as an effort level the model does not allow with thinking off. - `supported: boolean` Whether this capability is supported by the model. - `enabled: object` Whether the model accepts thinking with type 'enabled' (extended thinking with a caller-set `budget_tokens`). - `supported: boolean` Whether this capability is supported by the model. - `created_at: string` 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. format: date-time - `deprecated_at: string` RFC 3339 datetime string representing the time of the model's most recent deprecation. Populated for `deprecated` and `retired` models; `null` while the model is `active`. format: date-time - `display_name: string` A human-readable name for the model. - `lifecycle: "active" or "deprecated" or "retired"` The model's current lifecycle stage. - `active`: The model is available for use, open to new adopters, and not scheduled for retirement. - `deprecated`: The model remains callable for organizations with existing access, but is headed for retirement and closed to new adopters. - `retired`: The model is no longer available for use; inference requests naming it fail. It remains in the catalogue as the historical record of its retirement. - `"active"` - `"deprecated"` - `"retired"` - `line: "haiku" or "sonnet" or "opus" or 2 more` The model line this model belongs to, such as `opus` for both Claude Opus 4.5 and Claude Opus 4.6. More lines may be added. `null` when the model belongs to no line; do not infer a line from the `id`. - `"haiku"` - `"sonnet"` - `"opus"` - `"fable"` - `"mythos"` - `max_input_tokens: number` Maximum input context window size in tokens for this model. - `max_tokens: number` Maximum value for the `max_tokens` parameter when using this model. - `retires_at: string` RFC 3339 datetime string representing the model's currently scheduled retirement date. The schedule can be revised until retirement occurs; `null` while the model is `active` or while no retirement is scheduled. A past date on a `deprecated` model means retirement is overdue, not that it has occurred: `lifecycle` is the retirement signal. format: date-time #### Example ```bash ant beta:models retrieve \ --api-key my-anthropic-api-key \ --model-id model_id ``` ##### Response (200) ```json { "id": "claude-opus-5-5", "allowed_fallback_models": [ "string" ], "capabilities": { "batch": { "supported": true }, "citations": { "supported": true }, "code_execution": { "supported": true }, "compaction": { "summarize": { "supported": true }, "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 }, "server_tools": { "code_execution": { "supported": true }, "supported": true, "web_search": { "supported": true } }, "structured_outputs": { "supported": true }, "thinking": { "supported": true, "types": { "adaptive": { "supported": true }, "between_tools": { "supported": true }, "disabled": { "supported": true }, "enabled": { "supported": true } } } }, "created_at": "2026-09-21T00:00:00Z", "deprecated_at": "2019-12-27T18:11:19.117Z", "display_name": "Claude Opus 5.5", "lifecycle": "active", "line": "haiku", "max_input_tokens": 0, "max_tokens": 0, "retires_at": "2019-12-27T18:11:19.117Z", "type": "model" } ``` ## Beta › Messages ### Create a Message `$ ant beta:messages create` **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://platform.claude.com/docs/en/get-started?sdk_languages=cli) #### Parameters - `--max-tokens: number` 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://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli#pre-warming-the-cache) without generating a response. Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview?sdk_languages=cli) for details. minimum: 0 - `--message: array of BetaMessageParam` 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. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors?sdk_languages=cli#prefill-not-supported). 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, for models that support prefill: ```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://platform.claude.com/docs/en/build-with-claude/working-with-messages?sdk_languages=cli). Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=cli#give-claude-a-role), 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. - `--model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `--cache-control: optional object` Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - `--compaction: optional object` Compaction configuration. When set on `POST /v1/messages`, the request is a compaction request: the conversation in `messages` is summarized and the response holds only the resulting `compaction` block (`stop_reason` `"compaction"`), which later requests send first in `messages` in place of the messages it summarizes. `POST /v1/messages/count_tokens` accepts this parameter and ignores it: the count it returns is for the conversation in `messages` as sent. Cannot be combined with `context_management`. - `--container: optional BetaContainerParams or string` Container identifier for reuse across requests. - `--context-management: optional object` Context management configuration. This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. - `--diagnostics: optional object` Request-level diagnostics. Supply `previous_message_id` to have the response include `diagnostics.cache_miss_reason` explaining any prompt-cache divergence from that prior request. - `--fallback-credit-token: optional string or BetaFallbackCreditTokenParam` 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. - `--fallbacks: optional array of BetaFallbackParam or "default"` 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. Some models don't support fallbacks; on those models, a list of fallback models returns a 400 error. See [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback?sdk_languages=cli#server-side-fallback). The string "default" requests the requested model's server-defined default fallback configuration. On a model that doesn't support fallbacks, the request runs on the requested model alone, so a declined request stays declined. - `--inference-geo: optional string` Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. - `--mcp-server: optional array of BetaRequestMCPServerURLDefinition` MCP servers to be utilized in this request maxItems: 20 - `--metadata: optional object` An object describing metadata about the request. - `--output-config: optional object` Configuration options for the model's output, such as the output format. - `--output-format: optional object` Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=cli) A schema to specify Claude's output format in responses. This parameter will be removed in a future release. - `--service-tier: optional "auto" or "standard_only"` 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://platform.claude.com/docs/en/api/service-tiers?sdk_languages=cli) for details. - `--speed: optional "standard" or "fast"` The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. Some models require the `fast-mode-2026-02-01` beta header for any `speed` value. See [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode?sdk_languages=cli) for which models. - `--stop-sequence: optional array of string` 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. - `--system: optional string or array of BetaTextBlockParam` 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://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=cli#give-claude-a-role). - `--thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigBetweenTools or BetaThinkingConfigAdaptive` Configuration for Claude's thinking. With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit. Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=cli#configuring-thinking) for each model's behavior. - `--tool-choice: optional BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or BetaToolChoiceNone` 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. - `--tool: optional array of BetaToolUnion` 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://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools?sdk_languages=cli), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool?sdk_languages=cli)). 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://platform.claude.com/docs/en/agents-and-tools/tool-use/overview?sdk_languages=cli) for more details. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--user-profile-id: optional string` (header parameter) The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. - `--temperature: optional number` **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not support setting temperature. A value of 1.0 will be accepted for backwards compatibility, all other values will be rejected with a 400 error. 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. minimum: 0, maximum: 1 - `--top-k: optional number` **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not accept top_k; any value will be rejected with a 400 error. 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. minimum: 0 - `--top-p: optional number` **Deprecated**: Deprecated. Models released after Claude Opus 4.6 do not support setting top_p. A value >= 0.99 will be accepted for backwards compatibility, all other values will be rejected with a 400 error. 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. minimum: 0, maximum: 1 #### Returns - `beta_message: object` - `type: "message"` Object type. For Messages, this is always `"message"`. - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: object` Information about the container used in this request. This will be non-null if a container tool (e.g. code execution) was used. - `id: string` Identifier for the container used in this request - `expires_at: string` The time at which the container will expire. format: date-time - `skills: array of BetaContainerSkill` Skills loaded in the container - `type: "anthropic" or "custom"` Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - `"anthropic"` - `"custom"` - `skill_id: string` Skill ID minLength: 1, maxLength: 64 - `version: string` The resolved version: a skill version ID for custom skills. minLength: 1, maxLength: 64 - `content: array of BetaContentBlock` 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)"}] ``` - `beta_text_block: object` - `type: "text"` - `citations: array of BetaTextCitation` 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`. - `beta_citation_char_location: object` - `type: "char_location"` - `cited_text: string` - `document_index: number` minimum: 0 - `document_title: string` - `end_char_index: number` - `file_id: string` - `start_char_index: number` minimum: 0 - `beta_citation_page_location: object` - `type: "page_location"` - `cited_text: string` - `document_index: number` minimum: 0 - `document_title: string` - `end_page_number: number` - `file_id: string` - `start_page_number: number` minimum: 1 - `beta_citation_content_block_location: object` - `type: "content_block_location"` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` minimum: 0 - `document_title: string` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. minimum: 0 - `beta_citations_web_search_result_location: object` - `type: "web_search_result_location"` - `cited_text: string` - `encrypted_index: string` - `title: string` maxLength: 512 - `url: string` - `beta_citation_search_result_location: object` - `type: "search_result_location"` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. minimum: 0 - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. minimum: 0 - `title: string` - `text: string` - `beta_thinking_block: object` - `type: "thinking"` - `signature: string` A value used to verify that this thinking block was generated by Claude when it is passed back to the API. This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=cli) for details. - `thinking: string` The text of Claude's thinking process for this block. - `beta_redacted_thinking_block: object` - `type: "redacted_thinking"` - `data: string` The contents of this redacted thinking block, returned when portions of the model's thinking were safety-redacted. This field is opaque and encrypted, with no readable content. Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=cli#redacted-thinking-blocks) for details. - `beta_tool_use_block: object` - `type: "tool_use"` - `id: string` pattern: ^[a-zA-Z0-9_-]+$ - `input: map[unknown]` - `name: string` minLength: 1 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_direct_caller: object` Tool invocation directly from the model. - `type: "direct"` - `beta_server_tool_caller: object` Tool invocation generated by a server-side tool. - `type: "code_execution_20250825"` - `tool_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_server_tool_caller_20260120: object` - `type: "code_execution_20260120"` - `tool_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `toolset_name: optional string` For a toolset member tool_use, the toolset family. minLength: 1, maxLength: 64, pattern: ^[a-zA-Z0-9_-]+$ - `beta_server_tool_use_block: object` - `type: "server_tool_use"` - `id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `input: map[unknown]` - `name: "advisor" or "web_search" or "web_fetch" or 5 more` - `"advisor"` - `"web_search"` - `"web_fetch"` - `"code_execution"` - `"bash_code_execution"` - `"text_editor_code_execution"` - `"tool_search_tool_regex"` - `"tool_search_tool_bm25"` - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_direct_caller: object` Tool invocation directly from the model. - `beta_server_tool_caller: object` Tool invocation generated by a server-side tool. - `beta_server_tool_caller_20260120: object` - `beta_web_search_tool_result_block: object` - `type: "web_search_tool_result"` - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` - `beta_web_search_tool_result_error: object` - `type: "web_search_tool_result_error"` - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `union_member_1: array of BetaWebSearchResultBlock` - `type: "web_search_result"` - `encrypted_content: string` - `page_age: string` - `title: string` - `url: string` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_direct_caller: object` Tool invocation directly from the model. - `beta_server_tool_caller: object` Tool invocation generated by a server-side tool. - `beta_server_tool_caller_20260120: object` - `beta_web_fetch_tool_result_block: object` - `type: "web_fetch_tool_result"` - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` - `beta_web_fetch_tool_result_error_block: object` - `type: "web_fetch_tool_result_error"` - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 7 more` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `"content_too_large"` - `beta_web_fetch_block: object` - `type: "web_fetch_result"` - `content: object` - `type: "document"` - `citations: object` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource or BetaPlainTextSource` - `beta_base64_pdf_source: object` - `type: "base64"` - `data: string` format: byte - `media_type: "application/pdf"` - `beta_plain_text_source: object` - `type: "text"` - `data: string` - `media_type: "text/plain"` - `title: string` The title of the document - `retrieved_at: string` ISO 8601 timestamp when the content was retrieved - `url: string` Fetched content URL - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_direct_caller: object` Tool invocation directly from the model. - `beta_server_tool_caller: object` Tool invocation generated by a server-side tool. - `beta_server_tool_caller_20260120: object` - `beta_advisor_tool_result_block: object` - `type: "advisor_tool_result"` - `content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock` - `beta_advisor_tool_result_error: object` - `type: "advisor_tool_result_error"` - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `"model_not_found"` - `beta_advisor_result_block: object` - `type: "advisor_result"` - `stop_reason: string` 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. - `text: string` - `beta_advisor_redacted_result_block: object` - `type: "advisor_redacted_result"` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_code_execution_tool_result_block: object` - `type: "code_execution_tool_result"` - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` - `beta_code_execution_tool_result_error: object` - `type: "code_execution_tool_result_error"` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `beta_code_execution_result_block: object` - `type: "code_execution_result"` - `content: array of BetaCodeExecutionOutputBlock` - `type: "code_execution_output"` - `file_id: string` - `return_code: number` - `stderr: string` - `stdout: string` - `beta_encrypted_code_execution_result_block: object` Code execution result with encrypted stdout for PFC + web_search results. - `type: "encrypted_code_execution_result"` - `content: array of BetaCodeExecutionOutputBlock` - `type: "code_execution_output"` - `file_id: string` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_bash_code_execution_tool_result_block: object` - `type: "bash_code_execution_tool_result"` - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` - `beta_bash_code_execution_tool_result_error: object` - `type: "bash_code_execution_tool_result_error"` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `beta_bash_code_execution_result_block: object` - `type: "bash_code_execution_result"` - `content: array of BetaBashCodeExecutionOutputBlock` - `type: "bash_code_execution_output"` - `file_id: string` - `return_code: number` - `stderr: string` - `stdout: string` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_text_editor_code_execution_tool_result_block: object` - `type: "text_editor_code_execution_tool_result"` - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` - `beta_text_editor_code_execution_tool_result_error: object` - `type: "text_editor_code_execution_tool_result_error"` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"file_not_found"` - `error_message: string` - `beta_text_editor_code_execution_view_result_block: object` - `type: "text_editor_code_execution_view_result"` - `content: string` - `file_type: "text" or "image" or "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number` - `start_line: number` - `total_lines: number` - `beta_text_editor_code_execution_create_result_block: object` - `type: "text_editor_code_execution_create_result"` - `is_file_update: boolean` - `beta_text_editor_code_execution_str_replace_result_block: object` - `type: "text_editor_code_execution_str_replace_result"` - `lines: array of string` - `new_lines: number` - `new_start: number` - `old_lines: number` - `old_start: number` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_tool_search_tool_result_block: object` - `type: "tool_search_tool_result"` - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` - `beta_tool_search_tool_result_error: object` - `type: "tool_search_tool_result_error"` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string` - `beta_tool_search_tool_search_result_block: object` - `type: "tool_search_tool_search_result"` - `tool_references: array of BetaToolReferenceBlock` - `type: "tool_reference"` - `tool_name: string` minLength: 1, maxLength: 256, pattern: ^[a-zA-Z0-9_-]{1,256}$ - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_mcp_tool_use_block: object` - `type: "mcp_tool_use"` - `id: string` pattern: ^[a-zA-Z0-9_-]+$ - `input: map[unknown]` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `beta_mcp_tool_result_block: object` - `type: "mcp_tool_result"` - `content: string or array of BetaTextBlock` - `union_member_0: string` - `beta_mcp_tool_result_block_content: array of BetaTextBlock` - `type: "text"` - `citations: array of BetaTextCitation` 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`. - `text: string` - `is_error: boolean` - `tool_use_id: string` pattern: ^[a-zA-Z0-9_-]+$ - `beta_container_upload_block: object` Response model for a file uploaded to the container. - `type: "container_upload"` - `file_id: string` - `beta_compaction_block: object` 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. - `type: "compaction"` - `content: string` Summary of compacted content, or null if compaction failed - `encrypted_content: string` Opaque metadata from prior compaction, to be round-tripped verbatim - `signature: optional string` Signature over the summary, to be sent back with the block verbatim - `tool_changes: optional array of BetaResponseToolAdditionBlock or BetaResponseToolRemovalBlock` The tool changes of the compacted range: the `tool_addition` and `tool_removal` blocks that take the request's `tools` to the tool set in effect at the end of the range, or `[]` when the range changed no tool. Absent when the server did not compute them. Send the block back unchanged. - `beta_response_tool_addition_block: object` An entry of a `compaction` block's `tool_changes`: a tool the compacted range made available, as a reference to a `tools` entry or MCP toolset, or as the tool definition in effect at the end of the range, by value. Send it back unchanged. - `type: "tool_addition"` - `tool: BetaResponseToolChangeToolReference or BetaResponseToolChangeMCPToolReference or BetaResponseToolChangeMCPToolsetReference or BetaToolChangeToolDefinition` The tool made available: a reference to a `tools` entry or MCP toolset, or a `tool_definition` carrying the definition by value. - `beta_response_tool_change_tool_reference: object` Reference to a single tool, by the name the model uses to call it, as a `compaction` block's `tool_changes` entry reports it: a tool declared in `tools` or defined by an earlier `tool_addition` block. Send it back unchanged with the block. - `type: "tool_reference"` - `name: string` - `beta_response_tool_change_mcp_tool_reference: object` Reference to a single MCP tool, by its server and its name on that server, as a `compaction` block's `tool_changes` entry reports it. Send it back unchanged with the block. - `type: "mcp_tool_reference"` - `name: string` - `server_name: string` - `beta_response_tool_change_mcp_toolset_reference: object` Reference to every tool in the named MCP server's toolset, as a `compaction` block's `tool_changes` entry reports it. Send it back unchanged with the block. - `type: "mcp_toolset_reference"` - `server_name: string` - `beta_tool_change_tool_definition: object` A tool defined by value, as a `compaction` block's `tool_changes` entry reports it: `definition` is the tool's definition as it was sent, in the form of a `tools` entry, without `cache_control`. Send it back unchanged with the block. - `type: "tool_definition"` - `definition: BetaResponseTool or BetaToolBash20241022 or BetaToolBash20250124 or 25 more` - `beta_response_tool: object` A custom tool definition, as sent. - `type: optional "custom"` - `input_schema: object` [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. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. minLength: 1, maxLength: 128, pattern: ^[a-zA-Z0-9_-]{1,128}$ - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `description: optional string` 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. - `eager_input_streaming: optional boolean` 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. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_bash_20241022: object` - `type: "bash_20241022"` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `"5m"` - `"1h"` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_bash_20250124: object` - `type: "bash_20250124"` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_code_execution_tool_20250522: object` - `type: "code_execution_20250522"` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_code_execution_tool_20250825: object` - `type: "code_execution_20250825"` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_code_execution_tool_20260120: object` Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - `type: "code_execution_20260120"` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_code_execution_tool_20260521: object` Code execution tool with REPL state persistence. - `type: "code_execution_20260521"` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_browser_toolset_20260801: object` The browser toolset: a single `tools[]` entry (carrying no `name`) that declares the browser tool family. The model is served the family's tool with any members disabled via `configs` removed from its schema. - `type: "browser_toolset_20260801"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `configs: optional object` Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent. - `type: optional object` `type`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `close_tab: optional object` `close_tab`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `double_click: optional object` `double_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `file_upload: optional object` `file_upload`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `find: optional object` `find`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `form_input: optional object` `form_input`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `get_page_text: optional object` `get_page_text`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `hold_key: optional object` `hold_key`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `hover: optional object` `hover`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `javascript_exec: optional object` `javascript_exec`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `key: optional object` `key`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_click: optional object` `left_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_click_drag: optional object` `left_click_drag`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_mouse_down: optional object` `left_mouse_down`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_mouse_up: optional object` `left_mouse_up`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `list_tabs: optional object` `list_tabs`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `middle_click: optional object` `middle_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `mouse_move: optional object` `mouse_move`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `navigate: optional object` `navigate`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `new_tab: optional object` `new_tab`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `read_console: optional object` `read_console`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `read_network: optional object` `read_network`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `read_page: optional object` `read_page`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `right_click: optional object` `right_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `screenshot: optional object` `screenshot`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `scroll: optional object` `scroll`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `scroll_to: optional object` `scroll_to`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `switch_tab: optional object` `switch_tab`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `triple_click: optional object` `triple_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `wait: optional object` `wait`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `zoom: optional object` `zoom`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `beta_tool_computer_use_20241022: object` - `type: "computer_20241022"` - `display_height_px: number` The height of the display in pixels. minimum: 1 - `display_width_px: number` The width of the display in pixels. minimum: 1 - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number: optional number` The X11 display number (e.g. 0, 1) for the display. minimum: 0 - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_memory_tool_20250818: object` - `type: "memory_20250818"` - `name: "memory"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_computer_use_20250124: object` - `type: "computer_20250124"` - `display_height_px: number` The height of the display in pixels. minimum: 1 - `display_width_px: number` The width of the display in pixels. minimum: 1 - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number: optional number` The X11 display number (e.g. 0, 1) for the display. minimum: 0 - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_text_editor_20241022: object` - `type: "text_editor_20241022"` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_computer_use_20251124: object` - `type: "computer_20251124"` - `display_height_px: number` The height of the display in pixels. minimum: 1 - `display_width_px: number` The width of the display in pixels. minimum: 1 - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number: optional number` The X11 display number (e.g. 0, 1) for the display. minimum: 0 - `enable_zoom: optional boolean` Whether to enable an action to take a zoomed-in screenshot of the screen. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_computer_toolset_20260801: object` The computer toolset: a single `tools[]` entry (carrying no `name`) that declares the computer tool family. The model is served the family's tool with any members disabled via `configs` removed from its schema. Every member is enabled by default, zoom included. The single-tool options `display_number` and `enable_zoom` are not fields of a toolset entry — it carries only `type`, `configs`, and `cache_control`; zoom is controlled via `configs.zoom.enabled`. - `type: "computer_toolset_20260801"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `configs: optional object` Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent. - `type: optional object` `type`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `cursor_position: optional object` `cursor_position`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `double_click: optional object` `double_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `hold_key: optional object` `hold_key`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `key: optional object` `key`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_click: optional object` `left_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_click_drag: optional object` `left_click_drag`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_mouse_down: optional object` `left_mouse_down`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_mouse_up: optional object` `left_mouse_up`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `middle_click: optional object` `middle_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `mouse_move: optional object` `mouse_move`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `right_click: optional object` `right_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `screenshot: optional object` `screenshot`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `scroll: optional object` `scroll`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `triple_click: optional object` `triple_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `wait: optional object` `wait`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `zoom: optional object` `zoom`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `beta_tool_text_editor_20250124: object` - `type: "text_editor_20250124"` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_text_editor_20250429: object` - `type: "text_editor_20250429"` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_text_editor_20250728: object` - `type: "text_editor_20250728"` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `max_characters: optional number` Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_web_search_tool_20250305: object` - `type: "web_search_20250305"` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains: optional array of string` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `user_location: optional object` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `city: optional string` The city of the user. minLength: 1, maxLength: 255 - `country: optional string` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. minLength: 2, maxLength: 2 - `region: optional string` The region of the user. minLength: 1, maxLength: 255 - `timezone: optional string` The [IANA timezone](https://nodatime.org/TimeZones) of the user. minLength: 1, maxLength: 255 - `beta_web_fetch_tool_20250910: object` - `type: "web_fetch_20250910"` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` List of domains to allow fetching from - `blocked_domains: optional array of string` List of domains to block fetching from - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `citations: optional object` Citations configuration for fetched documents. Citations are disabled by default. - `enabled: optional boolean` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens: optional number` 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. minimum: 1 - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `url_sources: optional object` Which sources contribute to the set of URLs the tool may fetch. Omitted means every source. - `client_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which client tools' results contribute fetchable URLs: "all", "none", or an only or except list of client tool names from tools[]. - `beta_web_fetch_url_source_all: object` The `url_sources` variant under which a source contributes in full: every result of the tool filter's source, or all user input. - `type: "all"` - `beta_web_fetch_url_source_none: object` The `url_sources` variant under which a source contributes nothing: no result of the tool filter's source, or no user input. - `type: "none"` - `beta_web_fetch_url_source_only: object` The tool filter variant under which only the named tools' results contribute. - `type: "only"` - `tools: array of BetaWebFetchURLSourceToolReference` - `type: "tool_reference"` - `name: string` - `beta_web_fetch_url_source_except: object` The tool filter variant under which every result but the named tools' contributes. - `type: "except"` - `tools: array of BetaWebFetchURLSourceToolReference` - `type: "tool_reference"` - `name: string` - `server_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which server tools' results contribute fetchable URLs: "all", "none", or an only or except list of server tool names from tools[]; only web_search and web_fetch results ever contribute. - `beta_web_fetch_url_source_all: object` The `url_sources` variant under which a source contributes in full: every result of the tool filter's source, or all user input. - `beta_web_fetch_url_source_none: object` The `url_sources` variant under which a source contributes nothing: no result of the tool filter's source, or no user input. - `beta_web_fetch_url_source_only: object` The tool filter variant under which only the named tools' results contribute. - `beta_web_fetch_url_source_except: object` The tool filter variant under which every result but the named tools' contributes. - `user_input: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone` Whether URLs in user messages are fetchable: "all" or "none". - `beta_web_fetch_url_source_all: object` The `url_sources` variant under which a source contributes in full: every result of the tool filter's source, or all user input. - `beta_web_fetch_url_source_none: object` The `url_sources` variant under which a source contributes nothing: no result of the tool filter's source, or no user input. - `beta_web_search_tool_20260209: object` - `type: "web_search_20260209"` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains: optional array of string` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `user_location: optional object` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `city: optional string` The city of the user. minLength: 1, maxLength: 255 - `country: optional string` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. minLength: 2, maxLength: 2 - `region: optional string` The region of the user. minLength: 1, maxLength: 255 - `timezone: optional string` The [IANA timezone](https://nodatime.org/TimeZones) of the user. minLength: 1, maxLength: 255 - `beta_web_fetch_tool_20260209: object` - `type: "web_fetch_20260209"` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` List of domains to allow fetching from - `blocked_domains: optional array of string` List of domains to block fetching from - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `citations: optional object` Citations configuration for fetched documents. Citations are disabled by default. - `enabled: optional boolean` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens: optional number` 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. minimum: 1 - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `url_sources: optional object` Which sources contribute to the set of URLs the tool may fetch. Omitted means every source. - `client_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which client tools' results contribute fetchable URLs: "all", "none", or an only or except list of client tool names from tools[]. - `server_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which server tools' results contribute fetchable URLs: "all", "none", or an only or except list of server tool names from tools[]; only web_search and web_fetch results ever contribute. - `user_input: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone` Whether URLs in user messages are fetchable: "all" or "none". - `beta_web_fetch_tool_20260309: object` Web fetch tool with use_cache parameter for bypassing cached content. - `type: "web_fetch_20260309"` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` List of domains to allow fetching from - `blocked_domains: optional array of string` List of domains to block fetching from - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `citations: optional object` Citations configuration for fetched documents. Citations are disabled by default. - `enabled: optional boolean` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens: optional number` 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. minimum: 1 - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `url_sources: optional object` Which sources contribute to the set of URLs the tool may fetch. Omitted means every source. - `client_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which client tools' results contribute fetchable URLs: "all", "none", or an only or except list of client tool names from tools[]. - `server_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which server tools' results contribute fetchable URLs: "all", "none", or an only or except list of server tool names from tools[]; only web_search and web_fetch results ever contribute. - `user_input: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone` Whether URLs in user messages are fetchable: "all" or "none". - `use_cache: optional boolean` 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_search_tool_20260318: object` - `type: "web_search_20260318"` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains: optional array of string` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `response_inclusion: optional "full" or "excluded"` How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn. - `"full"` - `"excluded"` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `user_location: optional object` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `city: optional string` The city of the user. minLength: 1, maxLength: 255 - `country: optional string` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. minLength: 2, maxLength: 2 - `region: optional string` The region of the user. minLength: 1, maxLength: 255 - `timezone: optional string` The [IANA timezone](https://nodatime.org/TimeZones) of the user. minLength: 1, maxLength: 255 - `beta_web_fetch_tool_20260318: object` - `type: "web_fetch_20260318"` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` List of domains to allow fetching from - `blocked_domains: optional array of string` List of domains to block fetching from - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `citations: optional object` Citations configuration for fetched documents. Citations are disabled by default. - `enabled: optional boolean` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens: optional number` 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. minimum: 1 - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `response_inclusion: optional "full" or "excluded"` How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn. - `"full"` - `"excluded"` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `url_sources: optional object` Which sources contribute to the set of URLs the tool may fetch. Omitted means every source. - `client_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which client tools' results contribute fetchable URLs: "all", "none", or an only or except list of client tool names from tools[]. - `server_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which server tools' results contribute fetchable URLs: "all", "none", or an only or except list of server tool names from tools[]; only web_search and web_fetch results ever contribute. - `user_input: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone` Whether URLs in user messages are fetchable: "all" or "none". - `use_cache: optional boolean` 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_advisor_tool_20260301: object` - `type: "advisor_20260301"` - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `name: "advisor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `caching: optional object` 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. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_tokens: optional number` 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. minimum: 1024 - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_search_tool_bm25_20251119: object` - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` - `"tool_search_tool_bm25_20251119"` - `"tool_search_tool_bm25"` - `name: "tool_search_tool_bm25"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_search_tool_regex_20251119: object` - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` - `"tool_search_tool_regex_20251119"` - `"tool_search_tool_regex"` - `name: "tool_search_tool_regex"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_mcp_toolset: object` 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. - `type: "mcp_toolset"` - `mcp_server_name: string` Name of the MCP server to configure tools for minLength: 1, maxLength: 255 - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `configs: optional map[BetaMCPToolConfig]` Configuration overrides for specific tools, keyed by tool name - `defer_loading: optional boolean` - `enabled: optional boolean` - `default_config: optional object` Default configuration applied to all tools from this server - `defer_loading: optional boolean` - `enabled: optional boolean` - `tools: optional array of BetaMCPToolParam` The server's tool listing, pinned: when present, the server is not asked for its tools before sampling and exactly these entries, with `default_config` and `configs` applied, are the toolset's tools. Copy it from the `mcp_tool_listing` block of an earlier response. - `input_schema: map[unknown]` The tool's input schema as the MCP server lists it, verbatim. - `name: string` The tool's name as the MCP server lists it (not prefixed with the server name). minLength: 1 - `description: optional string` The tool's description as the MCP server lists it. - `beta_response_tool_removal_block: object` An entry of a `compaction` block's `tool_changes`: a tool of the request's `tools` (or an MCP tool or toolset) that the compacted range withdrew. Send it back unchanged. - `type: "tool_removal"` - `tool: BetaResponseToolChangeToolReference or BetaResponseToolChangeMCPToolReference or BetaResponseToolChangeMCPToolsetReference` A reference to the withdrawn `tools` entry, MCP tool or MCP toolset. - `beta_response_tool_change_tool_reference: object` Reference to a single tool, by the name the model uses to call it, as a `compaction` block's `tool_changes` entry reports it: a tool declared in `tools` or defined by an earlier `tool_addition` block. Send it back unchanged with the block. - `beta_response_tool_change_mcp_tool_reference: object` Reference to a single MCP tool, by its server and its name on that server, as a `compaction` block's `tool_changes` entry reports it. Send it back unchanged with the block. - `beta_response_tool_change_mcp_toolset_reference: object` Reference to every tool in the named MCP server's toolset, as a `compaction` block's `tool_changes` entry reports it. Send it back unchanged with the block. - `beta_fallback_block: object` Marks the point in `content` where one model's output gives way to the next. One block appears per hop where a preceding model actually ran this turn and declined. A turn where no preceding model ran and declined has no such boundary and carries no block — the signal for whether a fallback model served the response is the presence of a `fallback_message` entry in `usage.iterations`, not this block. The block is treated like a server-tool content block for streaming: it arrives via the standard `content_block_start` / `content_block_stop` pair and carries no deltas. - `type: "fallback"` - `from: object` 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: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `to: object` The fallback model producing the content that follows this block. Its `model` is always the canonical id. - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `trigger: object` What caused the `from` model to hand over at this hop. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the `from` model's refusal at this hop. `null` when the refusal doesn't map to a named category. Same vocabulary as `stop_details.category`. - `"cyber"` The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category. - `"bio"` The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category. - `"frontier_llm"` The request could assist the development of competing AI models, which is restricted under [Anthropic's commercial terms](https://www.anthropic.com/legal/commercial-terms). Benign machine learning work can also trigger this category. - `"reasoning_extraction"` The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking?sdk_languages=cli). - `"general_harms"` The request could be related to an area that was determined as harmful. Benign work might sometimes trigger this category. - `beta_mcp_tool_listing_block: object` The tool listing the server fetched from an MCP server while producing this response. Send the assistant message back unchanged, this block included, so later requests use this listing instead of asking the MCP server again. - `type: "mcp_tool_listing"` - `mcp_server_name: string` - `tools: array of BetaMCPTool` - `input_schema: map[unknown]` - `name: string` - `description: optional string` - `context_management: object` Context management response. Information about context management strategies applied during the request. - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` List of context management edits that were applied. - `beta_clear_tool_uses_20250919_edit_response: object` - `type: "clear_tool_uses_20250919"` The type of context management edit applied. - `cleared_input_tokens: number` Number of input tokens cleared by this edit. minimum: 0 - `cleared_tool_uses: number` Number of tool uses that were cleared. minimum: 0 - `beta_clear_thinking_20251015_edit_response: object` - `type: "clear_thinking_20251015"` The type of context management edit applied. - `cleared_input_tokens: number` Number of input tokens cleared by this edit. minimum: 0 - `cleared_thinking_turns: number` Number of thinking turns that were cleared. minimum: 0 - `diagnostics: object` Request-level diagnostics. `null` when the request did not supply `diagnostics`, or when it did and no prompt-cache divergence was detected. - `cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more` 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. - `beta_cache_miss_model_changed: object` - `type: "model_changed"` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `beta_cache_miss_system_changed: object` - `type: "system_changed"` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `beta_cache_miss_tools_changed: object` - `type: "tools_changed"` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `beta_cache_miss_messages_changed: object` - `type: "messages_changed"` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `beta_cache_miss_previous_message_not_found: object` - `type: "previous_message_not_found"` - `beta_cache_miss_unavailable: object` - `type: "unavailable"` - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `stop_details: object` Structured information about why model output stopped. This is `null` when the `stop_reason` has no additional detail to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category. - `"bio"` The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category. - `"frontier_llm"` The request could assist the development of competing AI models, which is restricted under [Anthropic's commercial terms](https://www.anthropic.com/legal/commercial-terms). Benign machine learning work can also trigger this category. - `"reasoning_extraction"` The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking?sdk_languages=cli). - `"general_harms"` The request could be related to an area that was determined as harmful. Benign work might sometimes trigger this category. - `explanation: string` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `fallback_credit_token: string` 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. - `fallback_has_prefill_claim: boolean` 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. - `recommended_model: string` 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. - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations * `"model_context_window_exceeded"`: we exceeded the model's context window In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string` 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. - `usage: object` 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`. - `cache_creation: object` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_creation_input_tokens: number` The number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. minimum: 0 - `fallback_credit: object` Outcome of the `fallback_credit_token` presented on this request. Present on every response to a non-batch request that carried a `fallback_credit_token`, in either redemption mode; absent otherwise (batch items accept and ignore the token and carry no outcome object). - `status: BetaFallbackCreditRedeemed or BetaFallbackCreditNotApplied` Whether the fallback-credit reprice was applied to this response's billing. A union discriminated on `type`. `redeemed`: the retry is billed as if the conversation had been on the retry model all along — including when the resulting shift is zero because there was nothing to move. `not_applied`: no reprice was applied; the arm's `reason` says why. - `beta_fallback_credit_redeemed: object` The reprice was applied: the retry is billed as if the conversation had been on the retry model all along. - `type: "redeemed"` - `beta_fallback_credit_not_applied: object` No reprice was applied; `reason` says why. - `type: "not_applied"` - `reason: "body_mismatch" or "continuation_excluded" or "continuation_only" or 9 more` Why the reprice was not applied. A closed enum; additions to the redemption-check vocabulary arrive as deliberate schema updates. - `"body_mismatch"` - `"continuation_excluded"` - `"continuation_only"` - `"expired"` - `"invalid_target_model"` - `"not_enabled"` - `"reprice_unavailable"` - `"temporarily_unavailable"` - `"variant_fields_present"` - `"wrong_organization"` - `"wrong_platform"` - `"wrong_workspace"` - `remove_to_redeem: optional array of string` Request fields to remove before retrying, so the retry can redeem this token. Present exactly when `reason` is `variant_fields_present` — never null, never an empty array; absent otherwise. Fields are named only from your own request, and only after the sealed variant hash matched. A served best-effort retry has already been billed at normal price; nothing redeems retroactively, but a corrected re-send inside the token's five-minute window can still redeem. - `inference_geo: string` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. minimum: 0 - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage or BetaAdvisorMessageIterationUsage or BetaFallbackMessageIterationUsage` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics, discriminated by `type`. For `message` entries (model sampling iterations, such as the turns of a server-side tool use loop), this allows you to: - Calculate the context window size from the last `message` entry - Understand token accumulation across server-side tool use loops A `compaction` entry reports the token usage of the compaction operation itself — the server-side request that summarizes the context being closed — NOT the size of the context that was compacted away, and its token counts can be much smaller than that closed context (for example, a compaction that closes a ~200k-token context can report only a few thousand tokens). Do not derive the context window size from a `compaction` entry, even when it is the last entry. A `compaction` entry's tokens are not included in the top-level `usage` fields. When an input-token trigger is in effect (the default — 150,000 tokens unless configured otherwise), each `compaction` entry closes a context that had reached at least that threshold, though the context can exceed it by the final iteration's output and tool results. - `beta_message_iteration_usage: object` Token usage for a sampling iteration. - `type: "message"` Usage for a sampling iteration - `cache_creation: object` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_creation_input_tokens: number` The number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. minimum: 0 - `input_tokens: number` The number of input tokens which were used. minimum: 0 - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `output_tokens: number` The number of output tokens which were used. minimum: 0 - `beta_compaction_iteration_usage: object` Token usage for a compaction iteration. - `type: "compaction"` Usage for a compaction iteration - `cache_creation: object` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_creation_input_tokens: number` The number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. minimum: 0 - `input_tokens: number` The number of input tokens which were used. minimum: 0 - `output_tokens: number` The number of output tokens which were used. minimum: 0 - `beta_advisor_message_iteration_usage: object` Token usage for an advisor sub-inference iteration. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `cache_creation: object` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_creation_input_tokens: number` The number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. minimum: 0 - `input_tokens: number` The number of input tokens which were used. minimum: 0 - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `output_tokens: number` The number of output tokens which were used. minimum: 0 - `beta_fallback_message_iteration_usage: object` Token usage for the fallback-model attempt of a server-side fallback request. The terminal entry of a fallback-served turn: when a fallback hop's output is the returned message, the entry for the iteration that completed it carries this type in place of `message`. A declined hop and the serving hop's earlier tool-loop iterations produce `message` entries. Whether a fallback model served the response is signalled by the presence of this entry in `usage.iterations`. - `type: "fallback_message"` Usage for the fallback-model attempt that served the response - `cache_creation: object` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_creation_input_tokens: number` The number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. minimum: 0 - `input_tokens: number` The number of input tokens which were used. minimum: 0 - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `output_tokens: number` The number of output tokens which were used. minimum: 0 - `output_tokens: number` The number of output tokens which were used. minimum: 0 - `output_tokens_details: object` 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. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. minimum: 0 - `server_tool_use: object` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. minimum: 0 - `web_search_requests: number` The number of web search tool requests. minimum: 0 - `service_tier: "standard" or "priority" or "batch"` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" or "fast"` The inference speed mode used for this request. - `"standard"` - `"fast"` - `input_transformations: optional array of BetaInputTransformation` Changes the API made to the request's input before showing it to the model, and blocks that failed a binding check but were left unchanged: one entry per block, in request order. Two entry types today. `thinking_dropped` — a `thinking`, `redacted_thinking` or `connector_text` block from the request's `messages` that was removed from the prompt instead of being shown to the model because it failed a binding check. `thinking_mismatch_allowed` — a `thinking` or `redacted_thinking` block that failed the conversation check (the conversation before it differs from the one it was created in, or it carries no record of one on a model that requires it) and was shown to the model all the same, because that check is not enforced for this request. More entry types may be added over time; ignore types you do not recognize. Requires `anthropic-beta: thinking-binding-controls-2026-08-01`. Present on every such response from a model that supports extended thinking, as `[]` when there is no entry to report; without the beta, blocks are removed or left in place all the same but nothing is reported. Removed blocks contribute nothing to `usage.input_tokens`; blocks left in place count as sent. When streaming, the array is final in `message_start`; the final `message_delta` event carries it only when a server-side model fallback happened mid-stream, in which case it holds the serving model's entries and replaces the one in `message_start`. - `beta_thinking_dropped_input_transformation: object` - `type: "thinking_dropped"` Always `thinking_dropped` for this entry type. - `path: string` Where the removed block was in your request, as `messages.{i}.content.{j}`: `i` indexes the `messages` array you sent and `j` that message's `content` array — the same form error messages use. - `reason: "model_binding_mismatch" or "prefix_binding_mismatch" or "organization_binding_mismatch" or "end_user_binding_mismatch"` Which binding check removed the block: `model_binding_mismatch` — it was created by a model whose reasoning the requested model may not read; `prefix_binding_mismatch` — the conversation before it differs from the conversation it was created in (the rest of that turn's consecutive thinking blocks are removed with it, each with this reason); `organization_binding_mismatch` — it was created under a different organization (an Anthropic organization, AWS account or Google Cloud project) and this organization is not one of its additional organizations; `end_user_binding_mismatch` — it was created for a different end user, or was removed by the consumer-organization binding. A block that would fail several checks reports one reason, in this order of precedence: `organization_binding_mismatch`, `end_user_binding_mismatch`, `model_binding_mismatch`, `prefix_binding_mismatch`. - `"model_binding_mismatch"` - `"prefix_binding_mismatch"` - `"organization_binding_mismatch"` - `"end_user_binding_mismatch"` - `beta_thinking_mismatch_allowed_input_transformation: object` - `type: "thinking_mismatch_allowed"` Always `thinking_mismatch_allowed` for this entry type. - `path: string` Where the block is in your request, as `messages.{i}.content.{j}`: `i` indexes the `messages` array you sent and `j` that message's `content` array — the same form error messages use. - `reason: "model_binding_mismatch" or "prefix_binding_mismatch" or "organization_binding_mismatch" or "end_user_binding_mismatch"` Which binding check the block failed; the block was shown to the model all the same. Always `prefix_binding_mismatch` today — the conversation before the block differs from the conversation it was created in, or the block carries no record of one on a model that requires it. Were the check enforced for this request, the block would have been removed or the request rejected (`thinking.block_binding.prefix_mismatch_behavior`). A removal also takes the rest of that turn's consecutive thinking blocks, whereas here each block is checked on its own, so `thinking_mismatch_allowed` entries are a lower bound on what enforcement would remove. - `"model_binding_mismatch"` - `"prefix_binding_mismatch"` - `"organization_binding_mismatch"` - `"end_user_binding_mismatch"` - `beta_raw_message_stream_event: BetaRawMessageStartEvent or BetaRawMessageDeltaEvent or BetaRawMessageStopEvent or 3 more` - `beta_raw_message_start_event: object` - `type: "message_start"` - `message: object` - `type: "message"` Object type. For Messages, this is always `"message"`. - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: object` Information about the container used in this request. This will be non-null if a container tool (e.g. code execution) was used. - `content: array of BetaContentBlock` 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)"}] ``` - `context_management: object` Context management response. Information about context management strategies applied during the request. - `diagnostics: object` Request-level diagnostics. `null` when the request did not supply `diagnostics`, or when it did and no prompt-cache divergence was detected. - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `stop_details: object` Structured information about why model output stopped. This is `null` when the `stop_reason` has no additional detail to report. - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations * `"model_context_window_exceeded"`: we exceeded the model's context window In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `stop_sequence: string` 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. - `usage: object` 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`. - `input_transformations: optional array of BetaInputTransformation` Changes the API made to the request's input before showing it to the model, and blocks that failed a binding check but were left unchanged: one entry per block, in request order. Two entry types today. `thinking_dropped` — a `thinking`, `redacted_thinking` or `connector_text` block from the request's `messages` that was removed from the prompt instead of being shown to the model because it failed a binding check. `thinking_mismatch_allowed` — a `thinking` or `redacted_thinking` block that failed the conversation check (the conversation before it differs from the one it was created in, or it carries no record of one on a model that requires it) and was shown to the model all the same, because that check is not enforced for this request. More entry types may be added over time; ignore types you do not recognize. Requires `anthropic-beta: thinking-binding-controls-2026-08-01`. Present on every such response from a model that supports extended thinking, as `[]` when there is no entry to report; without the beta, blocks are removed or left in place all the same but nothing is reported. Removed blocks contribute nothing to `usage.input_tokens`; blocks left in place count as sent. When streaming, the array is final in `message_start`; the final `message_delta` event carries it only when a server-side model fallback happened mid-stream, in which case it holds the serving model's entries and replaces the one in `message_start`. - `beta_raw_message_delta_event: object` - `type: "message_delta"` - `context_management: object` Information about context management strategies applied during the request - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` List of context management edits that were applied. - `delta: object` - `container: object` Information about the container used in this request. This will be non-null if a container tool (e.g. code execution) was used. - `id: string` Identifier for the container used in this request - `expires_at: string` The time at which the container will expire. format: date-time - `skills: array of BetaContainerSkill` Skills loaded in the container - `stop_details: object` Structured information about why model output stopped. This is `null` when the `stop_reason` has no additional detail to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `explanation: string` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `fallback_credit_token: string` 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. - `fallback_has_prefill_claim: boolean` 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. - `recommended_model: string` 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. - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string` - `usage: object` 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`. - `cache_creation_input_tokens: number` The cumulative number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The cumulative number of input tokens read from the cache. minimum: 0 - `fallback_credit: object` Outcome of the `fallback_credit_token` presented on this request. Present on every response to a non-batch request that carried a `fallback_credit_token`, in either redemption mode; absent otherwise (batch items accept and ignore the token and carry no outcome object). - `status: BetaFallbackCreditRedeemed or BetaFallbackCreditNotApplied` Whether the fallback-credit reprice was applied to this response's billing. A union discriminated on `type`. `redeemed`: the retry is billed as if the conversation had been on the retry model all along — including when the resulting shift is zero because there was nothing to move. `not_applied`: no reprice was applied; the arm's `reason` says why. - `input_tokens: number` The cumulative number of input tokens which were used. minimum: 0 - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage or BetaAdvisorMessageIterationUsage or BetaFallbackMessageIterationUsage` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics, discriminated by `type`. For `message` entries (model sampling iterations, such as the turns of a server-side tool use loop), this allows you to: - Calculate the context window size from the last `message` entry - Understand token accumulation across server-side tool use loops A `compaction` entry reports the token usage of the compaction operation itself — the server-side request that summarizes the context being closed — NOT the size of the context that was compacted away, and its token counts can be much smaller than that closed context (for example, a compaction that closes a ~200k-token context can report only a few thousand tokens). Do not derive the context window size from a `compaction` entry, even when it is the last entry. A `compaction` entry's tokens are not included in the top-level `usage` fields. When an input-token trigger is in effect (the default — 150,000 tokens unless configured otherwise), each `compaction` entry closes a context that had reached at least that threshold, though the context can exceed it by the final iteration's output and tool results. - `beta_message_iteration_usage: object` Token usage for a sampling iteration. - `beta_compaction_iteration_usage: object` Token usage for a compaction iteration. - `beta_advisor_message_iteration_usage: object` Token usage for an advisor sub-inference iteration. - `beta_fallback_message_iteration_usage: object` Token usage for the fallback-model attempt of a server-side fallback request. The terminal entry of a fallback-served turn: when a fallback hop's output is the returned message, the entry for the iteration that completed it carries this type in place of `message`. A declined hop and the serving hop's earlier tool-loop iterations produce `message` entries. Whether a fallback model served the response is signalled by the presence of this entry in `usage.iterations`. - `output_tokens: number` The cumulative number of output tokens which were used. - `output_tokens_details: object` 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. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. minimum: 0 - `server_tool_use: object` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. minimum: 0 - `web_search_requests: number` The number of web search tool requests. minimum: 0 - `input_transformations: optional array of BetaInputTransformation` Changes the API made to the request's input before showing it to the model, and blocks that failed a binding check but were left unchanged: one entry per block, in request order. Two entry types today. `thinking_dropped` — a `thinking`, `redacted_thinking` or `connector_text` block from the request's `messages` that was removed from the prompt instead of being shown to the model because it failed a binding check. `thinking_mismatch_allowed` — a `thinking` or `redacted_thinking` block that failed the conversation check (the conversation before it differs from the one it was created in, or it carries no record of one on a model that requires it) and was shown to the model all the same, because that check is not enforced for this request. More entry types may be added over time; ignore types you do not recognize. Requires `anthropic-beta: thinking-binding-controls-2026-08-01`. Present on every such response from a model that supports extended thinking, as `[]` when there is no entry to report; without the beta, blocks are removed or left in place all the same but nothing is reported. Removed blocks contribute nothing to `usage.input_tokens`; blocks left in place count as sent. When streaming, the array is final in `message_start`; the final `message_delta` event carries it only when a server-side model fallback happened mid-stream, in which case it holds the serving model's entries and replaces the one in `message_start`. - `beta_thinking_dropped_input_transformation: object` - `beta_thinking_mismatch_allowed_input_transformation: object` - `beta_raw_message_stop_event: object` - `type: "message_stop"` - `beta_raw_content_block_start_event: object` - `type: "content_block_start"` - `content_block: BetaTextBlock or BetaThinkingBlock or BetaRedactedThinkingBlock or 15 more` - `beta_text_block: object` - `type: "text"` - `citations: array of BetaTextCitation` 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`. - `text: string` - `beta_thinking_block: object` - `type: "thinking"` - `signature: string` A value used to verify that this thinking block was generated by Claude when it is passed back to the API. This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=cli) for details. - `thinking: string` The text of Claude's thinking process for this block. - `beta_redacted_thinking_block: object` - `type: "redacted_thinking"` - `data: string` The contents of this redacted thinking block, returned when portions of the model's thinking were safety-redacted. This field is opaque and encrypted, with no readable content. Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=cli#redacted-thinking-blocks) for details. - `beta_tool_use_block: object` - `type: "tool_use"` - `id: string` pattern: ^[a-zA-Z0-9_-]+$ - `input: map[unknown]` - `name: string` minLength: 1 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `toolset_name: optional string` For a toolset member tool_use, the toolset family. minLength: 1, maxLength: 64, pattern: ^[a-zA-Z0-9_-]+$ - `beta_server_tool_use_block: object` - `type: "server_tool_use"` - `id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `input: map[unknown]` - `name: "advisor" or "web_search" or "web_fetch" or 5 more` - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_web_search_tool_result_block: object` - `type: "web_search_tool_result"` - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_web_fetch_tool_result_block: object` - `type: "web_fetch_tool_result"` - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_advisor_tool_result_block: object` - `type: "advisor_tool_result"` - `content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_code_execution_tool_result_block: object` - `type: "code_execution_tool_result"` - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_bash_code_execution_tool_result_block: object` - `type: "bash_code_execution_tool_result"` - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_text_editor_code_execution_tool_result_block: object` - `type: "text_editor_code_execution_tool_result"` - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_tool_search_tool_result_block: object` - `type: "tool_search_tool_result"` - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_mcp_tool_use_block: object` - `type: "mcp_tool_use"` - `id: string` pattern: ^[a-zA-Z0-9_-]+$ - `input: map[unknown]` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `beta_mcp_tool_result_block: object` - `type: "mcp_tool_result"` - `content: string or array of BetaTextBlock` - `is_error: boolean` - `tool_use_id: string` pattern: ^[a-zA-Z0-9_-]+$ - `beta_container_upload_block: object` Response model for a file uploaded to the container. - `type: "container_upload"` - `file_id: string` - `beta_compaction_block: object` 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. - `type: "compaction"` - `content: string` Summary of compacted content, or null if compaction failed - `encrypted_content: string` Opaque metadata from prior compaction, to be round-tripped verbatim - `signature: optional string` Signature over the summary, to be sent back with the block verbatim - `tool_changes: optional array of BetaResponseToolAdditionBlock or BetaResponseToolRemovalBlock` The tool changes of the compacted range: the `tool_addition` and `tool_removal` blocks that take the request's `tools` to the tool set in effect at the end of the range, or `[]` when the range changed no tool. Absent when the server did not compute them. Send the block back unchanged. - `beta_fallback_block: object` Marks the point in `content` where one model's output gives way to the next. One block appears per hop where a preceding model actually ran this turn and declined. A turn where no preceding model ran and declined has no such boundary and carries no block — the signal for whether a fallback model served the response is the presence of a `fallback_message` entry in `usage.iterations`, not this block. The block is treated like a server-tool content block for streaming: it arrives via the standard `content_block_start` / `content_block_stop` pair and carries no deltas. - `type: "fallback"` - `from: object` The model whose output ends at this point — the model that declined at this hop. When the declining hop is the requested model, its `model` echoes the top-level `model` string the caller sent (alias or canonical); when the declining hop is a fallback model, its `model` is that model's canonical id. - `to: object` The fallback model producing the content that follows this block. Its `model` is always the canonical id. - `trigger: object` What caused the `from` model to hand over at this hop. - `beta_mcp_tool_listing_block: object` The tool listing the server fetched from an MCP server while producing this response. Send the assistant message back unchanged, this block included, so later requests use this listing instead of asking the MCP server again. - `type: "mcp_tool_listing"` - `mcp_server_name: string` - `tools: array of BetaMCPTool` - `index: number` - `beta_raw_content_block_delta_event: object` - `type: "content_block_delta"` - `delta: BetaTextDelta or BetaInputJSONDelta or BetaCitationsDelta or 3 more` - `beta_text_delta: object` - `type: "text_delta"` - `text: string` - `beta_input_json_delta: object` - `type: "input_json_delta"` - `partial_json: string` - `beta_citations_delta: object` - `type: "citations_delta"` - `citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more` - `beta_citation_char_location: object` - `type: "char_location"` - `cited_text: string` - `document_index: number` minimum: 0 - `document_title: string` - `end_char_index: number` - `file_id: string` - `start_char_index: number` minimum: 0 - `beta_citation_page_location: object` - `type: "page_location"` - `cited_text: string` - `document_index: number` minimum: 0 - `document_title: string` - `end_page_number: number` - `file_id: string` - `start_page_number: number` minimum: 1 - `beta_citation_content_block_location: object` - `type: "content_block_location"` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` minimum: 0 - `document_title: string` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. minimum: 0 - `beta_citations_web_search_result_location: object` - `type: "web_search_result_location"` - `cited_text: string` - `encrypted_index: string` - `title: string` maxLength: 512 - `url: string` - `beta_citation_search_result_location: object` - `type: "search_result_location"` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. minimum: 0 - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. minimum: 0 - `title: string` - `beta_thinking_delta: object` - `type: "thinking_delta"` - `estimated_tokens: number` 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. - `thinking: string` The incremental `thinking` text for this content block. Concatenate the `thinking` values of successive `thinking_delta` events to assemble the block's full `thinking` value. - `beta_signature_delta: object` - `type: "signature_delta"` - `signature: string` The `signature` for this thinking block: an opaque value used to verify that the block was generated by Claude when it is passed back to the API. Delivered in a `signature_delta` event just before the block's `content_block_stop` event. - `beta_compaction_content_block_delta: object` - `type: "compaction_delta"` - `content: string` - `encrypted_content: string` Opaque metadata from prior compaction, to be round-tripped verbatim - `index: number` - `beta_raw_content_block_stop_event: object` - `type: "content_block_stop"` - `index: number` #### Example ```bash ant beta:messages create \ --api-key my-anthropic-api-key \ --max-tokens 1024 \ --message '{content: [{text: x, type: text}], role: user}' \ --model claude-opus-5-5 ``` ##### Response (200) ```json { "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF", "container": { "id": "container_011CpZohnwH4vuy7gazohgSP", "expires_at": "2019-12-27T18:11:19.117Z", "skills": [ { "skill_id": "pdf", "type": "anthropic", "version": "latest" } ] }, "content": [ { "citations": [ { "cited_text": "The grass is green. The sky is blue.", "document_index": 0, "document_title": "My Document", "end_char_index": 0, "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "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-5-5", "role": "assistant", "stop_details": { "category": "cyber", "explanation": "This request was declined because it conflicts with Anthropic's Usage Policy.", "fallback_credit_token": "QW50aHJvcGljL0NsYXVkZQ==", "fallback_has_prefill_claim": true, "recommended_model": "claude-opus-4-8", "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, "fallback_credit": { "status": { "type": "redeemed" } }, "inference_geo": "global", "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-haiku-5-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" }, "input_transformations": [ { "path": "path", "reason": "model_binding_mismatch", "type": "thinking_dropped" } ] } ``` ### Count tokens in a Message `$ ant beta:messages count-tokens` **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://platform.claude.com/docs/en/build-with-claude/token-counting?sdk_languages=cli) #### Parameters - `--message: array of BetaMessageParam` 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. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors?sdk_languages=cli#prefill-not-supported). 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, for models that support prefill: ```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://platform.claude.com/docs/en/build-with-claude/working-with-messages?sdk_languages=cli). Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=cli#give-claude-a-role), 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. - `--model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `--cache-control: optional object` Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - `--compaction: optional object` Compaction configuration. When set on `POST /v1/messages`, the request is a compaction request: the conversation in `messages` is summarized and the response holds only the resulting `compaction` block (`stop_reason` `"compaction"`), which later requests send first in `messages` in place of the messages it summarizes. `POST /v1/messages/count_tokens` accepts this parameter and ignores it: the count it returns is for the conversation in `messages` as sent. Cannot be combined with `context_management`. - `--context-management: optional object` Context management configuration. This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. - `--mcp-server: optional array of BetaRequestMCPServerURLDefinition` MCP servers to be utilized in this request maxItems: 20 - `--output-config: optional object` Configuration options for the model's output, such as the output format. - `--output-format: optional object` Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=cli) A schema to specify Claude's output format in responses. This parameter will be removed in a future release. - `--speed: optional "standard" or "fast"` The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. Some models require the `fast-mode-2026-02-01` beta header for any `speed` value. See [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode?sdk_languages=cli) for which models. - `--system: optional string or array of BetaTextBlockParam` 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://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=cli#give-claude-a-role). - `--thinking: optional BetaThinkingConfigEnabled or BetaThinkingConfigDisabled or BetaThinkingConfigBetweenTools or BetaThinkingConfigAdaptive` Configuration for Claude's thinking. With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit. Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=cli#configuring-thinking) for each model's behavior. - `--tool-choice: optional BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or BetaToolChoiceNone` 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. - `--tool: optional array of BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 25 more` 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://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools?sdk_languages=cli), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool?sdk_languages=cli)). 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://platform.claude.com/docs/en/agents-and-tools/tool-use/overview?sdk_languages=cli) for more details. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--user-profile-id: optional string` (header parameter) The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_message_tokens_count: object` - `context_management: object` Information about context management applied to the message. - `original_input_tokens: number` The original token count before context management was applied - `input_tokens: number` The total number of tokens across the provided list of messages, system prompt, and tools. #### Example ```bash ant beta:messages count-tokens \ --api-key my-anthropic-api-key \ --message '{content: [{text: x, type: text}], role: user}' \ --model claude-opus-5-5 ``` ##### Response (200) ```json { "context_management": { "original_input_tokens": 0 }, "input_tokens": 2095 } ``` ## Beta › Messages › Batches ### Create a Message Batch `$ ant beta:messages:batches create` **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://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=cli) #### Parameters - `--request: array of object` List of requests for prompt completion. Each is an individual request to create a Message. minItems: 1, maxItems: 100000 - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--user-profile-id: optional string` (header parameter) The user profile ID to attribute the requests in this batch to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header. Applies to every request in the batch; an individual request whose `user_profile_id` body field conflicts with this header is errored. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_message_batch: object` - `type: "message_batch"` Object type. For Message Batches, this is always `"message_batch"`. - `id: string` Unique object identifier. The format and length of IDs may change over time. - `archived_at: string` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. format: date-time - `cancel_initiated_at: string` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. format: date-time - `created_at: string` RFC 3339 datetime string representing the time at which the Message Batch was created. format: date-time - `ended_at: string` 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. format: date-time - `expires_at: string` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. format: date-time - `processing_status: "in_progress" or "canceling" or "ended"` Processing status of the Message Batch. - `"in_progress"` - `"canceling"` - `"ended"` - `request_counts: object` 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. - `canceled: number` Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended. - `errored: number` Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended. - `expired: number` Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended. - `processing: number` Number of requests in the Message Batch that are processing. - `succeeded: number` Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended. - `results_url: string` 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. #### Example ```bash ant beta:messages:batches create \ --api-key my-anthropic-api-key \ --request '{custom_id: my-custom-id-1, params: {max_tokens: 1024, messages: [{content: [{text: x, type: text}], role: user}], model: claude-opus-5-5}}' ``` ##### Response (200) ```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 `$ ant beta:messages:batches retrieve` **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://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=cli) #### Parameters - `--message-batch-id: string` (path parameter) ID of the Message Batch. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_message_batch: object` - `type: "message_batch"` Object type. For Message Batches, this is always `"message_batch"`. - `id: string` Unique object identifier. The format and length of IDs may change over time. - `archived_at: string` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. format: date-time - `cancel_initiated_at: string` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. format: date-time - `created_at: string` RFC 3339 datetime string representing the time at which the Message Batch was created. format: date-time - `ended_at: string` 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. format: date-time - `expires_at: string` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. format: date-time - `processing_status: "in_progress" or "canceling" or "ended"` Processing status of the Message Batch. - `"in_progress"` - `"canceling"` - `"ended"` - `request_counts: object` 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. - `canceled: number` Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended. - `errored: number` Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended. - `expired: number` Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended. - `processing: number` Number of requests in the Message Batch that are processing. - `succeeded: number` Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended. - `results_url: string` 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. #### Example ```bash ant beta:messages:batches retrieve \ --api-key my-anthropic-api-key \ --message-batch-id message_batch_id ``` ##### Response (200) ```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 `$ ant beta:messages:batches list` **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://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=cli) #### Parameters - `--after-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - `--before-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaListResponse_MessageBatch_: object` - `data: array of BetaMessageBatch` - `type: "message_batch"` Object type. For Message Batches, this is always `"message_batch"`. - `id: string` Unique object identifier. The format and length of IDs may change over time. - `archived_at: string` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. format: date-time - `cancel_initiated_at: string` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. format: date-time - `created_at: string` RFC 3339 datetime string representing the time at which the Message Batch was created. format: date-time - `ended_at: string` 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. format: date-time - `expires_at: string` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. format: date-time - `processing_status: "in_progress" or "canceling" or "ended"` Processing status of the Message Batch. - `"in_progress"` - `"canceling"` - `"ended"` - `request_counts: object` 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. - `canceled: number` Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended. - `errored: number` Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended. - `expired: number` Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended. - `processing: number` Number of requests in the Message Batch that are processing. - `succeeded: number` Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended. - `results_url: string` 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. - `first_id: string` First ID in the `data` list. Can be used as the `before_id` for the previous page. - `has_more: boolean` Indicates if there are more results in the requested page direction. - `last_id: string` Last ID in the `data` list. Can be used as the `after_id` for the next page. #### Example ```bash ant beta:messages:batches list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```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 `$ ant beta:messages:batches cancel` **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://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=cli) #### Parameters - `--message-batch-id: string` (path parameter) ID of the Message Batch. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_message_batch: object` - `type: "message_batch"` Object type. For Message Batches, this is always `"message_batch"`. - `id: string` Unique object identifier. The format and length of IDs may change over time. - `archived_at: string` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. format: date-time - `cancel_initiated_at: string` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. format: date-time - `created_at: string` RFC 3339 datetime string representing the time at which the Message Batch was created. format: date-time - `ended_at: string` 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. format: date-time - `expires_at: string` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. format: date-time - `processing_status: "in_progress" or "canceling" or "ended"` Processing status of the Message Batch. - `"in_progress"` - `"canceling"` - `"ended"` - `request_counts: object` 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. - `canceled: number` Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended. - `errored: number` Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended. - `expired: number` Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended. - `processing: number` Number of requests in the Message Batch that are processing. - `succeeded: number` Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended. - `results_url: string` 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. #### Example ```bash ant beta:messages:batches cancel \ --api-key my-anthropic-api-key \ --message-batch-id message_batch_id ``` ##### Response (200) ```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 `$ ant beta:messages:batches delete` **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://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=cli) #### Parameters - `--message-batch-id: string` (path parameter) ID of the Message Batch. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_deleted_message_batch: object` - `type: "message_batch_deleted"` Deleted object type. For Message Batches, this is always `"message_batch_deleted"`. - `id: string` ID of the Message Batch. #### Example ```bash ant beta:messages:batches delete \ --api-key my-anthropic-api-key \ --message-batch-id message_batch_id ``` ##### Response (200) ```json { "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF", "type": "message_batch_deleted" } ``` ### Retrieve Message Batch results `$ ant beta:messages:batches results` **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://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=cli) #### Parameters - `--message-batch-id: string` (path parameter) ID of the Message Batch. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_message_batch_individual_response: object` This is a single line in the response `.jsonl` file and does not represent the response as a whole. - `custom_id: string` 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. - `result: BetaMessageBatchSucceededResult or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or BetaMessageBatchExpiredResult` 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. - `beta_message_batch_succeeded_result: object` - `type: "succeeded"` - `message: object` - `type: "message"` Object type. For Messages, this is always `"message"`. - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: object` Information about the container used in this request. This will be non-null if a container tool (e.g. code execution) was used. - `id: string` Identifier for the container used in this request - `expires_at: string` The time at which the container will expire. format: date-time - `skills: array of BetaContainerSkill` Skills loaded in the container - `type: "anthropic" or "custom"` Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - `"anthropic"` - `"custom"` - `skill_id: string` Skill ID minLength: 1, maxLength: 64 - `version: string` The resolved version: a skill version ID for custom skills. minLength: 1, maxLength: 64 - `content: array of BetaContentBlock` 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)"}] ``` - `beta_text_block: object` - `type: "text"` - `citations: array of BetaTextCitation` 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`. - `beta_citation_char_location: object` - `type: "char_location"` - `cited_text: string` - `document_index: number` minimum: 0 - `document_title: string` - `end_char_index: number` - `file_id: string` - `start_char_index: number` minimum: 0 - `beta_citation_page_location: object` - `type: "page_location"` - `cited_text: string` - `document_index: number` minimum: 0 - `document_title: string` - `end_page_number: number` - `file_id: string` - `start_page_number: number` minimum: 1 - `beta_citation_content_block_location: object` - `type: "content_block_location"` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` minimum: 0 - `document_title: string` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. minimum: 0 - `beta_citations_web_search_result_location: object` - `type: "web_search_result_location"` - `cited_text: string` - `encrypted_index: string` - `title: string` maxLength: 512 - `url: string` - `beta_citation_search_result_location: object` - `type: "search_result_location"` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. minimum: 0 - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. minimum: 0 - `title: string` - `text: string` - `beta_thinking_block: object` - `type: "thinking"` - `signature: string` A value used to verify that this thinking block was generated by Claude when it is passed back to the API. This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=cli) for details. - `thinking: string` The text of Claude's thinking process for this block. - `beta_redacted_thinking_block: object` - `type: "redacted_thinking"` - `data: string` The contents of this redacted thinking block, returned when portions of the model's thinking were safety-redacted. This field is opaque and encrypted, with no readable content. Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=cli#redacted-thinking-blocks) for details. - `beta_tool_use_block: object` - `type: "tool_use"` - `id: string` pattern: ^[a-zA-Z0-9_-]+$ - `input: map[unknown]` - `name: string` minLength: 1 - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_direct_caller: object` Tool invocation directly from the model. - `type: "direct"` - `beta_server_tool_caller: object` Tool invocation generated by a server-side tool. - `type: "code_execution_20250825"` - `tool_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_server_tool_caller_20260120: object` - `type: "code_execution_20260120"` - `tool_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `toolset_name: optional string` For a toolset member tool_use, the toolset family. minLength: 1, maxLength: 64, pattern: ^[a-zA-Z0-9_-]+$ - `beta_server_tool_use_block: object` - `type: "server_tool_use"` - `id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `input: map[unknown]` - `name: "advisor" or "web_search" or "web_fetch" or 5 more` - `"advisor"` - `"web_search"` - `"web_fetch"` - `"code_execution"` - `"bash_code_execution"` - `"text_editor_code_execution"` - `"tool_search_tool_regex"` - `"tool_search_tool_bm25"` - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_direct_caller: object` Tool invocation directly from the model. - `beta_server_tool_caller: object` Tool invocation generated by a server-side tool. - `beta_server_tool_caller_20260120: object` - `beta_web_search_tool_result_block: object` - `type: "web_search_tool_result"` - `content: BetaWebSearchToolResultError or array of BetaWebSearchResultBlock` - `beta_web_search_tool_result_error: object` - `type: "web_search_tool_result_error"` - `error_code: "invalid_tool_input" or "unavailable" or "max_uses_exceeded" or 3 more` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `union_member_1: array of BetaWebSearchResultBlock` - `type: "web_search_result"` - `encrypted_content: string` - `page_age: string` - `title: string` - `url: string` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_direct_caller: object` Tool invocation directly from the model. - `beta_server_tool_caller: object` Tool invocation generated by a server-side tool. - `beta_server_tool_caller_20260120: object` - `beta_web_fetch_tool_result_block: object` - `type: "web_fetch_tool_result"` - `content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock` - `beta_web_fetch_tool_result_error_block: object` - `type: "web_fetch_tool_result_error"` - `error_code: "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 7 more` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `"content_too_large"` - `beta_web_fetch_block: object` - `type: "web_fetch_result"` - `content: object` - `type: "document"` - `citations: object` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource or BetaPlainTextSource` - `beta_base64_pdf_source: object` - `type: "base64"` - `data: string` format: byte - `media_type: "application/pdf"` - `beta_plain_text_source: object` - `type: "text"` - `data: string` - `media_type: "text/plain"` - `title: string` The title of the document - `retrieved_at: string` ISO 8601 timestamp when the content was retrieved - `url: string` Fetched content URL - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120` - `beta_direct_caller: object` Tool invocation directly from the model. - `beta_server_tool_caller: object` Tool invocation generated by a server-side tool. - `beta_server_tool_caller_20260120: object` - `beta_advisor_tool_result_block: object` - `type: "advisor_tool_result"` - `content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock` - `beta_advisor_tool_result_error: object` - `type: "advisor_tool_result_error"` - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `"model_not_found"` - `beta_advisor_result_block: object` - `type: "advisor_result"` - `stop_reason: string` 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. - `text: string` - `beta_advisor_redacted_result_block: object` - `type: "advisor_redacted_result"` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_code_execution_tool_result_block: object` - `type: "code_execution_tool_result"` - `content: BetaCodeExecutionToolResultError or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock` - `beta_code_execution_tool_result_error: object` - `type: "code_execution_tool_result_error"` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `beta_code_execution_result_block: object` - `type: "code_execution_result"` - `content: array of BetaCodeExecutionOutputBlock` - `type: "code_execution_output"` - `file_id: string` - `return_code: number` - `stderr: string` - `stdout: string` - `beta_encrypted_code_execution_result_block: object` Code execution result with encrypted stdout for PFC + web_search results. - `type: "encrypted_code_execution_result"` - `content: array of BetaCodeExecutionOutputBlock` - `type: "code_execution_output"` - `file_id: string` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_bash_code_execution_tool_result_block: object` - `type: "bash_code_execution_tool_result"` - `content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock` - `beta_bash_code_execution_tool_result_error: object` - `type: "bash_code_execution_tool_result_error"` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `beta_bash_code_execution_result_block: object` - `type: "bash_code_execution_result"` - `content: array of BetaBashCodeExecutionOutputBlock` - `type: "bash_code_execution_output"` - `file_id: string` - `return_code: number` - `stderr: string` - `stdout: string` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_text_editor_code_execution_tool_result_block: object` - `type: "text_editor_code_execution_tool_result"` - `content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock` - `beta_text_editor_code_execution_tool_result_error: object` - `type: "text_editor_code_execution_tool_result_error"` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"file_not_found"` - `error_message: string` - `beta_text_editor_code_execution_view_result_block: object` - `type: "text_editor_code_execution_view_result"` - `content: string` - `file_type: "text" or "image" or "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number` - `start_line: number` - `total_lines: number` - `beta_text_editor_code_execution_create_result_block: object` - `type: "text_editor_code_execution_create_result"` - `is_file_update: boolean` - `beta_text_editor_code_execution_str_replace_result_block: object` - `type: "text_editor_code_execution_str_replace_result"` - `lines: array of string` - `new_lines: number` - `new_start: number` - `old_lines: number` - `old_start: number` - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_tool_search_tool_result_block: object` - `type: "tool_search_tool_result"` - `content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock` - `beta_tool_search_tool_result_error: object` - `type: "tool_search_tool_result_error"` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string` - `beta_tool_search_tool_search_result_block: object` - `type: "tool_search_tool_search_result"` - `tool_references: array of BetaToolReferenceBlock` - `type: "tool_reference"` - `tool_name: string` minLength: 1, maxLength: 256, pattern: ^[a-zA-Z0-9_-]{1,256}$ - `tool_use_id: string` pattern: ^srvtoolu_[a-zA-Z0-9_]+$ - `beta_mcp_tool_use_block: object` - `type: "mcp_tool_use"` - `id: string` pattern: ^[a-zA-Z0-9_-]+$ - `input: map[unknown]` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `beta_mcp_tool_result_block: object` - `type: "mcp_tool_result"` - `content: string or array of BetaTextBlock` - `union_member_0: string` - `beta_mcp_tool_result_block_content: array of BetaTextBlock` - `type: "text"` - `citations: array of BetaTextCitation` 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`. - `text: string` - `is_error: boolean` - `tool_use_id: string` pattern: ^[a-zA-Z0-9_-]+$ - `beta_container_upload_block: object` Response model for a file uploaded to the container. - `type: "container_upload"` - `file_id: string` - `beta_compaction_block: object` 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. - `type: "compaction"` - `content: string` Summary of compacted content, or null if compaction failed - `encrypted_content: string` Opaque metadata from prior compaction, to be round-tripped verbatim - `signature: optional string` Signature over the summary, to be sent back with the block verbatim - `tool_changes: optional array of BetaResponseToolAdditionBlock or BetaResponseToolRemovalBlock` The tool changes of the compacted range: the `tool_addition` and `tool_removal` blocks that take the request's `tools` to the tool set in effect at the end of the range, or `[]` when the range changed no tool. Absent when the server did not compute them. Send the block back unchanged. - `beta_response_tool_addition_block: object` An entry of a `compaction` block's `tool_changes`: a tool the compacted range made available, as a reference to a `tools` entry or MCP toolset, or as the tool definition in effect at the end of the range, by value. Send it back unchanged. - `type: "tool_addition"` - `tool: BetaResponseToolChangeToolReference or BetaResponseToolChangeMCPToolReference or BetaResponseToolChangeMCPToolsetReference or BetaToolChangeToolDefinition` The tool made available: a reference to a `tools` entry or MCP toolset, or a `tool_definition` carrying the definition by value. - `beta_response_tool_change_tool_reference: object` Reference to a single tool, by the name the model uses to call it, as a `compaction` block's `tool_changes` entry reports it: a tool declared in `tools` or defined by an earlier `tool_addition` block. Send it back unchanged with the block. - `type: "tool_reference"` - `name: string` - `beta_response_tool_change_mcp_tool_reference: object` Reference to a single MCP tool, by its server and its name on that server, as a `compaction` block's `tool_changes` entry reports it. Send it back unchanged with the block. - `type: "mcp_tool_reference"` - `name: string` - `server_name: string` - `beta_response_tool_change_mcp_toolset_reference: object` Reference to every tool in the named MCP server's toolset, as a `compaction` block's `tool_changes` entry reports it. Send it back unchanged with the block. - `type: "mcp_toolset_reference"` - `server_name: string` - `beta_tool_change_tool_definition: object` A tool defined by value, as a `compaction` block's `tool_changes` entry reports it: `definition` is the tool's definition as it was sent, in the form of a `tools` entry, without `cache_control`. Send it back unchanged with the block. - `type: "tool_definition"` - `definition: BetaResponseTool or BetaToolBash20241022 or BetaToolBash20250124 or 25 more` - `beta_response_tool: object` A custom tool definition, as sent. - `type: optional "custom"` - `input_schema: object` [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. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. minLength: 1, maxLength: 128, pattern: ^[a-zA-Z0-9_-]{1,128}$ - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `description: optional string` 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. - `eager_input_streaming: optional boolean` 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. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_bash_20241022: object` - `type: "bash_20241022"` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `"5m"` - `"1h"` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_bash_20250124: object` - `type: "bash_20250124"` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_code_execution_tool_20250522: object` - `type: "code_execution_20250522"` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_code_execution_tool_20250825: object` - `type: "code_execution_20250825"` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_code_execution_tool_20260120: object` Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - `type: "code_execution_20260120"` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_code_execution_tool_20260521: object` Code execution tool with REPL state persistence. - `type: "code_execution_20260521"` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_browser_toolset_20260801: object` The browser toolset: a single `tools[]` entry (carrying no `name`) that declares the browser tool family. The model is served the family's tool with any members disabled via `configs` removed from its schema. - `type: "browser_toolset_20260801"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `configs: optional object` Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent. - `type: optional object` `type`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `close_tab: optional object` `close_tab`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `double_click: optional object` `double_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `file_upload: optional object` `file_upload`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `find: optional object` `find`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `form_input: optional object` `form_input`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `get_page_text: optional object` `get_page_text`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `hold_key: optional object` `hold_key`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `hover: optional object` `hover`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `javascript_exec: optional object` `javascript_exec`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `key: optional object` `key`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_click: optional object` `left_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_click_drag: optional object` `left_click_drag`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_mouse_down: optional object` `left_mouse_down`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_mouse_up: optional object` `left_mouse_up`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `list_tabs: optional object` `list_tabs`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `middle_click: optional object` `middle_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `mouse_move: optional object` `mouse_move`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `navigate: optional object` `navigate`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `new_tab: optional object` `new_tab`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `read_console: optional object` `read_console`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `read_network: optional object` `read_network`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `read_page: optional object` `read_page`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `right_click: optional object` `right_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `screenshot: optional object` `screenshot`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `scroll: optional object` `scroll`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `scroll_to: optional object` `scroll_to`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `switch_tab: optional object` `switch_tab`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `triple_click: optional object` `triple_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `wait: optional object` `wait`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `zoom: optional object` `zoom`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `beta_tool_computer_use_20241022: object` - `type: "computer_20241022"` - `display_height_px: number` The height of the display in pixels. minimum: 1 - `display_width_px: number` The width of the display in pixels. minimum: 1 - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number: optional number` The X11 display number (e.g. 0, 1) for the display. minimum: 0 - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_memory_tool_20250818: object` - `type: "memory_20250818"` - `name: "memory"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_computer_use_20250124: object` - `type: "computer_20250124"` - `display_height_px: number` The height of the display in pixels. minimum: 1 - `display_width_px: number` The width of the display in pixels. minimum: 1 - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number: optional number` The X11 display number (e.g. 0, 1) for the display. minimum: 0 - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_text_editor_20241022: object` - `type: "text_editor_20241022"` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_computer_use_20251124: object` - `type: "computer_20251124"` - `display_height_px: number` The height of the display in pixels. minimum: 1 - `display_width_px: number` The width of the display in pixels. minimum: 1 - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number: optional number` The X11 display number (e.g. 0, 1) for the display. minimum: 0 - `enable_zoom: optional boolean` Whether to enable an action to take a zoomed-in screenshot of the screen. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_computer_toolset_20260801: object` The computer toolset: a single `tools[]` entry (carrying no `name`) that declares the computer tool family. The model is served the family's tool with any members disabled via `configs` removed from its schema. Every member is enabled by default, zoom included. The single-tool options `display_number` and `enable_zoom` are not fields of a toolset entry — it carries only `type`, `configs`, and `cache_control`; zoom is controlled via `configs.zoom.enabled`. - `type: "computer_toolset_20260801"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `configs: optional object` Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent. - `type: optional object` `type`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `cursor_position: optional object` `cursor_position`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `double_click: optional object` `double_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `hold_key: optional object` `hold_key`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `key: optional object` `key`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_click: optional object` `left_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_click_drag: optional object` `left_click_drag`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_mouse_down: optional object` `left_mouse_down`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `left_mouse_up: optional object` `left_mouse_up`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `middle_click: optional object` `middle_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `mouse_move: optional object` `mouse_move`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `right_click: optional object` `right_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `screenshot: optional object` `screenshot`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `scroll: optional object` `scroll`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `triple_click: optional object` `triple_click`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `wait: optional object` `wait`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `zoom: optional object` `zoom`'s config overrides. - `defer_loading: optional boolean` Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - `enabled: optional boolean` Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - `beta_tool_text_editor_20250124: object` - `type: "text_editor_20250124"` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_text_editor_20250429: object` - `type: "text_editor_20250429"` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_text_editor_20250728: object` - `type: "text_editor_20250728"` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples: optional array of map[unknown]` - `max_characters: optional number` Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_web_search_tool_20250305: object` - `type: "web_search_20250305"` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains: optional array of string` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `user_location: optional object` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `city: optional string` The city of the user. minLength: 1, maxLength: 255 - `country: optional string` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. minLength: 2, maxLength: 2 - `region: optional string` The region of the user. minLength: 1, maxLength: 255 - `timezone: optional string` The [IANA timezone](https://nodatime.org/TimeZones) of the user. minLength: 1, maxLength: 255 - `beta_web_fetch_tool_20250910: object` - `type: "web_fetch_20250910"` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` List of domains to allow fetching from - `blocked_domains: optional array of string` List of domains to block fetching from - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `citations: optional object` Citations configuration for fetched documents. Citations are disabled by default. - `enabled: optional boolean` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens: optional number` 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. minimum: 1 - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `url_sources: optional object` Which sources contribute to the set of URLs the tool may fetch. Omitted means every source. - `client_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which client tools' results contribute fetchable URLs: "all", "none", or an only or except list of client tool names from tools[]. - `beta_web_fetch_url_source_all: object` The `url_sources` variant under which a source contributes in full: every result of the tool filter's source, or all user input. - `type: "all"` - `beta_web_fetch_url_source_none: object` The `url_sources` variant under which a source contributes nothing: no result of the tool filter's source, or no user input. - `type: "none"` - `beta_web_fetch_url_source_only: object` The tool filter variant under which only the named tools' results contribute. - `type: "only"` - `tools: array of BetaWebFetchURLSourceToolReference` - `type: "tool_reference"` - `name: string` - `beta_web_fetch_url_source_except: object` The tool filter variant under which every result but the named tools' contributes. - `type: "except"` - `tools: array of BetaWebFetchURLSourceToolReference` - `type: "tool_reference"` - `name: string` - `server_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which server tools' results contribute fetchable URLs: "all", "none", or an only or except list of server tool names from tools[]; only web_search and web_fetch results ever contribute. - `beta_web_fetch_url_source_all: object` The `url_sources` variant under which a source contributes in full: every result of the tool filter's source, or all user input. - `beta_web_fetch_url_source_none: object` The `url_sources` variant under which a source contributes nothing: no result of the tool filter's source, or no user input. - `beta_web_fetch_url_source_only: object` The tool filter variant under which only the named tools' results contribute. - `beta_web_fetch_url_source_except: object` The tool filter variant under which every result but the named tools' contributes. - `user_input: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone` Whether URLs in user messages are fetchable: "all" or "none". - `beta_web_fetch_url_source_all: object` The `url_sources` variant under which a source contributes in full: every result of the tool filter's source, or all user input. - `beta_web_fetch_url_source_none: object` The `url_sources` variant under which a source contributes nothing: no result of the tool filter's source, or no user input. - `beta_web_search_tool_20260209: object` - `type: "web_search_20260209"` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains: optional array of string` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `user_location: optional object` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `city: optional string` The city of the user. minLength: 1, maxLength: 255 - `country: optional string` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. minLength: 2, maxLength: 2 - `region: optional string` The region of the user. minLength: 1, maxLength: 255 - `timezone: optional string` The [IANA timezone](https://nodatime.org/TimeZones) of the user. minLength: 1, maxLength: 255 - `beta_web_fetch_tool_20260209: object` - `type: "web_fetch_20260209"` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` List of domains to allow fetching from - `blocked_domains: optional array of string` List of domains to block fetching from - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `citations: optional object` Citations configuration for fetched documents. Citations are disabled by default. - `enabled: optional boolean` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens: optional number` 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. minimum: 1 - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `url_sources: optional object` Which sources contribute to the set of URLs the tool may fetch. Omitted means every source. - `client_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which client tools' results contribute fetchable URLs: "all", "none", or an only or except list of client tool names from tools[]. - `server_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which server tools' results contribute fetchable URLs: "all", "none", or an only or except list of server tool names from tools[]; only web_search and web_fetch results ever contribute. - `user_input: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone` Whether URLs in user messages are fetchable: "all" or "none". - `beta_web_fetch_tool_20260309: object` Web fetch tool with use_cache parameter for bypassing cached content. - `type: "web_fetch_20260309"` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` List of domains to allow fetching from - `blocked_domains: optional array of string` List of domains to block fetching from - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `citations: optional object` Citations configuration for fetched documents. Citations are disabled by default. - `enabled: optional boolean` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens: optional number` 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. minimum: 1 - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `url_sources: optional object` Which sources contribute to the set of URLs the tool may fetch. Omitted means every source. - `client_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which client tools' results contribute fetchable URLs: "all", "none", or an only or except list of client tool names from tools[]. - `server_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which server tools' results contribute fetchable URLs: "all", "none", or an only or except list of server tool names from tools[]; only web_search and web_fetch results ever contribute. - `user_input: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone` Whether URLs in user messages are fetchable: "all" or "none". - `use_cache: optional boolean` 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_search_tool_20260318: object` - `type: "web_search_20260318"` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains: optional array of string` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `response_inclusion: optional "full" or "excluded"` How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn. - `"full"` - `"excluded"` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `user_location: optional object` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `city: optional string` The city of the user. minLength: 1, maxLength: 255 - `country: optional string` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. minLength: 2, maxLength: 2 - `region: optional string` The region of the user. minLength: 1, maxLength: 255 - `timezone: optional string` The [IANA timezone](https://nodatime.org/TimeZones) of the user. minLength: 1, maxLength: 255 - `beta_web_fetch_tool_20260318: object` - `type: "web_fetch_20260318"` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `allowed_domains: optional array of string` List of domains to allow fetching from - `blocked_domains: optional array of string` List of domains to block fetching from - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `citations: optional object` Citations configuration for fetched documents. Citations are disabled by default. - `enabled: optional boolean` - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens: optional number` 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. minimum: 1 - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `response_inclusion: optional "full" or "excluded"` How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn. - `"full"` - `"excluded"` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `url_sources: optional object` Which sources contribute to the set of URLs the tool may fetch. Omitted means every source. - `client_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which client tools' results contribute fetchable URLs: "all", "none", or an only or except list of client tool names from tools[]. - `server_tool_results: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone or BetaWebFetchURLSourceOnly or BetaWebFetchURLSourceExcept` Which server tools' results contribute fetchable URLs: "all", "none", or an only or except list of server tool names from tools[]; only web_search and web_fetch results ever contribute. - `user_input: optional BetaWebFetchURLSourceAll or BetaWebFetchURLSourceNone` Whether URLs in user messages are fetchable: "all" or "none". - `use_cache: optional boolean` 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_advisor_tool_20260301: object` - `type: "advisor_20260301"` - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `name: "advisor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `caching: optional object` 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. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_tokens: optional number` 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. minimum: 1024 - `max_uses: optional number` Maximum number of times the tool can be used in the API request. minimum: 1 - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_search_tool_bm25_20251119: object` - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` - `"tool_search_tool_bm25_20251119"` - `"tool_search_tool_bm25"` - `name: "tool_search_tool_bm25"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_tool_search_tool_regex_20251119: object` - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` - `"tool_search_tool_regex_20251119"` - `"tool_search_tool_regex"` - `name: "tool_search_tool_regex"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `"code_execution_20260521"` - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `defer_loading: optional boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - `beta_mcp_toolset: object` 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. - `type: "mcp_toolset"` - `mcp_server_name: string` Name of the MCP server to configure tools for minLength: 1, maxLength: 255 - `cache_control: optional object` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `ttl: optional "5m" or "1h"` The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=cli) for details. - `configs: optional map[BetaMCPToolConfig]` Configuration overrides for specific tools, keyed by tool name - `defer_loading: optional boolean` - `enabled: optional boolean` - `default_config: optional object` Default configuration applied to all tools from this server - `defer_loading: optional boolean` - `enabled: optional boolean` - `tools: optional array of BetaMCPToolParam` The server's tool listing, pinned: when present, the server is not asked for its tools before sampling and exactly these entries, with `default_config` and `configs` applied, are the toolset's tools. Copy it from the `mcp_tool_listing` block of an earlier response. - `input_schema: map[unknown]` The tool's input schema as the MCP server lists it, verbatim. - `name: string` The tool's name as the MCP server lists it (not prefixed with the server name). minLength: 1 - `description: optional string` The tool's description as the MCP server lists it. - `beta_response_tool_removal_block: object` An entry of a `compaction` block's `tool_changes`: a tool of the request's `tools` (or an MCP tool or toolset) that the compacted range withdrew. Send it back unchanged. - `type: "tool_removal"` - `tool: BetaResponseToolChangeToolReference or BetaResponseToolChangeMCPToolReference or BetaResponseToolChangeMCPToolsetReference` A reference to the withdrawn `tools` entry, MCP tool or MCP toolset. - `beta_response_tool_change_tool_reference: object` Reference to a single tool, by the name the model uses to call it, as a `compaction` block's `tool_changes` entry reports it: a tool declared in `tools` or defined by an earlier `tool_addition` block. Send it back unchanged with the block. - `beta_response_tool_change_mcp_tool_reference: object` Reference to a single MCP tool, by its server and its name on that server, as a `compaction` block's `tool_changes` entry reports it. Send it back unchanged with the block. - `beta_response_tool_change_mcp_toolset_reference: object` Reference to every tool in the named MCP server's toolset, as a `compaction` block's `tool_changes` entry reports it. Send it back unchanged with the block. - `beta_fallback_block: object` Marks the point in `content` where one model's output gives way to the next. One block appears per hop where a preceding model actually ran this turn and declined. A turn where no preceding model ran and declined has no such boundary and carries no block — the signal for whether a fallback model served the response is the presence of a `fallback_message` entry in `usage.iterations`, not this block. The block is treated like a server-tool content block for streaming: it arrives via the standard `content_block_start` / `content_block_stop` pair and carries no deltas. - `type: "fallback"` - `from: object` 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: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `to: object` The fallback model producing the content that follows this block. Its `model` is always the canonical id. - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `trigger: object` What caused the `from` model to hand over at this hop. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the `from` model's refusal at this hop. `null` when the refusal doesn't map to a named category. Same vocabulary as `stop_details.category`. - `"cyber"` The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category. - `"bio"` The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category. - `"frontier_llm"` The request could assist the development of competing AI models, which is restricted under [Anthropic's commercial terms](https://www.anthropic.com/legal/commercial-terms). Benign machine learning work can also trigger this category. - `"reasoning_extraction"` The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking?sdk_languages=cli). - `"general_harms"` The request could be related to an area that was determined as harmful. Benign work might sometimes trigger this category. - `beta_mcp_tool_listing_block: object` The tool listing the server fetched from an MCP server while producing this response. Send the assistant message back unchanged, this block included, so later requests use this listing instead of asking the MCP server again. - `type: "mcp_tool_listing"` - `mcp_server_name: string` - `tools: array of BetaMCPTool` - `input_schema: map[unknown]` - `name: string` - `description: optional string` - `context_management: object` Context management response. Information about context management strategies applied during the request. - `applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse` List of context management edits that were applied. - `beta_clear_tool_uses_20250919_edit_response: object` - `type: "clear_tool_uses_20250919"` The type of context management edit applied. - `cleared_input_tokens: number` Number of input tokens cleared by this edit. minimum: 0 - `cleared_tool_uses: number` Number of tool uses that were cleared. minimum: 0 - `beta_clear_thinking_20251015_edit_response: object` - `type: "clear_thinking_20251015"` The type of context management edit applied. - `cleared_input_tokens: number` Number of input tokens cleared by this edit. minimum: 0 - `cleared_thinking_turns: number` Number of thinking turns that were cleared. minimum: 0 - `diagnostics: object` Request-level diagnostics. `null` when the request did not supply `diagnostics`, or when it did and no prompt-cache divergence was detected. - `cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more` 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. - `beta_cache_miss_model_changed: object` - `type: "model_changed"` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `beta_cache_miss_system_changed: object` - `type: "system_changed"` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `beta_cache_miss_tools_changed: object` - `type: "tools_changed"` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `beta_cache_miss_messages_changed: object` - `type: "messages_changed"` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `beta_cache_miss_previous_message_not_found: object` - `type: "previous_message_not_found"` - `beta_cache_miss_unavailable: object` - `type: "unavailable"` - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `stop_details: object` Structured information about why model output stopped. This is `null` when the `stop_reason` has no additional detail to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category. - `"bio"` The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category. - `"frontier_llm"` The request could assist the development of competing AI models, which is restricted under [Anthropic's commercial terms](https://www.anthropic.com/legal/commercial-terms). Benign machine learning work can also trigger this category. - `"reasoning_extraction"` The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking?sdk_languages=cli). - `"general_harms"` The request could be related to an area that was determined as harmful. Benign work might sometimes trigger this category. - `explanation: string` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `fallback_credit_token: string` 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. - `fallback_has_prefill_claim: boolean` 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. - `recommended_model: string` 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. - `stop_reason: "end_turn" or "max_tokens" or "stop_sequence" or 5 more` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations * `"model_context_window_exceeded"`: we exceeded the model's context window In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string` 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. - `usage: object` 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`. - `cache_creation: object` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_creation_input_tokens: number` The number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. minimum: 0 - `fallback_credit: object` Outcome of the `fallback_credit_token` presented on this request. Present on every response to a non-batch request that carried a `fallback_credit_token`, in either redemption mode; absent otherwise (batch items accept and ignore the token and carry no outcome object). - `status: BetaFallbackCreditRedeemed or BetaFallbackCreditNotApplied` Whether the fallback-credit reprice was applied to this response's billing. A union discriminated on `type`. `redeemed`: the retry is billed as if the conversation had been on the retry model all along — including when the resulting shift is zero because there was nothing to move. `not_applied`: no reprice was applied; the arm's `reason` says why. - `beta_fallback_credit_redeemed: object` The reprice was applied: the retry is billed as if the conversation had been on the retry model all along. - `type: "redeemed"` - `beta_fallback_credit_not_applied: object` No reprice was applied; `reason` says why. - `type: "not_applied"` - `reason: "body_mismatch" or "continuation_excluded" or "continuation_only" or 9 more` Why the reprice was not applied. A closed enum; additions to the redemption-check vocabulary arrive as deliberate schema updates. - `"body_mismatch"` - `"continuation_excluded"` - `"continuation_only"` - `"expired"` - `"invalid_target_model"` - `"not_enabled"` - `"reprice_unavailable"` - `"temporarily_unavailable"` - `"variant_fields_present"` - `"wrong_organization"` - `"wrong_platform"` - `"wrong_workspace"` - `remove_to_redeem: optional array of string` Request fields to remove before retrying, so the retry can redeem this token. Present exactly when `reason` is `variant_fields_present` — never null, never an empty array; absent otherwise. Fields are named only from your own request, and only after the sealed variant hash matched. A served best-effort retry has already been billed at normal price; nothing redeems retroactively, but a corrected re-send inside the token's five-minute window can still redeem. - `inference_geo: string` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. minimum: 0 - `iterations: array of BetaMessageIterationUsage or BetaCompactionIterationUsage or BetaAdvisorMessageIterationUsage or BetaFallbackMessageIterationUsage` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics, discriminated by `type`. For `message` entries (model sampling iterations, such as the turns of a server-side tool use loop), this allows you to: - Calculate the context window size from the last `message` entry - Understand token accumulation across server-side tool use loops A `compaction` entry reports the token usage of the compaction operation itself — the server-side request that summarizes the context being closed — NOT the size of the context that was compacted away, and its token counts can be much smaller than that closed context (for example, a compaction that closes a ~200k-token context can report only a few thousand tokens). Do not derive the context window size from a `compaction` entry, even when it is the last entry. A `compaction` entry's tokens are not included in the top-level `usage` fields. When an input-token trigger is in effect (the default — 150,000 tokens unless configured otherwise), each `compaction` entry closes a context that had reached at least that threshold, though the context can exceed it by the final iteration's output and tool results. - `beta_message_iteration_usage: object` Token usage for a sampling iteration. - `type: "message"` Usage for a sampling iteration - `cache_creation: object` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_creation_input_tokens: number` The number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. minimum: 0 - `input_tokens: number` The number of input tokens which were used. minimum: 0 - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `output_tokens: number` The number of output tokens which were used. minimum: 0 - `beta_compaction_iteration_usage: object` Token usage for a compaction iteration. - `type: "compaction"` Usage for a compaction iteration - `cache_creation: object` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_creation_input_tokens: number` The number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. minimum: 0 - `input_tokens: number` The number of input tokens which were used. minimum: 0 - `output_tokens: number` The number of output tokens which were used. minimum: 0 - `beta_advisor_message_iteration_usage: object` Token usage for an advisor sub-inference iteration. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `cache_creation: object` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_creation_input_tokens: number` The number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. minimum: 0 - `input_tokens: number` The number of input tokens which were used. minimum: 0 - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `output_tokens: number` The number of output tokens which were used. minimum: 0 - `beta_fallback_message_iteration_usage: object` Token usage for the fallback-model attempt of a server-side fallback request. The terminal entry of a fallback-served turn: when a fallback hop's output is the returned message, the entry for the iteration that completed it carries this type in place of `message`. A declined hop and the serving hop's earlier tool-loop iterations produce `message` entries. Whether a fallback model served the response is signalled by the presence of this entry in `usage.iterations`. - `type: "fallback_message"` Usage for the fallback-model attempt that served the response - `cache_creation: object` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_creation_input_tokens: number` The number of input tokens used to create the cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. minimum: 0 - `input_tokens: number` The number of input tokens which were used. minimum: 0 - `model: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-fable-5-1" or 17 more or string` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-mythos-5-1"` Our most capable model for cybersecurity and biology research, available through trusted access programs - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-mythos-5"` Most capable model for cybersecurity and biology research - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-mythos-preview"` **Deprecated**: Will reach end-of-life on June 30, 2026. Please migrate to claude-mythos-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. New class of intelligence, strongest in coding and cybersecurity - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `output_tokens: number` The number of output tokens which were used. minimum: 0 - `output_tokens: number` The number of output tokens which were used. minimum: 0 - `output_tokens_details: object` 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. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. minimum: 0 - `server_tool_use: object` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. minimum: 0 - `web_search_requests: number` The number of web search tool requests. minimum: 0 - `service_tier: "standard" or "priority" or "batch"` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" or "fast"` The inference speed mode used for this request. - `"standard"` - `"fast"` - `input_transformations: optional array of BetaInputTransformation` Changes the API made to the request's input before showing it to the model, and blocks that failed a binding check but were left unchanged: one entry per block, in request order. Two entry types today. `thinking_dropped` — a `thinking`, `redacted_thinking` or `connector_text` block from the request's `messages` that was removed from the prompt instead of being shown to the model because it failed a binding check. `thinking_mismatch_allowed` — a `thinking` or `redacted_thinking` block that failed the conversation check (the conversation before it differs from the one it was created in, or it carries no record of one on a model that requires it) and was shown to the model all the same, because that check is not enforced for this request. More entry types may be added over time; ignore types you do not recognize. Requires `anthropic-beta: thinking-binding-controls-2026-08-01`. Present on every such response from a model that supports extended thinking, as `[]` when there is no entry to report; without the beta, blocks are removed or left in place all the same but nothing is reported. Removed blocks contribute nothing to `usage.input_tokens`; blocks left in place count as sent. When streaming, the array is final in `message_start`; the final `message_delta` event carries it only when a server-side model fallback happened mid-stream, in which case it holds the serving model's entries and replaces the one in `message_start`. - `beta_thinking_dropped_input_transformation: object` - `type: "thinking_dropped"` Always `thinking_dropped` for this entry type. - `path: string` Where the removed block was in your request, as `messages.{i}.content.{j}`: `i` indexes the `messages` array you sent and `j` that message's `content` array — the same form error messages use. - `reason: "model_binding_mismatch" or "prefix_binding_mismatch" or "organization_binding_mismatch" or "end_user_binding_mismatch"` Which binding check removed the block: `model_binding_mismatch` — it was created by a model whose reasoning the requested model may not read; `prefix_binding_mismatch` — the conversation before it differs from the conversation it was created in (the rest of that turn's consecutive thinking blocks are removed with it, each with this reason); `organization_binding_mismatch` — it was created under a different organization (an Anthropic organization, AWS account or Google Cloud project) and this organization is not one of its additional organizations; `end_user_binding_mismatch` — it was created for a different end user, or was removed by the consumer-organization binding. A block that would fail several checks reports one reason, in this order of precedence: `organization_binding_mismatch`, `end_user_binding_mismatch`, `model_binding_mismatch`, `prefix_binding_mismatch`. - `"model_binding_mismatch"` - `"prefix_binding_mismatch"` - `"organization_binding_mismatch"` - `"end_user_binding_mismatch"` - `beta_thinking_mismatch_allowed_input_transformation: object` - `type: "thinking_mismatch_allowed"` Always `thinking_mismatch_allowed` for this entry type. - `path: string` Where the block is in your request, as `messages.{i}.content.{j}`: `i` indexes the `messages` array you sent and `j` that message's `content` array — the same form error messages use. - `reason: "model_binding_mismatch" or "prefix_binding_mismatch" or "organization_binding_mismatch" or "end_user_binding_mismatch"` Which binding check the block failed; the block was shown to the model all the same. Always `prefix_binding_mismatch` today — the conversation before the block differs from the conversation it was created in, or the block carries no record of one on a model that requires it. Were the check enforced for this request, the block would have been removed or the request rejected (`thinking.block_binding.prefix_mismatch_behavior`). A removal also takes the rest of that turn's consecutive thinking blocks, whereas here each block is checked on its own, so `thinking_mismatch_allowed` entries are a lower bound on what enforcement would remove. - `"model_binding_mismatch"` - `"prefix_binding_mismatch"` - `"organization_binding_mismatch"` - `"end_user_binding_mismatch"` - `beta_message_batch_errored_result: object` - `type: "errored"` - `error: object` - `type: "error"` - `error: BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more` - `beta_invalid_request_error: object` - `type: "invalid_request_error"` - `message: string` - `beta_authentication_error: object` - `type: "authentication_error"` - `message: string` - `beta_billing_error: object` - `type: "billing_error"` - `message: string` - `beta_permission_error: object` - `type: "permission_error"` - `message: string` - `beta_not_found_error: object` - `type: "not_found_error"` - `message: string` - `beta_rate_limit_error: object` - `type: "rate_limit_error"` - `message: string` - `beta_gateway_timeout_error: object` - `type: "timeout_error"` - `message: string` - `beta_api_error: object` - `type: "api_error"` - `message: string` - `beta_overloaded_error: object` - `type: "overloaded_error"` - `message: string` - `request_id: string` - `beta_message_batch_canceled_result: object` - `type: "canceled"` - `beta_message_batch_expired_result: object` - `type: "expired"` #### Example ```bash ant beta:messages:batches results \ --api-key my-anthropic-api-key \ --message-batch-id message_batch_id ``` ## Beta › Agents ### Create Agent `$ ant beta:agents create` **POST** `/v1/agents` Create Agent #### Parameters - `--model: BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview?sdk_languages=cli#latest-models-comparison), e.g. `claude-opus-5-5`, or a `model_config` object for additional configuration control - `--name: string` Human-readable name for the agent. minLength: 1, maxLength: 256 - `--description: optional string` Description of what the agent does. maxLength: 2048 - `--execution-identity: optional BetaManagedAgentsAWSRoleExecutionIdentityParams or BetaManagedAgentsServiceAccountExecutionIdentityParams` Execution principal for runs of this agent. Omitting it, sending null, or sending `{"type": "service_account"}` stores the default. - `--mcp-server: optional array of BetaManagedAgentsURLMCPServerParams` MCP servers this agent connects to. Maximum 20. Names must be unique within the array. Every server must be referenced by an `mcp_toolset` in `tools`; unreferenced servers are rejected. See the [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector?sdk_languages=cli). - `--metadata: optional map[string]` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `--multiagent: optional BetaManagedAgentsMultiagentCoordinatorParams or BetaManagedAgentsMultiagent20261001Params` Multiagent orchestration configuration. - `--skill: optional array of BetaManagedAgentsSkillParams` Skills available to the agent. - `--system: optional string` System prompt for the agent. maxLength: 100000 - `--tool: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` Tool configurations available to the agent. Maximum of 256 tools across all toolsets allowed. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_agent: object` A Managed Agents `agent`. - `type: "agent"` - `id: string` - `archived_at: string` When the agent was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `metadata: map[string]` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagentCoordinator or BetaManagedAgentsMultiagent20261001` Multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_multiagent_coordinator: object` Resolved coordinator topology with a concrete agent roster. - `type: "coordinator"` - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `beta_managed_agents_agent_reference: object` A resolved agent reference with a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent20261001: object` Resolved multiagent configuration with three members, each enabled or disabled on its own. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. format: int32 #### Example ```bash ant beta:agents create \ --api-key my-anthropic-api-key \ --model claude-opus-5-5 \ --name 'My First Agent' ``` ##### Response (200) ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "advisor": { "type": "disabled" }, "subagents": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" }, "type": "multiagent_20261001", "workflows": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" } }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "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 `$ ant beta:agents list` **GET** `/v1/agents` List Agents #### Parameters - `--created-at-gte: optional string` (query parameter) Return agents created at or after this time (inclusive). format: date-time - `--created-at-lte: optional string` (query parameter) Return agents created at or before this time (inclusive). format: date-time - `--include-archived: optional boolean` (query parameter) Include archived agents in results. Defaults to false. - `--limit: optional number` (query parameter) Maximum results per page. Default 20, maximum 100. format: int32 - `--page: optional string` (query parameter) Opaque pagination cursor from a previous response. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListAgents: object` Paginated list of agents. - `data: array of BetaManagedAgentsAgent` List of agents. - `type: "agent"` - `id: string` - `archived_at: string` When the agent was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `metadata: map[string]` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagentCoordinator or BetaManagedAgentsMultiagent20261001` Multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_multiagent_coordinator: object` Resolved coordinator topology with a concrete agent roster. - `type: "coordinator"` - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `beta_managed_agents_agent_reference: object` A resolved agent reference with a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent20261001: object` Resolved multiagent configuration with three members, each enabled or disabled on its own. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. format: int32 - `next_page: optional string` Opaque cursor for the next page. Null when no more results. #### Example ```bash ant beta:agents list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "advisor": { "type": "disabled" }, "subagents": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" }, "type": "multiagent_20261001", "workflows": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" } }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "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 `$ ant beta:agents retrieve` **GET** `/v1/agents/{agent_id}` Get Agent #### Parameters - `--agent-id: string` (path parameter) Unique identifier of the agent to retrieve. - `--version: optional number` (query parameter) Agent version. Omit for the most recent version. Must be at least 1 if specified. format: int32 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_agent: object` A Managed Agents `agent`. - `type: "agent"` - `id: string` - `archived_at: string` When the agent was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `metadata: map[string]` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagentCoordinator or BetaManagedAgentsMultiagent20261001` Multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_multiagent_coordinator: object` Resolved coordinator topology with a concrete agent roster. - `type: "coordinator"` - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `beta_managed_agents_agent_reference: object` A resolved agent reference with a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent20261001: object` Resolved multiagent configuration with three members, each enabled or disabled on its own. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. format: int32 #### Example ```bash ant beta:agents retrieve \ --api-key my-anthropic-api-key \ --agent-id agent_011CZkYpogX7uDKUyvBTophP ``` ##### Response (200) ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "advisor": { "type": "disabled" }, "subagents": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" }, "type": "multiagent_20261001", "workflows": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" } }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "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 `$ ant beta:agents update` **POST** `/v1/agents/{agent_id}` Update Agent #### Parameters - `--agent-id: string` (path parameter) Unique identifier of the agent to update. - `--description: optional string` Description. Omit to preserve; send empty string or null to clear. maxLength: 2048 - `--execution-identity: optional BetaManagedAgentsAWSRoleExecutionIdentityParams or BetaManagedAgentsServiceAccountExecutionIdentityParams` Execution principal for runs of this agent. Full replacement. Omit to preserve; send null or `{"type": "service_account"}` to restore the default. - `--mcp-server: optional array of BetaManagedAgentsURLMCPServerParams` MCP servers. Full replacement. Omit to preserve; send empty array or `null` to clear. Names must be unique. Maximum 20. Every server must be referenced by an `mcp_toolset` in the agent's resulting `tools`; unreferenced servers are rejected. See the [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector?sdk_languages=cli). - `--metadata: optional map[string]` 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. - `--model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview?sdk_languages=cli#latest-models-comparison), e.g. `claude-opus-5-5`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. - `--multiagent: optional BetaManagedAgentsMultiagentCoordinatorParams or BetaManagedAgentsMultiagent20261001Params` Multiagent orchestration configuration. Full replacement. Omit to preserve; send null to clear. - `--name: optional string` Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared. maxLength: 256 - `--skill: optional array of BetaManagedAgentsSkillParams` Skills. Full replacement. Omit to preserve; send empty array or null to clear. - `--system: optional string` System prompt. Omit to preserve; send empty string or null to clear. maxLength: 100000 - `--tool: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 256 tools across all toolsets allowed. - `--version: optional number` The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. Must be at least 1 if specified. When supplied, the request fails if it does not match the server's current version; omit to apply the update unconditionally. format: int32 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_agent: object` A Managed Agents `agent`. - `type: "agent"` - `id: string` - `archived_at: string` When the agent was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `metadata: map[string]` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagentCoordinator or BetaManagedAgentsMultiagent20261001` Multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_multiagent_coordinator: object` Resolved coordinator topology with a concrete agent roster. - `type: "coordinator"` - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `beta_managed_agents_agent_reference: object` A resolved agent reference with a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent20261001: object` Resolved multiagent configuration with three members, each enabled or disabled on its own. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. format: int32 #### Example ```bash ant beta:agents update \ --api-key my-anthropic-api-key \ --agent-id agent_011CZkYpogX7uDKUyvBTophP ``` ##### Response (200) ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "advisor": { "type": "disabled" }, "subagents": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" }, "type": "multiagent_20261001", "workflows": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" } }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "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 `$ ant beta:agents archive` **POST** `/v1/agents/{agent_id}/archive` Archive Agent #### Parameters - `--agent-id: string` (path parameter) Unique identifier of the agent to archive. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_agent: object` A Managed Agents `agent`. - `type: "agent"` - `id: string` - `archived_at: string` When the agent was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `metadata: map[string]` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagentCoordinator or BetaManagedAgentsMultiagent20261001` Multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_multiagent_coordinator: object` Resolved coordinator topology with a concrete agent roster. - `type: "coordinator"` - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `beta_managed_agents_agent_reference: object` A resolved agent reference with a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent20261001: object` Resolved multiagent configuration with three members, each enabled or disabled on its own. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. format: int32 #### Example ```bash ant beta:agents archive \ --api-key my-anthropic-api-key \ --agent-id agent_011CZkYpogX7uDKUyvBTophP ``` ##### Response (200) ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "advisor": { "type": "disabled" }, "subagents": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" }, "type": "multiagent_20261001", "workflows": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" } }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "updated_at": "2026-03-15T10:00:00Z", "version": 1 } ``` ## Beta › Agents › Versions ### List Agent Versions `$ ant beta:agents:versions list` **GET** `/v1/agents/{agent_id}/versions` List Agent Versions #### Parameters - `--agent-id: string` (path parameter) Agent ID to list versions for. - `--limit: optional number` (query parameter) Maximum results per page. Default 20, maximum 100. format: int32 - `--page: optional string` (query parameter) Opaque pagination cursor. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListAgentVersions: object` Paginated list of agent versions. - `data: array of BetaManagedAgentsAgent` Agent versions. - `type: "agent"` - `id: string` - `archived_at: string` When the agent was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `metadata: map[string]` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagentCoordinator or BetaManagedAgentsMultiagent20261001` Multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_multiagent_coordinator: object` Resolved coordinator topology with a concrete agent roster. - `type: "coordinator"` - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `beta_managed_agents_agent_reference: object` A resolved agent reference with a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent20261001: object` Resolved multiagent configuration with three members, each enabled or disabled on its own. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsAgentReference` Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. format: int32 - `next_page: optional string` Opaque cursor for the next page. Null when no more results. #### Example ```bash ant beta:agents:versions list \ --api-key my-anthropic-api-key \ --agent-id agent_011CZkYpogX7uDKUyvBTophP ``` ##### Response (200) ```json { "data": [ { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "advisor": { "type": "disabled" }, "subagents": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" }, "type": "multiagent_20261001", "workflows": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" } }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "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" } ``` ## Beta › Environments ### Create Environment `$ ant beta:environments create` **POST** `/v1/environments` Create a new environment with the specified configuration. #### Parameters - `--name: string` Human-readable name for the environment minLength: 1, maxLength: 256 - `--config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams` Environment configuration - `--description: optional string` Optional description of the environment maxLength: 1024 - `--metadata: optional map[string]` User-provided metadata key-value pairs - `--scope: optional "organization" or "account"` The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. API organizations support only 'organization'; 'account' is rejected. If not specified, defaults based on organization type. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_environment: object` Unified Environment resource for both cloud and self-hosted environments. - `type: "environment"` The type of object (always 'environment') - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig or BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `beta_cloud_config: object` `cloud` environment configuration. - `type: "cloud"` Environment type - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` Network configuration policy. - `beta_unrestricted_network: object` Unrestricted network access. - `type: "unrestricted"` Network policy type - `beta_limited_network: object` Limited network access. - `type: "limited"` Network policy type - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: array of string` Specifies domains the container can reach. - `packages: object` Package manager configuration. - `type: optional "packages"` Package configuration type - `apt: array of string` Ubuntu/Debian packages to install - `cargo: array of string` Rust packages to install - `gem: array of string` Ruby packages to install - `go: array of string` Go packages to install - `npm: array of string` Node.js packages to install - `pip: array of string` Python packages to install - `beta_self_hosted_config: object` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment; null when unset - `metadata: map[string]` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope: optional "organization" or "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` #### Example ```bash ant beta:environments create \ --api-key my-anthropic-api-key \ --name python-data-analysis ``` ##### Response (200) ```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 `$ ant beta:environments list` **GET** `/v1/environments` List environments with pagination support. #### Parameters - `--include-archived: optional boolean` (query parameter) Include archived environments in the response - `--limit: optional number` (query parameter) Maximum number of environments to return minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaEnvironmentListResponse: object` Response when listing environments. This response model uses opaque cursor-based pagination. Use the `page` query parameter with the value from `next_page` to fetch the next page. - `data: array of BetaEnvironment` List of environments. - `type: "environment"` The type of object (always 'environment') - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig or BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `beta_cloud_config: object` `cloud` environment configuration. - `type: "cloud"` Environment type - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` Network configuration policy. - `beta_unrestricted_network: object` Unrestricted network access. - `type: "unrestricted"` Network policy type - `beta_limited_network: object` Limited network access. - `type: "limited"` Network policy type - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: array of string` Specifies domains the container can reach. - `packages: object` Package manager configuration. - `type: optional "packages"` Package configuration type - `apt: array of string` Ubuntu/Debian packages to install - `cargo: array of string` Rust packages to install - `gem: array of string` Ruby packages to install - `go: array of string` Go packages to install - `npm: array of string` Node.js packages to install - `pip: array of string` Python packages to install - `beta_self_hosted_config: object` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment; null when unset - `metadata: map[string]` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope: optional "organization" or "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` - `next_page: string` Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request. #### Example ```bash ant beta:environments list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```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 `$ ant beta:environments retrieve` **GET** `/v1/environments/{environment_id}` Retrieve a specific environment by ID. #### Parameters - `--environment-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_environment: object` Unified Environment resource for both cloud and self-hosted environments. - `type: "environment"` The type of object (always 'environment') - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig or BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `beta_cloud_config: object` `cloud` environment configuration. - `type: "cloud"` Environment type - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` Network configuration policy. - `beta_unrestricted_network: object` Unrestricted network access. - `type: "unrestricted"` Network policy type - `beta_limited_network: object` Limited network access. - `type: "limited"` Network policy type - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: array of string` Specifies domains the container can reach. - `packages: object` Package manager configuration. - `type: optional "packages"` Package configuration type - `apt: array of string` Ubuntu/Debian packages to install - `cargo: array of string` Rust packages to install - `gem: array of string` Ruby packages to install - `go: array of string` Go packages to install - `npm: array of string` Node.js packages to install - `pip: array of string` Python packages to install - `beta_self_hosted_config: object` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment; null when unset - `metadata: map[string]` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope: optional "organization" or "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` #### Example ```bash ant beta:environments retrieve \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW ``` ##### Response (200) ```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 `$ ant beta:environments update` **POST** `/v1/environments/{environment_id}` Update an existing environment's configuration. #### Parameters - `--environment-id: string` (path parameter) - `--config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams` Updated environment configuration - `--description: optional string` Updated description of the environment. Omit to preserve; null clears to null; an empty string is stored as an empty string. maxLength: 1024 - `--metadata: optional map[string]` User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. - `--name: optional string` Updated name for the environment minLength: 1, maxLength: 256 - `--scope: optional "organization" or "account"` The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_environment: object` Unified Environment resource for both cloud and self-hosted environments. - `type: "environment"` The type of object (always 'environment') - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig or BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `beta_cloud_config: object` `cloud` environment configuration. - `type: "cloud"` Environment type - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` Network configuration policy. - `beta_unrestricted_network: object` Unrestricted network access. - `type: "unrestricted"` Network policy type - `beta_limited_network: object` Limited network access. - `type: "limited"` Network policy type - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: array of string` Specifies domains the container can reach. - `packages: object` Package manager configuration. - `type: optional "packages"` Package configuration type - `apt: array of string` Ubuntu/Debian packages to install - `cargo: array of string` Rust packages to install - `gem: array of string` Ruby packages to install - `go: array of string` Go packages to install - `npm: array of string` Node.js packages to install - `pip: array of string` Python packages to install - `beta_self_hosted_config: object` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment; null when unset - `metadata: map[string]` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope: optional "organization" or "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` #### Example ```bash ant beta:environments update \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW ``` ##### Response (200) ```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 `$ ant beta:environments delete` **DELETE** `/v1/environments/{environment_id}` Delete an environment by ID. Returns a confirmation of the deletion. #### Parameters - `--environment-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_environment_delete_response: object` Response after deleting an environment. - `type: "environment_deleted"` The type of response - `id: string` Environment identifier #### Example ```bash ant beta:environments delete \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW ``` ##### Response (200) ```json { "id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "type": "environment_deleted" } ``` ### Archive Environment `$ ant beta:environments archive` **POST** `/v1/environments/{environment_id}/archive` Archive an environment by ID. Archived environments cannot be used to create new sessions. #### Parameters - `--environment-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_environment: object` Unified Environment resource for both cloud and self-hosted environments. - `type: "environment"` The type of object (always 'environment') - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig or BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `beta_cloud_config: object` `cloud` environment configuration. - `type: "cloud"` Environment type - `networking: BetaUnrestrictedNetwork or BetaLimitedNetwork` Network configuration policy. - `beta_unrestricted_network: object` Unrestricted network access. - `type: "unrestricted"` Network policy type - `beta_limited_network: object` Limited network access. - `type: "limited"` Network policy type - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: array of string` Specifies domains the container can reach. - `packages: object` Package manager configuration. - `type: optional "packages"` Package configuration type - `apt: array of string` Ubuntu/Debian packages to install - `cargo: array of string` Rust packages to install - `gem: array of string` Ruby packages to install - `go: array of string` Go packages to install - `npm: array of string` Node.js packages to install - `pip: array of string` Python packages to install - `beta_self_hosted_config: object` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment; null when unset - `metadata: map[string]` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope: optional "organization" or "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` #### Example ```bash ant beta:environments archive \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW ``` ##### Response (200) ```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" } ``` ## Beta › Environments › Work ### Get Work Item `$ ant beta:environments:work retrieve` **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 - `--environment-id: string` (path parameter) - `--work-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_self_hosted_work: object` 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. - `type: "work"` The type of object (always 'work') - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: object` The actual work to be performed - `type: "session"` Type of work data - `id: string` Session identifier (e.g., 'session_...') - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string` RFC 3339 timestamp of the most recent heartbeat - `metadata: map[string]` User-provided metadata key-value pairs associated with this work item - `secret: string` Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. - `started_at: string` RFC 3339 timestamp when work execution started - `state: "queued" or "starting" or "active" or 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string` RFC 3339 timestamp when stop was requested - `stopped_at: string` RFC 3339 timestamp when work execution stopped #### Example ```bash ant beta:environments:work retrieve \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW \ --work-id work_id ``` ##### Response (200) ```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" }, "secret": "secret", "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ``` ### Poll for Work `$ ant beta:environments:work poll` **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 - `--environment-id: string` (path parameter) - `--block-ms: optional number` (query parameter) 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). minimum: 1 - `--reclaim-older-than-ms: optional number` (query parameter) Reclaim unacknowledged work items older than this many milliseconds. If omitted, uses the default (5000ms). minimum: 1 - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--anthropic-worker-id: optional string` (header parameter) Unique identifier for the specific worker polling, used to track aggregated environment-level work metrics in Console #### Returns - `beta_self_hosted_work: object` 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. - `type: "work"` The type of object (always 'work') - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: object` The actual work to be performed - `type: "session"` Type of work data - `id: string` Session identifier (e.g., 'session_...') - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string` RFC 3339 timestamp of the most recent heartbeat - `metadata: map[string]` User-provided metadata key-value pairs associated with this work item - `secret: string` Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. - `started_at: string` RFC 3339 timestamp when work execution started - `state: "queued" or "starting" or "active" or 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string` RFC 3339 timestamp when stop was requested - `stopped_at: string` RFC 3339 timestamp when work execution stopped #### Example ```bash ant beta:environments:work poll \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW ``` ##### Response (200) ```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" }, "secret": "secret", "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ``` ### Acknowledge Work `$ ant beta:environments:work ack` **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 - `--environment-id: string` (path parameter) - `--work-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_self_hosted_work: object` 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. - `type: "work"` The type of object (always 'work') - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: object` The actual work to be performed - `type: "session"` Type of work data - `id: string` Session identifier (e.g., 'session_...') - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string` RFC 3339 timestamp of the most recent heartbeat - `metadata: map[string]` User-provided metadata key-value pairs associated with this work item - `secret: string` Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. - `started_at: string` RFC 3339 timestamp when work execution started - `state: "queued" or "starting" or "active" or 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string` RFC 3339 timestamp when stop was requested - `stopped_at: string` RFC 3339 timestamp when work execution stopped #### Example ```bash ant beta:environments:work ack \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW \ --work-id work_id ``` ##### Response (200) ```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" }, "secret": "secret", "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ``` ### Record Heartbeat `$ ant beta:environments:work heartbeat` **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 - `--environment-id: string` (path parameter) - `--work-id: string` (path parameter) - `--desired-ttl-seconds: optional number` (query parameter) Desired TTL in seconds - `--expected-last-heartbeat: optional string` (query parameter) 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. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_self_hosted_work_heartbeat_response: object` Response after recording a heartbeat for a work item. - `type: "work_heartbeat"` The type of response - `last_heartbeat: string` RFC 3339 timestamp of the actual heartbeat from DB - `lease_extended: boolean` Whether the heartbeat succeeded in extending the lease - `state: "queued" or "starting" or "active" or 2 more` Current state of the work item (active/stopping/stopped) - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `ttl_seconds: number` Effective TTL applied to the lease #### Example ```bash ant beta:environments:work heartbeat \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW \ --work-id work_id ``` ##### Response (200) ```json { "last_heartbeat": "last_heartbeat", "lease_extended": true, "state": "queued", "ttl_seconds": 0, "type": "work_heartbeat" } ``` ### Stop Work `$ ant beta:environments:work stop` **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 - `--environment-id: string` (path parameter) - `--work-id: string` (path parameter) - `--force: optional boolean` If true, immediately stop work without graceful shutdown - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_self_hosted_work: object` 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. - `type: "work"` The type of object (always 'work') - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: object` The actual work to be performed - `type: "session"` Type of work data - `id: string` Session identifier (e.g., 'session_...') - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string` RFC 3339 timestamp of the most recent heartbeat - `metadata: map[string]` User-provided metadata key-value pairs associated with this work item - `secret: string` Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. - `started_at: string` RFC 3339 timestamp when work execution started - `state: "queued" or "starting" or "active" or 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string` RFC 3339 timestamp when stop was requested - `stopped_at: string` RFC 3339 timestamp when work execution stopped #### Example ```bash ant beta:environments:work stop \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW \ --work-id work_id ``` ##### Response (200) ```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" }, "secret": "secret", "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ``` ### List Work Items `$ ant beta:environments:work list` **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 - `--environment-id: string` (path parameter) - `--limit: optional number` (query parameter) Maximum number of work items to return minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Opaque cursor from previous response for pagination - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_self_hosted_work_list_response: object` Response when listing work items with cursor-based pagination. - `data: array of BetaSelfHostedWork` List of work items - `type: "work"` The type of object (always 'work') - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: object` The actual work to be performed - `type: "session"` Type of work data - `id: string` Session identifier (e.g., 'session_...') - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string` RFC 3339 timestamp of the most recent heartbeat - `metadata: map[string]` User-provided metadata key-value pairs associated with this work item - `secret: string` Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. - `started_at: string` RFC 3339 timestamp when work execution started - `state: "queued" or "starting" or "active" or 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string` RFC 3339 timestamp when stop was requested - `stopped_at: string` RFC 3339 timestamp when work execution stopped - `next_page: string` Opaque cursor for fetching the next page of results #### Example ```bash ant beta:environments:work list \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW ``` ##### Response (200) ```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" }, "secret": "secret", "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 `$ ant beta:environments:work update` **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 - `--environment-id: string` (path parameter) - `--work-id: string` (path parameter) - `--metadata: map[string]` 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: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_self_hosted_work: object` 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. - `type: "work"` The type of object (always 'work') - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: object` The actual work to be performed - `type: "session"` Type of work data - `id: string` Session identifier (e.g., 'session_...') - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string` RFC 3339 timestamp of the most recent heartbeat - `metadata: map[string]` User-provided metadata key-value pairs associated with this work item - `secret: string` Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. - `started_at: string` RFC 3339 timestamp when work execution started - `state: "queued" or "starting" or "active" or 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string` RFC 3339 timestamp when stop was requested - `stopped_at: string` RFC 3339 timestamp when work execution stopped #### Example ```bash ant beta:environments:work update \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW \ --work-id work_id \ --metadata '{foo: string}' ``` ##### Response (200) ```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" }, "secret": "secret", "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ``` ### Get Queue Statistics `$ ant beta:environments:work stats` **GET** `/v1/environments/{environment_id}/work/stats` Get statistics about the work queue for an environment. #### Parameters - `--environment-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_self_hosted_work_queue_stats: object` Statistics about the work queue for an environment. Uses Redis Stream consumer group metrics for O(1) queries. - `type: "work_queue_stats"` The type of object - `depth: number` Number of work items waiting to be picked up (lag from consumer group) - `oldest_queued_at: string` RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty - `pending: number` Number of work items being processed (polled but not acknowledged) - `workers_polling: number` Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests. #### Example ```bash ant beta:environments:work stats \ --api-key my-anthropic-api-key \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW ``` ##### Response (200) ```json { "depth": 0, "oldest_queued_at": "oldest_queued_at", "pending": 0, "type": "work_queue_stats", "workers_polling": 0 } ``` ## Beta › Sessions ### Create Session `$ ant beta:sessions create` **POST** `/v1/sessions` Create Session #### Parameters - `--agent: string or BetaManagedAgentsAgentParams or BetaManagedAgentsAgentWithOverridesParams` 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. - `--environment-id: string` ID of the `environment` defining the container configuration for this session. minLength: 1, maxLength: 128 - `--budget: optional object` Enforced spend ceiling for the session. Omit to create an uncapped session. Every model the session can run — the agent's model and each callable agent's model — must have a public list price, or the request is rejected with reason `model_not_budgetable`. - `--initial-event: optional array of BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserDefineOutcomeEventParams` Initial events to send to the `session` at creation, processed in order. Supports `user.message` and `user.define_outcome` events. Maximum 50 events. - `--metadata: optional map[string]` Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `--resource: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam` Resources (e.g. repositories, files) to mount into the session's container. - `--title: optional string` Human-readable session title. maxLength: 500 - `--vault-id: optional array of string` Vault IDs for stored credentials the agent can use during the session. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_session: object` A Managed Agents `session`. - `type: "session"` - `id: string` - `agent: object` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_session_multiagent_coordinator: object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_session_multiagent20261001: object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_session_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_session_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string` When the session was archived. Null if not archived. format: date-time - `budget: object` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `beta_managed_agents_github_repository_resource: object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `beta_managed_agents_file_resource: object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `beta_managed_agents_memory_store_resource: object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string` 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. - `name: optional string` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: object` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: object` Cumulative token usage for the session. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string` Deployment ID when the session was created from a deployment reference. Null otherwise. #### Example ```bash ant beta:sessions create \ --api-key my-anthropic-api-key \ --agent agent_011CZkYpogX7uDKUyvBTophP \ --environment-id env_011CZkZ9X2dpNyB7HsEFoRfW ``` ##### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "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" }, "type": "bash" } ], "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_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" }, "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_011CZkZRSw2kEfs6ncTVmjxP", "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_011CZkZCKr6eXym1gWMPdQiu", "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": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ### List Sessions `$ ant beta:sessions list` **GET** `/v1/sessions` List Sessions #### Parameters - `--agent-id: optional string` (query parameter) Filter sessions created with this agent ID. - `--agent-version: optional number` (query parameter) Filter by agent version. Only applies when `agent_id` is also set. format: int32 - `--created-at-gt: optional string` (query parameter) Return sessions created after this time (exclusive). format: date-time - `--created-at-gte: optional string` (query parameter) Return sessions created at or after this time (inclusive). format: date-time - `--created-at-lt: optional string` (query parameter) Return sessions created before this time (exclusive). format: date-time - `--created-at-lte: optional string` (query parameter) Return sessions created at or before this time (inclusive). format: date-time - `--deployment-id: optional string` (query parameter) Filter sessions created by this deployment ID. - `--include-archived: optional boolean` (query parameter) When true, includes archived sessions. Default: false (exclude archived). - `--limit: optional number` (query parameter) Maximum number of results to return. format: int32 - `--memory-store-id: optional string` (query parameter) Filter sessions whose resources contain a `memory_store` with this memory store ID. - `--order: optional "asc" or "desc"` (query parameter) Sort direction for results, ordered by `created_at`. Defaults to `desc` (newest first). - `--page: optional string` (query parameter) Opaque pagination cursor from a previous response. - `--status: optional array of "rescheduling" or "running" or "idle" or "terminated"` (query parameter) Filter by session status. Repeat the parameter to match any of multiple statuses. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListSessions: object` Paginated list of sessions. - `data: optional array of BetaManagedAgentsSession` List of sessions. - `type: "session"` - `id: string` - `agent: object` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_session_multiagent_coordinator: object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_session_multiagent20261001: object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_session_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_session_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string` When the session was archived. Null if not archived. format: date-time - `budget: object` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `beta_managed_agents_github_repository_resource: object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `beta_managed_agents_file_resource: object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `beta_managed_agents_memory_store_resource: object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string` 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. - `name: optional string` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: object` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: object` Cumulative token usage for the session. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string` Deployment ID when the session was created from a deployment reference. Null otherwise. - `next_page: optional string` Opaque cursor for the next page. Null when no more results. - `prev_page: optional string` Opaque cursor for the previous page. Null when on the first page. Pass as the `page` parameter to navigate backward. #### Example ```bash ant beta:sessions list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "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" }, "type": "bash" } ], "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_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" }, "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_011CZkZRSw2kEfs6ncTVmjxP", "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_011CZkZCKr6eXym1gWMPdQiu", "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": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=", "prev_page": "page_MjAyNS0wNS0xM1QwMDowMDowMFo=" } ``` ### Get Session `$ ant beta:sessions retrieve` **GET** `/v1/sessions/{session_id}` Get Session #### Parameters - `--session-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_session: object` A Managed Agents `session`. - `type: "session"` - `id: string` - `agent: object` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_session_multiagent_coordinator: object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_session_multiagent20261001: object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_session_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_session_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string` When the session was archived. Null if not archived. format: date-time - `budget: object` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `beta_managed_agents_github_repository_resource: object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `beta_managed_agents_file_resource: object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `beta_managed_agents_memory_store_resource: object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string` 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. - `name: optional string` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: object` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: object` Cumulative token usage for the session. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string` Deployment ID when the session was created from a deployment reference. Null otherwise. #### Example ```bash ant beta:sessions retrieve \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 ``` ##### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "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" }, "type": "bash" } ], "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_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" }, "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_011CZkZRSw2kEfs6ncTVmjxP", "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_011CZkZCKr6eXym1gWMPdQiu", "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": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ### Update Session `$ ant beta:sessions update` **POST** `/v1/sessions/{session_id}` Update Session #### Parameters - `--session-id: string` (path parameter) - `--agent: optional object` Agent configuration update. Only `tools` and `mcp_servers` are updatable mid-session. Only valid for sessions created from an agent or deployment reference. The session must not be running. - `--budget: optional object` Enforced spend ceiling for the session. Set an object to replace the budget of a session that was created with one, or `null` to remove it; omit to preserve. A budget cannot be added to a session created without one (rejected with reason `budget_create_only`), and a removed budget cannot be re-added. Allowed in any non-terminated status. Lowering `max_list_cost` to at or below the session's consumed list cost is rejected with reason `budget_not_raised`, and every model the session can run must have a public list price or the request is rejected with reason `model_not_budgetable`. - `--metadata: optional map[string]` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. - `--title: optional string` Human-readable session title. minLength: 1, maxLength: 500 - `--vault-id: optional array of string` Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_session: object` A Managed Agents `session`. - `type: "session"` - `id: string` - `agent: object` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_session_multiagent_coordinator: object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_session_multiagent20261001: object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_session_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_session_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string` When the session was archived. Null if not archived. format: date-time - `budget: object` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `beta_managed_agents_github_repository_resource: object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `beta_managed_agents_file_resource: object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `beta_managed_agents_memory_store_resource: object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string` 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. - `name: optional string` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: object` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: object` Cumulative token usage for the session. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string` Deployment ID when the session was created from a deployment reference. Null otherwise. #### Example ```bash ant beta:sessions update \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 ``` ##### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "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" }, "type": "bash" } ], "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_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" }, "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_011CZkZRSw2kEfs6ncTVmjxP", "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_011CZkZCKr6eXym1gWMPdQiu", "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": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ### Delete Session `$ ant beta:sessions delete` **DELETE** `/v1/sessions/{session_id}` Delete Session #### Parameters - `--session-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deleted_session: object` Confirmation that a `session` has been permanently deleted. - `type: "session_deleted"` - `id: string` #### Example ```bash ant beta:sessions delete \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 ``` ##### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "type": "session_deleted" } ``` ### Archive Session `$ ant beta:sessions archive` **POST** `/v1/sessions/{session_id}/archive` Archive Session #### Parameters - `--session-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_session: object` A Managed Agents `session`. - `type: "session"` - `id: string` - `agent: object` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_session_multiagent_coordinator: object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_session_multiagent20261001: object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_session_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_session_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `version: number` format: int32 - `archived_at: string` When the session was archived. Null if not archived. format: date-time - `budget: object` The session's enforced spend ceiling, or null when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `environment_id: string` - `metadata: map[string]` - `outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource` Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. - `type: "outcome_evaluation"` - `completed_at: string` When the outcome reached a terminal result. Null while `pending`/`running`/`evaluating`. format: date-time - `description: string` What the agent should produce. - `explanation: string` 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. - `iteration: number` 0-indexed revision cycle the outcome is currently on. format: int32 - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` 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. - `resources: array of BetaManagedAgentsSessionResource` - `beta_managed_agents_github_repository_resource: object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `beta_managed_agents_file_resource: object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `beta_managed_agents_memory_store_resource: object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string` 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. - `name: optional string` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: object` Timing statistics for the session. - `active_seconds: optional number` Cumulative time in seconds the session spent in `running` status. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. format: double - `status: "rescheduling" or "running" or "idle" or "terminated"` - `"rescheduling"` Transient error occurred, retrying automatically. - `"running"` Agent is actively executing. - `"idle"` Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `"terminated"` Session has ended, either due to an error or completion. - `title: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `usage: object` Cumulative token usage for the session. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of the session across all turns, priced at public list rates. Absent until cost tracking is available for the session. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns. Absent until server-tool tracking is available for the session. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied. - `deployment_id: optional string` Deployment ID when the session was created from a deployment reference. Null otherwise. #### Example ```bash ant beta:sessions archive \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 ``` ##### Response (200) ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "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" }, "type": "bash" } ], "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_011CZkZFNu9hAbo3jZPRgTmx", "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" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" }, "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_011CZkZRSw2kEfs6ncTVmjxP", "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_011CZkZCKr6eXym1gWMPdQiu", "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": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "deployment_id": "deployment_id" } ``` ## Beta › Sessions › Events ### List Events `$ ant beta:sessions:events list` **GET** `/v1/sessions/{session_id}/events` List Events #### Parameters - `--session-id: string` (path parameter) - `--created-at-gt: optional string` (query parameter) Return events created after this time (exclusive). Compared against the event's `processed_at` value. format: date-time - `--created-at-gte: optional string` (query parameter) Return events created at or after this time (inclusive). Compared against the event's `processed_at` value. format: date-time - `--created-at-lt: optional string` (query parameter) Return events created before this time (exclusive). Compared against the event's `processed_at` value. format: date-time - `--created-at-lte: optional string` (query parameter) Return events created at or before this time (inclusive). Compared against the event's `processed_at` value. format: date-time - `--limit: optional number` (query parameter) format: int32 - `--order: optional "asc" or "desc"` (query parameter) Sort direction for results, ordered by the event's `processed_at`. Defaults to `asc` (chronological). - `--page: optional string` (query parameter) Opaque pagination cursor from a previous response's `next_page`. - `--type: optional array of BetaManagedAgentsSessionEventType` (query parameter) 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. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListSessionEvents: object` Paginated list of events for a `session`. - `data: optional array of BetaManagedAgentsSessionEvent` Events for the session, ordered by `processed_at`. - `beta_managed_agents_user_message_event: object` A user message event in the session conversation. - `type: "user.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks comprising the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `processed_at: optional string` Timestamp when the agent finished processing this message. format: date-time - `beta_managed_agents_user_interrupt_event: object` An interrupt event that pauses agent execution and returns control to the user. - `type: "user.interrupt"` - `id: string` Unique identifier for this event. - `processed_at: optional string` Timestamp when the interrupt was processed. format: date-time - `session_thread_id: optional string` 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_tool_confirmation_event: object` A tool confirmation event that approves or denies a pending tool execution. - `type: "user.tool_confirmation"` - `id: string` Unique identifier for this event. - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` 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?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `deny_message: optional string` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `processed_at: optional string` Timestamp when the confirmation was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_user_custom_tool_result_event: object` Event sent by the client providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `type: "search_result"` - `citations: object` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean` Whether the tool execution resulted in an error. - `processed_at: optional string` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_agent_custom_tool_use_event: object` 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. The client can send it as soon as this event arrives, without waiting for `session.status_idle`. - `type: "agent.custom_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` Timestamp when this tool use was processed. format: date-time - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_message_event: object` An agent response event in the session conversation. - `type: "agent.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock` Array of text blocks comprising the agent response. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when this response was generated. format: date-time - `beta_managed_agents_agent_thinking_event: object` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `type: "agent.thinking"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this thinking was produced. format: date-time - `beta_managed_agents_agent_mcp_tool_use_event: object` Event emitted when the agent invokes a tool provided by an MCP server. - `type: "agent.mcp_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional "allow" or "ask" or "deny"` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluationAlwaysAllow or BetaManagedAgentsAgentToolEvaluationAlwaysAsk or BetaManagedAgentsAgentToolEvaluationAuto` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `beta_managed_agents_agent_tool_evaluation_always_allow: object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `type: "always_allow"` - `beta_managed_agents_agent_tool_evaluation_always_ask: object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `type: "always_ask"` - `beta_managed_agents_agent_tool_evaluation_auto: object` The resolved permission_policy was auto: the server judged this invocation individually. - `type: "auto"` - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermissionAllow or BetaManagedAgentsAgentAutoEvaluatedPermissionAsk or BetaManagedAgentsAgentAutoEvaluatedPermissionDeny` The server's judgement for this invocation. - `beta_managed_agents_agent_auto_evaluated_permission_allow: object` The server judged the invocation safe to execute without client approval. - `type: "allow"` - `beta_managed_agents_agent_auto_evaluated_permission_ask: object` The server reached no judgement; the invocation is held for client approval. - `type: "ask"` - `reason_code: string` The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set. maxLength: 64 - `beta_managed_agents_agent_auto_evaluated_permission_deny: object` The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended. - `type: "deny"` - `reason_code: string` The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set. maxLength: 64 - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_mcp_tool_result_event: object` Event representing the result of an MCP tool execution. - `type: "agent.mcp_tool_result"` - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` Timestamp when this event was processed. format: date-time - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `beta_managed_agents_agent_tool_use_event: object` Event emitted when the agent invokes a built-in agent tool. - `type: "agent.tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional "allow" or "ask" or "deny"` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluationAlwaysAllow or BetaManagedAgentsAgentToolEvaluationAlwaysAsk or BetaManagedAgentsAgentToolEvaluationAuto` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `beta_managed_agents_agent_tool_evaluation_always_allow: object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `beta_managed_agents_agent_tool_evaluation_always_ask: object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `beta_managed_agents_agent_tool_evaluation_auto: object` The resolved permission_policy was auto: the server judged this invocation individually. - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_tool_result_event: object` Event representing the result of an agent tool execution. - `type: "agent.tool_result"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `beta_managed_agents_agent_thread_message_received_event: object` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `type: "agent.thread_message_received"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` Timestamp when the message was received. format: date-time - `from_agent_name: optional string` Name of the callable agent this message came from. Absent when received from the primary agent. - `beta_managed_agents_agent_thread_message_sent_event: object` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `type: "agent.thread_message_sent"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when the message was sent. format: date-time - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `to_agent_name: optional string` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `beta_managed_agents_agent_thread_context_compacted_event: object` Indicates that context compaction (summarization) occurred during the session. - `type: "agent.thread_context_compacted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when compaction was processed. format: date-time - `beta_managed_agents_session_error_event: object` An error event indicating a problem occurred during session execution. - `type: "session.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 10 more` - `beta_managed_agents_unknown_error: object` 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. - `type: "unknown_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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: "retrying"` - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `beta_managed_agents_model_overloaded_error: object` The model is currently overloaded. Emitted after automatic retries are exhausted. - `type: "model_overloaded_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_model_rate_limited_error: object` The model request was rate-limited. - `type: "model_rate_limited_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_model_request_failed_error: object` A model request failed for a reason other than overload or rate-limiting. - `type: "model_request_failed_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_mcp_connection_failed_error: object` Failed to connect to an MCP server. - `type: "mcp_connection_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_mcp_authentication_failed_error: object` Authentication to an MCP server failed. - `type: "mcp_authentication_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_billing_error: object` 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. - `type: "billing_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_credential_host_unreachable_error: object` An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit. - `type: "credential_host_unreachable_error"` - `credential_id: string` ID of the affected credential. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `vault_id: string` ID of the vault containing the affected credential. - `beta_managed_agents_repository_authentication_error: object` The repository host rejected the credentials, or required credentials and received none. - `type: "repository_authentication_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_forbidden_error: object` The repository host refused access to the repository. - `type: "repository_forbidden_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_not_found_error: object` The repository host reported the repository as not found. - `type: "repository_not_found_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_checkout_error: object` The requested branch or commit does not exist in the repository. - `type: "repository_checkout_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_clone_error: object` The repository could not be cloned. - `type: "repository_clone_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `processed_at: string` Timestamp when the error occurred. format: date-time - `beta_managed_agents_session_status_rescheduled_event: object` Indicates the session is recovering from an error state and is rescheduled for execution. - `type: "session.status_rescheduled"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_status_running_event: object` Indicates the session is actively running and the agent is working. - `type: "session.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_status_idle_event: object` Indicates the agent has paused and is awaiting user input. - `type: "session.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `stop_details: object` Structured information about why the session stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `"cyber"` - `"bio"` - `"frontier_llm"` - `"reasoning_extraction"` - `"general_harms"` - `explanation: string` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `beta_managed_agents_session_end_turn: object` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `beta_managed_agents_session_requires_action: object` 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. - `type: "requires_action"` - `event_ids: array of string` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `beta_managed_agents_session_retries_exhausted: object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `type: "retries_exhausted"` - `beta_managed_agents_session_budget_reached: object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `type: "budget_reached"` - `beta_managed_agents_session_refusal: object` The turn ended because the model's response was refused, for example by a safety classifier. - `type: "refusal"` - `beta_managed_agents_session_status_terminated_event: object` Indicates the session has terminated, either due to an error or completion. - `type: "session.status_terminated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_thread_created_event: object` Emitted when a child thread is created. Written to the parent thread's output stream so clients observing the session see child creation. - `type: "session.thread_created"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` Timestamp when the thread was created. format: date-time - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `workflow_run_id: string` Identifier of the workflow run that created the thread, or `null` for any other thread. - `beta_managed_agents_span_outcome_evaluation_start_event: object` Emitted when an outcome evaluation cycle begins. - `type: "span.outcome_evaluation_start"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation started. format: date-time - `beta_managed_agents_span_outcome_evaluation_end_event: object` 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. - `type: "span.outcome_evaluation_end"` - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation ended. format: date-time - `result: string` 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. - `usage: object` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast"` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `"standard"` - `"fast"` - `beta_managed_agents_span_model_request_start_event: object` Emitted when a model request is initiated by the agent. - `type: "span.model_request_start"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the model request started. format: date-time - `beta_managed_agents_span_model_request_end_event: object` Emitted when a model request completes. - `type: "span.model_request_end"` - `id: string` Unique identifier for this event. - `is_error: boolean` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: object` Token usage for this model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast"` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `processed_at: string` Timestamp when the model request completed. format: date-time - `beta_managed_agents_span_outcome_evaluation_ongoing_event: object` 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. - `type: "span.outcome_evaluation_ongoing"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when this heartbeat was emitted. format: date-time - `beta_managed_agents_user_define_outcome_event: object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `type: "user.define_outcome"` - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number` Evaluate-then-revise cycles before giving up. Default 3, max 20. format: int32 - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` Timestamp when the outcome was accepted. format: date-time - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `beta_managed_agents_session_deleted_event: object` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `type: "session.deleted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the session was deleted. format: date-time - `beta_managed_agents_session_thread_status_running_event: object` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_running"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `beta_managed_agents_session_thread_status_idle_event: object` 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. - `type: "session.thread_status_idle"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_details: object` Structured information about why the thread stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `explanation: string` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `beta_managed_agents_session_end_turn: object` The agent completed its turn naturally and is ready for the next user message. - `beta_managed_agents_session_requires_action: object` 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. - `beta_managed_agents_session_retries_exhausted: object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `beta_managed_agents_session_budget_reached: object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `beta_managed_agents_session_refusal: object` The turn ended because the model's response was refused, for example by a safety classifier. - `beta_managed_agents_session_thread_status_terminated_event: object` 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. - `type: "session.thread_status_terminated"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `beta_managed_agents_user_tool_result_event: object` 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. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` 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?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `processed_at: optional string` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_session_thread_status_rescheduled_event: object` 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. - `type: "session.thread_status_rescheduled"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `beta_managed_agents_session_updated_event: object` 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. - `type: "session.updated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the update was applied. format: date-time - `agent: optional object` The session's effective agent configuration after the update. Present only when the update changed `agent` (tools or mcp_servers); when present it is the full materialised snapshot, not a diff. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_session_multiagent_coordinator: object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_session_multiagent20261001: object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_session_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_session_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `version: number` format: int32 - `budget: optional object` The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `metadata: optional map[string]` 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. - `title: optional string` The session's new title. Present only when the update changed it. - `beta_managed_agents_system_message_event: object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string` Timestamp when this system message was processed. format: date-time - `beta_managed_agents_session_usage_event: object` Periodic snapshot of the session's cumulative usage and tracked list cost. - `type: "session.usage"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the snapshot was taken. format: date-time - `usage: object` The session's cumulative usage at the snapshot time. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of the session across all turns, priced at public list rates. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `budget: optional object` The session's configured budget at the snapshot time, or null when the session has no budget. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `beta_managed_agents_workflow_run_created_event: object` A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events. - `type: "workflow_run.created"` - `id: string` Unique identifier for this event. - `description: string` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `phases: array of BetaManagedAgentsWorkflowRunPhase` The phases that the run's plan declares, in the plan's order. Can be empty. - `id: string` Unique identifier for the phase. - `description: string` Description that the agent gave the phase, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the phase, passed on as written. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_status_ended_event: object` A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events. - `type: "workflow_run.status_ended"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `result: BetaManagedAgentsWorkflowRunResultCompleted or BetaManagedAgentsWorkflowRunResultError or BetaManagedAgentsWorkflowRunResultStopped` How the run ended. - `beta_managed_agents_workflow_run_result_completed: object` The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded. - `type: "completed"` - `beta_managed_agents_workflow_run_result_error: object` The run failed or reached its time limit. - `type: "error"` - `error: BetaManagedAgentsTimeoutWorkflowRunError or BetaManagedAgentsProgramWorkflowRunError or BetaManagedAgentsUnknownWorkflowRunError or 2 more` Why the run did not finish. - `beta_managed_agents_timeout_workflow_run_error: object` The run reached its time limit. - `type: "timeout_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_program_workflow_run_error: object` The plan, a program that the agent wrote, failed, or the server refused it. - `type: "program_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_unknown_workflow_run_error: object` A failure that has no type of its own. - `type: "unknown_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_thread_limit_workflow_run_error: object` The run exceeded the limit on the number of threads that a run can create. - `type: "thread_limit_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_max_workflow_runs_workflow_run_error: object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `type: "max_workflow_runs_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_workflow_run_result_stopped: object` The agent stopped the run. - `type: "stopped"` - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_phase_started_event: object` A workflow run's plan entered a phase. - `type: "workflow_run.phase_started"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `beta_managed_agents_workflow_run_phase_ended_event: object` A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left. - `type: "workflow_run.phase_ended"` - `id: string` Unique identifier for this event. - `phase_started_id: string` Identifier of the `workflow_run.phase_started` event that opened the phase. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `beta_managed_agents_workflow_run_status_running_event: object` A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first. - `type: "workflow_run.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_status_idle_event: object` A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`. - `type: "workflow_run.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_error_event: object` A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`. - `type: "workflow_run.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsTimeoutWorkflowRunError or BetaManagedAgentsProgramWorkflowRunError or BetaManagedAgentsUnknownWorkflowRunError or 2 more` Why the run did not finish, or was not created. - `beta_managed_agents_timeout_workflow_run_error: object` The run reached its time limit. - `beta_managed_agents_program_workflow_run_error: object` The plan, a program that the agent wrote, failed, or the server refused it. - `beta_managed_agents_unknown_workflow_run_error: object` A failure that has no type of its own. - `beta_managed_agents_thread_limit_workflow_run_error: object` The run exceeded the limit on the number of threads that a run can create. - `beta_managed_agents_max_workflow_runs_workflow_run_error: object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run that met the error, or `null` when the error kept a run from being created. - `next_page: optional string` Opaque cursor for the next page. Null when no more results. #### Example ```bash ant beta:sessions:events list \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 ``` ##### Response (200) ```json { "data": [ { "id": "sevt_011CZkZGPp1iBcp4kaQSihUm", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" }, { "id": "sevt_011CZkZHPq1jCdq5mbRTjiVn", "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 `$ ant beta:sessions:events send` **POST** `/v1/sessions/{session_id}/events` Send Events #### Parameters - `--session-id: string` (path parameter) - `--event: array of BetaManagedAgentsEventParams` Events to send to the `session`. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_send_session_events: object` Events that were successfully sent to the session. - `data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 4 more` Sent events - `beta_managed_agents_user_message_event: object` A user message event in the session conversation. - `type: "user.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks comprising the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `processed_at: optional string` Timestamp when the agent finished processing this message. format: date-time - `beta_managed_agents_user_interrupt_event: object` An interrupt event that pauses agent execution and returns control to the user. - `type: "user.interrupt"` - `id: string` Unique identifier for this event. - `processed_at: optional string` Timestamp when the interrupt was processed. format: date-time - `session_thread_id: optional string` 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_tool_confirmation_event: object` A tool confirmation event that approves or denies a pending tool execution. - `type: "user.tool_confirmation"` - `id: string` Unique identifier for this event. - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` 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?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `deny_message: optional string` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `processed_at: optional string` Timestamp when the confirmation was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_user_custom_tool_result_event: object` Event sent by the client providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `type: "search_result"` - `citations: object` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean` Whether the tool execution resulted in an error. - `processed_at: optional string` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_user_define_outcome_event: object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `type: "user.define_outcome"` - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number` Evaluate-then-revise cycles before giving up. Default 3, max 20. format: int32 - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` Timestamp when the outcome was accepted. format: date-time - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `beta_managed_agents_user_tool_result_event: object` 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. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` 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?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `processed_at: optional string` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_system_message_event: object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string` Timestamp when this system message was processed. format: date-time #### Example ```bash ant beta:sessions:events send \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ --event '{content: [{text: '\''Where is my order #1234?'\'', type: text}], type: user.message}' ``` ##### Response (200) ```json { "data": [ { "id": "sevt_011CZkZGPp1iBcp4kaQSihUm", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ] } ``` ### Stream Events `$ ant beta:sessions:events stream` **GET** `/v1/sessions/{session_id}/events/stream` Stream Events #### Parameters - `--session-id: string` (path parameter) - `--event-delta: optional array of BetaManagedAgentsDeltaType` (query parameter) When set, this connection also receives streaming deltas (`event_start`, `event_delta`) while an event is being produced, before the event itself arrives. Deltas are best-effort; when the final event is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no final event — its terminal `span.model_request_end` closes the preview. Accepts one or more event types to preview and may be repeated: `agent.message` streams `content_delta` fragments; `agent.thinking` is start-only — a signal that the agent has begun extended thinking, concluded by the `agent.thinking` event itself. Only previews of the requested event types are sent. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 41 more` Server-sent event in the session stream. - `beta_managed_agents_user_message_event: object` A user message event in the session conversation. - `type: "user.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks comprising the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `processed_at: optional string` Timestamp when the agent finished processing this message. format: date-time - `beta_managed_agents_user_interrupt_event: object` An interrupt event that pauses agent execution and returns control to the user. - `type: "user.interrupt"` - `id: string` Unique identifier for this event. - `processed_at: optional string` Timestamp when the interrupt was processed. format: date-time - `session_thread_id: optional string` 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_tool_confirmation_event: object` A tool confirmation event that approves or denies a pending tool execution. - `type: "user.tool_confirmation"` - `id: string` Unique identifier for this event. - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` 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?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `deny_message: optional string` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `processed_at: optional string` Timestamp when the confirmation was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_user_custom_tool_result_event: object` Event sent by the client providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `type: "search_result"` - `citations: object` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean` Whether the tool execution resulted in an error. - `processed_at: optional string` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_agent_custom_tool_use_event: object` 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. The client can send it as soon as this event arrives, without waiting for `session.status_idle`. - `type: "agent.custom_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` Timestamp when this tool use was processed. format: date-time - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_message_event: object` An agent response event in the session conversation. - `type: "agent.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock` Array of text blocks comprising the agent response. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when this response was generated. format: date-time - `beta_managed_agents_agent_thinking_event: object` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `type: "agent.thinking"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this thinking was produced. format: date-time - `beta_managed_agents_agent_mcp_tool_use_event: object` Event emitted when the agent invokes a tool provided by an MCP server. - `type: "agent.mcp_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional "allow" or "ask" or "deny"` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluationAlwaysAllow or BetaManagedAgentsAgentToolEvaluationAlwaysAsk or BetaManagedAgentsAgentToolEvaluationAuto` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `beta_managed_agents_agent_tool_evaluation_always_allow: object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `type: "always_allow"` - `beta_managed_agents_agent_tool_evaluation_always_ask: object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `type: "always_ask"` - `beta_managed_agents_agent_tool_evaluation_auto: object` The resolved permission_policy was auto: the server judged this invocation individually. - `type: "auto"` - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermissionAllow or BetaManagedAgentsAgentAutoEvaluatedPermissionAsk or BetaManagedAgentsAgentAutoEvaluatedPermissionDeny` The server's judgement for this invocation. - `beta_managed_agents_agent_auto_evaluated_permission_allow: object` The server judged the invocation safe to execute without client approval. - `type: "allow"` - `beta_managed_agents_agent_auto_evaluated_permission_ask: object` The server reached no judgement; the invocation is held for client approval. - `type: "ask"` - `reason_code: string` The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set. maxLength: 64 - `beta_managed_agents_agent_auto_evaluated_permission_deny: object` The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended. - `type: "deny"` - `reason_code: string` The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set. maxLength: 64 - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_mcp_tool_result_event: object` Event representing the result of an MCP tool execution. - `type: "agent.mcp_tool_result"` - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` Timestamp when this event was processed. format: date-time - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `beta_managed_agents_agent_tool_use_event: object` Event emitted when the agent invokes a built-in agent tool. - `type: "agent.tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional "allow" or "ask" or "deny"` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluationAlwaysAllow or BetaManagedAgentsAgentToolEvaluationAlwaysAsk or BetaManagedAgentsAgentToolEvaluationAuto` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `beta_managed_agents_agent_tool_evaluation_always_allow: object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `beta_managed_agents_agent_tool_evaluation_always_ask: object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `beta_managed_agents_agent_tool_evaluation_auto: object` The resolved permission_policy was auto: the server judged this invocation individually. - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_tool_result_event: object` Event representing the result of an agent tool execution. - `type: "agent.tool_result"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `beta_managed_agents_agent_thread_message_received_event: object` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `type: "agent.thread_message_received"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` Timestamp when the message was received. format: date-time - `from_agent_name: optional string` Name of the callable agent this message came from. Absent when received from the primary agent. - `beta_managed_agents_agent_thread_message_sent_event: object` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `type: "agent.thread_message_sent"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when the message was sent. format: date-time - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `to_agent_name: optional string` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `beta_managed_agents_agent_thread_context_compacted_event: object` Indicates that context compaction (summarization) occurred during the session. - `type: "agent.thread_context_compacted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when compaction was processed. format: date-time - `beta_managed_agents_session_error_event: object` An error event indicating a problem occurred during session execution. - `type: "session.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 10 more` - `beta_managed_agents_unknown_error: object` 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. - `type: "unknown_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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: "retrying"` - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `beta_managed_agents_model_overloaded_error: object` The model is currently overloaded. Emitted after automatic retries are exhausted. - `type: "model_overloaded_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_model_rate_limited_error: object` The model request was rate-limited. - `type: "model_rate_limited_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_model_request_failed_error: object` A model request failed for a reason other than overload or rate-limiting. - `type: "model_request_failed_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_mcp_connection_failed_error: object` Failed to connect to an MCP server. - `type: "mcp_connection_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_mcp_authentication_failed_error: object` Authentication to an MCP server failed. - `type: "mcp_authentication_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_billing_error: object` 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. - `type: "billing_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_credential_host_unreachable_error: object` An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit. - `type: "credential_host_unreachable_error"` - `credential_id: string` ID of the affected credential. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `vault_id: string` ID of the vault containing the affected credential. - `beta_managed_agents_repository_authentication_error: object` The repository host rejected the credentials, or required credentials and received none. - `type: "repository_authentication_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_forbidden_error: object` The repository host refused access to the repository. - `type: "repository_forbidden_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_not_found_error: object` The repository host reported the repository as not found. - `type: "repository_not_found_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_checkout_error: object` The requested branch or commit does not exist in the repository. - `type: "repository_checkout_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_clone_error: object` The repository could not be cloned. - `type: "repository_clone_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `processed_at: string` Timestamp when the error occurred. format: date-time - `beta_managed_agents_session_status_rescheduled_event: object` Indicates the session is recovering from an error state and is rescheduled for execution. - `type: "session.status_rescheduled"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_status_running_event: object` Indicates the session is actively running and the agent is working. - `type: "session.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_status_idle_event: object` Indicates the agent has paused and is awaiting user input. - `type: "session.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `stop_details: object` Structured information about why the session stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `"cyber"` - `"bio"` - `"frontier_llm"` - `"reasoning_extraction"` - `"general_harms"` - `explanation: string` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `beta_managed_agents_session_end_turn: object` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `beta_managed_agents_session_requires_action: object` 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. - `type: "requires_action"` - `event_ids: array of string` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `beta_managed_agents_session_retries_exhausted: object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `type: "retries_exhausted"` - `beta_managed_agents_session_budget_reached: object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `type: "budget_reached"` - `beta_managed_agents_session_refusal: object` The turn ended because the model's response was refused, for example by a safety classifier. - `type: "refusal"` - `beta_managed_agents_session_status_terminated_event: object` Indicates the session has terminated, either due to an error or completion. - `type: "session.status_terminated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_thread_created_event: object` Emitted when a child thread is created. Written to the parent thread's output stream so clients observing the session see child creation. - `type: "session.thread_created"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` Timestamp when the thread was created. format: date-time - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `workflow_run_id: string` Identifier of the workflow run that created the thread, or `null` for any other thread. - `beta_managed_agents_span_outcome_evaluation_start_event: object` Emitted when an outcome evaluation cycle begins. - `type: "span.outcome_evaluation_start"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation started. format: date-time - `beta_managed_agents_span_outcome_evaluation_end_event: object` 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. - `type: "span.outcome_evaluation_end"` - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation ended. format: date-time - `result: string` 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. - `usage: object` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast"` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `"standard"` - `"fast"` - `beta_managed_agents_span_model_request_start_event: object` Emitted when a model request is initiated by the agent. - `type: "span.model_request_start"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the model request started. format: date-time - `beta_managed_agents_span_model_request_end_event: object` Emitted when a model request completes. - `type: "span.model_request_end"` - `id: string` Unique identifier for this event. - `is_error: boolean` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: object` Token usage for this model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast"` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `processed_at: string` Timestamp when the model request completed. format: date-time - `beta_managed_agents_span_outcome_evaluation_ongoing_event: object` 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. - `type: "span.outcome_evaluation_ongoing"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when this heartbeat was emitted. format: date-time - `beta_managed_agents_user_define_outcome_event: object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `type: "user.define_outcome"` - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number` Evaluate-then-revise cycles before giving up. Default 3, max 20. format: int32 - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` Timestamp when the outcome was accepted. format: date-time - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `beta_managed_agents_session_deleted_event: object` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `type: "session.deleted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the session was deleted. format: date-time - `beta_managed_agents_session_thread_status_running_event: object` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_running"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `beta_managed_agents_session_thread_status_idle_event: object` 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. - `type: "session.thread_status_idle"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_details: object` Structured information about why the thread stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `explanation: string` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `beta_managed_agents_session_end_turn: object` The agent completed its turn naturally and is ready for the next user message. - `beta_managed_agents_session_requires_action: object` 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. - `beta_managed_agents_session_retries_exhausted: object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `beta_managed_agents_session_budget_reached: object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `beta_managed_agents_session_refusal: object` The turn ended because the model's response was refused, for example by a safety classifier. - `beta_managed_agents_session_thread_status_terminated_event: object` 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. - `type: "session.thread_status_terminated"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `beta_managed_agents_user_tool_result_event: object` 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. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` 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?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `processed_at: optional string` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_session_thread_status_rescheduled_event: object` 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. - `type: "session.thread_status_rescheduled"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `beta_managed_agents_session_updated_event: object` 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. - `type: "session.updated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the update was applied. format: date-time - `agent: optional object` The session's effective agent configuration after the update. Present only when the update changed `agent` (tools or mcp_servers); when present it is the full materialised snapshot, not a diff. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_session_multiagent_coordinator: object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_session_multiagent20261001: object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_session_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_session_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `version: number` format: int32 - `budget: optional object` The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `metadata: optional map[string]` 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. - `title: optional string` The session's new title. Present only when the update changed it. - `beta_managed_agents_start_event: object` Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history. - `type: "event_start"` - `event: BetaManagedAgentsAgentMessagePreview or BetaManagedAgentsAgentThinkingPreview` The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them. - `beta_managed_agents_agent_message_preview: object` - `type: "agent.message"` - `id: string` The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events. - `beta_managed_agents_agent_thinking_preview: object` - `type: "agent.thinking"` - `id: string` The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow. - `beta_managed_agents_delta_event: object` An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history. - `type: "event_delta"` - `delta: object` One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array. - `type: "content_delta"` - `content: object` A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content. - `type: "text"` - `text: string` The text content. minLength: 1 - `index: optional number` Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise. - `event_id: string` The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview. - `beta_managed_agents_system_message_event: object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string` Timestamp when this system message was processed. format: date-time - `beta_managed_agents_session_usage_event: object` Periodic snapshot of the session's cumulative usage and tracked list cost. - `type: "session.usage"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the snapshot was taken. format: date-time - `usage: object` The session's cumulative usage at the snapshot time. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of the session across all turns, priced at public list rates. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `budget: optional object` The session's configured budget at the snapshot time, or null when the session has no budget. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `beta_managed_agents_workflow_run_created_event: object` A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events. - `type: "workflow_run.created"` - `id: string` Unique identifier for this event. - `description: string` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `phases: array of BetaManagedAgentsWorkflowRunPhase` The phases that the run's plan declares, in the plan's order. Can be empty. - `id: string` Unique identifier for the phase. - `description: string` Description that the agent gave the phase, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the phase, passed on as written. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_status_ended_event: object` A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events. - `type: "workflow_run.status_ended"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `result: BetaManagedAgentsWorkflowRunResultCompleted or BetaManagedAgentsWorkflowRunResultError or BetaManagedAgentsWorkflowRunResultStopped` How the run ended. - `beta_managed_agents_workflow_run_result_completed: object` The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded. - `type: "completed"` - `beta_managed_agents_workflow_run_result_error: object` The run failed or reached its time limit. - `type: "error"` - `error: BetaManagedAgentsTimeoutWorkflowRunError or BetaManagedAgentsProgramWorkflowRunError or BetaManagedAgentsUnknownWorkflowRunError or 2 more` Why the run did not finish. - `beta_managed_agents_timeout_workflow_run_error: object` The run reached its time limit. - `type: "timeout_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_program_workflow_run_error: object` The plan, a program that the agent wrote, failed, or the server refused it. - `type: "program_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_unknown_workflow_run_error: object` A failure that has no type of its own. - `type: "unknown_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_thread_limit_workflow_run_error: object` The run exceeded the limit on the number of threads that a run can create. - `type: "thread_limit_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_max_workflow_runs_workflow_run_error: object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `type: "max_workflow_runs_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_workflow_run_result_stopped: object` The agent stopped the run. - `type: "stopped"` - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_phase_started_event: object` A workflow run's plan entered a phase. - `type: "workflow_run.phase_started"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `beta_managed_agents_workflow_run_phase_ended_event: object` A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left. - `type: "workflow_run.phase_ended"` - `id: string` Unique identifier for this event. - `phase_started_id: string` Identifier of the `workflow_run.phase_started` event that opened the phase. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `beta_managed_agents_workflow_run_status_running_event: object` A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first. - `type: "workflow_run.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_status_idle_event: object` A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`. - `type: "workflow_run.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_error_event: object` A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`. - `type: "workflow_run.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsTimeoutWorkflowRunError or BetaManagedAgentsProgramWorkflowRunError or BetaManagedAgentsUnknownWorkflowRunError or 2 more` Why the run did not finish, or was not created. - `beta_managed_agents_timeout_workflow_run_error: object` The run reached its time limit. - `beta_managed_agents_program_workflow_run_error: object` The plan, a program that the agent wrote, failed, or the server refused it. - `beta_managed_agents_unknown_workflow_run_error: object` A failure that has no type of its own. - `beta_managed_agents_thread_limit_workflow_run_error: object` The run exceeded the limit on the number of threads that a run can create. - `beta_managed_agents_max_workflow_runs_workflow_run_error: object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run that met the error, or `null` when the error kept a run from being created. #### Example ```bash ant beta:sessions:events stream \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 ``` ##### Response (200) ```json { "id": "sevt_011CZkZGPp1iBcp4kaQSihUm", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ``` ## Beta › Sessions › Resources ### Add Session Resource `$ ant beta:sessions:resources add` **POST** `/v1/sessions/{session_id}/resources` Add Session Resource #### Parameters - `--session-id: string` (path parameter) - `--file-id: string` ID of a previously uploaded file. minLength: 1, maxLength: 128 - `--type: "file"` - `--mount-path: optional string` Mount path in the container. Defaults to `/mnt/session/uploads/`. minLength: 1, maxLength: 4096 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_file_resource: object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time #### Example ```bash ant beta:sessions:resources add \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ --file-id file_011CNha8iCJcU1wXNR6q4V8w \ --type file ``` ##### Response (200) ```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 `$ ant beta:sessions:resources list` **GET** `/v1/sessions/{session_id}/resources` List Session Resources #### Parameters - `--session-id: string` (path parameter) - `--limit: optional number` (query parameter) Maximum number of resources to return per page (max 1000). If omitted, returns all resources. format: int32 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListSessionResources: object` Paginated list of resources attached to a session. - `data: array of BetaManagedAgentsSessionResource` Resources for the session, ordered by `created_at`. - `beta_managed_agents_github_repository_resource: object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `beta_managed_agents_file_resource: object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `beta_managed_agents_memory_store_resource: object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string` 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. - `name: optional string` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `next_page: optional string` Opaque cursor for the next page. Null when no more results. #### Example ```bash ant beta:sessions:resources list \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 ``` ##### Response (200) ```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_011CZkZCKr6eXym1gWMPdQiu", "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 `$ ant beta:sessions:resources retrieve` **GET** `/v1/sessions/{session_id}/resources/{resource_id}` Get Session Resource #### Parameters - `--session-id: string` (path parameter) - `--resource-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaSessionResourceGetResponse: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource or BetaManagedAgentsMemoryStoreResource` The requested session resource. - `beta_managed_agents_github_repository_resource: object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `beta_managed_agents_file_resource: object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `beta_managed_agents_memory_store_resource: object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string` 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. - `name: optional string` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. #### Example ```bash ant beta:sessions:resources retrieve \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht ``` ##### Response (200) ```json { "id": "sesrsc_011CZkZCKr6eXym1gWMPdQiu", "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 `$ ant beta:sessions:resources update` **POST** `/v1/sessions/{session_id}/resources/{resource_id}` Update Session Resource #### Parameters - `--session-id: string` (path parameter) - `--resource-id: string` (path parameter) - `--authorization-token: string` New authorization token for the resource. Currently only `github_repository` resources support token rotation. minLength: 1, maxLength: 4096 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaSessionResourceUpdateResponse: BetaManagedAgentsGitHubRepositoryResource or BetaManagedAgentsFileResource or BetaManagedAgentsMemoryStoreResource` The updated session resource. - `beta_managed_agents_github_repository_resource: object` - `type: "github_repository"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `beta_managed_agents_file_resource: object` - `type: "file"` - `id: string` - `created_at: string` A timestamp in RFC 3339 format format: date-time - `file_id: string` - `mount_path: string` - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `beta_managed_agents_memory_store_resource: object` A memory store attached to an agent session. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `description: optional string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. maxLength: 4096 - `mount_path: optional string` 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. - `name: optional string` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. #### Example ```bash ant beta:sessions:resources update \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht \ --authorization-token ghp_exampletoken ``` ##### Response (200) ```json { "id": "sesrsc_011CZkZCKr6eXym1gWMPdQiu", "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 `$ ant beta:sessions:resources delete` **DELETE** `/v1/sessions/{session_id}/resources/{resource_id}` Delete Session Resource #### Parameters - `--session-id: string` (path parameter) - `--resource-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_delete_session_resource: object` Confirmation of resource deletion. - `type: "session_resource_deleted"` - `id: string` #### Example ```bash ant beta:sessions:resources delete \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ --resource-id sesrsc_011CZkZBJq5dWxk9fVLNcPht ``` ##### Response (200) ```json { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "type": "session_resource_deleted" } ``` ## Beta › Sessions › Threads ### List Session Threads `$ ant beta:sessions:threads list` **GET** `/v1/sessions/{session_id}/threads` List Session Threads #### Parameters - `--session-id: string` (path parameter) - `--limit: optional number` (query parameter) Maximum results per page. Defaults to 1000. format: int32 - `--page: optional string` (query parameter) Opaque pagination cursor from a previous response's `next_page`. Forward-only. - `--status: optional array of BetaManagedAgentsSessionThreadStatus` (query parameter) Return only threads that have one of these statuses. Repeat the parameter to give more than one status. Leave it out to return threads of every status. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListSessionThreads: object` Paginated list of threads within a `session`. - `data: optional array of BetaManagedAgentsSessionThread` Threads in the session, primary first then children in spawn order. - `type: "session_thread"` - `id: string` Unique identifier for this thread. - `agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor or BetaManagedAgentsInlineAgent` Resolved agent definition for this thread. Snapshot of the agent at thread creation time. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_inline_agent: object` An agent that has no Agent resource, and so no `id` or `version`. It is defined inline, in a workflow run's plan or when a session thread is spawned, and is not saved. - `type: "inline"` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` The session's execution principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` The name that the agent's definition gave, or one that the server assigned. - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `archived_at: string` When the thread was archived. Null if not archived. format: date-time - `created_at: string` When the thread was created. format: date-time - `parent_thread_id: string` Parent thread that spawned this thread. Null for the primary thread. - `session_id: string` The session this thread belongs to. - `stats: object` Timing statistics for this thread. Null until the thread's first status transition. - `active_seconds: optional number` Cumulative time in seconds the thread spent actively running. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. format: double - `startup_seconds: optional number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. format: double - `status: "running" or "idle" or "rescheduling" or "terminated"` Current execution status of the thread. - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` - `updated_at: string` When the thread was last updated. format: date-time - `usage: object` Cumulative token usage for this thread. Null until the thread's first idle transition. - `active_seconds: optional number` Cumulative time in seconds this thread spent in running status. Equal to `stats.active_seconds`; surfaced here so a thread's usage carries every quantity its cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of this thread across all turns, priced at public list rates. Absent until cost tracking is available for the thread. Each figure is rounded to the nearest cent independently and the session's aggregate `usage.list_cost` additionally includes session runtime, so per-thread costs do not sum exactly to the session figure; the session figure is authoritative and is what a budget is enforced against. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns of this thread. Absent until server-tool tracking is available for the thread. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `workflow_run_id: string` Identifier of the workflow run that created the thread, or `null` for any other thread. - `next_page: optional string` Opaque cursor for the next page. Null when no more results. #### Example ```bash ant beta:sessions:threads list \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 ``` ##### Response (200) ```json { "data": [ { "id": "sthr_011CZkZVWa6oJjw1rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "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" }, "type": "bash" } ], "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": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "workflow_run_id": null } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Get Session Thread `$ ant beta:sessions:threads retrieve` **GET** `/v1/sessions/{session_id}/threads/{thread_id}` Get Session Thread #### Parameters - `--session-id: string` (path parameter) - `--thread-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_session_thread: object` An execution thread within a `session`. Each session has one primary thread plus zero or more child threads. - `type: "session_thread"` - `id: string` Unique identifier for this thread. - `agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor or BetaManagedAgentsInlineAgent` Resolved agent definition for this thread. Snapshot of the agent at thread creation time. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_inline_agent: object` An agent that has no Agent resource, and so no `id` or `version`. It is defined inline, in a workflow run's plan or when a session thread is spawned, and is not saved. - `type: "inline"` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` The session's execution principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` The name that the agent's definition gave, or one that the server assigned. - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `archived_at: string` When the thread was archived. Null if not archived. format: date-time - `created_at: string` When the thread was created. format: date-time - `parent_thread_id: string` Parent thread that spawned this thread. Null for the primary thread. - `session_id: string` The session this thread belongs to. - `stats: object` Timing statistics for this thread. Null until the thread's first status transition. - `active_seconds: optional number` Cumulative time in seconds the thread spent actively running. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. format: double - `startup_seconds: optional number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. format: double - `status: "running" or "idle" or "rescheduling" or "terminated"` Current execution status of the thread. - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` - `updated_at: string` When the thread was last updated. format: date-time - `usage: object` Cumulative token usage for this thread. Null until the thread's first idle transition. - `active_seconds: optional number` Cumulative time in seconds this thread spent in running status. Equal to `stats.active_seconds`; surfaced here so a thread's usage carries every quantity its cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of this thread across all turns, priced at public list rates. Absent until cost tracking is available for the thread. Each figure is rounded to the nearest cent independently and the session's aggregate `usage.list_cost` additionally includes session runtime, so per-thread costs do not sum exactly to the session figure; the session figure is authoritative and is what a budget is enforced against. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns of this thread. Absent until server-tool tracking is available for the thread. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `workflow_run_id: string` Identifier of the workflow run that created the thread, or `null` for any other thread. #### Example ```bash ant beta:sessions:threads retrieve \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ --thread-id sthr_011CZkZVWa6oJjw1rgXZpnBt ``` ##### Response (200) ```json { "id": "sthr_011CZkZVWa6oJjw1rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "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" }, "type": "bash" } ], "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": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "workflow_run_id": null } ``` ### Archive Session Thread `$ ant beta:sessions:threads archive` **POST** `/v1/sessions/{session_id}/threads/{thread_id}/archive` Archive Session Thread #### Parameters - `--session-id: string` (path parameter) - `--thread-id: string` (path parameter) - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_session_thread: object` An execution thread within a `session`. Each session has one primary thread plus zero or more child threads. - `type: "session_thread"` - `id: string` Unique identifier for this thread. - `agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor or BetaManagedAgentsInlineAgent` Resolved agent definition for this thread. Snapshot of the agent at thread creation time. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_inline_agent: object` An agent that has no Agent resource, and so no `id` or `version`. It is defined inline, in a workflow run's plan or when a session thread is spawned, and is not saved. - `type: "inline"` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` The session's execution principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` The name that the agent's definition gave, or one that the server assigned. - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `archived_at: string` When the thread was archived. Null if not archived. format: date-time - `created_at: string` When the thread was created. format: date-time - `parent_thread_id: string` Parent thread that spawned this thread. Null for the primary thread. - `session_id: string` The session this thread belongs to. - `stats: object` Timing statistics for this thread. Null until the thread's first status transition. - `active_seconds: optional number` Cumulative time in seconds the thread spent actively running. Excludes idle time. format: double - `duration_seconds: optional number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. format: double - `startup_seconds: optional number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. format: double - `status: "running" or "idle" or "rescheduling" or "terminated"` Current execution status of the thread. - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` - `updated_at: string` When the thread was last updated. format: date-time - `usage: object` Cumulative token usage for this thread. Null until the thread's first idle transition. - `active_seconds: optional number` Cumulative time in seconds this thread spent in running status. Equal to `stats.active_seconds`; surfaced here so a thread's usage carries every quantity its cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of this thread across all turns, priced at public list rates. Absent until cost tracking is available for the thread. Each figure is rounded to the nearest cent independently and the session's aggregate `usage.list_cost` additionally includes session runtime, so per-thread costs do not sum exactly to the session figure; the session figure is authoritative and is what a budget is enforced against. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns of this thread. Absent until server-tool tracking is available for the thread. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `workflow_run_id: string` Identifier of the workflow run that created the thread, or `null` for any other thread. #### Example ```bash ant beta:sessions:threads archive \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ --thread-id sthr_011CZkZVWa6oJjw1rgXZpnBt ``` ##### Response (200) ```json { "id": "sthr_011CZkZVWa6oJjw1rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-opus-5-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "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" }, "type": "bash" } ], "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": { "active_seconds": 0, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "list_cost": { "amount": "2500", "currency": "USD" }, "output_tokens": 0, "server_tool_use": { "web_fetch_requests": 0, "web_search_requests": 3 } }, "workflow_run_id": null } ``` ## Beta › Sessions › Threads › Events ### List Session Thread Events `$ ant beta:sessions:threads:events list` **GET** `/v1/sessions/{session_id}/threads/{thread_id}/events` List Session Thread Events #### Parameters - `--session-id: string` (path parameter) - `--thread-id: string` (path parameter) - `--limit: optional number` (query parameter) format: int32 - `--page: optional string` (query parameter) - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListSessionThreadEvents: object` Paginated list of events for a single thread within a `session`. - `data: optional array of BetaManagedAgentsSessionEvent` Events for the thread, ordered by `processed_at`. - `beta_managed_agents_user_message_event: object` A user message event in the session conversation. - `type: "user.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks comprising the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `processed_at: optional string` Timestamp when the agent finished processing this message. format: date-time - `beta_managed_agents_user_interrupt_event: object` An interrupt event that pauses agent execution and returns control to the user. - `type: "user.interrupt"` - `id: string` Unique identifier for this event. - `processed_at: optional string` Timestamp when the interrupt was processed. format: date-time - `session_thread_id: optional string` 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_tool_confirmation_event: object` A tool confirmation event that approves or denies a pending tool execution. - `type: "user.tool_confirmation"` - `id: string` Unique identifier for this event. - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` 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?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `deny_message: optional string` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `processed_at: optional string` Timestamp when the confirmation was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_user_custom_tool_result_event: object` Event sent by the client providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `type: "search_result"` - `citations: object` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean` Whether the tool execution resulted in an error. - `processed_at: optional string` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_agent_custom_tool_use_event: object` 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. The client can send it as soon as this event arrives, without waiting for `session.status_idle`. - `type: "agent.custom_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` Timestamp when this tool use was processed. format: date-time - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_message_event: object` An agent response event in the session conversation. - `type: "agent.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock` Array of text blocks comprising the agent response. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when this response was generated. format: date-time - `beta_managed_agents_agent_thinking_event: object` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `type: "agent.thinking"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this thinking was produced. format: date-time - `beta_managed_agents_agent_mcp_tool_use_event: object` Event emitted when the agent invokes a tool provided by an MCP server. - `type: "agent.mcp_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional "allow" or "ask" or "deny"` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluationAlwaysAllow or BetaManagedAgentsAgentToolEvaluationAlwaysAsk or BetaManagedAgentsAgentToolEvaluationAuto` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `beta_managed_agents_agent_tool_evaluation_always_allow: object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `type: "always_allow"` - `beta_managed_agents_agent_tool_evaluation_always_ask: object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `type: "always_ask"` - `beta_managed_agents_agent_tool_evaluation_auto: object` The resolved permission_policy was auto: the server judged this invocation individually. - `type: "auto"` - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermissionAllow or BetaManagedAgentsAgentAutoEvaluatedPermissionAsk or BetaManagedAgentsAgentAutoEvaluatedPermissionDeny` The server's judgement for this invocation. - `beta_managed_agents_agent_auto_evaluated_permission_allow: object` The server judged the invocation safe to execute without client approval. - `type: "allow"` - `beta_managed_agents_agent_auto_evaluated_permission_ask: object` The server reached no judgement; the invocation is held for client approval. - `type: "ask"` - `reason_code: string` The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set. maxLength: 64 - `beta_managed_agents_agent_auto_evaluated_permission_deny: object` The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended. - `type: "deny"` - `reason_code: string` The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set. maxLength: 64 - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_mcp_tool_result_event: object` Event representing the result of an MCP tool execution. - `type: "agent.mcp_tool_result"` - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` Timestamp when this event was processed. format: date-time - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `beta_managed_agents_agent_tool_use_event: object` Event emitted when the agent invokes a built-in agent tool. - `type: "agent.tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional "allow" or "ask" or "deny"` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluationAlwaysAllow or BetaManagedAgentsAgentToolEvaluationAlwaysAsk or BetaManagedAgentsAgentToolEvaluationAuto` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `beta_managed_agents_agent_tool_evaluation_always_allow: object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `beta_managed_agents_agent_tool_evaluation_always_ask: object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `beta_managed_agents_agent_tool_evaluation_auto: object` The resolved permission_policy was auto: the server judged this invocation individually. - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_tool_result_event: object` Event representing the result of an agent tool execution. - `type: "agent.tool_result"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `beta_managed_agents_agent_thread_message_received_event: object` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `type: "agent.thread_message_received"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` Timestamp when the message was received. format: date-time - `from_agent_name: optional string` Name of the callable agent this message came from. Absent when received from the primary agent. - `beta_managed_agents_agent_thread_message_sent_event: object` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `type: "agent.thread_message_sent"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when the message was sent. format: date-time - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `to_agent_name: optional string` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `beta_managed_agents_agent_thread_context_compacted_event: object` Indicates that context compaction (summarization) occurred during the session. - `type: "agent.thread_context_compacted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when compaction was processed. format: date-time - `beta_managed_agents_session_error_event: object` An error event indicating a problem occurred during session execution. - `type: "session.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 10 more` - `beta_managed_agents_unknown_error: object` 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. - `type: "unknown_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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: "retrying"` - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `beta_managed_agents_model_overloaded_error: object` The model is currently overloaded. Emitted after automatic retries are exhausted. - `type: "model_overloaded_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_model_rate_limited_error: object` The model request was rate-limited. - `type: "model_rate_limited_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_model_request_failed_error: object` A model request failed for a reason other than overload or rate-limiting. - `type: "model_request_failed_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_mcp_connection_failed_error: object` Failed to connect to an MCP server. - `type: "mcp_connection_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_mcp_authentication_failed_error: object` Authentication to an MCP server failed. - `type: "mcp_authentication_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_billing_error: object` 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. - `type: "billing_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_credential_host_unreachable_error: object` An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit. - `type: "credential_host_unreachable_error"` - `credential_id: string` ID of the affected credential. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `vault_id: string` ID of the vault containing the affected credential. - `beta_managed_agents_repository_authentication_error: object` The repository host rejected the credentials, or required credentials and received none. - `type: "repository_authentication_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_forbidden_error: object` The repository host refused access to the repository. - `type: "repository_forbidden_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_not_found_error: object` The repository host reported the repository as not found. - `type: "repository_not_found_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_checkout_error: object` The requested branch or commit does not exist in the repository. - `type: "repository_checkout_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_clone_error: object` The repository could not be cloned. - `type: "repository_clone_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `processed_at: string` Timestamp when the error occurred. format: date-time - `beta_managed_agents_session_status_rescheduled_event: object` Indicates the session is recovering from an error state and is rescheduled for execution. - `type: "session.status_rescheduled"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_status_running_event: object` Indicates the session is actively running and the agent is working. - `type: "session.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_status_idle_event: object` Indicates the agent has paused and is awaiting user input. - `type: "session.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `stop_details: object` Structured information about why the session stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `"cyber"` - `"bio"` - `"frontier_llm"` - `"reasoning_extraction"` - `"general_harms"` - `explanation: string` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `beta_managed_agents_session_end_turn: object` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `beta_managed_agents_session_requires_action: object` 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. - `type: "requires_action"` - `event_ids: array of string` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `beta_managed_agents_session_retries_exhausted: object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `type: "retries_exhausted"` - `beta_managed_agents_session_budget_reached: object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `type: "budget_reached"` - `beta_managed_agents_session_refusal: object` The turn ended because the model's response was refused, for example by a safety classifier. - `type: "refusal"` - `beta_managed_agents_session_status_terminated_event: object` Indicates the session has terminated, either due to an error or completion. - `type: "session.status_terminated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_thread_created_event: object` Emitted when a child thread is created. Written to the parent thread's output stream so clients observing the session see child creation. - `type: "session.thread_created"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` Timestamp when the thread was created. format: date-time - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `workflow_run_id: string` Identifier of the workflow run that created the thread, or `null` for any other thread. - `beta_managed_agents_span_outcome_evaluation_start_event: object` Emitted when an outcome evaluation cycle begins. - `type: "span.outcome_evaluation_start"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation started. format: date-time - `beta_managed_agents_span_outcome_evaluation_end_event: object` 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. - `type: "span.outcome_evaluation_end"` - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation ended. format: date-time - `result: string` 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. - `usage: object` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast"` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `"standard"` - `"fast"` - `beta_managed_agents_span_model_request_start_event: object` Emitted when a model request is initiated by the agent. - `type: "span.model_request_start"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the model request started. format: date-time - `beta_managed_agents_span_model_request_end_event: object` Emitted when a model request completes. - `type: "span.model_request_end"` - `id: string` Unique identifier for this event. - `is_error: boolean` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: object` Token usage for this model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast"` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `processed_at: string` Timestamp when the model request completed. format: date-time - `beta_managed_agents_span_outcome_evaluation_ongoing_event: object` 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. - `type: "span.outcome_evaluation_ongoing"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when this heartbeat was emitted. format: date-time - `beta_managed_agents_user_define_outcome_event: object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `type: "user.define_outcome"` - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number` Evaluate-then-revise cycles before giving up. Default 3, max 20. format: int32 - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` Timestamp when the outcome was accepted. format: date-time - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `beta_managed_agents_session_deleted_event: object` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `type: "session.deleted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the session was deleted. format: date-time - `beta_managed_agents_session_thread_status_running_event: object` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_running"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `beta_managed_agents_session_thread_status_idle_event: object` 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. - `type: "session.thread_status_idle"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_details: object` Structured information about why the thread stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `explanation: string` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `beta_managed_agents_session_end_turn: object` The agent completed its turn naturally and is ready for the next user message. - `beta_managed_agents_session_requires_action: object` 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. - `beta_managed_agents_session_retries_exhausted: object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `beta_managed_agents_session_budget_reached: object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `beta_managed_agents_session_refusal: object` The turn ended because the model's response was refused, for example by a safety classifier. - `beta_managed_agents_session_thread_status_terminated_event: object` 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. - `type: "session.thread_status_terminated"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `beta_managed_agents_user_tool_result_event: object` 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. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` 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?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `processed_at: optional string` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_session_thread_status_rescheduled_event: object` 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. - `type: "session.thread_status_rescheduled"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `beta_managed_agents_session_updated_event: object` 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. - `type: "session.updated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the update was applied. format: date-time - `agent: optional object` The session's effective agent configuration after the update. Present only when the update changed `agent` (tools or mcp_servers); when present it is the full materialised snapshot, not a diff. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_session_multiagent_coordinator: object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_session_multiagent20261001: object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_session_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_session_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `version: number` format: int32 - `budget: optional object` The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `metadata: optional map[string]` 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. - `title: optional string` The session's new title. Present only when the update changed it. - `beta_managed_agents_system_message_event: object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string` Timestamp when this system message was processed. format: date-time - `beta_managed_agents_session_usage_event: object` Periodic snapshot of the session's cumulative usage and tracked list cost. - `type: "session.usage"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the snapshot was taken. format: date-time - `usage: object` The session's cumulative usage at the snapshot time. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of the session across all turns, priced at public list rates. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `budget: optional object` The session's configured budget at the snapshot time, or null when the session has no budget. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `beta_managed_agents_workflow_run_created_event: object` A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events. - `type: "workflow_run.created"` - `id: string` Unique identifier for this event. - `description: string` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `phases: array of BetaManagedAgentsWorkflowRunPhase` The phases that the run's plan declares, in the plan's order. Can be empty. - `id: string` Unique identifier for the phase. - `description: string` Description that the agent gave the phase, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the phase, passed on as written. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_status_ended_event: object` A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events. - `type: "workflow_run.status_ended"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `result: BetaManagedAgentsWorkflowRunResultCompleted or BetaManagedAgentsWorkflowRunResultError or BetaManagedAgentsWorkflowRunResultStopped` How the run ended. - `beta_managed_agents_workflow_run_result_completed: object` The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded. - `type: "completed"` - `beta_managed_agents_workflow_run_result_error: object` The run failed or reached its time limit. - `type: "error"` - `error: BetaManagedAgentsTimeoutWorkflowRunError or BetaManagedAgentsProgramWorkflowRunError or BetaManagedAgentsUnknownWorkflowRunError or 2 more` Why the run did not finish. - `beta_managed_agents_timeout_workflow_run_error: object` The run reached its time limit. - `type: "timeout_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_program_workflow_run_error: object` The plan, a program that the agent wrote, failed, or the server refused it. - `type: "program_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_unknown_workflow_run_error: object` A failure that has no type of its own. - `type: "unknown_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_thread_limit_workflow_run_error: object` The run exceeded the limit on the number of threads that a run can create. - `type: "thread_limit_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_max_workflow_runs_workflow_run_error: object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `type: "max_workflow_runs_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_workflow_run_result_stopped: object` The agent stopped the run. - `type: "stopped"` - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_phase_started_event: object` A workflow run's plan entered a phase. - `type: "workflow_run.phase_started"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `beta_managed_agents_workflow_run_phase_ended_event: object` A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left. - `type: "workflow_run.phase_ended"` - `id: string` Unique identifier for this event. - `phase_started_id: string` Identifier of the `workflow_run.phase_started` event that opened the phase. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `beta_managed_agents_workflow_run_status_running_event: object` A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first. - `type: "workflow_run.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_status_idle_event: object` A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`. - `type: "workflow_run.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_error_event: object` A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`. - `type: "workflow_run.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsTimeoutWorkflowRunError or BetaManagedAgentsProgramWorkflowRunError or BetaManagedAgentsUnknownWorkflowRunError or 2 more` Why the run did not finish, or was not created. - `beta_managed_agents_timeout_workflow_run_error: object` The run reached its time limit. - `beta_managed_agents_program_workflow_run_error: object` The plan, a program that the agent wrote, failed, or the server refused it. - `beta_managed_agents_unknown_workflow_run_error: object` A failure that has no type of its own. - `beta_managed_agents_thread_limit_workflow_run_error: object` The run exceeded the limit on the number of threads that a run can create. - `beta_managed_agents_max_workflow_runs_workflow_run_error: object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run that met the error, or `null` when the error kept a run from being created. - `next_page: optional string` Opaque cursor for the next page. Null when no more results. #### Example ```bash ant beta:sessions:threads:events list \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ --thread-id sthr_011CZkZVWa6oJjw1rgXZpnBt ``` ##### Response (200) ```json { "data": [ { "id": "sevt_011CZkZGPp1iBcp4kaQSihUm", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" }, { "id": "sevt_011CZkZHPq1jCdq5mbRTjiVn", "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=" } ``` ### Stream Session Thread Events `$ ant beta:sessions:threads:events stream` **GET** `/v1/sessions/{session_id}/threads/{thread_id}/stream` Stream Session Thread Events #### Parameters - `--session-id: string` (path parameter) - `--thread-id: string` (path parameter) - `--event-delta: optional array of BetaManagedAgentsDeltaType` (query parameter) When set, this connection also receives streaming deltas (`event_start`, `event_delta`) while an event is being produced, before the event itself arrives. Deltas are best-effort; when the final event is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no final event — its terminal `span.model_request_end` closes the preview. Accepts one or more event types to preview and may be repeated: `agent.message` streams `content_delta` fragments; `agent.thinking` is start-only — a signal that the agent has begun extended thinking, concluded by the `agent.thinking` event itself. Only previews of the requested event types are sent. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_stream_session_thread_events: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 41 more` Server-sent event in a single thread's stream. - `beta_managed_agents_user_message_event: object` A user message event in the session conversation. - `type: "user.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks comprising the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `processed_at: optional string` Timestamp when the agent finished processing this message. format: date-time - `beta_managed_agents_user_interrupt_event: object` An interrupt event that pauses agent execution and returns control to the user. - `type: "user.interrupt"` - `id: string` Unique identifier for this event. - `processed_at: optional string` Timestamp when the interrupt was processed. format: date-time - `session_thread_id: optional string` 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_tool_confirmation_event: object` A tool confirmation event that approves or denies a pending tool execution. - `type: "user.tool_confirmation"` - `id: string` Unique identifier for this event. - `result: "allow" or "deny"` The confirmation result: 'allow' or 'deny'. - `"allow"` - `"deny"` - `tool_use_id: string` 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?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `deny_message: optional string` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. maxLength: 10000 - `processed_at: optional string` Timestamp when the confirmation was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_user_custom_tool_result_event: object` Event sent by the client providing the result of a custom tool execution. - `type: "user.custom_tool_result"` - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `type: "search_result"` - `citations: object` Citation settings for this search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: array of BetaManagedAgentsSearchResultContent` Array of text content blocks from the search result. - `type: "text"` - `text: string` The text content. minLength: 1 - `source: string` The URL source of the search result. minLength: 1 - `title: string` The title of the search result. minLength: 1 - `is_error: optional boolean` Whether the tool execution resulted in an error. - `processed_at: optional string` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_agent_custom_tool_use_event: object` 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. The client can send it as soon as this event arrives, without waiting for `session.status_idle`. - `type: "agent.custom_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` Timestamp when this tool use was processed. format: date-time - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.custom_tool_result` by `custom_tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_message_event: object` An agent response event in the session conversation. - `type: "agent.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock` Array of text blocks comprising the agent response. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when this response was generated. format: date-time - `beta_managed_agents_agent_thinking_event: object` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `type: "agent.thinking"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this thinking was produced. format: date-time - `beta_managed_agents_agent_mcp_tool_use_event: object` Event emitted when the agent invokes a tool provided by an MCP server. - `type: "agent.mcp_tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional "allow" or "ask" or "deny"` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluationAlwaysAllow or BetaManagedAgentsAgentToolEvaluationAlwaysAsk or BetaManagedAgentsAgentToolEvaluationAuto` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `beta_managed_agents_agent_tool_evaluation_always_allow: object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `type: "always_allow"` - `beta_managed_agents_agent_tool_evaluation_always_ask: object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `type: "always_ask"` - `beta_managed_agents_agent_tool_evaluation_auto: object` The resolved permission_policy was auto: the server judged this invocation individually. - `type: "auto"` - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermissionAllow or BetaManagedAgentsAgentAutoEvaluatedPermissionAsk or BetaManagedAgentsAgentAutoEvaluatedPermissionDeny` The server's judgement for this invocation. - `beta_managed_agents_agent_auto_evaluated_permission_allow: object` The server judged the invocation safe to execute without client approval. - `type: "allow"` - `beta_managed_agents_agent_auto_evaluated_permission_ask: object` The server reached no judgement; the invocation is held for client approval. - `type: "ask"` - `reason_code: string` The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set. maxLength: 64 - `beta_managed_agents_agent_auto_evaluated_permission_deny: object` The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended. - `type: "deny"` - `reason_code: string` The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set. maxLength: 64 - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.tool_confirmation` by `tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_mcp_tool_result_event: object` Event representing the result of an MCP tool execution. - `type: "agent.mcp_tool_result"` - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` Timestamp when this event was processed. format: date-time - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `beta_managed_agents_agent_tool_use_event: object` Event emitted when the agent invokes a built-in agent tool. - `type: "agent.tool_use"` - `id: string` Unique identifier for this event. - `input: map[unknown]` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` Timestamp when this event was processed. format: date-time - `evaluated_permission: optional "allow" or "ask" or "deny"` The evaluated permission policy for this tool invocation. - `"allow"` - `"ask"` - `"deny"` - `evaluation: optional BetaManagedAgentsAgentToolEvaluationAlwaysAllow or BetaManagedAgentsAgentToolEvaluationAlwaysAsk or BetaManagedAgentsAgentToolEvaluationAuto` Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask). - `beta_managed_agents_agent_tool_evaluation_always_allow: object` The resolved permission_policy was always_allow; accompanies evaluated_permission "allow". - `beta_managed_agents_agent_tool_evaluation_always_ask: object` The resolved permission_policy was always_ask; accompanies evaluated_permission "ask". - `beta_managed_agents_agent_tool_evaluation_auto: object` The resolved permission_policy was auto: the server judged this invocation individually. - `session_thread_id: optional string` 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. Informational only: the server routes the matching `user.tool_confirmation` or `user.tool_result` by `tool_use_id`, so clients do not send it back. - `beta_managed_agents_agent_tool_result_event: object` Event representing the result of an agent tool execution. - `type: "agent.tool_result"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `beta_managed_agents_agent_thread_message_received_event: object` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `type: "agent.thread_message_received"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` Timestamp when the message was received. format: date-time - `from_agent_name: optional string` Name of the callable agent this message came from. Absent when received from the primary agent. - `beta_managed_agents_agent_thread_message_sent_event: object` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `type: "agent.thread_message_sent"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Message content blocks. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `processed_at: string` Timestamp when the message was sent. format: date-time - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `to_agent_name: optional string` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `beta_managed_agents_agent_thread_context_compacted_event: object` Indicates that context compaction (summarization) occurred during the session. - `type: "agent.thread_context_compacted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when compaction was processed. format: date-time - `beta_managed_agents_session_error_event: object` An error event indicating a problem occurred during session execution. - `type: "session.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 10 more` - `beta_managed_agents_unknown_error: object` 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. - `type: "unknown_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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: "retrying"` - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `beta_managed_agents_model_overloaded_error: object` The model is currently overloaded. Emitted after automatic retries are exhausted. - `type: "model_overloaded_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_model_rate_limited_error: object` The model request was rate-limited. - `type: "model_rate_limited_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_model_request_failed_error: object` A model request failed for a reason other than overload or rate-limiting. - `type: "model_request_failed_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_mcp_connection_failed_error: object` Failed to connect to an MCP server. - `type: "mcp_connection_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_mcp_authentication_failed_error: object` Authentication to an MCP server failed. - `type: "mcp_authentication_failed_error"` - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_billing_error: object` 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. - `type: "billing_error"` - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_credential_host_unreachable_error: object` An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit. - `type: "credential_host_unreachable_error"` - `credential_id: string` ID of the affected credential. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `vault_id: string` ID of the vault containing the affected credential. - `beta_managed_agents_repository_authentication_error: object` The repository host rejected the credentials, or required credentials and received none. - `type: "repository_authentication_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_forbidden_error: object` The repository host refused access to the repository. - `type: "repository_forbidden_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_not_found_error: object` The repository host reported the repository as not found. - `type: "repository_not_found_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_checkout_error: object` The requested branch or commit does not exist in the repository. - `type: "repository_checkout_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `beta_managed_agents_repository_clone_error: object` The repository could not be cloned. - `type: "repository_clone_error"` - `message: string` Human-readable error description. - `repository_url: string` URL of the repository that could not be cloned. Null when it could not be identified. - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal` What the client should do next. Always `retrying`: the session keeps running without the repository. - `beta_managed_agents_retry_status_retrying: object` 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. - `beta_managed_agents_retry_status_exhausted: object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `beta_managed_agents_retry_status_terminal: object` The session encountered a terminal error and will transition to `terminated` state. - `processed_at: string` Timestamp when the error occurred. format: date-time - `beta_managed_agents_session_status_rescheduled_event: object` Indicates the session is recovering from an error state and is rescheduled for execution. - `type: "session.status_rescheduled"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_status_running_event: object` Indicates the session is actively running and the agent is working. - `type: "session.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_status_idle_event: object` Indicates the agent has paused and is awaiting user input. - `type: "session.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `stop_details: object` Structured information about why the session stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `"cyber"` - `"bio"` - `"frontier_llm"` - `"reasoning_extraction"` - `"general_harms"` - `explanation: string` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `beta_managed_agents_session_end_turn: object` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `beta_managed_agents_session_requires_action: object` 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. - `type: "requires_action"` - `event_ids: array of string` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `beta_managed_agents_session_retries_exhausted: object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `type: "retries_exhausted"` - `beta_managed_agents_session_budget_reached: object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `type: "budget_reached"` - `beta_managed_agents_session_refusal: object` The turn ended because the model's response was refused, for example by a safety classifier. - `type: "refusal"` - `beta_managed_agents_session_status_terminated_event: object` Indicates the session has terminated, either due to an error or completion. - `type: "session.status_terminated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp of status change. format: date-time - `beta_managed_agents_session_thread_created_event: object` Emitted when a child thread is created. Written to the parent thread's output stream so clients observing the session see child creation. - `type: "session.thread_created"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` Timestamp when the thread was created. format: date-time - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `workflow_run_id: string` Identifier of the workflow run that created the thread, or `null` for any other thread. - `beta_managed_agents_span_outcome_evaluation_start_event: object` Emitted when an outcome evaluation cycle begins. - `type: "span.outcome_evaluation_start"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation started. format: date-time - `beta_managed_agents_span_outcome_evaluation_end_event: object` 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. - `type: "span.outcome_evaluation_end"` - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when outcome evaluation ended. format: date-time - `result: string` 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. - `usage: object` Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast"` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `"standard"` - `"fast"` - `beta_managed_agents_span_model_request_start_event: object` Emitted when a model request is initiated by the agent. - `type: "span.model_request_start"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the model request started. format: date-time - `beta_managed_agents_span_model_request_end_event: object` Emitted when a model request completes. - `type: "span.model_request_end"` - `id: string` Unique identifier for this event. - `is_error: boolean` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: object` Token usage for this model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. format: int32 - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. format: int32 - `input_tokens: number` Input tokens consumed by this request. format: int32 - `output_tokens: number` Output tokens generated by this request. format: int32 - `speed: optional "standard" or "fast"` Inference speed tier this request actually ran at. Mirrors `usage.speed` on /v1/messages. Only present when the fast-mode beta is active. - `processed_at: string` Timestamp when the model request completed. format: date-time - `beta_managed_agents_span_outcome_evaluation_ongoing_event: object` 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. - `type: "span.outcome_evaluation_ongoing"` - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. format: int32 - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` Timestamp when this heartbeat was emitted. format: date-time - `beta_managed_agents_user_define_outcome_event: object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `type: "user.define_outcome"` - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number` Evaluate-then-revise cycles before giving up. Default 3, max 20. format: int32 - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` Timestamp when the outcome was accepted. format: date-time - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `beta_managed_agents_session_deleted_event: object` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `type: "session.deleted"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the session was deleted. format: date-time - `beta_managed_agents_session_thread_status_running_event: object` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `type: "session.thread_status_running"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `beta_managed_agents_session_thread_status_idle_event: object` 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. - `type: "session.thread_status_idle"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_details: object` Structured information about why the thread stopped. `null` when there is nothing more to report. - `type: "refusal"` - `category: "cyber" or "bio" or "frontier_llm" or 2 more` The policy category that triggered the refusal, or `null` when there is no named category. New values can be added over time. - `explanation: string` Human-readable explanation of the refusal, or `null` when none is available. The wording can change, so do not parse it. - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more` - `beta_managed_agents_session_end_turn: object` The agent completed its turn naturally and is ready for the next user message. - `beta_managed_agents_session_requires_action: object` 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. - `beta_managed_agents_session_retries_exhausted: object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `beta_managed_agents_session_budget_reached: object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `beta_managed_agents_session_refusal: object` The turn ended because the model's response was refused, for example by a safety classifier. - `beta_managed_agents_session_thread_status_terminated_event: object` 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. - `type: "session.thread_status_terminated"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `beta_managed_agents_user_tool_result_event: object` 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. - `type: "user.tool_result"` - `id: string` Unique identifier for this event. - `tool_use_id: string` 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?sdk_languages=cli#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock` The result content returned by the tool. - `beta_managed_agents_text_block: object` Regular text content. - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `beta_managed_agents_search_result_block: object` A block containing a web search result. - `is_error: optional boolean` Whether the tool execution resulted in an error. - `processed_at: optional string` Timestamp when this result was processed. format: date-time - `session_thread_id: optional string` Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. - `beta_managed_agents_session_thread_status_rescheduled_event: object` 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. - `type: "session.thread_status_rescheduled"` - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` Timestamp of the status transition. format: date-time - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `beta_managed_agents_session_updated_event: object` 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. - `type: "session.updated"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the update was applied. format: date-time - `agent: optional object` The session's effective agent configuration after the update. Present only when the update changed `agent` (tools or mcp_servers); when present it is the full materialised snapshot, not a diff. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `type: "aws_role"` - `role_arn: string` The IAM role's ARN. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `type: "service_account"` - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient model for coding and agents - `"claude-fable-5"` Next generation of intelligence for the hardest knowledge work and coding problems - `"claude-opus-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-8"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-7"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-6"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` - `"claude-haiku-4-5-20251001"` - `"claude-opus-4-5"` Powerful intelligence for long-running agents and coding - `"claude-opus-4-5-20251101"` Powerful intelligence for long-running agents and coding - `"claude-sonnet-4-5"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `beta_managed_agents_effort_low: object` Low effort. Favors latency over reasoning depth. - `type: "low"` - `beta_managed_agents_effort_medium: object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - `beta_managed_agents_effort_high: object` High effort. Favors reasoning depth. - `type: "high"` - `beta_managed_agents_effort_xhigh: object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - `beta_managed_agents_effort_max: object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001` Resolved multiagent orchestration configuration. Null when the agent is single-threaded. - `beta_managed_agents_session_multiagent_coordinator: object` Resolved coordinator topology with full agent definitions for each roster member. - `type: "coordinator"` - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor` Full `agent` definitions the coordinator may spawn as session threads. - `beta_managed_agents_session_thread_agent: object` 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`. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `beta_managed_agents_aws_role_execution_identity: object` An AWS IAM role principal as returned in API responses. - `beta_managed_agents_service_account_execution_identity: object` The Anthropic-managed service account as returned in API responses. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `type: "url"` - `name: string` - `url: string` - `model: object` Model identifier and configuration. - `id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: optional "standard" or "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `type: "anthropic"` - `skill_id: string` - `version: string` - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `type: "custom"` - `skill_id: string` - `version: string` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `type: "agent_toolset_20260401"` - `configs: array of BetaManagedAgentsAgentToolConfig` - `beta_managed_agents_bash_tool_config: object` Configuration for the bash tool. - `type: "bash"` - `enabled: boolean` - `name: "bash"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `type: "always_ask"` - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `type: "auto"` - `beta_managed_agents_edit_tool_config: object` Configuration for the edit tool. - `type: "edit"` - `enabled: boolean` - `name: "edit"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_read_tool_config: object` Configuration for the read tool. - `type: "read"` - `enabled: boolean` - `name: "read"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_write_tool_config: object` Configuration for the write tool. - `type: "write"` - `enabled: boolean` - `name: "write"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_glob_tool_config: object` Configuration for the glob tool. - `type: "glob"` - `enabled: boolean` - `name: "glob"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_grep_tool_config: object` Configuration for the grep tool. - `type: "grep"` - `enabled: boolean` - `name: "grep"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_web_fetch_tool_config: object` Configuration for the web_fetch tool. - `type: "web_fetch"` - `enabled: boolean` - `name: "web_fetch"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `url_sources: object` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `type: "only"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: "except"` - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference` The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results. - `type: "tool_reference"` Must be "tool_reference". - `name: string` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone or BetaManagedAgentsWebFetchURLSourceOnly or BetaManagedAgentsWebFetchURLSourceExcept` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_only: object` Only the named tools' results contribute URLs that may be fetched. - `beta_managed_agents_web_fetch_url_source_except: object` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `user_input: BetaManagedAgentsWebFetchURLSourceAll or BetaManagedAgentsWebFetchURLSourceNone` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `beta_managed_agents_web_fetch_url_source_all: object` Every URL from this source may be fetched. This is the default. - `type: "all"` - `beta_managed_agents_web_fetch_url_source_none: object` This source contributes no URLs that may be fetched. - `type: "none"` - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number` format: int32 - `beta_managed_agents_web_search_tool_config: object` Configuration for the web_search tool. - `type: "web_search"` - `enabled: boolean` - `name: "web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `user_location: optional object` Approximate user location for search result localization. - `type: "approximate"` Location precision. Only "approximate" is supported. - `city: optional string` City name. minLength: 1, maxLength: 255 - `country: optional string` Two-letter ISO 3166-1 country code, uppercase. - `region: optional string` Region or state name. minLength: 1, maxLength: 255 - `timezone: optional string` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: object` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `beta_managed_agents_mcp_toolset: object` - `type: "mcp_toolset"` - `configs: array of BetaManagedAgentsMCPToolConfig` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `default_config: object` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy` Permission policy for tool execution. - `beta_managed_agents_always_allow_policy: object` Tool calls are automatically approved without user confirmation. - `beta_managed_agents_always_ask_policy: object` Tool calls require user confirmation before execution. - `beta_managed_agents_auto_policy: object` The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask. - `mcp_server_name: string` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `type: "custom"` - `description: string` - `input_schema: object` JSON Schema for custom tool input parameters. - `type: "object"` - `properties: optional map[unknown]` - `required: optional array of string` - `name: string` - `version: number` format: int32 - `beta_managed_agents_advisor: object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: "advisor"` - `model: string` The advisor model id. - `beta_managed_agents_session_multiagent20261001: object` Resolved multiagent configuration with three members, as copied to the `session` at creation. - `type: "multiagent_20261001"` - `advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled` Whether the session's primary thread can consult an advisor model. - `beta_managed_agents_multiagent_advisor_enabled: object` The session's primary thread can consult `model` mid-turn. - `type: "enabled"` - `model: string` The advisor model id. - `beta_managed_agents_multiagent_advisor_disabled: object` The agent has no advisor. - `type: "disabled"` - `subagents: BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled` Whether the agent can spawn session threads. - `beta_managed_agents_session_multiagent_subagents_enabled: object` The agent can spawn session threads. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `type: "enabled"` - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `type: "disabled"` - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_subagents_disabled: object` The agent cannot spawn session threads. - `type: "disabled"` - `workflows: BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled` Whether the agent can start workflow runs. - `beta_managed_agents_session_multiagent_workflows_enabled: object` The agent can start workflow runs. - `type: "enabled"` - `inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled` Whether a run's plan can define inline agents, which are not saved. - `beta_managed_agents_multiagent_inline_agents_enabled: object` The agent can define inline agents. - `beta_managed_agents_multiagent_inline_agents_disabled: object` The agent cannot define inline agents. - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent` Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use. - `type: "agent"` - `id: string` - `description: string` - `execution_identity: BetaManagedAgentsAWSRoleExecutionIdentity or BetaManagedAgentsServiceAccountExecutionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition` - `model: object` Model identifier and configuration. - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `version: number` format: int32 - `beta_managed_agents_multiagent_workflows_disabled: object` The agent cannot start workflow runs. - `type: "disabled"` - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - `beta_managed_agents_anthropic_skill: object` A resolved Anthropic-managed skill. - `beta_managed_agents_custom_skill: object` A resolved user-created custom skill. - `system: string` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - `beta_managed_agents_agent_toolset20260401: object` - `beta_managed_agents_mcp_toolset: object` - `beta_managed_agents_custom_tool: object` A custom tool as returned in API responses. - `version: number` format: int32 - `budget: optional object` The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `metadata: optional map[string]` 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. - `title: optional string` The session's new title. Present only when the update changed it. - `beta_managed_agents_start_event: object` Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history. - `type: "event_start"` - `event: BetaManagedAgentsAgentMessagePreview or BetaManagedAgentsAgentThinkingPreview` The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them. - `beta_managed_agents_agent_message_preview: object` - `type: "agent.message"` - `id: string` The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events. - `beta_managed_agents_agent_thinking_preview: object` - `type: "agent.thinking"` - `id: string` The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow. - `beta_managed_agents_delta_event: object` An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history. - `type: "event_delta"` - `delta: object` One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array. - `type: "content_delta"` - `content: object` A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content. - `type: "text"` - `text: string` The text content. minLength: 1 - `index: optional number` Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise. - `event_id: string` The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview. - `beta_managed_agents_system_message_event: object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn. - `type: "system.message"` - `id: string` Unique identifier for this event. - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `processed_at: optional string` Timestamp when this system message was processed. format: date-time - `beta_managed_agents_session_usage_event: object` Periodic snapshot of the session's cumulative usage and tracked list cost. - `type: "session.usage"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when the snapshot was taken. format: date-time - `usage: object` The session's cumulative usage at the snapshot time. - `active_seconds: optional number` Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. format: double - `cache_creation: optional object` Tokens used to create prompt cache entries, broken down by cache TTL. - `ephemeral_1h_input_tokens: optional number` Tokens used to create 1-hour ephemeral cache entries. format: int32 - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. format: int32 - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. format: int32 - `input_tokens: optional number` Total input tokens consumed across all turns. format: int32 - `list_cost: optional object` Cumulative list cost of the session across all turns, priced at public list rates. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `output_tokens: optional number` Total output tokens generated across all turns. format: int32 - `server_tool_use: optional object` Cumulative server-executed tool usage across all turns. - `web_fetch_requests: optional number` Number of server-executed web fetch requests. format: int32 - `web_search_requests: optional number` Number of server-executed web search requests. format: int32 - `budget: optional object` The session's configured budget at the snapshot time, or null when the session has no budget. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `beta_managed_agents_workflow_run_created_event: object` A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events. - `type: "workflow_run.created"` - `id: string` Unique identifier for this event. - `description: string` Description that the agent gave the run, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the run, passed on as written, or a name that the server assigned. - `phases: array of BetaManagedAgentsWorkflowRunPhase` The phases that the run's plan declares, in the plan's order. Can be empty. - `id: string` Unique identifier for the phase. - `description: string` Description that the agent gave the phase, passed on as written, or `null` if it gave none. - `name: string` Name that the agent gave the phase, passed on as written. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_status_ended_event: object` A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events. - `type: "workflow_run.status_ended"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `result: BetaManagedAgentsWorkflowRunResultCompleted or BetaManagedAgentsWorkflowRunResultError or BetaManagedAgentsWorkflowRunResultStopped` How the run ended. - `beta_managed_agents_workflow_run_result_completed: object` The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded. - `type: "completed"` - `beta_managed_agents_workflow_run_result_error: object` The run failed or reached its time limit. - `type: "error"` - `error: BetaManagedAgentsTimeoutWorkflowRunError or BetaManagedAgentsProgramWorkflowRunError or BetaManagedAgentsUnknownWorkflowRunError or 2 more` Why the run did not finish. - `beta_managed_agents_timeout_workflow_run_error: object` The run reached its time limit. - `type: "timeout_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_program_workflow_run_error: object` The plan, a program that the agent wrote, failed, or the server refused it. - `type: "program_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_unknown_workflow_run_error: object` A failure that has no type of its own. - `type: "unknown_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_thread_limit_workflow_run_error: object` The run exceeded the limit on the number of threads that a run can create. - `type: "thread_limit_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_max_workflow_runs_workflow_run_error: object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `type: "max_workflow_runs_error"` - `message: string` Short explanation written by the server. It never contains content from the run or its agents. - `beta_managed_agents_workflow_run_result_stopped: object` The agent stopped the run. - `type: "stopped"` - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_phase_started_event: object` A workflow run's plan entered a phase. - `type: "workflow_run.phase_started"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `beta_managed_agents_workflow_run_phase_ended_event: object` A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left. - `type: "workflow_run.phase_ended"` - `id: string` Unique identifier for this event. - `phase_started_id: string` Identifier of the `workflow_run.phase_started` event that opened the phase. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `workflow_run_phase_id: string` Identifier of the phase, as in `phases` on the run's `workflow_run.created` event. - `beta_managed_agents_workflow_run_status_running_event: object` A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first. - `type: "workflow_run.status_running"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_status_idle_event: object` A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`. - `type: "workflow_run.status_idle"` - `id: string` Unique identifier for this event. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run. The same value is on all of the run's `workflow_run.*` events. - `beta_managed_agents_workflow_run_error_event: object` A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`. - `type: "workflow_run.error"` - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsTimeoutWorkflowRunError or BetaManagedAgentsProgramWorkflowRunError or BetaManagedAgentsUnknownWorkflowRunError or 2 more` Why the run did not finish, or was not created. - `beta_managed_agents_timeout_workflow_run_error: object` The run reached its time limit. - `beta_managed_agents_program_workflow_run_error: object` The plan, a program that the agent wrote, failed, or the server refused it. - `beta_managed_agents_unknown_workflow_run_error: object` A failure that has no type of its own. - `beta_managed_agents_thread_limit_workflow_run_error: object` The run exceeded the limit on the number of threads that a run can create. - `beta_managed_agents_max_workflow_runs_workflow_run_error: object` No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type. - `processed_at: string` Timestamp when this event was processed. format: date-time - `workflow_run_id: string` Identifier of the run that met the error, or `null` when the error kept a run from being created. #### Example ```bash ant beta:sessions:threads:events stream \ --api-key my-anthropic-api-key \ --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \ --thread-id sthr_011CZkZVWa6oJjw1rgXZpnBt ``` ##### Response (200) ```json { "id": "sevt_011CZkZGPp1iBcp4kaQSihUm", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ``` ## Beta › Deployments ### Create Deployment `$ ant beta:deployments create` **POST** `/v1/deployments` Create Deployment #### Parameters - `--agent: string or BetaManagedAgentsAgentParams` 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. - `--environment-id: string` ID of the `environment` defining the container configuration for sessions created from this deployment. minLength: 1, maxLength: 128 - `--initial-event: array of BetaManagedAgentsDeploymentInitialEventParams` Events to send to each session immediately after creation. At least 1, maximum 50. - `--name: string` Human-readable name for the deployment. minLength: 1, maxLength: 256 - `--budget: optional object` Enforced spend ceiling stamped onto each session created from this deployment, copied at session-creation time. Omit to leave sessions uncapped. The deployment agent's model must have a public list price, or the request is rejected; a multiagent roster is re-validated in full when each fire copies the cap, which fails closed the same way. - `--description: optional string` Description of what the deployment does. maxLength: 2048 - `--metadata: optional map[string]` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `--resource: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam` Resources (e.g. repositories, files) to mount into each session's container. Maximum 500. - `--schedule: optional object` Optional recurring cron schedule. When present, the deployment fires automatically. Both expression and timezone are required when schedule is set. - `--vault-id: optional array of string` Vault IDs for stored credentials the agent can use during sessions created from this deployment. Maximum 50. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deployment: object` 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. - `type: "deployment"` - `id: string` Unique identifier for this deployment. - `agent: object` Reference to the agent this deployment runs, resolved to a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `archived_at: string` Time the deployment was archived. Null if not archived. format: date-time - `created_at: string` Time the deployment was created. format: date-time - `description: string` Description of what the deployment does. - `environment_id: string` ID of the `environment` where sessions run. - `initial_events: array of BetaManagedAgentsDeploymentInitialEvent` Events sent to each session immediately after creation. - `beta_managed_agents_deployment_user_message_event: object` A user message sent to the session. - `type: "user.message"` - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks for the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `beta_managed_agents_deployment_user_define_outcome_event: object` An outcome the agent should work toward. The agent begins work on receipt. - `type: "user.define_outcome"` - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. Text or file reference. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `max_iterations: optional number` Eval→revision cycles before giving up. Default 3, max 20. format: int32 - `beta_managed_agents_deployment_system_message_event: object` 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. - `type: "system.message"` - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks to append. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs. - `name: string` Human-readable name. - `paused_reason: BetaManagedAgentsManualDeploymentPausedReason or BetaManagedAgentsErrorDeploymentPausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `beta_managed_agents_manual_deployment_paused_reason: object` The caller invoked the pause endpoint on the deployment. - `type: "manual"` - `beta_managed_agents_error_deployment_paused_reason: object` A scheduled fire recorded a failed run whose error auto-pauses the deployment. - `type: "error"` - `error: BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError or BetaManagedAgentsAgentArchivedDeploymentPausedReasonError or BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError or 11 more` The failed run's error. - `beta_managed_agents_environment_archived_deployment_paused_reason_error: object` The deployment's environment was archived. - `type: "environment_archived_error"` - `beta_managed_agents_agent_archived_deployment_paused_reason_error: object` The deployment's agent was archived. - `type: "agent_archived_error"` - `beta_managed_agents_environment_not_found_deployment_paused_reason_error: object` The deployment's environment no longer exists. - `type: "environment_not_found_error"` - `beta_managed_agents_vault_not_found_deployment_paused_reason_error: object` A vault referenced by the deployment no longer exists. - `type: "vault_not_found_error"` - `beta_managed_agents_file_not_found_deployment_paused_reason_error: object` A file resource referenced by the deployment no longer exists. - `type: "file_not_found_error"` - `beta_managed_agents_session_resource_not_found_deployment_paused_reason_error: object` A referenced resource no longer exists and its kind was not reported. - `type: "session_resource_not_found_error"` - `beta_managed_agents_workspace_archived_deployment_paused_reason_error: object` The deployment's workspace was archived. - `type: "workspace_archived_error"` - `beta_managed_agents_organization_disabled_deployment_paused_reason_error: object` The deployment's organization is disabled. - `type: "organization_disabled_error"` - `beta_managed_agents_memory_store_archived_deployment_paused_reason_error: object` A memory store referenced by the deployment is archived. - `type: "memory_store_archived_error"` - `beta_managed_agents_skill_not_found_deployment_paused_reason_error: object` A skill referenced by the deployment's agent no longer exists. - `type: "skill_not_found_error"` - `beta_managed_agents_vault_archived_deployment_paused_reason_error: object` A vault referenced by the deployment is archived. - `type: "vault_archived_error"` - `beta_managed_agents_unknown_deployment_paused_reason_error: object` An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`. - `type: "unknown_error"` - `beta_managed_agents_self_hosted_resources_unsupported_deployment_paused_reason_error: object` The deployment configures resources, but its environment is self-hosted and cannot mount them. - `type: "self_hosted_resources_unsupported_error"` - `beta_managed_agents_mcp_egress_blocked_deployment_paused_reason_error: object` An MCP server host used by the deployment's agent is blocked by the environment's network policy. - `type: "mcp_egress_blocked_error"` - `resources: array of BetaManagedAgentsSessionResourceConfig` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `beta_managed_agents_github_repository_resource_config: object` A GitHub repository mounted into each session's container. The authorization token is write-only and never returned. - `type: "github_repository"` - `url: string` Github URL of the repository - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` Branch or commit to check out. Defaults to the repository's default branch. - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `mount_path: optional string` Mount path in the container. Defaults to `/workspace/`. - `beta_managed_agents_file_resource_config: object` A file mounted into each session's container. - `type: "file"` - `file_id: string` ID of a previously uploaded file. - `mount_path: optional string` Mount path in the container. Defaults to `/mnt/session/uploads/`. - `beta_managed_agents_memory_store_resource_config: object` A memory store attached to each session created from this deployment. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `schedule: object` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `type: "cron"` - `expression: string` 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). minLength: 1, maxLength: 256 - `timezone: string` IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). minLength: 1 - `last_run_at: optional string` Time the most recent scheduled run actually started. Null until one completes; preserved after the deployment is archived. Manual runs do not update this. format: date-time - `upcoming_runs_at: optional array of string` 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. - `status: "active" or "paused"` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `"active"` The deployment is active and can run sessions. Archived deployments also report this status; check `archived_at` to distinguish them. - `"paused"` The deployment is paused. Autonomous triggers are suppressed; manual runs are still permitted. - `updated_at: string` Time the deployment was last updated. format: date-time - `vault_ids: array of string` Vault IDs supplying stored credentials for sessions created from this deployment. - `budget: optional object` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. #### Example ```bash ant beta:deployments create \ --api-key my-anthropic-api-key \ --agent string \ --environment-id x \ --initial-event '{content: [{text: '\''Where is my order #1234?'\'', type: text}], type: user.message}' \ --name x ``` ##### Response (200) ```json { "id": "depl_011CZkZcDH3vPqd7xnEfwTai", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "Compiles yesterday's orders into a report every weekday morning.", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "initial_events": [ { "content": [ { "text": "Compile yesterday's orders into report.md.", "type": "text" } ], "type": "user.message" } ], "metadata": {}, "name": "Daily order report", "paused_reason": { "type": "manual" }, "resources": [ { "type": "github_repository", "url": "url", "checkout": { "name": "main", "type": "branch" }, "mount_path": "mount_path" } ], "schedule": { "expression": "0 9 * * 1-5", "timezone": "America/Los_Angeles", "type": "cron", "last_run_at": "2026-03-16T16:00:09Z", "upcoming_runs_at": [ "2026-03-17T16:00:00Z", "2026-03-18T16:00:00Z" ] }, "status": "active", "type": "deployment", "updated_at": "2026-03-15T10:00:00Z", "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" } } ``` ### List Deployments `$ ant beta:deployments list` **GET** `/v1/deployments` List Deployments #### Parameters - `--agent-id: optional string` (query parameter) Filter by agent ID. - `--created-at-gte: optional string` (query parameter) Return deployments created at or after this time (inclusive). format: date-time - `--created-at-lte: optional string` (query parameter) Return deployments created at or before this time (inclusive). format: date-time - `--include-archived: optional boolean` (query parameter) When true, includes archived deployments. Default: false (exclude archived). - `--limit: optional number` (query parameter) Maximum results per page. Default 20, maximum 100. format: int32 - `--page: optional string` (query parameter) Opaque pagination cursor. - `--status: optional "active" or "paused"` (query parameter) Filter by status: `active` or `paused`. Omit for both. To include archived deployments, use `include_archived` instead; the two cannot be combined. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListDeploymentsData: object` Paginated list of deployments. - `data: array of BetaManagedAgentsDeployment` List of deployments. - `type: "deployment"` - `id: string` Unique identifier for this deployment. - `agent: object` Reference to the agent this deployment runs, resolved to a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `archived_at: string` Time the deployment was archived. Null if not archived. format: date-time - `created_at: string` Time the deployment was created. format: date-time - `description: string` Description of what the deployment does. - `environment_id: string` ID of the `environment` where sessions run. - `initial_events: array of BetaManagedAgentsDeploymentInitialEvent` Events sent to each session immediately after creation. - `beta_managed_agents_deployment_user_message_event: object` A user message sent to the session. - `type: "user.message"` - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks for the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `beta_managed_agents_deployment_user_define_outcome_event: object` An outcome the agent should work toward. The agent begins work on receipt. - `type: "user.define_outcome"` - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. Text or file reference. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `max_iterations: optional number` Eval→revision cycles before giving up. Default 3, max 20. format: int32 - `beta_managed_agents_deployment_system_message_event: object` 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. - `type: "system.message"` - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks to append. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs. - `name: string` Human-readable name. - `paused_reason: BetaManagedAgentsManualDeploymentPausedReason or BetaManagedAgentsErrorDeploymentPausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `beta_managed_agents_manual_deployment_paused_reason: object` The caller invoked the pause endpoint on the deployment. - `type: "manual"` - `beta_managed_agents_error_deployment_paused_reason: object` A scheduled fire recorded a failed run whose error auto-pauses the deployment. - `type: "error"` - `error: BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError or BetaManagedAgentsAgentArchivedDeploymentPausedReasonError or BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError or 11 more` The failed run's error. - `beta_managed_agents_environment_archived_deployment_paused_reason_error: object` The deployment's environment was archived. - `type: "environment_archived_error"` - `beta_managed_agents_agent_archived_deployment_paused_reason_error: object` The deployment's agent was archived. - `type: "agent_archived_error"` - `beta_managed_agents_environment_not_found_deployment_paused_reason_error: object` The deployment's environment no longer exists. - `type: "environment_not_found_error"` - `beta_managed_agents_vault_not_found_deployment_paused_reason_error: object` A vault referenced by the deployment no longer exists. - `type: "vault_not_found_error"` - `beta_managed_agents_file_not_found_deployment_paused_reason_error: object` A file resource referenced by the deployment no longer exists. - `type: "file_not_found_error"` - `beta_managed_agents_session_resource_not_found_deployment_paused_reason_error: object` A referenced resource no longer exists and its kind was not reported. - `type: "session_resource_not_found_error"` - `beta_managed_agents_workspace_archived_deployment_paused_reason_error: object` The deployment's workspace was archived. - `type: "workspace_archived_error"` - `beta_managed_agents_organization_disabled_deployment_paused_reason_error: object` The deployment's organization is disabled. - `type: "organization_disabled_error"` - `beta_managed_agents_memory_store_archived_deployment_paused_reason_error: object` A memory store referenced by the deployment is archived. - `type: "memory_store_archived_error"` - `beta_managed_agents_skill_not_found_deployment_paused_reason_error: object` A skill referenced by the deployment's agent no longer exists. - `type: "skill_not_found_error"` - `beta_managed_agents_vault_archived_deployment_paused_reason_error: object` A vault referenced by the deployment is archived. - `type: "vault_archived_error"` - `beta_managed_agents_unknown_deployment_paused_reason_error: object` An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`. - `type: "unknown_error"` - `beta_managed_agents_self_hosted_resources_unsupported_deployment_paused_reason_error: object` The deployment configures resources, but its environment is self-hosted and cannot mount them. - `type: "self_hosted_resources_unsupported_error"` - `beta_managed_agents_mcp_egress_blocked_deployment_paused_reason_error: object` An MCP server host used by the deployment's agent is blocked by the environment's network policy. - `type: "mcp_egress_blocked_error"` - `resources: array of BetaManagedAgentsSessionResourceConfig` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `beta_managed_agents_github_repository_resource_config: object` A GitHub repository mounted into each session's container. The authorization token is write-only and never returned. - `type: "github_repository"` - `url: string` Github URL of the repository - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` Branch or commit to check out. Defaults to the repository's default branch. - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `mount_path: optional string` Mount path in the container. Defaults to `/workspace/`. - `beta_managed_agents_file_resource_config: object` A file mounted into each session's container. - `type: "file"` - `file_id: string` ID of a previously uploaded file. - `mount_path: optional string` Mount path in the container. Defaults to `/mnt/session/uploads/`. - `beta_managed_agents_memory_store_resource_config: object` A memory store attached to each session created from this deployment. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `schedule: object` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `type: "cron"` - `expression: string` 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). minLength: 1, maxLength: 256 - `timezone: string` IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). minLength: 1 - `last_run_at: optional string` Time the most recent scheduled run actually started. Null until one completes; preserved after the deployment is archived. Manual runs do not update this. format: date-time - `upcoming_runs_at: optional array of string` 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. - `status: "active" or "paused"` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `"active"` The deployment is active and can run sessions. Archived deployments also report this status; check `archived_at` to distinguish them. - `"paused"` The deployment is paused. Autonomous triggers are suppressed; manual runs are still permitted. - `updated_at: string` Time the deployment was last updated. format: date-time - `vault_ids: array of string` Vault IDs supplying stored credentials for sessions created from this deployment. - `budget: optional object` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - `next_page: optional string` Opaque cursor for the next page. Null when no more results. #### Example ```bash ant beta:deployments list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "depl_011CZkZcDH3vPqd7xnEfwTai", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "Compiles yesterday's orders into a report every weekday morning.", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "initial_events": [ { "content": [ { "text": "Compile yesterday's orders into report.md.", "type": "text" } ], "type": "user.message" } ], "metadata": {}, "name": "Daily order report", "paused_reason": { "type": "manual" }, "resources": [ { "type": "github_repository", "url": "url", "checkout": { "name": "main", "type": "branch" }, "mount_path": "mount_path" } ], "schedule": { "expression": "0 9 * * 1-5", "timezone": "America/Los_Angeles", "type": "cron", "last_run_at": "2026-03-16T16:00:09Z", "upcoming_runs_at": [ "2026-03-17T16:00:00Z", "2026-03-18T16:00:00Z" ] }, "status": "active", "type": "deployment", "updated_at": "2026-03-15T10:00:00Z", "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" } } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Get Deployment `$ ant beta:deployments retrieve` **GET** `/v1/deployments/{deployment_id}` Get Deployment #### Parameters - `--deployment-id: string` (path parameter) Unique identifier of the deployment. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deployment: object` 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. - `type: "deployment"` - `id: string` Unique identifier for this deployment. - `agent: object` Reference to the agent this deployment runs, resolved to a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `archived_at: string` Time the deployment was archived. Null if not archived. format: date-time - `created_at: string` Time the deployment was created. format: date-time - `description: string` Description of what the deployment does. - `environment_id: string` ID of the `environment` where sessions run. - `initial_events: array of BetaManagedAgentsDeploymentInitialEvent` Events sent to each session immediately after creation. - `beta_managed_agents_deployment_user_message_event: object` A user message sent to the session. - `type: "user.message"` - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks for the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `beta_managed_agents_deployment_user_define_outcome_event: object` An outcome the agent should work toward. The agent begins work on receipt. - `type: "user.define_outcome"` - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. Text or file reference. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `max_iterations: optional number` Eval→revision cycles before giving up. Default 3, max 20. format: int32 - `beta_managed_agents_deployment_system_message_event: object` 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. - `type: "system.message"` - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks to append. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs. - `name: string` Human-readable name. - `paused_reason: BetaManagedAgentsManualDeploymentPausedReason or BetaManagedAgentsErrorDeploymentPausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `beta_managed_agents_manual_deployment_paused_reason: object` The caller invoked the pause endpoint on the deployment. - `type: "manual"` - `beta_managed_agents_error_deployment_paused_reason: object` A scheduled fire recorded a failed run whose error auto-pauses the deployment. - `type: "error"` - `error: BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError or BetaManagedAgentsAgentArchivedDeploymentPausedReasonError or BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError or 11 more` The failed run's error. - `beta_managed_agents_environment_archived_deployment_paused_reason_error: object` The deployment's environment was archived. - `type: "environment_archived_error"` - `beta_managed_agents_agent_archived_deployment_paused_reason_error: object` The deployment's agent was archived. - `type: "agent_archived_error"` - `beta_managed_agents_environment_not_found_deployment_paused_reason_error: object` The deployment's environment no longer exists. - `type: "environment_not_found_error"` - `beta_managed_agents_vault_not_found_deployment_paused_reason_error: object` A vault referenced by the deployment no longer exists. - `type: "vault_not_found_error"` - `beta_managed_agents_file_not_found_deployment_paused_reason_error: object` A file resource referenced by the deployment no longer exists. - `type: "file_not_found_error"` - `beta_managed_agents_session_resource_not_found_deployment_paused_reason_error: object` A referenced resource no longer exists and its kind was not reported. - `type: "session_resource_not_found_error"` - `beta_managed_agents_workspace_archived_deployment_paused_reason_error: object` The deployment's workspace was archived. - `type: "workspace_archived_error"` - `beta_managed_agents_organization_disabled_deployment_paused_reason_error: object` The deployment's organization is disabled. - `type: "organization_disabled_error"` - `beta_managed_agents_memory_store_archived_deployment_paused_reason_error: object` A memory store referenced by the deployment is archived. - `type: "memory_store_archived_error"` - `beta_managed_agents_skill_not_found_deployment_paused_reason_error: object` A skill referenced by the deployment's agent no longer exists. - `type: "skill_not_found_error"` - `beta_managed_agents_vault_archived_deployment_paused_reason_error: object` A vault referenced by the deployment is archived. - `type: "vault_archived_error"` - `beta_managed_agents_unknown_deployment_paused_reason_error: object` An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`. - `type: "unknown_error"` - `beta_managed_agents_self_hosted_resources_unsupported_deployment_paused_reason_error: object` The deployment configures resources, but its environment is self-hosted and cannot mount them. - `type: "self_hosted_resources_unsupported_error"` - `beta_managed_agents_mcp_egress_blocked_deployment_paused_reason_error: object` An MCP server host used by the deployment's agent is blocked by the environment's network policy. - `type: "mcp_egress_blocked_error"` - `resources: array of BetaManagedAgentsSessionResourceConfig` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `beta_managed_agents_github_repository_resource_config: object` A GitHub repository mounted into each session's container. The authorization token is write-only and never returned. - `type: "github_repository"` - `url: string` Github URL of the repository - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` Branch or commit to check out. Defaults to the repository's default branch. - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `mount_path: optional string` Mount path in the container. Defaults to `/workspace/`. - `beta_managed_agents_file_resource_config: object` A file mounted into each session's container. - `type: "file"` - `file_id: string` ID of a previously uploaded file. - `mount_path: optional string` Mount path in the container. Defaults to `/mnt/session/uploads/`. - `beta_managed_agents_memory_store_resource_config: object` A memory store attached to each session created from this deployment. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `schedule: object` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `type: "cron"` - `expression: string` 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). minLength: 1, maxLength: 256 - `timezone: string` IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). minLength: 1 - `last_run_at: optional string` Time the most recent scheduled run actually started. Null until one completes; preserved after the deployment is archived. Manual runs do not update this. format: date-time - `upcoming_runs_at: optional array of string` 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. - `status: "active" or "paused"` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `"active"` The deployment is active and can run sessions. Archived deployments also report this status; check `archived_at` to distinguish them. - `"paused"` The deployment is paused. Autonomous triggers are suppressed; manual runs are still permitted. - `updated_at: string` Time the deployment was last updated. format: date-time - `vault_ids: array of string` Vault IDs supplying stored credentials for sessions created from this deployment. - `budget: optional object` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. #### Example ```bash ant beta:deployments retrieve \ --api-key my-anthropic-api-key \ --deployment-id depl_011CZkZcDH3vPqd7xnEfwTai ``` ##### Response (200) ```json { "id": "depl_011CZkZcDH3vPqd7xnEfwTai", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "Compiles yesterday's orders into a report every weekday morning.", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "initial_events": [ { "content": [ { "text": "Compile yesterday's orders into report.md.", "type": "text" } ], "type": "user.message" } ], "metadata": {}, "name": "Daily order report", "paused_reason": { "type": "manual" }, "resources": [ { "type": "github_repository", "url": "url", "checkout": { "name": "main", "type": "branch" }, "mount_path": "mount_path" } ], "schedule": { "expression": "0 9 * * 1-5", "timezone": "America/Los_Angeles", "type": "cron", "last_run_at": "2026-03-16T16:00:09Z", "upcoming_runs_at": [ "2026-03-17T16:00:00Z", "2026-03-18T16:00:00Z" ] }, "status": "active", "type": "deployment", "updated_at": "2026-03-15T10:00:00Z", "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" } } ``` ### Update Deployment `$ ant beta:deployments update` **POST** `/v1/deployments/{deployment_id}` Update Deployment #### Parameters - `--deployment-id: string` (path parameter) Unique identifier of the deployment to update. - `--agent: optional string or BetaManagedAgentsAgentParams` 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. - `--budget: optional object` Spend ceiling for future sessions. Full replacement. Omit to preserve; send null to clear (sessions created afterwards are uncapped). The deployment agent's model must have a public list price, or the request is rejected; a multiagent roster is re-validated in full when each fire copies the cap, which fails closed the same way. - `--description: optional string` Description. Omit to preserve; send empty string or null to clear. maxLength: 2048 - `--environment-id: optional string` ID of the `environment` where sessions run. Omit to preserve. Cannot be cleared. maxLength: 128 - `--initial-event: optional array of BetaManagedAgentsDeploymentInitialEventParams` Initial events. Full replacement. Omit to preserve. Cannot be cleared. At least 1, maximum 50. - `--metadata: optional map[string]` 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. - `--name: optional string` Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared. maxLength: 256 - `--resource: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam` Session resources. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 500. - `--schedule: optional object` Cron schedule. Full replacement. Omit to preserve; send null to clear (revert to manual-only). - `--vault-id: optional array of string` Vault IDs. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 50. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deployment: object` 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. - `type: "deployment"` - `id: string` Unique identifier for this deployment. - `agent: object` Reference to the agent this deployment runs, resolved to a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `archived_at: string` Time the deployment was archived. Null if not archived. format: date-time - `created_at: string` Time the deployment was created. format: date-time - `description: string` Description of what the deployment does. - `environment_id: string` ID of the `environment` where sessions run. - `initial_events: array of BetaManagedAgentsDeploymentInitialEvent` Events sent to each session immediately after creation. - `beta_managed_agents_deployment_user_message_event: object` A user message sent to the session. - `type: "user.message"` - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks for the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `beta_managed_agents_deployment_user_define_outcome_event: object` An outcome the agent should work toward. The agent begins work on receipt. - `type: "user.define_outcome"` - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. Text or file reference. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `max_iterations: optional number` Eval→revision cycles before giving up. Default 3, max 20. format: int32 - `beta_managed_agents_deployment_system_message_event: object` 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. - `type: "system.message"` - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks to append. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs. - `name: string` Human-readable name. - `paused_reason: BetaManagedAgentsManualDeploymentPausedReason or BetaManagedAgentsErrorDeploymentPausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `beta_managed_agents_manual_deployment_paused_reason: object` The caller invoked the pause endpoint on the deployment. - `type: "manual"` - `beta_managed_agents_error_deployment_paused_reason: object` A scheduled fire recorded a failed run whose error auto-pauses the deployment. - `type: "error"` - `error: BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError or BetaManagedAgentsAgentArchivedDeploymentPausedReasonError or BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError or 11 more` The failed run's error. - `beta_managed_agents_environment_archived_deployment_paused_reason_error: object` The deployment's environment was archived. - `type: "environment_archived_error"` - `beta_managed_agents_agent_archived_deployment_paused_reason_error: object` The deployment's agent was archived. - `type: "agent_archived_error"` - `beta_managed_agents_environment_not_found_deployment_paused_reason_error: object` The deployment's environment no longer exists. - `type: "environment_not_found_error"` - `beta_managed_agents_vault_not_found_deployment_paused_reason_error: object` A vault referenced by the deployment no longer exists. - `type: "vault_not_found_error"` - `beta_managed_agents_file_not_found_deployment_paused_reason_error: object` A file resource referenced by the deployment no longer exists. - `type: "file_not_found_error"` - `beta_managed_agents_session_resource_not_found_deployment_paused_reason_error: object` A referenced resource no longer exists and its kind was not reported. - `type: "session_resource_not_found_error"` - `beta_managed_agents_workspace_archived_deployment_paused_reason_error: object` The deployment's workspace was archived. - `type: "workspace_archived_error"` - `beta_managed_agents_organization_disabled_deployment_paused_reason_error: object` The deployment's organization is disabled. - `type: "organization_disabled_error"` - `beta_managed_agents_memory_store_archived_deployment_paused_reason_error: object` A memory store referenced by the deployment is archived. - `type: "memory_store_archived_error"` - `beta_managed_agents_skill_not_found_deployment_paused_reason_error: object` A skill referenced by the deployment's agent no longer exists. - `type: "skill_not_found_error"` - `beta_managed_agents_vault_archived_deployment_paused_reason_error: object` A vault referenced by the deployment is archived. - `type: "vault_archived_error"` - `beta_managed_agents_unknown_deployment_paused_reason_error: object` An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`. - `type: "unknown_error"` - `beta_managed_agents_self_hosted_resources_unsupported_deployment_paused_reason_error: object` The deployment configures resources, but its environment is self-hosted and cannot mount them. - `type: "self_hosted_resources_unsupported_error"` - `beta_managed_agents_mcp_egress_blocked_deployment_paused_reason_error: object` An MCP server host used by the deployment's agent is blocked by the environment's network policy. - `type: "mcp_egress_blocked_error"` - `resources: array of BetaManagedAgentsSessionResourceConfig` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `beta_managed_agents_github_repository_resource_config: object` A GitHub repository mounted into each session's container. The authorization token is write-only and never returned. - `type: "github_repository"` - `url: string` Github URL of the repository - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` Branch or commit to check out. Defaults to the repository's default branch. - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `mount_path: optional string` Mount path in the container. Defaults to `/workspace/`. - `beta_managed_agents_file_resource_config: object` A file mounted into each session's container. - `type: "file"` - `file_id: string` ID of a previously uploaded file. - `mount_path: optional string` Mount path in the container. Defaults to `/mnt/session/uploads/`. - `beta_managed_agents_memory_store_resource_config: object` A memory store attached to each session created from this deployment. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `schedule: object` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `type: "cron"` - `expression: string` 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). minLength: 1, maxLength: 256 - `timezone: string` IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). minLength: 1 - `last_run_at: optional string` Time the most recent scheduled run actually started. Null until one completes; preserved after the deployment is archived. Manual runs do not update this. format: date-time - `upcoming_runs_at: optional array of string` 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. - `status: "active" or "paused"` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `"active"` The deployment is active and can run sessions. Archived deployments also report this status; check `archived_at` to distinguish them. - `"paused"` The deployment is paused. Autonomous triggers are suppressed; manual runs are still permitted. - `updated_at: string` Time the deployment was last updated. format: date-time - `vault_ids: array of string` Vault IDs supplying stored credentials for sessions created from this deployment. - `budget: optional object` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. #### Example ```bash ant beta:deployments update \ --api-key my-anthropic-api-key \ --deployment-id depl_011CZkZcDH3vPqd7xnEfwTai ``` ##### Response (200) ```json { "id": "depl_011CZkZcDH3vPqd7xnEfwTai", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "Compiles yesterday's orders into a report every weekday morning.", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "initial_events": [ { "content": [ { "text": "Compile yesterday's orders into report.md.", "type": "text" } ], "type": "user.message" } ], "metadata": {}, "name": "Daily order report", "paused_reason": { "type": "manual" }, "resources": [ { "type": "github_repository", "url": "url", "checkout": { "name": "main", "type": "branch" }, "mount_path": "mount_path" } ], "schedule": { "expression": "0 9 * * 1-5", "timezone": "America/Los_Angeles", "type": "cron", "last_run_at": "2026-03-16T16:00:09Z", "upcoming_runs_at": [ "2026-03-17T16:00:00Z", "2026-03-18T16:00:00Z" ] }, "status": "active", "type": "deployment", "updated_at": "2026-03-15T10:00:00Z", "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" } } ``` ### Archive Deployment `$ ant beta:deployments archive` **POST** `/v1/deployments/{deployment_id}/archive` Archive Deployment #### Parameters - `--deployment-id: string` (path parameter) Unique identifier of the deployment to archive. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deployment: object` 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. - `type: "deployment"` - `id: string` Unique identifier for this deployment. - `agent: object` Reference to the agent this deployment runs, resolved to a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `archived_at: string` Time the deployment was archived. Null if not archived. format: date-time - `created_at: string` Time the deployment was created. format: date-time - `description: string` Description of what the deployment does. - `environment_id: string` ID of the `environment` where sessions run. - `initial_events: array of BetaManagedAgentsDeploymentInitialEvent` Events sent to each session immediately after creation. - `beta_managed_agents_deployment_user_message_event: object` A user message sent to the session. - `type: "user.message"` - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks for the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `beta_managed_agents_deployment_user_define_outcome_event: object` An outcome the agent should work toward. The agent begins work on receipt. - `type: "user.define_outcome"` - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. Text or file reference. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `max_iterations: optional number` Eval→revision cycles before giving up. Default 3, max 20. format: int32 - `beta_managed_agents_deployment_system_message_event: object` 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. - `type: "system.message"` - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks to append. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs. - `name: string` Human-readable name. - `paused_reason: BetaManagedAgentsManualDeploymentPausedReason or BetaManagedAgentsErrorDeploymentPausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `beta_managed_agents_manual_deployment_paused_reason: object` The caller invoked the pause endpoint on the deployment. - `type: "manual"` - `beta_managed_agents_error_deployment_paused_reason: object` A scheduled fire recorded a failed run whose error auto-pauses the deployment. - `type: "error"` - `error: BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError or BetaManagedAgentsAgentArchivedDeploymentPausedReasonError or BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError or 11 more` The failed run's error. - `beta_managed_agents_environment_archived_deployment_paused_reason_error: object` The deployment's environment was archived. - `type: "environment_archived_error"` - `beta_managed_agents_agent_archived_deployment_paused_reason_error: object` The deployment's agent was archived. - `type: "agent_archived_error"` - `beta_managed_agents_environment_not_found_deployment_paused_reason_error: object` The deployment's environment no longer exists. - `type: "environment_not_found_error"` - `beta_managed_agents_vault_not_found_deployment_paused_reason_error: object` A vault referenced by the deployment no longer exists. - `type: "vault_not_found_error"` - `beta_managed_agents_file_not_found_deployment_paused_reason_error: object` A file resource referenced by the deployment no longer exists. - `type: "file_not_found_error"` - `beta_managed_agents_session_resource_not_found_deployment_paused_reason_error: object` A referenced resource no longer exists and its kind was not reported. - `type: "session_resource_not_found_error"` - `beta_managed_agents_workspace_archived_deployment_paused_reason_error: object` The deployment's workspace was archived. - `type: "workspace_archived_error"` - `beta_managed_agents_organization_disabled_deployment_paused_reason_error: object` The deployment's organization is disabled. - `type: "organization_disabled_error"` - `beta_managed_agents_memory_store_archived_deployment_paused_reason_error: object` A memory store referenced by the deployment is archived. - `type: "memory_store_archived_error"` - `beta_managed_agents_skill_not_found_deployment_paused_reason_error: object` A skill referenced by the deployment's agent no longer exists. - `type: "skill_not_found_error"` - `beta_managed_agents_vault_archived_deployment_paused_reason_error: object` A vault referenced by the deployment is archived. - `type: "vault_archived_error"` - `beta_managed_agents_unknown_deployment_paused_reason_error: object` An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`. - `type: "unknown_error"` - `beta_managed_agents_self_hosted_resources_unsupported_deployment_paused_reason_error: object` The deployment configures resources, but its environment is self-hosted and cannot mount them. - `type: "self_hosted_resources_unsupported_error"` - `beta_managed_agents_mcp_egress_blocked_deployment_paused_reason_error: object` An MCP server host used by the deployment's agent is blocked by the environment's network policy. - `type: "mcp_egress_blocked_error"` - `resources: array of BetaManagedAgentsSessionResourceConfig` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `beta_managed_agents_github_repository_resource_config: object` A GitHub repository mounted into each session's container. The authorization token is write-only and never returned. - `type: "github_repository"` - `url: string` Github URL of the repository - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` Branch or commit to check out. Defaults to the repository's default branch. - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `mount_path: optional string` Mount path in the container. Defaults to `/workspace/`. - `beta_managed_agents_file_resource_config: object` A file mounted into each session's container. - `type: "file"` - `file_id: string` ID of a previously uploaded file. - `mount_path: optional string` Mount path in the container. Defaults to `/mnt/session/uploads/`. - `beta_managed_agents_memory_store_resource_config: object` A memory store attached to each session created from this deployment. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `schedule: object` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `type: "cron"` - `expression: string` 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). minLength: 1, maxLength: 256 - `timezone: string` IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). minLength: 1 - `last_run_at: optional string` Time the most recent scheduled run actually started. Null until one completes; preserved after the deployment is archived. Manual runs do not update this. format: date-time - `upcoming_runs_at: optional array of string` 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. - `status: "active" or "paused"` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `"active"` The deployment is active and can run sessions. Archived deployments also report this status; check `archived_at` to distinguish them. - `"paused"` The deployment is paused. Autonomous triggers are suppressed; manual runs are still permitted. - `updated_at: string` Time the deployment was last updated. format: date-time - `vault_ids: array of string` Vault IDs supplying stored credentials for sessions created from this deployment. - `budget: optional object` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. #### Example ```bash ant beta:deployments archive \ --api-key my-anthropic-api-key \ --deployment-id depl_011CZkZcDH3vPqd7xnEfwTai ``` ##### Response (200) ```json { "id": "depl_011CZkZcDH3vPqd7xnEfwTai", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "Compiles yesterday's orders into a report every weekday morning.", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "initial_events": [ { "content": [ { "text": "Compile yesterday's orders into report.md.", "type": "text" } ], "type": "user.message" } ], "metadata": {}, "name": "Daily order report", "paused_reason": { "type": "manual" }, "resources": [ { "type": "github_repository", "url": "url", "checkout": { "name": "main", "type": "branch" }, "mount_path": "mount_path" } ], "schedule": { "expression": "0 9 * * 1-5", "timezone": "America/Los_Angeles", "type": "cron", "last_run_at": "2026-03-16T16:00:09Z", "upcoming_runs_at": [ "2026-03-17T16:00:00Z", "2026-03-18T16:00:00Z" ] }, "status": "active", "type": "deployment", "updated_at": "2026-03-15T10:00:00Z", "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" } } ``` ### Run Deployment Now `$ ant beta:deployments run` **POST** `/v1/deployments/{deployment_id}/run` Run Deployment Now #### Parameters - `--deployment-id: string` (path parameter) Unique identifier of the deployment to run. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deployment_run: object` A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking. - `type: "deployment_run"` - `id: string` Unique identifier for this run (`drun_...`). - `agent: object` Snapshot of the agent at fire time. Always fully resolved — deployments pin agent + version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `created_at: string` Time this run record was persisted. format: date-time - `deployment_id: string` ID of the deployment that produced this run. - `error: BetaManagedAgentsEnvironmentArchivedRunError or BetaManagedAgentsAgentArchivedRunError or BetaManagedAgentsEnvironmentNotFoundRunError or 13 more` Populated on creation failure. Null on success. Exactly one of `session_id` or `error` is non-null. - `beta_managed_agents_environment_archived_run_error: object` The deployment's environment was archived. - `type: "environment_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_agent_archived_run_error: object` The deployment's agent was archived. - `type: "agent_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_environment_not_found_run_error: object` The deployment's environment no longer exists. - `type: "environment_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_vault_not_found_run_error: object` A vault referenced by the deployment no longer exists. - `type: "vault_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_vault_archived_run_error: object` A vault referenced by the deployment is archived. - `type: "vault_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_file_not_found_run_error: object` A file resource referenced by the deployment no longer exists. - `type: "file_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_memory_store_archived_run_error: object` A memory store referenced by the deployment is archived. - `type: "memory_store_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_skill_not_found_run_error: object` A skill referenced by the deployment's agent no longer exists. - `type: "skill_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_session_resource_not_found_run_error: object` A referenced resource no longer exists and its kind was not reported. - `type: "session_resource_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_workspace_archived_run_error: object` The deployment's workspace was archived. - `type: "workspace_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_organization_disabled_run_error: object` The deployment's organization is disabled. - `type: "organization_disabled_error"` - `message: string` Human-readable error description. - `beta_managed_agents_session_rate_limited_run_error: object` Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed. - `type: "session_rate_limited_error"` - `message: string` Human-readable error description. - `beta_managed_agents_session_creation_rejected_run_error: object` The session create request was rejected with a non-retryable validation error. - `type: "session_creation_rejected_error"` - `message: string` Human-readable error description. - `beta_managed_agents_unknown_run_error: object` 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. - `type: "unknown_error"` - `message: string` Human-readable error description. - `beta_managed_agents_self_hosted_resources_unsupported_run_error: object` The deployment configures resources, but its environment is self-hosted and cannot mount them. - `type: "self_hosted_resources_unsupported_error"` - `message: string` Human-readable error description. - `beta_managed_agents_mcp_egress_blocked_run_error: object` An MCP server host used by the deployment's agent is blocked by the environment's network policy. - `type: "mcp_egress_blocked_error"` - `message: string` Human-readable error description. - `session_id: string` Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null. - `trigger_context: BetaManagedAgentsScheduleTriggerContext or BetaManagedAgentsManualTriggerContext` What triggered this run and trigger-specific metadata. - `beta_managed_agents_schedule_trigger_context: object` The run was fired by the deployment's cron schedule. - `type: "schedule"` - `scheduled_at: string` The UTC instant at which the cron expression matched in the configured timezone, before jitter is applied. At most one run is recorded per (`deployment_id`, `scheduled_at`) pair. format: date-time - `beta_managed_agents_manual_trigger_context: object` The run was started manually by creating a session directly against the deployment. - `type: "manual"` #### Example ```bash ant beta:deployments run \ --api-key my-anthropic-api-key \ --deployment-id depl_011CZkZcDH3vPqd7xnEfwTai ``` ##### Response (200) ```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 `$ ant beta:deployments pause` **POST** `/v1/deployments/{deployment_id}/pause` Pause Deployment #### Parameters - `--deployment-id: string` (path parameter) Unique identifier of the deployment to pause. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deployment: object` 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. - `type: "deployment"` - `id: string` Unique identifier for this deployment. - `agent: object` Reference to the agent this deployment runs, resolved to a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `archived_at: string` Time the deployment was archived. Null if not archived. format: date-time - `created_at: string` Time the deployment was created. format: date-time - `description: string` Description of what the deployment does. - `environment_id: string` ID of the `environment` where sessions run. - `initial_events: array of BetaManagedAgentsDeploymentInitialEvent` Events sent to each session immediately after creation. - `beta_managed_agents_deployment_user_message_event: object` A user message sent to the session. - `type: "user.message"` - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks for the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `beta_managed_agents_deployment_user_define_outcome_event: object` An outcome the agent should work toward. The agent begins work on receipt. - `type: "user.define_outcome"` - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. Text or file reference. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `max_iterations: optional number` Eval→revision cycles before giving up. Default 3, max 20. format: int32 - `beta_managed_agents_deployment_system_message_event: object` 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. - `type: "system.message"` - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks to append. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs. - `name: string` Human-readable name. - `paused_reason: BetaManagedAgentsManualDeploymentPausedReason or BetaManagedAgentsErrorDeploymentPausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `beta_managed_agents_manual_deployment_paused_reason: object` The caller invoked the pause endpoint on the deployment. - `type: "manual"` - `beta_managed_agents_error_deployment_paused_reason: object` A scheduled fire recorded a failed run whose error auto-pauses the deployment. - `type: "error"` - `error: BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError or BetaManagedAgentsAgentArchivedDeploymentPausedReasonError or BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError or 11 more` The failed run's error. - `beta_managed_agents_environment_archived_deployment_paused_reason_error: object` The deployment's environment was archived. - `type: "environment_archived_error"` - `beta_managed_agents_agent_archived_deployment_paused_reason_error: object` The deployment's agent was archived. - `type: "agent_archived_error"` - `beta_managed_agents_environment_not_found_deployment_paused_reason_error: object` The deployment's environment no longer exists. - `type: "environment_not_found_error"` - `beta_managed_agents_vault_not_found_deployment_paused_reason_error: object` A vault referenced by the deployment no longer exists. - `type: "vault_not_found_error"` - `beta_managed_agents_file_not_found_deployment_paused_reason_error: object` A file resource referenced by the deployment no longer exists. - `type: "file_not_found_error"` - `beta_managed_agents_session_resource_not_found_deployment_paused_reason_error: object` A referenced resource no longer exists and its kind was not reported. - `type: "session_resource_not_found_error"` - `beta_managed_agents_workspace_archived_deployment_paused_reason_error: object` The deployment's workspace was archived. - `type: "workspace_archived_error"` - `beta_managed_agents_organization_disabled_deployment_paused_reason_error: object` The deployment's organization is disabled. - `type: "organization_disabled_error"` - `beta_managed_agents_memory_store_archived_deployment_paused_reason_error: object` A memory store referenced by the deployment is archived. - `type: "memory_store_archived_error"` - `beta_managed_agents_skill_not_found_deployment_paused_reason_error: object` A skill referenced by the deployment's agent no longer exists. - `type: "skill_not_found_error"` - `beta_managed_agents_vault_archived_deployment_paused_reason_error: object` A vault referenced by the deployment is archived. - `type: "vault_archived_error"` - `beta_managed_agents_unknown_deployment_paused_reason_error: object` An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`. - `type: "unknown_error"` - `beta_managed_agents_self_hosted_resources_unsupported_deployment_paused_reason_error: object` The deployment configures resources, but its environment is self-hosted and cannot mount them. - `type: "self_hosted_resources_unsupported_error"` - `beta_managed_agents_mcp_egress_blocked_deployment_paused_reason_error: object` An MCP server host used by the deployment's agent is blocked by the environment's network policy. - `type: "mcp_egress_blocked_error"` - `resources: array of BetaManagedAgentsSessionResourceConfig` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `beta_managed_agents_github_repository_resource_config: object` A GitHub repository mounted into each session's container. The authorization token is write-only and never returned. - `type: "github_repository"` - `url: string` Github URL of the repository - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` Branch or commit to check out. Defaults to the repository's default branch. - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `mount_path: optional string` Mount path in the container. Defaults to `/workspace/`. - `beta_managed_agents_file_resource_config: object` A file mounted into each session's container. - `type: "file"` - `file_id: string` ID of a previously uploaded file. - `mount_path: optional string` Mount path in the container. Defaults to `/mnt/session/uploads/`. - `beta_managed_agents_memory_store_resource_config: object` A memory store attached to each session created from this deployment. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `schedule: object` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `type: "cron"` - `expression: string` 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). minLength: 1, maxLength: 256 - `timezone: string` IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). minLength: 1 - `last_run_at: optional string` Time the most recent scheduled run actually started. Null until one completes; preserved after the deployment is archived. Manual runs do not update this. format: date-time - `upcoming_runs_at: optional array of string` 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. - `status: "active" or "paused"` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `"active"` The deployment is active and can run sessions. Archived deployments also report this status; check `archived_at` to distinguish them. - `"paused"` The deployment is paused. Autonomous triggers are suppressed; manual runs are still permitted. - `updated_at: string` Time the deployment was last updated. format: date-time - `vault_ids: array of string` Vault IDs supplying stored credentials for sessions created from this deployment. - `budget: optional object` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. #### Example ```bash ant beta:deployments pause \ --api-key my-anthropic-api-key \ --deployment-id depl_011CZkZcDH3vPqd7xnEfwTai ``` ##### Response (200) ```json { "id": "depl_011CZkZcDH3vPqd7xnEfwTai", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "Compiles yesterday's orders into a report every weekday morning.", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "initial_events": [ { "content": [ { "text": "Compile yesterday's orders into report.md.", "type": "text" } ], "type": "user.message" } ], "metadata": {}, "name": "Daily order report", "paused_reason": { "type": "manual" }, "resources": [ { "type": "github_repository", "url": "url", "checkout": { "name": "main", "type": "branch" }, "mount_path": "mount_path" } ], "schedule": { "expression": "0 9 * * 1-5", "timezone": "America/Los_Angeles", "type": "cron", "last_run_at": "2026-03-16T16:00:09Z", "upcoming_runs_at": [ "2026-03-17T16:00:00Z", "2026-03-18T16:00:00Z" ] }, "status": "active", "type": "deployment", "updated_at": "2026-03-15T10:00:00Z", "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" } } ``` ### Unpause Deployment `$ ant beta:deployments unpause` **POST** `/v1/deployments/{deployment_id}/unpause` Unpause Deployment #### Parameters - `--deployment-id: string` (path parameter) Unique identifier of the deployment to unpause. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deployment: object` 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. - `type: "deployment"` - `id: string` Unique identifier for this deployment. - `agent: object` Reference to the agent this deployment runs, resolved to a concrete version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `archived_at: string` Time the deployment was archived. Null if not archived. format: date-time - `created_at: string` Time the deployment was created. format: date-time - `description: string` Description of what the deployment does. - `environment_id: string` ID of the `environment` where sessions run. - `initial_events: array of BetaManagedAgentsDeploymentInitialEvent` Events sent to each session immediately after creation. - `beta_managed_agents_deployment_user_message_event: object` A user message sent to the session. - `type: "user.message"` - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock` Array of content blocks for the user message. - `beta_managed_agents_text_block: object` Regular text content. - `type: "text"` - `text: string` The text content. minLength: 1 - `beta_managed_agents_image_block: object` Image content specified directly as base64 data or as a reference via a URL. - `type: "image"` - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource` The source of the image data. - `beta_managed_agents_base64_image_source: object` Base64-encoded image data. - `type: "base64"` - `data: string` Base64-encoded image data. minLength: 1 - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). minLength: 1 - `beta_managed_agents_url_image_source: object` Image referenced by URL. - `type: "url"` - `url: string` URL of the image to fetch. minLength: 1 - `beta_managed_agents_file_image_source: object` Image referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `beta_managed_agents_document_block: object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `type: "document"` - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource` The source of the document data. - `beta_managed_agents_base64_document_source: object` Base64-encoded document data. - `type: "base64"` - `data: string` Base64-encoded document data. minLength: 1 - `media_type: string` MIME type of the document (e.g., "application/pdf"). minLength: 1 - `beta_managed_agents_plain_text_document_source: object` Plain text document content. - `type: "text"` - `data: string` The plain text content. minLength: 1 - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `beta_managed_agents_url_document_source: object` Document referenced by URL. - `type: "url"` - `url: string` URL of the document to fetch. minLength: 1 - `beta_managed_agents_file_document_source: object` Document referenced by file ID. - `type: "file"` - `file_id: string` ID of a previously uploaded file. minLength: 1 - `context: optional string` Additional context about the document for the model. - `title: optional string` The title of the document. - `beta_managed_agents_redacted_block: object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - `beta_managed_agents_deployment_user_define_outcome_event: object` An outcome the agent should work toward. The agent begins work on receipt. - `type: "user.define_outcome"` - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` How to grade the outcome. Text or file reference. - `beta_managed_agents_file_rubric: object` Rubric referenced by a file uploaded via the Files API. - `type: "file"` - `file_id: string` ID of the rubric file. - `beta_managed_agents_text_rubric: object` Rubric content provided inline as text. - `type: "text"` - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `max_iterations: optional number` Eval→revision cycles before giving up. Default 3, max 20. format: int32 - `beta_managed_agents_deployment_system_message_event: object` 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. - `type: "system.message"` - `content: array of BetaManagedAgentsSystemContentBlock` System content blocks to append. Text-only. - `type: "text"` - `text: string` The text content. minLength: 1 - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs. - `name: string` Human-readable name. - `paused_reason: BetaManagedAgentsManualDeploymentPausedReason or BetaManagedAgentsErrorDeploymentPausedReason` Why the deployment is `paused`. Non-null exactly when `status` is `paused`; null otherwise. - `beta_managed_agents_manual_deployment_paused_reason: object` The caller invoked the pause endpoint on the deployment. - `type: "manual"` - `beta_managed_agents_error_deployment_paused_reason: object` A scheduled fire recorded a failed run whose error auto-pauses the deployment. - `type: "error"` - `error: BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError or BetaManagedAgentsAgentArchivedDeploymentPausedReasonError or BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError or 11 more` The failed run's error. - `beta_managed_agents_environment_archived_deployment_paused_reason_error: object` The deployment's environment was archived. - `type: "environment_archived_error"` - `beta_managed_agents_agent_archived_deployment_paused_reason_error: object` The deployment's agent was archived. - `type: "agent_archived_error"` - `beta_managed_agents_environment_not_found_deployment_paused_reason_error: object` The deployment's environment no longer exists. - `type: "environment_not_found_error"` - `beta_managed_agents_vault_not_found_deployment_paused_reason_error: object` A vault referenced by the deployment no longer exists. - `type: "vault_not_found_error"` - `beta_managed_agents_file_not_found_deployment_paused_reason_error: object` A file resource referenced by the deployment no longer exists. - `type: "file_not_found_error"` - `beta_managed_agents_session_resource_not_found_deployment_paused_reason_error: object` A referenced resource no longer exists and its kind was not reported. - `type: "session_resource_not_found_error"` - `beta_managed_agents_workspace_archived_deployment_paused_reason_error: object` The deployment's workspace was archived. - `type: "workspace_archived_error"` - `beta_managed_agents_organization_disabled_deployment_paused_reason_error: object` The deployment's organization is disabled. - `type: "organization_disabled_error"` - `beta_managed_agents_memory_store_archived_deployment_paused_reason_error: object` A memory store referenced by the deployment is archived. - `type: "memory_store_archived_error"` - `beta_managed_agents_skill_not_found_deployment_paused_reason_error: object` A skill referenced by the deployment's agent no longer exists. - `type: "skill_not_found_error"` - `beta_managed_agents_vault_archived_deployment_paused_reason_error: object` A vault referenced by the deployment is archived. - `type: "vault_archived_error"` - `beta_managed_agents_unknown_deployment_paused_reason_error: object` An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`. - `type: "unknown_error"` - `beta_managed_agents_self_hosted_resources_unsupported_deployment_paused_reason_error: object` The deployment configures resources, but its environment is self-hosted and cannot mount them. - `type: "self_hosted_resources_unsupported_error"` - `beta_managed_agents_mcp_egress_blocked_deployment_paused_reason_error: object` An MCP server host used by the deployment's agent is blocked by the environment's network policy. - `type: "mcp_egress_blocked_error"` - `resources: array of BetaManagedAgentsSessionResourceConfig` Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials. - `beta_managed_agents_github_repository_resource_config: object` A GitHub repository mounted into each session's container. The authorization token is write-only and never returned. - `type: "github_repository"` - `url: string` Github URL of the repository - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout` Branch or commit to check out. Defaults to the repository's default branch. - `beta_managed_agents_branch_checkout: object` - `type: "branch"` - `name: string` Branch name to check out. minLength: 1, maxLength: 255 - `beta_managed_agents_commit_checkout: object` - `type: "commit"` - `sha: string` Full commit SHA to check out. minLength: 7, maxLength: 64 - `mount_path: optional string` Mount path in the container. Defaults to `/workspace/`. - `beta_managed_agents_file_resource_config: object` A file mounted into each session's container. - `type: "file"` - `file_id: string` ID of a previously uploaded file. - `mount_path: optional string` Mount path in the container. Defaults to `/mnt/session/uploads/`. - `beta_managed_agents_memory_store_resource_config: object` A memory store attached to each session created from this deployment. - `type: "memory_store"` - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `access: optional "read_write" or "read_only"` Access mode for the mounted store. Defaults to `read_write`. `read_only` mounts the store as a read-only filesystem. - `"read_write"` - `"read_only"` - `instructions: optional string` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `schedule: object` Recurring cron schedule. Presence enables scheduled execution; null means manual-only. Includes computed timestamps (next fire times, last run) on the cron variant. - `type: "cron"` - `expression: string` 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). minLength: 1, maxLength: 256 - `timezone: string` IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). minLength: 1 - `last_run_at: optional string` Time the most recent scheduled run actually started. Null until one completes; preserved after the deployment is archived. Manual runs do not update this. format: date-time - `upcoming_runs_at: optional array of string` 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. - `status: "active" or "paused"` Computed status of the deployment: `active` or `paused`. Archived deployments report `active` with `archived_at` set. - `"active"` The deployment is active and can run sessions. Archived deployments also report this status; check `archived_at` to distinguish them. - `"paused"` The deployment is paused. Autonomous triggers are suppressed; manual runs are still permitted. - `updated_at: string` Time the deployment was last updated. format: date-time - `vault_ids: array of string` Vault IDs supplying stored credentials for sessions created from this deployment. - `budget: optional object` Spend ceiling stamped onto each session created from this deployment. Absent when no budget is set. - `type: "limit"` - `max_list_cost: object` Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge. - `amount: string` Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied. - `currency: "USD"` Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. #### Example ```bash ant beta:deployments unpause \ --api-key my-anthropic-api-key \ --deployment-id depl_011CZkZcDH3vPqd7xnEfwTai ``` ##### Response (200) ```json { "id": "depl_011CZkZcDH3vPqd7xnEfwTai", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "Compiles yesterday's orders into a report every weekday morning.", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "initial_events": [ { "content": [ { "text": "Compile yesterday's orders into report.md.", "type": "text" } ], "type": "user.message" } ], "metadata": {}, "name": "Daily order report", "paused_reason": { "type": "manual" }, "resources": [ { "type": "github_repository", "url": "url", "checkout": { "name": "main", "type": "branch" }, "mount_path": "mount_path" } ], "schedule": { "expression": "0 9 * * 1-5", "timezone": "America/Los_Angeles", "type": "cron", "last_run_at": "2026-03-16T16:00:09Z", "upcoming_runs_at": [ "2026-03-17T16:00:00Z", "2026-03-18T16:00:00Z" ] }, "status": "active", "type": "deployment", "updated_at": "2026-03-15T10:00:00Z", "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ], "budget": { "max_list_cost": { "amount": "2500", "currency": "USD" }, "type": "limit" } } ``` ## Beta › Deployment Runs ### List Deployment Runs `$ ant beta:deployment-runs list` **GET** `/v1/deployment_runs` List Deployment Runs #### Parameters - `--created-at-gt: optional string` (query parameter) Return runs created strictly after this time (exclusive). format: date-time - `--created-at-gte: optional string` (query parameter) Return runs created at or after this time (inclusive). format: date-time - `--created-at-lt: optional string` (query parameter) Return runs created strictly before this time (exclusive). format: date-time - `--created-at-lte: optional string` (query parameter) Return runs created at or before this time (inclusive). format: date-time - `--deployment-id: optional string` (query parameter) 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. - `--has-error: optional boolean` (query parameter) Filter: true for runs with non-null `error`, false for runs with non-null `session_id`. Omit for all. - `--limit: optional number` (query parameter) Maximum results per page. Default 20, maximum 1000. format: int32 - `--page: optional string` (query parameter) Opaque pagination cursor. Pass `next_page` from the previous response. Invalid or expired cursors return 400. - `--trigger-type: optional "schedule" or "manual"` (query parameter) Filter runs by what triggered them. Omit to return all runs. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListDeploymentRunsData: object` Paginated list of deployment runs. Sorted by `created_at` descending (most recent first). - `data: array of BetaManagedAgentsDeploymentRun` List of deployment runs. - `type: "deployment_run"` - `id: string` Unique identifier for this run (`drun_...`). - `agent: object` Snapshot of the agent at fire time. Always fully resolved — deployments pin agent + version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `created_at: string` Time this run record was persisted. format: date-time - `deployment_id: string` ID of the deployment that produced this run. - `error: BetaManagedAgentsEnvironmentArchivedRunError or BetaManagedAgentsAgentArchivedRunError or BetaManagedAgentsEnvironmentNotFoundRunError or 13 more` Populated on creation failure. Null on success. Exactly one of `session_id` or `error` is non-null. - `beta_managed_agents_environment_archived_run_error: object` The deployment's environment was archived. - `type: "environment_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_agent_archived_run_error: object` The deployment's agent was archived. - `type: "agent_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_environment_not_found_run_error: object` The deployment's environment no longer exists. - `type: "environment_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_vault_not_found_run_error: object` A vault referenced by the deployment no longer exists. - `type: "vault_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_vault_archived_run_error: object` A vault referenced by the deployment is archived. - `type: "vault_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_file_not_found_run_error: object` A file resource referenced by the deployment no longer exists. - `type: "file_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_memory_store_archived_run_error: object` A memory store referenced by the deployment is archived. - `type: "memory_store_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_skill_not_found_run_error: object` A skill referenced by the deployment's agent no longer exists. - `type: "skill_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_session_resource_not_found_run_error: object` A referenced resource no longer exists and its kind was not reported. - `type: "session_resource_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_workspace_archived_run_error: object` The deployment's workspace was archived. - `type: "workspace_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_organization_disabled_run_error: object` The deployment's organization is disabled. - `type: "organization_disabled_error"` - `message: string` Human-readable error description. - `beta_managed_agents_session_rate_limited_run_error: object` Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed. - `type: "session_rate_limited_error"` - `message: string` Human-readable error description. - `beta_managed_agents_session_creation_rejected_run_error: object` The session create request was rejected with a non-retryable validation error. - `type: "session_creation_rejected_error"` - `message: string` Human-readable error description. - `beta_managed_agents_unknown_run_error: object` 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. - `type: "unknown_error"` - `message: string` Human-readable error description. - `beta_managed_agents_self_hosted_resources_unsupported_run_error: object` The deployment configures resources, but its environment is self-hosted and cannot mount them. - `type: "self_hosted_resources_unsupported_error"` - `message: string` Human-readable error description. - `beta_managed_agents_mcp_egress_blocked_run_error: object` An MCP server host used by the deployment's agent is blocked by the environment's network policy. - `type: "mcp_egress_blocked_error"` - `message: string` Human-readable error description. - `session_id: string` Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null. - `trigger_context: BetaManagedAgentsScheduleTriggerContext or BetaManagedAgentsManualTriggerContext` What triggered this run and trigger-specific metadata. - `beta_managed_agents_schedule_trigger_context: object` The run was fired by the deployment's cron schedule. - `type: "schedule"` - `scheduled_at: string` The UTC instant at which the cron expression matched in the configured timezone, before jitter is applied. At most one run is recorded per (`deployment_id`, `scheduled_at`) pair. format: date-time - `beta_managed_agents_manual_trigger_context: object` The run was started manually by creating a session directly against the deployment. - `type: "manual"` - `next_page: optional string` Opaque cursor for the next page. Null when no more results. #### Example ```bash ant beta:deployment-runs list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```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 `$ ant beta:deployment-runs retrieve` **GET** `/v1/deployment_runs/{deployment_run_id}` Get Deployment Run #### Parameters - `--deployment-run-id: string` (path parameter) Unique identifier of the deployment run. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deployment_run: object` A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking. - `type: "deployment_run"` - `id: string` Unique identifier for this run (`drun_...`). - `agent: object` Snapshot of the agent at fire time. Always fully resolved — deployments pin agent + version. - `type: "agent"` - `id: string` - `version: number` format: int32 - `created_at: string` Time this run record was persisted. format: date-time - `deployment_id: string` ID of the deployment that produced this run. - `error: BetaManagedAgentsEnvironmentArchivedRunError or BetaManagedAgentsAgentArchivedRunError or BetaManagedAgentsEnvironmentNotFoundRunError or 13 more` Populated on creation failure. Null on success. Exactly one of `session_id` or `error` is non-null. - `beta_managed_agents_environment_archived_run_error: object` The deployment's environment was archived. - `type: "environment_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_agent_archived_run_error: object` The deployment's agent was archived. - `type: "agent_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_environment_not_found_run_error: object` The deployment's environment no longer exists. - `type: "environment_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_vault_not_found_run_error: object` A vault referenced by the deployment no longer exists. - `type: "vault_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_vault_archived_run_error: object` A vault referenced by the deployment is archived. - `type: "vault_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_file_not_found_run_error: object` A file resource referenced by the deployment no longer exists. - `type: "file_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_memory_store_archived_run_error: object` A memory store referenced by the deployment is archived. - `type: "memory_store_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_skill_not_found_run_error: object` A skill referenced by the deployment's agent no longer exists. - `type: "skill_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_session_resource_not_found_run_error: object` A referenced resource no longer exists and its kind was not reported. - `type: "session_resource_not_found_error"` - `message: string` Human-readable error description. - `beta_managed_agents_workspace_archived_run_error: object` The deployment's workspace was archived. - `type: "workspace_archived_error"` - `message: string` Human-readable error description. - `beta_managed_agents_organization_disabled_run_error: object` The deployment's organization is disabled. - `type: "organization_disabled_error"` - `message: string` Human-readable error description. - `beta_managed_agents_session_rate_limited_run_error: object` Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed. - `type: "session_rate_limited_error"` - `message: string` Human-readable error description. - `beta_managed_agents_session_creation_rejected_run_error: object` The session create request was rejected with a non-retryable validation error. - `type: "session_creation_rejected_error"` - `message: string` Human-readable error description. - `beta_managed_agents_unknown_run_error: object` 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. - `type: "unknown_error"` - `message: string` Human-readable error description. - `beta_managed_agents_self_hosted_resources_unsupported_run_error: object` The deployment configures resources, but its environment is self-hosted and cannot mount them. - `type: "self_hosted_resources_unsupported_error"` - `message: string` Human-readable error description. - `beta_managed_agents_mcp_egress_blocked_run_error: object` An MCP server host used by the deployment's agent is blocked by the environment's network policy. - `type: "mcp_egress_blocked_error"` - `message: string` Human-readable error description. - `session_id: string` Populated on success. Null on creation failure. Exactly one of `session_id` or `error` is non-null. - `trigger_context: BetaManagedAgentsScheduleTriggerContext or BetaManagedAgentsManualTriggerContext` What triggered this run and trigger-specific metadata. - `beta_managed_agents_schedule_trigger_context: object` The run was fired by the deployment's cron schedule. - `type: "schedule"` - `scheduled_at: string` The UTC instant at which the cron expression matched in the configured timezone, before jitter is applied. At most one run is recorded per (`deployment_id`, `scheduled_at`) pair. format: date-time - `beta_managed_agents_manual_trigger_context: object` The run was started manually by creating a session directly against the deployment. - `type: "manual"` #### Example ```bash ant beta:deployment-runs retrieve \ --api-key my-anthropic-api-key \ --deployment-run-id deployment_run_id ``` ##### Response (200) ```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" } ``` ## Beta › Vaults ### Create a Vault `$ ant beta:vaults create` **POST** `/v1/vaults` Create a Vault #### Parameters - `--display-name: string` Human-readable name for the vault. 1-255 characters. minLength: 1, maxLength: 255 - `--metadata: optional map[string]` Arbitrary key-value metadata to attach to the vault. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_vault: object` A vault that stores credentials for use by agents during sessions. - `type: "vault"` - `id: string` The unique ID of the vault (`vlt_...`). - `archived_at: string` When the vault was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `display_name: string` Human-readable name for the vault. - `metadata: map[string]` Arbitrary key-value metadata attached to the vault. - `updated_at: string` A timestamp in RFC 3339 format format: date-time #### Example ```bash ant beta:vaults create \ --api-key my-anthropic-api-key \ --display-name 'Example vault' ``` ##### Response (200) ```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 `$ ant beta:vaults list` **GET** `/v1/vaults` List Vaults #### Parameters - `--include-archived: optional boolean` (query parameter) Whether to include archived vaults in the results. Defaults to `false`. - `--limit: optional number` (query parameter) Maximum number of vaults to return per page. Defaults to 20, maximum 100. format: int32 - `--page: optional string` (query parameter) The `next_page` value from a previous [List Vaults](https://platform.claude.com/docs/en/api/beta/vaults/list?sdk_languages=cli) response, to get the next page. Leave it out to get the first page. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListVaultsResponse: object` Response containing a paginated list of vaults. - `data: optional array of BetaManagedAgentsVault` The vaults on this page, newest first. - `type: "vault"` - `id: string` The unique ID of the vault (`vlt_...`). - `archived_at: string` When the vault was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `display_name: string` Human-readable name for the vault. - `metadata: map[string]` Arbitrary key-value metadata attached to the vault. - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `next_page: optional string` Pagination token for the next page, or null if no more results. #### Example ```bash ant beta:vaults list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```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=" } ``` ### Retrieve a Vault `$ ant beta:vaults retrieve` **GET** `/v1/vaults/{vault_id}` Retrieve a Vault #### Parameters - `--vault-id: string` (path parameter) Unique identifier of the vault to retrieve. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_vault: object` A vault that stores credentials for use by agents during sessions. - `type: "vault"` - `id: string` The unique ID of the vault (`vlt_...`). - `archived_at: string` When the vault was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `display_name: string` Human-readable name for the vault. - `metadata: map[string]` Arbitrary key-value metadata attached to the vault. - `updated_at: string` A timestamp in RFC 3339 format format: date-time #### Example ```bash ant beta:vaults retrieve \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv ``` ##### Response (200) ```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 a Vault `$ ant beta:vaults update` **POST** `/v1/vaults/{vault_id}` Update a Vault #### Parameters - `--vault-id: string` (path parameter) Unique identifier of the vault to update. - `--display-name: optional string` Updated human-readable name for the vault. 1-255 characters. minLength: 1, maxLength: 255 - `--metadata: optional map[string]` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_vault: object` A vault that stores credentials for use by agents during sessions. - `type: "vault"` - `id: string` The unique ID of the vault (`vlt_...`). - `archived_at: string` When the vault was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `display_name: string` Human-readable name for the vault. - `metadata: map[string]` Arbitrary key-value metadata attached to the vault. - `updated_at: string` A timestamp in RFC 3339 format format: date-time #### Example ```bash ant beta:vaults update \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv ``` ##### Response (200) ```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 a Vault `$ ant beta:vaults delete` **DELETE** `/v1/vaults/{vault_id}` Delete a Vault #### Parameters - `--vault-id: string` (path parameter) Unique identifier of the vault to delete. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deleted_vault: object` Confirmation of a deleted vault. - `type: "vault_deleted"` - `id: string` The unique ID of the deleted vault (`vlt_...`). #### Example ```bash ant beta:vaults delete \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv ``` ##### Response (200) ```json { "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "type": "vault_deleted" } ``` ### Archive a Vault `$ ant beta:vaults archive` **POST** `/v1/vaults/{vault_id}/archive` Archive a Vault #### Parameters - `--vault-id: string` (path parameter) Unique identifier of the vault to archive. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_vault: object` A vault that stores credentials for use by agents during sessions. - `type: "vault"` - `id: string` The unique ID of the vault (`vlt_...`). - `archived_at: string` When the vault was archived. Null if not archived. format: date-time - `created_at: string` A timestamp in RFC 3339 format format: date-time - `display_name: string` Human-readable name for the vault. - `metadata: map[string]` Arbitrary key-value metadata attached to the vault. - `updated_at: string` A timestamp in RFC 3339 format format: date-time #### Example ```bash ant beta:vaults archive \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv ``` ##### Response (200) ```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" } ``` ## Beta › Vaults › Credentials ### Create a Credential `$ ant beta:vaults:credentials create` **POST** `/v1/vaults/{vault_id}/credentials` Create a Credential #### Parameters - `--vault-id: string` (path parameter) Identifier of the vault to create the credential in. - `--auth: BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams or BetaManagedAgentsEnvironmentVariableCreateParams` Authentication configuration for the credential. - `--display-name: optional string` Human-readable name for the credential. Up to 255 characters. maxLength: 255 - `--metadata: optional map[string]` Arbitrary key-value metadata to attach to the credential. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_credential: object` A credential stored in a vault. Sensitive fields are never returned in responses. - `type: "vault_credential"` - `id: string` The unique ID of the credential (`vcrd_...`). - `archived_at: string` When the credential was archived. Null if not archived. format: date-time - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse or BetaManagedAgentsEnvironmentVariableAuthResponse` Authentication configuration for this credential. - `beta_managed_agents_mcp_oauth_auth_response: object` OAuth credential details for an MCP server. - `type: "mcp_oauth"` - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `expires_at: optional string` When the credential's access token expires, in RFC 3339. Absent if the expiry isn't known. format: date-time - `refresh: optional object` Refresh token configuration, if the credential supports token refresh. - `client_id: string` The OAuth client ID used when refreshing the access token. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` - `beta_managed_agents_token_endpoint_auth_none_response: object` Token endpoint requires no client authentication. - `type: "none"` - `beta_managed_agents_token_endpoint_auth_basic_response: object` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `beta_managed_agents_token_endpoint_auth_post_response: object` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `resource: optional string` OAuth resource indicator. - `scope: optional string` OAuth scope for the refresh request. - `beta_managed_agents_static_bearer_auth_response: object` Static bearer token credential details for an MCP server. - `type: "static_bearer"` - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `beta_managed_agents_environment_variable_auth_response: object` Environment variable credential details. The secret value is never returned. - `type: "environment_variable"` - `injection_location: object` Where in the outbound request the secret value is substituted. - `body: boolean` Whether the placeholder is substituted in the request body. - `header: boolean` Whether the placeholder is substituted in request header values. - `networking: BetaManagedAgentsUnrestrictedCredentialNetworkingResponse or BetaManagedAgentsLimitedCredentialNetworkingResponse` Outbound hosts the secret value is substituted on. - `beta_managed_agents_unrestricted_credential_networking_response: object` The secret is substituted on any host the session's Environment network policy permits egress to. - `type: "unrestricted"` - `beta_managed_agents_limited_credential_networking_response: object` The secret is substituted only on requests to the listed hosts. - `type: "limited"` - `allowed_hosts: array of string` The destination hosts of the outbound requests that the credential's secret is substituted into. An entry matches the request host exactly. An entry such as `*.example.com` matches any subdomain of `example.com` but not `example.com` itself. - `secret_name: string` Name of the environment variable. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `metadata: map[string]` Arbitrary key-value metadata attached to the credential. - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name: optional string` Human-readable name for the credential. #### Example ```bash ant beta:vaults:credentials create \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ --auth '{token: bearer_exampletoken, mcp_server_url: https://example-server.modelcontextprotocol.io/sse, type: static_bearer}' ``` ##### Response (200) ```json { "id": "vcrd_011CZkZEMt8gZan2iYPQfSkw", "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 `$ ant beta:vaults:credentials list` **GET** `/v1/vaults/{vault_id}/credentials` List Credentials #### Parameters - `--vault-id: string` (path parameter) Identifier of the vault to list credentials for. - `--include-archived: optional boolean` (query parameter) Whether to include archived credentials in the results. Defaults to `false`. - `--limit: optional number` (query parameter) Maximum number of credentials to return per page. Defaults to 20, maximum 100. format: int32 - `--page: optional string` (query parameter) The `next_page` value from a previous [List Credentials](https://platform.claude.com/docs/en/api/beta/vaults/credentials/list?sdk_languages=cli) response, to get the next page. Leave it out to get the first page. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListCredentialsResponse: object` Response containing a paginated list of credentials. - `data: optional array of BetaManagedAgentsCredential` The credentials on this page, newest first. - `type: "vault_credential"` - `id: string` The unique ID of the credential (`vcrd_...`). - `archived_at: string` When the credential was archived. Null if not archived. format: date-time - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse or BetaManagedAgentsEnvironmentVariableAuthResponse` Authentication configuration for this credential. - `beta_managed_agents_mcp_oauth_auth_response: object` OAuth credential details for an MCP server. - `type: "mcp_oauth"` - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `expires_at: optional string` When the credential's access token expires, in RFC 3339. Absent if the expiry isn't known. format: date-time - `refresh: optional object` Refresh token configuration, if the credential supports token refresh. - `client_id: string` The OAuth client ID used when refreshing the access token. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` - `beta_managed_agents_token_endpoint_auth_none_response: object` Token endpoint requires no client authentication. - `type: "none"` - `beta_managed_agents_token_endpoint_auth_basic_response: object` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `beta_managed_agents_token_endpoint_auth_post_response: object` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `resource: optional string` OAuth resource indicator. - `scope: optional string` OAuth scope for the refresh request. - `beta_managed_agents_static_bearer_auth_response: object` Static bearer token credential details for an MCP server. - `type: "static_bearer"` - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `beta_managed_agents_environment_variable_auth_response: object` Environment variable credential details. The secret value is never returned. - `type: "environment_variable"` - `injection_location: object` Where in the outbound request the secret value is substituted. - `body: boolean` Whether the placeholder is substituted in the request body. - `header: boolean` Whether the placeholder is substituted in request header values. - `networking: BetaManagedAgentsUnrestrictedCredentialNetworkingResponse or BetaManagedAgentsLimitedCredentialNetworkingResponse` Outbound hosts the secret value is substituted on. - `beta_managed_agents_unrestricted_credential_networking_response: object` The secret is substituted on any host the session's Environment network policy permits egress to. - `type: "unrestricted"` - `beta_managed_agents_limited_credential_networking_response: object` The secret is substituted only on requests to the listed hosts. - `type: "limited"` - `allowed_hosts: array of string` The destination hosts of the outbound requests that the credential's secret is substituted into. An entry matches the request host exactly. An entry such as `*.example.com` matches any subdomain of `example.com` but not `example.com` itself. - `secret_name: string` Name of the environment variable. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `metadata: map[string]` Arbitrary key-value metadata attached to the credential. - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name: optional string` Human-readable name for the credential. - `next_page: optional string` Pagination token for the next page, or null if no more results. #### Example ```bash ant beta:vaults:credentials list \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv ``` ##### Response (200) ```json { "data": [ { "id": "vcrd_011CZkZEMt8gZan2iYPQfSkw", "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=" } ``` ### Retrieve a Credential `$ ant beta:vaults:credentials retrieve` **GET** `/v1/vaults/{vault_id}/credentials/{credential_id}` Retrieve a Credential #### Parameters - `--vault-id: string` (path parameter) Identifier of the vault containing the credential. - `--credential-id: string` (path parameter) Unique identifier of the credential to retrieve. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_credential: object` A credential stored in a vault. Sensitive fields are never returned in responses. - `type: "vault_credential"` - `id: string` The unique ID of the credential (`vcrd_...`). - `archived_at: string` When the credential was archived. Null if not archived. format: date-time - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse or BetaManagedAgentsEnvironmentVariableAuthResponse` Authentication configuration for this credential. - `beta_managed_agents_mcp_oauth_auth_response: object` OAuth credential details for an MCP server. - `type: "mcp_oauth"` - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `expires_at: optional string` When the credential's access token expires, in RFC 3339. Absent if the expiry isn't known. format: date-time - `refresh: optional object` Refresh token configuration, if the credential supports token refresh. - `client_id: string` The OAuth client ID used when refreshing the access token. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` - `beta_managed_agents_token_endpoint_auth_none_response: object` Token endpoint requires no client authentication. - `type: "none"` - `beta_managed_agents_token_endpoint_auth_basic_response: object` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `beta_managed_agents_token_endpoint_auth_post_response: object` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `resource: optional string` OAuth resource indicator. - `scope: optional string` OAuth scope for the refresh request. - `beta_managed_agents_static_bearer_auth_response: object` Static bearer token credential details for an MCP server. - `type: "static_bearer"` - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `beta_managed_agents_environment_variable_auth_response: object` Environment variable credential details. The secret value is never returned. - `type: "environment_variable"` - `injection_location: object` Where in the outbound request the secret value is substituted. - `body: boolean` Whether the placeholder is substituted in the request body. - `header: boolean` Whether the placeholder is substituted in request header values. - `networking: BetaManagedAgentsUnrestrictedCredentialNetworkingResponse or BetaManagedAgentsLimitedCredentialNetworkingResponse` Outbound hosts the secret value is substituted on. - `beta_managed_agents_unrestricted_credential_networking_response: object` The secret is substituted on any host the session's Environment network policy permits egress to. - `type: "unrestricted"` - `beta_managed_agents_limited_credential_networking_response: object` The secret is substituted only on requests to the listed hosts. - `type: "limited"` - `allowed_hosts: array of string` The destination hosts of the outbound requests that the credential's secret is substituted into. An entry matches the request host exactly. An entry such as `*.example.com` matches any subdomain of `example.com` but not `example.com` itself. - `secret_name: string` Name of the environment variable. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `metadata: map[string]` Arbitrary key-value metadata attached to the credential. - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name: optional string` Human-readable name for the credential. #### Example ```bash ant beta:vaults:credentials retrieve \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ --credential-id vcrd_011CZkZEMt8gZan2iYPQfSkw ``` ##### Response (200) ```json { "id": "vcrd_011CZkZEMt8gZan2iYPQfSkw", "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 a Credential `$ ant beta:vaults:credentials update` **POST** `/v1/vaults/{vault_id}/credentials/{credential_id}` Update a Credential #### Parameters - `--vault-id: string` (path parameter) Identifier of the vault containing the credential. - `--credential-id: string` (path parameter) Unique identifier of the credential to update. - `--auth: optional BetaManagedAgentsMCPOAuthUpdateParams or BetaManagedAgentsStaticBearerUpdateParams or BetaManagedAgentsEnvironmentVariableUpdateParams` New authentication settings for the credential. The `type` must match the credential's current type, which can't be changed. - `--display-name: optional string` Updated human-readable name for the credential. 1-255 characters. minLength: 1, maxLength: 255 - `--metadata: optional map[string]` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_credential: object` A credential stored in a vault. Sensitive fields are never returned in responses. - `type: "vault_credential"` - `id: string` The unique ID of the credential (`vcrd_...`). - `archived_at: string` When the credential was archived. Null if not archived. format: date-time - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse or BetaManagedAgentsEnvironmentVariableAuthResponse` Authentication configuration for this credential. - `beta_managed_agents_mcp_oauth_auth_response: object` OAuth credential details for an MCP server. - `type: "mcp_oauth"` - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `expires_at: optional string` When the credential's access token expires, in RFC 3339. Absent if the expiry isn't known. format: date-time - `refresh: optional object` Refresh token configuration, if the credential supports token refresh. - `client_id: string` The OAuth client ID used when refreshing the access token. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` - `beta_managed_agents_token_endpoint_auth_none_response: object` Token endpoint requires no client authentication. - `type: "none"` - `beta_managed_agents_token_endpoint_auth_basic_response: object` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `beta_managed_agents_token_endpoint_auth_post_response: object` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `resource: optional string` OAuth resource indicator. - `scope: optional string` OAuth scope for the refresh request. - `beta_managed_agents_static_bearer_auth_response: object` Static bearer token credential details for an MCP server. - `type: "static_bearer"` - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `beta_managed_agents_environment_variable_auth_response: object` Environment variable credential details. The secret value is never returned. - `type: "environment_variable"` - `injection_location: object` Where in the outbound request the secret value is substituted. - `body: boolean` Whether the placeholder is substituted in the request body. - `header: boolean` Whether the placeholder is substituted in request header values. - `networking: BetaManagedAgentsUnrestrictedCredentialNetworkingResponse or BetaManagedAgentsLimitedCredentialNetworkingResponse` Outbound hosts the secret value is substituted on. - `beta_managed_agents_unrestricted_credential_networking_response: object` The secret is substituted on any host the session's Environment network policy permits egress to. - `type: "unrestricted"` - `beta_managed_agents_limited_credential_networking_response: object` The secret is substituted only on requests to the listed hosts. - `type: "limited"` - `allowed_hosts: array of string` The destination hosts of the outbound requests that the credential's secret is substituted into. An entry matches the request host exactly. An entry such as `*.example.com` matches any subdomain of `example.com` but not `example.com` itself. - `secret_name: string` Name of the environment variable. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `metadata: map[string]` Arbitrary key-value metadata attached to the credential. - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name: optional string` Human-readable name for the credential. #### Example ```bash ant beta:vaults:credentials update \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ --credential-id vcrd_011CZkZEMt8gZan2iYPQfSkw ``` ##### Response (200) ```json { "id": "vcrd_011CZkZEMt8gZan2iYPQfSkw", "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 a Credential `$ ant beta:vaults:credentials delete` **DELETE** `/v1/vaults/{vault_id}/credentials/{credential_id}` Delete a Credential #### Parameters - `--vault-id: string` (path parameter) Identifier of the vault containing the credential. - `--credential-id: string` (path parameter) Unique identifier of the credential to delete. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deleted_credential: object` Confirmation of a deleted credential. - `type: "vault_credential_deleted"` - `id: string` The unique ID of the deleted credential (`vcrd_...`). #### Example ```bash ant beta:vaults:credentials delete \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ --credential-id vcrd_011CZkZEMt8gZan2iYPQfSkw ``` ##### Response (200) ```json { "id": "vcrd_011CZkZEMt8gZan2iYPQfSkw", "type": "vault_credential_deleted" } ``` ### Archive a Credential `$ ant beta:vaults:credentials archive` **POST** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` Archive a Credential #### Parameters - `--vault-id: string` (path parameter) Identifier of the vault containing the credential. - `--credential-id: string` (path parameter) Unique identifier of the credential to archive. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_credential: object` A credential stored in a vault. Sensitive fields are never returned in responses. - `type: "vault_credential"` - `id: string` The unique ID of the credential (`vcrd_...`). - `archived_at: string` When the credential was archived. Null if not archived. format: date-time - `auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse or BetaManagedAgentsEnvironmentVariableAuthResponse` Authentication configuration for this credential. - `beta_managed_agents_mcp_oauth_auth_response: object` OAuth credential details for an MCP server. - `type: "mcp_oauth"` - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `expires_at: optional string` When the credential's access token expires, in RFC 3339. Absent if the expiry isn't known. format: date-time - `refresh: optional object` Refresh token configuration, if the credential supports token refresh. - `client_id: string` The OAuth client ID used when refreshing the access token. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse` - `beta_managed_agents_token_endpoint_auth_none_response: object` Token endpoint requires no client authentication. - `type: "none"` - `beta_managed_agents_token_endpoint_auth_basic_response: object` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `beta_managed_agents_token_endpoint_auth_post_response: object` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `resource: optional string` OAuth resource indicator. - `scope: optional string` OAuth scope for the refresh request. - `beta_managed_agents_static_bearer_auth_response: object` Static bearer token credential details for an MCP server. - `type: "static_bearer"` - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `beta_managed_agents_environment_variable_auth_response: object` Environment variable credential details. The secret value is never returned. - `type: "environment_variable"` - `injection_location: object` Where in the outbound request the secret value is substituted. - `body: boolean` Whether the placeholder is substituted in the request body. - `header: boolean` Whether the placeholder is substituted in request header values. - `networking: BetaManagedAgentsUnrestrictedCredentialNetworkingResponse or BetaManagedAgentsLimitedCredentialNetworkingResponse` Outbound hosts the secret value is substituted on. - `beta_managed_agents_unrestricted_credential_networking_response: object` The secret is substituted on any host the session's Environment network policy permits egress to. - `type: "unrestricted"` - `beta_managed_agents_limited_credential_networking_response: object` The secret is substituted only on requests to the listed hosts. - `type: "limited"` - `allowed_hosts: array of string` The destination hosts of the outbound requests that the credential's secret is substituted into. An entry matches the request host exactly. An entry such as `*.example.com` matches any subdomain of `example.com` but not `example.com` itself. - `secret_name: string` Name of the environment variable. - `created_at: string` A timestamp in RFC 3339 format format: date-time - `metadata: map[string]` Arbitrary key-value metadata attached to the credential. - `updated_at: string` A timestamp in RFC 3339 format format: date-time - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name: optional string` Human-readable name for the credential. #### Example ```bash ant beta:vaults:credentials archive \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ --credential-id vcrd_011CZkZEMt8gZan2iYPQfSkw ``` ##### Response (200) ```json { "id": "vcrd_011CZkZEMt8gZan2iYPQfSkw", "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 an MCP OAuth Credential `$ ant beta:vaults:credentials mcp-oauth-validate` **POST** `/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate` Validate an MCP OAuth Credential #### Parameters - `--vault-id: string` (path parameter) Identifier of the vault containing the credential. - `--credential-id: string` (path parameter) Unique identifier of the credential to validate. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_credential_validation: object` Result of live-probing a credential against its configured MCP server. - `type: "vault_credential_validation"` - `credential_id: string` Unique identifier of the credential that was validated. - `has_refresh_token: boolean` Whether the credential has a refresh token configured. - `mcp_probe: object` Details of the MCP probe step that failed, or `null` if the probe succeeded or there was no access token to test. - `http_response: object` The HTTP error response from the MCP server, or `null` if the MCP server didn't return one for the failing step, for example after a timeout or a DNS or TLS failure. - `body: string` Response body. May be truncated and has sensitive values scrubbed. - `body_truncated: boolean` Whether `body` was truncated. - `content_type: string` Value of the `Content-Type` response header. - `status_code: number` HTTP status code. format: int32 - `method: string` The MCP method that failed (for example `initialize` or `tools/list`). - `refresh: object` Details of the refresh-token exchange attempted on a 401. Null when no refresh was attempted. - `http_response: object` The captured HTTP error response from the token endpoint. Populated only when `status` is `failed`. - `body: string` Response body. May be truncated and has sensitive values scrubbed. - `body_truncated: boolean` Whether `body` was truncated. - `content_type: string` Value of the `Content-Type` response header. - `status_code: number` HTTP status code. format: int32 - `status: "succeeded" or "failed" or "connect_error" or "no_refresh_token"` Outcome of the refresh attempt. - `"succeeded"` The token endpoint returned a new access token. - `"failed"` The token endpoint returned an error response. See `http_response` for detail. - `"connect_error"` The token endpoint could not be reached (DNS, TLS, or connection error). - `"no_refresh_token"` No refresh token is stored for the credential, so no exchange was attempted. - `status: "valid" or "invalid" or "unknown"` Overall verdict of the validation probe. - `"valid"` The credential successfully authenticated against its MCP server. - `"invalid"` The probe reached the MCP server and the server rejected the credential, or no access token is stored. A refresh, if one was tried, didn't recover it. Usually the end user needs to authorize again. - `"unknown"` The probe couldn't tell whether the credential works, for example because of a network error or because a refresh succeeded but the new access token wasn't tested. Validate the credential again to find out. - `validated_at: string` When the validation probe was performed. format: date-time - `vault_id: string` Identifier of the vault containing the credential. #### Example ```bash ant beta:vaults:credentials mcp-oauth-validate \ --api-key my-anthropic-api-key \ --vault-id vlt_011CZkZDLs7fYzm1hXNPeRjv \ --credential-id vcrd_011CZkZEMt8gZan2iYPQfSkw ``` ##### Response (200) ```json { "credential_id": "vcrd_011CZkZEMt8gZan2iYPQfSkw", "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" } ``` ## Beta › Memory Stores ### Create a memory store `$ ant beta:memory-stores create` **POST** `/v1/memory_stores` Create a memory store #### Parameters - `--name: string` 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. minLength: 1, maxLength: 255 - `--description: optional string` 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. maxLength: 1024 - `--metadata: optional map[string]` 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. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_memory_store: object` 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. - `type: "memory_store"` - `id: string` 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. - `archived_at: string` Timestamp when the store was archived, or `null` if active. Set once and never cleared; archiving is one-way. Archived stores are read-only and cannot be attached to new sessions. format: date-time - `created_at: string` Timestamp when the store was created. format: date-time - `description: string` 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. - `metadata: map[string]` 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. - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `updated_at: string` Timestamp when the store's `name`, `description`, or `metadata` was last modified. Memory writes inside the store do not advance this. format: date-time #### Example ```bash ant beta:memory-stores create \ --api-key my-anthropic-api-key \ --name x ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "description": "description", "metadata": { "foo": "string" }, "name": "name", "type": "memory_store", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### List memory stores `$ ant beta:memory-stores list` **GET** `/v1/memory_stores` List memory stores #### Parameters - `--created-at-gte: optional string` (query parameter) Return only stores whose `created_at` is at or after this time (inclusive). Sent on the wire as `created_at[gte]`. format: date-time - `--created-at-lte: optional string` (query parameter) Return only stores whose `created_at` is at or before this time (inclusive). Sent on the wire as `created_at[lte]`. format: date-time - `--include-archived: optional boolean` (query parameter) When `true`, archived stores are included in the results. Defaults to `false` (archived stores are excluded). - `--limit: optional number` (query parameter) Maximum number of stores to return per page. Must be between 1 and 100. Defaults to 20 when omitted. format: int32 - `--page: optional string` (query parameter) 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. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListMemoryStoresResponse: object` A page of `memory_store` results, ordered by `created_at` descending (newest first). - `data: optional array of BetaManagedAgentsMemoryStore` Memory stores on this page, newest first. Empty when there are no stores matching the filters. - `type: "memory_store"` - `id: string` 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. - `archived_at: string` Timestamp when the store was archived, or `null` if active. Set once and never cleared; archiving is one-way. Archived stores are read-only and cannot be attached to new sessions. format: date-time - `created_at: string` Timestamp when the store was created. format: date-time - `description: string` 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. - `metadata: map[string]` 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. - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `updated_at: string` Timestamp when the store's `name`, `description`, or `metadata` was last modified. Memory writes inside the store do not advance this. format: date-time - `next_page: optional string` Opaque cursor for the next page (a `page_...` value). Pass as `page` on the next request. `null` when there are no more results. #### Example ```bash ant beta:memory-stores list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "memstore_01Wf3kQ8tZxB2mVr7HcJ4aNd", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "Per-user preferences and project context.", "metadata": {}, "name": "User Preferences", "type": "memory_store", "updated_at": "2026-03-15T10:00:00Z" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Retrieve a memory store `$ ant beta:memory-stores retrieve` **GET** `/v1/memory_stores/{memory_store_id}` Retrieve a memory store #### Parameters - `--memory-store-id: string` (path parameter) ID of the memory store to retrieve (a `memstore_...` identifier). Required. Enumerate IDs via `GET /v1/memory_stores`. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_memory_store: object` 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. - `type: "memory_store"` - `id: string` 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. - `archived_at: string` Timestamp when the store was archived, or `null` if active. Set once and never cleared; archiving is one-way. Archived stores are read-only and cannot be attached to new sessions. format: date-time - `created_at: string` Timestamp when the store was created. format: date-time - `description: string` 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. - `metadata: map[string]` 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. - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `updated_at: string` Timestamp when the store's `name`, `description`, or `metadata` was last modified. Memory writes inside the store do not advance this. format: date-time #### Example ```bash ant beta:memory-stores retrieve \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "description": "description", "metadata": { "foo": "string" }, "name": "name", "type": "memory_store", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### Update a memory store `$ ant beta:memory-stores update` **POST** `/v1/memory_stores/{memory_store_id}` Update a memory store #### Parameters - `--memory-store-id: string` (path parameter) ID of the memory store to update (a `memstore_...` identifier). Required. Enumerate IDs via `GET /v1/memory_stores`. Updating an archived store returns 400. - `--description: optional string` New description for the store, up to 1024 characters. Pass an empty string to clear it. maxLength: 1024 - `--metadata: optional map[string]` 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. - `--name: optional string` 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. minLength: 1, maxLength: 255 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_memory_store: object` 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. - `type: "memory_store"` - `id: string` 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. - `archived_at: string` Timestamp when the store was archived, or `null` if active. Set once and never cleared; archiving is one-way. Archived stores are read-only and cannot be attached to new sessions. format: date-time - `created_at: string` Timestamp when the store was created. format: date-time - `description: string` 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. - `metadata: map[string]` 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. - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `updated_at: string` Timestamp when the store's `name`, `description`, or `metadata` was last modified. Memory writes inside the store do not advance this. format: date-time #### Example ```bash ant beta:memory-stores update \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "description": "description", "metadata": { "foo": "string" }, "name": "name", "type": "memory_store", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### Delete a memory store `$ ant beta:memory-stores delete` **DELETE** `/v1/memory_stores/{memory_store_id}` Delete a memory store #### Parameters - `--memory-store-id: string` (path parameter) ID of the memory store to permanently delete (a `memstore_...` identifier). Required. Deletion cascades to all memories and memory versions in the store and cannot be undone. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deleted_memory_store: object` Confirmation that a `memory_store` was deleted. - `type: "memory_store_deleted"` - `id: string` ID of the deleted memory store (a `memstore_...` identifier). The store and all its memories and versions are no longer retrievable. #### Example ```bash ant beta:memory-stores delete \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id ``` ##### Response (200) ```json { "id": "id", "type": "memory_store_deleted" } ``` ### Archive a memory store `$ ant beta:memory-stores archive` **POST** `/v1/memory_stores/{memory_store_id}/archive` Archive a memory store #### Parameters - `--memory-store-id: string` (path parameter) ID of the memory store to archive (a `memstore_...` identifier). Required. Archiving is one-way and idempotent; archived stores cannot be unarchived. Enumerate IDs via `GET /v1/memory_stores`. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_memory_store: object` 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. - `type: "memory_store"` - `id: string` 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. - `archived_at: string` Timestamp when the store was archived, or `null` if active. Set once and never cleared; archiving is one-way. Archived stores are read-only and cannot be attached to new sessions. format: date-time - `created_at: string` Timestamp when the store was created. format: date-time - `description: string` 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. - `metadata: map[string]` 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. - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `updated_at: string` Timestamp when the store's `name`, `description`, or `metadata` was last modified. Memory writes inside the store do not advance this. format: date-time #### Example ```bash ant beta:memory-stores archive \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "description": "description", "metadata": { "foo": "string" }, "name": "name", "type": "memory_store", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## Beta › Memory Stores › Memories ### Create a memory `$ ant beta:memory-stores:memories create` **POST** `/v1/memory_stores/{memory_store_id}/memories` Create a memory #### Parameters - `--memory-store-id: string` (path parameter) The ID of the memory store to create the memory in (`memstore_...`). - `--content: string` UTF-8 text content for the new memory. Maximum 100 kB (102,400 bytes). Required; pass `""` explicitly to create an empty memory. - `--path: string` 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, or the Unicode line and paragraph separators (U+2028, U+2029), and must be NFC-normalized. Paths are case-sensitive. minLength: 2, maxLength: 1024 - `--view: optional "basic" or "full"` (query parameter) 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. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_memory: object` 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. - `type: "memory"` - `id: string` Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. - `content_sha256: string` 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`. - `content_size_bytes: number` Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. format: int32 - `created_at: string` When this memory was created, in RFC 3339 format. format: date-time - `memory_store_id: string` ID of the memory store this memory belongs to (a `memstore_...` value). - `memory_version_id: string` 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 history via [List memory versions](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli). - `path: string` 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. - `updated_at: string` When this memory was last modified, in RFC 3339 format. Use this as a cheap freshness signal; for who made the change, look up the head version's `created_by` via [List memory versions](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli). format: date-time - `content: optional string` The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). #### Example ```bash ant beta:memory-stores:memories create \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id \ --content content \ --path xx ``` ##### Response (200) ```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 `$ ant beta:memory-stores:memories list` **GET** `/v1/memory_stores/{memory_store_id}/memories` List memories #### Parameters - `--memory-store-id: string` (path parameter) The ID of the memory store to list memories from (`memstore_...`). - `--depth: optional number` (query parameter) `0` (or omitted) returns all descendants below `path_prefix` (recursive). `1` returns immediate children only; deeper entries roll up as `memory_prefix` items. `depth=1` behaves like `ls`; omitting `depth` behaves like `find`. format: int32 - `--limit: optional number` (query parameter) Maximum number of items to return per page. Must be between 1 and 100. Defaults to 20 when omitted. Capped at 20 when `view=full`. Both `memory` and `memory_prefix` items count toward the limit. format: int32 - `--page: optional string` (query parameter) 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. - `--path-prefix: optional string` (query parameter) Optional path prefix filter. Must end with `/` (segment-aligned), e.g., `/notes/`. This value appears in request URLs. Do not include secrets or personally identifiable information. - `--view: optional "basic" or "full"` (query parameter) Which projection of each `memory` to return. Defaults to `basic` (content omitted). `full` populates `content` on each item and caps `limit` at 20; use this as the bulk-read path for export and sync. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListMemoriesResult: object` Response payload for [List memories](https://platform.claude.com/docs/en/api/beta/memory_stores/memories/list?sdk_languages=cli). - `data: optional array of BetaManagedAgentsMemoryListItem` One page of results. Each item is either a `memory` object or, when `depth` was set, a `memory_prefix` rollup marker. Items are returned in a stable, server-defined order. - `beta_managed_agents_memory: object` 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. - `type: "memory"` - `id: string` Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. - `content_sha256: string` 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`. - `content_size_bytes: number` Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. format: int32 - `created_at: string` When this memory was created, in RFC 3339 format. format: date-time - `memory_store_id: string` ID of the memory store this memory belongs to (a `memstore_...` value). - `memory_version_id: string` 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 history via [List memory versions](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli). - `path: string` 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. - `updated_at: string` When this memory was last modified, in RFC 3339 format. Use this as a cheap freshness signal; for who made the change, look up the head version's `created_by` via [List memory versions](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli). format: date-time - `content: optional string` 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_prefix: object` A rolled-up directory marker returned by [List memories](https://platform.claude.com/docs/en/api/beta/memory_stores/memories/list?sdk_languages=cli) 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. - `type: "memory_prefix"` - `path: string` 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. - `next_page: optional string` Opaque cursor for the next page (a `page_...` value), or `null` if there are no more results. Pass as `page` on the next request. #### Example ```bash ant beta:memory-stores:memories list \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id ``` ##### Response (200) ```json { "data": [ { "id": "mem_011CZkZ9X2dpNyB6YbtxvB6e", "content_sha256": "ba7936d94c84d948a2232088f78228f175df6a8353b2d5bc9228eee5794a0024", "content_size_bytes": 28, "created_at": "2026-03-15T10:00:00Z", "memory_store_id": "memstore_01Wf3kQ8tZxB2mVr7HcJ4aNd", "memory_version_id": "memver_011CZkZBJq5dWxk9fVLNcPht", "path": "/preferences/formatting.md", "type": "memory", "updated_at": "2026-03-15T10:00:00Z", "content": null } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Retrieve a memory `$ ant beta:memory-stores:memories retrieve` **GET** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` Retrieve a memory #### Parameters - `--memory-store-id: string` (path parameter) The ID of the memory store that holds the memory (`memstore_...`). - `--memory-id: string` (path parameter) The ID of the memory to retrieve (`mem_...`). - `--view: optional "basic" or "full"` (query parameter) 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. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_memory: object` 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. - `type: "memory"` - `id: string` Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. - `content_sha256: string` 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`. - `content_size_bytes: number` Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. format: int32 - `created_at: string` When this memory was created, in RFC 3339 format. format: date-time - `memory_store_id: string` ID of the memory store this memory belongs to (a `memstore_...` value). - `memory_version_id: string` 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 history via [List memory versions](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli). - `path: string` 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. - `updated_at: string` When this memory was last modified, in RFC 3339 format. Use this as a cheap freshness signal; for who made the change, look up the head version's `created_by` via [List memory versions](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli). format: date-time - `content: optional string` The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). #### Example ```bash ant beta:memory-stores:memories retrieve \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id \ --memory-id memory_id ``` ##### Response (200) ```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 `$ ant beta:memory-stores:memories update` **POST** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` Update a memory #### Parameters - `--memory-store-id: string` (path parameter) The ID of the memory store that holds the memory (`memstore_...`). - `--memory-id: string` (path parameter) The ID of the memory to update (`mem_...`). - `--view: optional "basic" or "full"` (query parameter) 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. - `--content: optional string` 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). - `--path: optional string` 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, or the Unicode line and paragraph separators (U+2028, U+2029), and must be NFC-normalized. Paths are case-sensitive. The memory's `id` is preserved across renames. Omit to leave the path unchanged. minLength: 2, maxLength: 1024 - `--precondition: optional object` Optional optimistic-concurrency precondition. When supplied, the update applies only if the memory's current state matches; on mismatch the request returns `memory_precondition_failed_error` (HTTP 409). When omitted, the update is unconditional. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_memory: object` 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. - `type: "memory"` - `id: string` Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. - `content_sha256: string` 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`. - `content_size_bytes: number` Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. format: int32 - `created_at: string` When this memory was created, in RFC 3339 format. format: date-time - `memory_store_id: string` ID of the memory store this memory belongs to (a `memstore_...` value). - `memory_version_id: string` 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 history via [List memory versions](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli). - `path: string` 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. - `updated_at: string` When this memory was last modified, in RFC 3339 format. Use this as a cheap freshness signal; for who made the change, look up the head version's `created_by` via [List memory versions](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli). format: date-time - `content: optional string` The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). #### Example ```bash ant beta:memory-stores:memories update \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id \ --memory-id memory_id ``` ##### Response (200) ```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 `$ ant beta:memory-stores:memories delete` **DELETE** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` Delete a memory #### Parameters - `--memory-store-id: string` (path parameter) The ID of the memory store that holds the memory (`memstore_...`). - `--memory-id: string` (path parameter) The ID of the memory to delete (`mem_...`). - `--expected-content-sha256: optional string` (query parameter) Delete the memory only if its current `content_sha256` equals this value, given as 64 lowercase hexadecimal characters. Omit it to delete unconditionally. If the hashes differ, the request fails with HTTP status 409 and nothing is deleted. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_deleted_memory: object` Tombstone returned by [Delete a memory](https://platform.claude.com/docs/en/api/beta/memory_stores/memories/delete?sdk_languages=cli). Deleting a memory does not erase its version history: its versions remain listable via [List memory versions](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli) while they are retained (each version is kept for at least the version retention period after it was written, unless the store itself is deleted). - `type: "memory_deleted"` - `id: string` ID of the deleted memory (a `mem_...` value). #### Example ```bash ant beta:memory-stores:memories delete \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id \ --memory-id memory_id ``` ##### Response (200) ```json { "id": "id", "type": "memory_deleted" } ``` ## Beta › Memory Stores › Memory Versions ### List memory versions `$ ant beta:memory-stores:memory-versions list` **GET** `/v1/memory_stores/{memory_store_id}/memory_versions` List memory versions #### Parameters - `--memory-store-id: string` (path parameter) The ID of the memory store whose version history to list (`memstore_...`). - `--api-key-id: optional string` (query parameter) Return only versions written with the API key that has this ID. - `--created-at-gte: optional string` (query parameter) Return versions created at or after this time (inclusive). format: date-time - `--created-at-lte: optional string` (query parameter) Return versions created at or before this time (inclusive). format: date-time - `--limit: optional number` (query parameter) The maximum number of versions to return per page. Defaults to 20. format: int32 - `--memory-id: optional string` (query parameter) Return only versions of the memory with this ID (`mem_...`). The filter still works after the memory is deleted. The results then include the version whose `operation` is `deleted`. - `--operation: optional "created" or "modified" or "deleted"` (query parameter) Return only versions that record this kind of change. - `--page: optional string` (query parameter) The `next_page` value from a previous response, to get the next page. Omit it to get the first page. - `--service-account-id: optional string` (query parameter) Return only versions written by the service account with this ID (`svac_...`). - `--session-id: optional string` (query parameter) Return only versions written by the session with this ID. - `--view: optional "basic" or "full"` (query parameter) 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. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaManagedAgentsListMemoryVersionsResult: object` Response payload for [List memory versions](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli). - `data: optional array of BetaManagedAgentsMemoryVersion` One page of `memory_version` objects, ordered by `created_at` descending (newest first), with `id` as tiebreak. - `type: "memory_version"` - `id: string` Unique identifier for this version (a `memver_...` value). - `created_at: string` When this version was written, in RFC 3339 format. format: date-time - `memory_id: string` 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](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli) to retrieve the memory's retained versions, including the `deleted` row while the lineage is retained. - `memory_store_id: string` ID of the memory store this version belongs to (a `memstore_...` value). - `operation: "created" or "modified" or "deleted"` The kind of mutation this version records: `created`, `modified`, or `deleted`. - `"created"` The memory was created. The first version in any memory's lineage. - `"modified"` The memory's `content`, `path`, or both were changed via update. Writes the agent makes through the filesystem mount also appear as `modified`. - `"deleted"` The memory was deleted. The `content`, `content_size_bytes`, and `content_sha256` fields are `null` on this version. The preceding version, while it is retained, records the deleted content's size and hash. - `content: optional string` 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. - `content_sha256: optional string` 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. - `content_size_bytes: optional number` Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. format: int32 - `created_by: optional BetaManagedAgentsSessionActor or BetaManagedAgentsAPIActor or BetaManagedAgentsUserActor or BetaManagedAgentsServiceAccountActor` Who performed this write: one of `session_actor`, `api_actor`, `user_actor`, or `service_account_actor`; `null` when no writer is recorded. Captured at write time and preserved through redaction. A `session_actor` is an agent writing through the store's mounted filesystem at `/mnt/memory/`. The API key that created that session is not recorded on agent writes, so attribution names who made the write, not who is ultimately responsible; look up session provenance via the [Sessions API](https://platform.claude.com/docs/en/api/beta/sessions/retrieve?sdk_languages=cli). - `beta_managed_agents_session_actor: object` An agent acting during a session, for example through the session's mounted filesystem. It names the session itself, not the user or API key that started the session. - `type: "session_actor"` - `session_id: string` ID of the session (a `sesn_...` value). Look up the session via [Retrieve a session](https://platform.claude.com/docs/en/api/beta/sessions/retrieve?sdk_languages=cli) for further provenance. minLength: 1 - `beta_managed_agents_api_actor: object` A direct caller of the public API, identified by the API key that authenticated the request. - `type: "api_actor"` - `api_key_id: string` ID of the API key (an `apikey_...` value). This identifies the key, not the secret. minLength: 1 - `beta_managed_agents_user_actor: object` A human user, for example acting through the Anthropic Console. - `type: "user_actor"` - `user_id: string` ID of the user (a `user_...` value). minLength: 1 - `beta_managed_agents_service_account_actor: object` A workload authenticated as a service account, for example via Workload Identity Federation. - `type: "service_account_actor"` - `service_account_id: string` ID of the service account (a `svac_...` value). minLength: 1 - `path: optional string` The memory's path at the time of this write. `null` if and only if `redacted_at` is set. - `redacted_at: optional string` When this version was redacted, in RFC 3339 format, or `null` if it has not been redacted. When set, `content`, `path`, `content_size_bytes`, and `content_sha256` are all `null`. See [Redact a memory version](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/redact?sdk_languages=cli). format: date-time - `redacted_by: optional BetaManagedAgentsSessionActor or BetaManagedAgentsAPIActor or BetaManagedAgentsUserActor or BetaManagedAgentsServiceAccountActor` Who redacted this version, or `null` if it has not been redacted. In practice always an `api_actor`, `user_actor`, or `service_account_actor` (agents do not have a redact capability). - `beta_managed_agents_session_actor: object` An agent acting during a session, for example through the session's mounted filesystem. It names the session itself, not the user or API key that started the session. - `beta_managed_agents_api_actor: object` A direct caller of the public API, identified by the API key that authenticated the request. - `beta_managed_agents_user_actor: object` A human user, for example acting through the Anthropic Console. - `beta_managed_agents_service_account_actor: object` A workload authenticated as a service account, for example via Workload Identity Federation. - `next_page: optional string` Opaque cursor for the next page (a `page_...` value), or `null` if there are no more results. Pass as `page` on the next request. #### Example ```bash ant beta:memory-stores:memory-versions list \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id ``` ##### Response (200) ```json { "data": [ { "id": "memver_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "memory_id": "mem_011CZkZ9X2dpNyB6YbtxvB6e", "memory_store_id": "memstore_01Wf3kQ8tZxB2mVr7HcJ4aNd", "operation": "created", "type": "memory_version", "content": null, "content_sha256": "ba7936d94c84d948a2232088f78228f175df6a8353b2d5bc9228eee5794a0024", "content_size_bytes": 28, "created_by": { "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "type": "session_actor" }, "path": "/preferences/formatting.md", "redacted_at": null, "redacted_by": { "session_id": "x", "type": "session_actor" } } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Retrieve a memory version `$ ant beta:memory-stores:memory-versions retrieve` **GET** `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}` Retrieve a memory version #### Parameters - `--memory-store-id: string` (path parameter) The ID of the memory store that holds the version (`memstore_...`). - `--memory-version-id: string` (path parameter) The ID of the memory version to retrieve (`memver_...`). - `--view: optional "basic" or "full"` (query parameter) 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. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_memory_version: object` 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 are not deleted with the memory; each version is retained for at least the version retention period after it was written, unless the store itself 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. - `type: "memory_version"` - `id: string` Unique identifier for this version (a `memver_...` value). - `created_at: string` When this version was written, in RFC 3339 format. format: date-time - `memory_id: string` 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](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli) to retrieve the memory's retained versions, including the `deleted` row while the lineage is retained. - `memory_store_id: string` ID of the memory store this version belongs to (a `memstore_...` value). - `operation: "created" or "modified" or "deleted"` The kind of mutation this version records: `created`, `modified`, or `deleted`. - `"created"` The memory was created. The first version in any memory's lineage. - `"modified"` The memory's `content`, `path`, or both were changed via update. Writes the agent makes through the filesystem mount also appear as `modified`. - `"deleted"` The memory was deleted. The `content`, `content_size_bytes`, and `content_sha256` fields are `null` on this version. The preceding version, while it is retained, records the deleted content's size and hash. - `content: optional string` 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. - `content_sha256: optional string` 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. - `content_size_bytes: optional number` Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. format: int32 - `created_by: optional BetaManagedAgentsSessionActor or BetaManagedAgentsAPIActor or BetaManagedAgentsUserActor or BetaManagedAgentsServiceAccountActor` Who performed this write: one of `session_actor`, `api_actor`, `user_actor`, or `service_account_actor`; `null` when no writer is recorded. Captured at write time and preserved through redaction. A `session_actor` is an agent writing through the store's mounted filesystem at `/mnt/memory/`. The API key that created that session is not recorded on agent writes, so attribution names who made the write, not who is ultimately responsible; look up session provenance via the [Sessions API](https://platform.claude.com/docs/en/api/beta/sessions/retrieve?sdk_languages=cli). - `beta_managed_agents_session_actor: object` An agent acting during a session, for example through the session's mounted filesystem. It names the session itself, not the user or API key that started the session. - `type: "session_actor"` - `session_id: string` ID of the session (a `sesn_...` value). Look up the session via [Retrieve a session](https://platform.claude.com/docs/en/api/beta/sessions/retrieve?sdk_languages=cli) for further provenance. minLength: 1 - `beta_managed_agents_api_actor: object` A direct caller of the public API, identified by the API key that authenticated the request. - `type: "api_actor"` - `api_key_id: string` ID of the API key (an `apikey_...` value). This identifies the key, not the secret. minLength: 1 - `beta_managed_agents_user_actor: object` A human user, for example acting through the Anthropic Console. - `type: "user_actor"` - `user_id: string` ID of the user (a `user_...` value). minLength: 1 - `beta_managed_agents_service_account_actor: object` A workload authenticated as a service account, for example via Workload Identity Federation. - `type: "service_account_actor"` - `service_account_id: string` ID of the service account (a `svac_...` value). minLength: 1 - `path: optional string` The memory's path at the time of this write. `null` if and only if `redacted_at` is set. - `redacted_at: optional string` When this version was redacted, in RFC 3339 format, or `null` if it has not been redacted. When set, `content`, `path`, `content_size_bytes`, and `content_sha256` are all `null`. See [Redact a memory version](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/redact?sdk_languages=cli). format: date-time - `redacted_by: optional BetaManagedAgentsSessionActor or BetaManagedAgentsAPIActor or BetaManagedAgentsUserActor or BetaManagedAgentsServiceAccountActor` Who redacted this version, or `null` if it has not been redacted. In practice always an `api_actor`, `user_actor`, or `service_account_actor` (agents do not have a redact capability). - `beta_managed_agents_session_actor: object` An agent acting during a session, for example through the session's mounted filesystem. It names the session itself, not the user or API key that started the session. - `beta_managed_agents_api_actor: object` A direct caller of the public API, identified by the API key that authenticated the request. - `beta_managed_agents_user_actor: object` A human user, for example acting through the Anthropic Console. - `beta_managed_agents_service_account_actor: object` A workload authenticated as a service account, for example via Workload Identity Federation. #### Example ```bash ant beta:memory-stores:memory-versions retrieve \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id \ --memory-version-id memory_version_id ``` ##### Response (200) ```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 `$ ant beta:memory-stores:memory-versions redact` **POST** `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}/redact` Redact a memory version #### Parameters - `--memory-store-id: string` (path parameter) The ID of the memory store that holds the version (`memstore_...`). - `--memory-version-id: string` (path parameter) The ID of the memory version to redact (`memver_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `agent-memory-2026-07-22` or `managed-agents-2026-04-01` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_managed_agents_memory_version: object` 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 are not deleted with the memory; each version is retained for at least the version retention period after it was written, unless the store itself 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. - `type: "memory_version"` - `id: string` Unique identifier for this version (a `memver_...` value). - `created_at: string` When this version was written, in RFC 3339 format. format: date-time - `memory_id: string` 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](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/list?sdk_languages=cli) to retrieve the memory's retained versions, including the `deleted` row while the lineage is retained. - `memory_store_id: string` ID of the memory store this version belongs to (a `memstore_...` value). - `operation: "created" or "modified" or "deleted"` The kind of mutation this version records: `created`, `modified`, or `deleted`. - `"created"` The memory was created. The first version in any memory's lineage. - `"modified"` The memory's `content`, `path`, or both were changed via update. Writes the agent makes through the filesystem mount also appear as `modified`. - `"deleted"` The memory was deleted. The `content`, `content_size_bytes`, and `content_sha256` fields are `null` on this version. The preceding version, while it is retained, records the deleted content's size and hash. - `content: optional string` 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. - `content_sha256: optional string` 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. - `content_size_bytes: optional number` Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. format: int32 - `created_by: optional BetaManagedAgentsSessionActor or BetaManagedAgentsAPIActor or BetaManagedAgentsUserActor or BetaManagedAgentsServiceAccountActor` Who performed this write: one of `session_actor`, `api_actor`, `user_actor`, or `service_account_actor`; `null` when no writer is recorded. Captured at write time and preserved through redaction. A `session_actor` is an agent writing through the store's mounted filesystem at `/mnt/memory/`. The API key that created that session is not recorded on agent writes, so attribution names who made the write, not who is ultimately responsible; look up session provenance via the [Sessions API](https://platform.claude.com/docs/en/api/beta/sessions/retrieve?sdk_languages=cli). - `beta_managed_agents_session_actor: object` An agent acting during a session, for example through the session's mounted filesystem. It names the session itself, not the user or API key that started the session. - `type: "session_actor"` - `session_id: string` ID of the session (a `sesn_...` value). Look up the session via [Retrieve a session](https://platform.claude.com/docs/en/api/beta/sessions/retrieve?sdk_languages=cli) for further provenance. minLength: 1 - `beta_managed_agents_api_actor: object` A direct caller of the public API, identified by the API key that authenticated the request. - `type: "api_actor"` - `api_key_id: string` ID of the API key (an `apikey_...` value). This identifies the key, not the secret. minLength: 1 - `beta_managed_agents_user_actor: object` A human user, for example acting through the Anthropic Console. - `type: "user_actor"` - `user_id: string` ID of the user (a `user_...` value). minLength: 1 - `beta_managed_agents_service_account_actor: object` A workload authenticated as a service account, for example via Workload Identity Federation. - `type: "service_account_actor"` - `service_account_id: string` ID of the service account (a `svac_...` value). minLength: 1 - `path: optional string` The memory's path at the time of this write. `null` if and only if `redacted_at` is set. - `redacted_at: optional string` When this version was redacted, in RFC 3339 format, or `null` if it has not been redacted. When set, `content`, `path`, `content_size_bytes`, and `content_sha256` are all `null`. See [Redact a memory version](https://platform.claude.com/docs/en/api/beta/memory_stores/memory_versions/redact?sdk_languages=cli). format: date-time - `redacted_by: optional BetaManagedAgentsSessionActor or BetaManagedAgentsAPIActor or BetaManagedAgentsUserActor or BetaManagedAgentsServiceAccountActor` Who redacted this version, or `null` if it has not been redacted. In practice always an `api_actor`, `user_actor`, or `service_account_actor` (agents do not have a redact capability). - `beta_managed_agents_session_actor: object` An agent acting during a session, for example through the session's mounted filesystem. It names the session itself, not the user or API key that started the session. - `beta_managed_agents_api_actor: object` A direct caller of the public API, identified by the API key that authenticated the request. - `beta_managed_agents_user_actor: object` A human user, for example acting through the Anthropic Console. - `beta_managed_agents_service_account_actor: object` A workload authenticated as a service account, for example via Workload Identity Federation. #### Example ```bash ant beta:memory-stores:memory-versions redact \ --api-key my-anthropic-api-key \ --memory-store-id memory_store_id \ --memory-version-id memory_version_id ``` ##### Response (200) ```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" } } ``` ## Beta › Files ### Upload File `$ ant beta:files upload` **POST** `/v1/files` Upload File #### Parameters - `--file: string` The file to upload. Only the final path component of the part's `filename` is kept; an absent or empty `filename` is replaced with `unnamed` plus the extension for the file's stored `mime_type`, when known. format: binary - `--expires-in-seconds: optional number` Seconds from upload until the file expires and its bytes become permanently unavailable. Must be between 3600 (one hour) and 7776000 (ninety days). minimum: 3600, maximum: 7776000 - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_file_metadata: object` - `type: "file"` Object type. For files, this is always `"file"`. - `id: string` Unique object identifier. The format and length of IDs may change over time. - `created_at: string` RFC 3339 datetime string representing when the file was created. format: date-time - `filename: string` Original filename of the uploaded file. minLength: 1, maxLength: 500 - `mime_type: string` MIME type of the file. minLength: 1, maxLength: 255 - `size_bytes: number` Size of the file in bytes. minimum: 0 - `downloadable: optional boolean` Whether the file can be downloaded. - `expires_at: optional string` RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value. format: date-time - `scope: optional object` The scope of this file, indicating the context in which it was created (e.g., a session). - `type: "session"` The type of scope (e.g., `"session"`). - `id: string` The ID of the scoping resource (e.g., the session ID). #### Example ```bash ant beta:files upload \ --api-key my-anthropic-api-key \ --file 'Example data' ``` ##### Response (200) ```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, "expires_at": "2025-05-15T18:37:24.100435Z", "scope": { "id": "id", "type": "session" } } ``` ### List Files `$ ant beta:files list` **GET** `/v1/files` List Files #### Parameters - `--id: optional array of string` (query parameter) Restrict the result set to Files whose `id` is in this list. At most 100 entries (after de-duplication). Mutually exclusive with `page` and `limit`. When supplied, the response is always a single page (`next_page` is null). IDs that do not resolve to a visible File — including deleted Files — are silently omitted. - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Opaque page cursor returned in a prior list response's `next_page`. Prefixed `page_`. - `--scope-id: optional string` (query parameter) Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaFileListResponse: object` - `data: array of BetaFileMetadata` List of file metadata objects. - `type: "file"` Object type. For files, this is always `"file"`. - `id: string` Unique object identifier. The format and length of IDs may change over time. - `created_at: string` RFC 3339 datetime string representing when the file was created. format: date-time - `filename: string` Original filename of the uploaded file. minLength: 1, maxLength: 500 - `mime_type: string` MIME type of the file. minLength: 1, maxLength: 255 - `size_bytes: number` Size of the file in bytes. minimum: 0 - `downloadable: optional boolean` Whether the file can be downloaded. - `expires_at: optional string` RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value. format: date-time - `scope: optional object` The scope of this file, indicating the context in which it was created (e.g., a session). - `type: "session"` The type of scope (e.g., `"session"`). - `id: string` The ID of the scoping resource (e.g., the session ID). - `next_page: optional string` Opaque cursor for the next page. Supply as `?page=` to fetch the next page; null when there are no more results. #### Example ```bash ant beta:files list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```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, "expires_at": "2025-05-15T18:37:24.100435Z", "scope": { "id": "id", "type": "session" } } ], "next_page": "next_page" } ``` ### Download File `$ ant beta:files download` **GET** `/v1/files/{file_id}/content` Download File #### Parameters - `--file-id: string` (path parameter) ID of the File. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `unnamed_schema_1: file path` #### Example ```bash ant beta:files download \ --api-key my-anthropic-api-key \ --file-id file_id ``` ### Get File Metadata `$ ant beta:files retrieve-metadata` **GET** `/v1/files/{file_id}` Get File Metadata #### Parameters - `--file-id: string` (path parameter) ID of the File. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_file_metadata: object` - `type: "file"` Object type. For files, this is always `"file"`. - `id: string` Unique object identifier. The format and length of IDs may change over time. - `created_at: string` RFC 3339 datetime string representing when the file was created. format: date-time - `filename: string` Original filename of the uploaded file. minLength: 1, maxLength: 500 - `mime_type: string` MIME type of the file. minLength: 1, maxLength: 255 - `size_bytes: number` Size of the file in bytes. minimum: 0 - `downloadable: optional boolean` Whether the file can be downloaded. - `expires_at: optional string` RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value. format: date-time - `scope: optional object` The scope of this file, indicating the context in which it was created (e.g., a session). - `type: "session"` The type of scope (e.g., `"session"`). - `id: string` The ID of the scoping resource (e.g., the session ID). #### Example ```bash ant beta:files retrieve-metadata \ --api-key my-anthropic-api-key \ --file-id file_id ``` ##### Response (200) ```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, "expires_at": "2025-05-15T18:37:24.100435Z", "scope": { "id": "id", "type": "session" } } ``` ### Delete File `$ ant beta:files delete` **DELETE** `/v1/files/{file_id}` Delete File #### Parameters - `--file-id: string` (path parameter) ID of the File. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_deleted_file: object` - `type: optional "file_deleted"` Deleted object type. For file deletion, this is always `"file_deleted"`. - `id: string` ID of the deleted file. #### Example ```bash ant beta:files delete \ --api-key my-anthropic-api-key \ --file-id file_id ``` ##### Response (200) ```json { "id": "file_011CNha8iCJcU1wXNR6q4V8w", "type": "file_deleted" } ``` ## Beta › Skills ### Create Skill `$ ant beta:skills create` **POST** `/v1/skills` Create Skill #### Parameters - `--file: array of string` 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. - `--display-name: optional string` Human-readable, single-line label for the Skill. Maximum 255 characters. Always set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not unique. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_skill: object` - `type: "skill"` Object type. For Skills, this is always `"skill"`. - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill was created. format: date-time - `display_name: string` Human-readable, single-line label for the Skill. Maximum 255 characters. Always set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not unique. - `latest_version_id: string` ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version. - `source: object` Where the Skill comes from. Possible values: * `"custom"`: authored by the platform user; private to their workspace * `"anthropic"`: published by Anthropic; shared and read-only * `"anthropic_example"`: Anthropic-published sample Skill * `"plugin"`: resolved from an installed plugin - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"` Where the Skill comes from. Possible values: * `"custom"`: authored by the platform user; private to their workspace * `"anthropic"`: published by Anthropic; shared and read-only * `"anthropic_example"`: Anthropic-published sample Skill * `"plugin"`: resolved from an installed plugin - `"custom"` - `"anthropic"` - `"anthropic_example"` - `"plugin"` - `updated_at: string` ISO 8601 timestamp of when the skill was last updated. format: date-time #### Example ```bash ant beta:skills create \ --api-key my-anthropic-api-key \ --file 'Example data' ``` ##### Response (200) ```json { "id": "skill_01JAbcdefghijklmnopqrstuvw", "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "display_name", "latest_version_id": "latest_version_id", "source": { "type": "custom" }, "type": "skill", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### List Skills `$ ant beta:skills list` **GET** `/v1/skills` List Skills #### Parameters - `--limit: optional number` (query parameter) Number of results to return per page. Ranges from `1` to `1000`. Defaults to `20`. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) 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. - `--source: optional string` (query parameter) 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 - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaListSkillsResponse: object` - `data: array of BetaSkill` List of skills. - `type: "skill"` Object type. For Skills, this is always `"skill"`. - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill was created. format: date-time - `display_name: string` Human-readable, single-line label for the Skill. Maximum 255 characters. Always set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not unique. - `latest_version_id: string` ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version. - `source: object` Where the Skill comes from. Possible values: * `"custom"`: authored by the platform user; private to their workspace * `"anthropic"`: published by Anthropic; shared and read-only * `"anthropic_example"`: Anthropic-published sample Skill * `"plugin"`: resolved from an installed plugin - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"` Where the Skill comes from. Possible values: * `"custom"`: authored by the platform user; private to their workspace * `"anthropic"`: published by Anthropic; shared and read-only * `"anthropic_example"`: Anthropic-published sample Skill * `"plugin"`: resolved from an installed plugin - `"custom"` - `"anthropic"` - `"anthropic_example"` - `"plugin"` - `updated_at: string` ISO 8601 timestamp of when the skill was last updated. format: date-time - `next_page: string` Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request to get the next page. #### Example ```bash ant beta:skills list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "skill_01JAbcdefghijklmnopqrstuvw", "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "display_name", "latest_version_id": "latest_version_id", "source": { "type": "custom" }, "type": "skill", "updated_at": "2024-10-30T23:58:27.427722Z" } ], "next_page": "next_page" } ``` ### Get Skill `$ ant beta:skills retrieve` **GET** `/v1/skills/{skill_id}` Get Skill #### Parameters - `--skill-id: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_skill: object` - `type: "skill"` Object type. For Skills, this is always `"skill"`. - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill was created. format: date-time - `display_name: string` Human-readable, single-line label for the Skill. Maximum 255 characters. Always set: derived from the SKILL.md frontmatter `name` when omitted at creation. Not unique. - `latest_version_id: string` ID of the newest Skill Version — what `latest` references resolve to. Always set: a Skill holds at least one version. - `source: object` Where the Skill comes from. Possible values: * `"custom"`: authored by the platform user; private to their workspace * `"anthropic"`: published by Anthropic; shared and read-only * `"anthropic_example"`: Anthropic-published sample Skill * `"plugin"`: resolved from an installed plugin - `type: "custom" or "anthropic" or "anthropic_example" or "plugin"` Where the Skill comes from. Possible values: * `"custom"`: authored by the platform user; private to their workspace * `"anthropic"`: published by Anthropic; shared and read-only * `"anthropic_example"`: Anthropic-published sample Skill * `"plugin"`: resolved from an installed plugin - `"custom"` - `"anthropic"` - `"anthropic_example"` - `"plugin"` - `updated_at: string` ISO 8601 timestamp of when the skill was last updated. format: date-time #### Example ```bash ant beta:skills retrieve \ --api-key my-anthropic-api-key \ --skill-id skill_id ``` ##### Response (200) ```json { "id": "skill_01JAbcdefghijklmnopqrstuvw", "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "display_name", "latest_version_id": "latest_version_id", "source": { "type": "custom" }, "type": "skill", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### Delete Skill `$ ant beta:skills delete` **DELETE** `/v1/skills/{skill_id}` Delete Skill #### Parameters - `--skill-id: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_deleted_skill: object` - `type: "skill_deleted"` Deleted object type. For Skills, this is always `"skill_deleted"`. - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. #### Example ```bash ant beta:skills delete \ --api-key my-anthropic-api-key \ --skill-id skill_id ``` ##### Response (200) ```json { "id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "skill_deleted" } ``` ## Beta › Skills › Versions ### Create Skill Version `$ ant beta:skills:versions create` **POST** `/v1/skills/{skill_id}/versions` Create Skill Version #### Parameters - `--skill-id: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `--file: array of string` 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. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_skill_version: object` - `type: "skill_version"` Object type. For Skill Versions, this is always `"skill_version"`. - `id: string` Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. - `created_at: string` ISO 8601 timestamp of when the skill was created. format: date-time - `description: string` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `name: string` The Skill's immutable kebab-case slug, set at creation from the first upload's SKILL.md frontmatter `name` (or its enclosing directory). Every later upload must resolve to the same value. Also the top-level directory of the Skill's mounted files and the base name of a downloaded archive. - `skill_id: string` Unique identifier for the skill. The format and length of IDs may change over time. #### Example ```bash ant beta:skills:versions create \ --api-key my-anthropic-api-key \ --skill-id skill_id \ --file 'Example data' ``` ##### Response (200) ```json { "id": "id", "created_at": "2024-10-30T23:58:27.427722Z", "description": "description", "name": "name", "skill_id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "skill_version" } ``` ### List Skill Versions `$ ant beta:skills:versions list` **GET** `/v1/skills/{skill_id}/versions` List Skill Versions #### Parameters - `--skill-id: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `--limit: optional number` (query parameter) Number of results to return per page. Ranges from `1` to `1000`. Defaults to `20`. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaListSkillVersionsResponse: object` - `data: array of BetaSkillVersion` List of skills. - `type: "skill_version"` Object type. For Skill Versions, this is always `"skill_version"`. - `id: string` Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. - `created_at: string` ISO 8601 timestamp of when the skill was created. format: date-time - `description: string` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `name: string` The Skill's immutable kebab-case slug, set at creation from the first upload's SKILL.md frontmatter `name` (or its enclosing directory). Every later upload must resolve to the same value. Also the top-level directory of the Skill's mounted files and the base name of a downloaded archive. - `skill_id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `next_page: string` Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request to get the next page. #### Example ```bash ant beta:skills:versions list \ --api-key my-anthropic-api-key \ --skill-id skill_id ``` ##### Response (200) ```json { "data": [ { "id": "id", "created_at": "2024-10-30T23:58:27.427722Z", "description": "description", "name": "name", "skill_id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "skill_version" } ], "next_page": "next_page" } ``` ### Download Skill Version Content `$ ant beta:skills:versions download` **GET** `/v1/skills/{skill_id}/versions/{version}/content` Download a skill version's content as a zip archive. #### Parameters - `--skill-id: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `--version: string` (path parameter) Identifies the skill version by its version ID. Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129"). - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `unnamed_schema_2: file path` #### Example ```bash ant beta:skills:versions download \ --api-key my-anthropic-api-key \ --skill-id skill_id \ --version version ``` ### Get Skill Version `$ ant beta:skills:versions retrieve` **GET** `/v1/skills/{skill_id}/versions/{version}` Get Skill Version #### Parameters - `--skill-id: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `--version: string` (path parameter) Identifies the skill version: a version ID, or the literal `latest` for the skill's most recent version. Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129"). - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_skill_version: object` - `type: "skill_version"` Object type. For Skill Versions, this is always `"skill_version"`. - `id: string` Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. - `created_at: string` ISO 8601 timestamp of when the skill was created. format: date-time - `description: string` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `name: string` The Skill's immutable kebab-case slug, set at creation from the first upload's SKILL.md frontmatter `name` (or its enclosing directory). Every later upload must resolve to the same value. Also the top-level directory of the Skill's mounted files and the base name of a downloaded archive. - `skill_id: string` Unique identifier for the skill. The format and length of IDs may change over time. #### Example ```bash ant beta:skills:versions retrieve \ --api-key my-anthropic-api-key \ --skill-id skill_id \ --version version ``` ##### Response (200) ```json { "id": "id", "created_at": "2024-10-30T23:58:27.427722Z", "description": "description", "name": "name", "skill_id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "skill_version" } ``` ### Delete Skill Version `$ ant beta:skills:versions delete` **DELETE** `/v1/skills/{skill_id}/versions/{version}` Delete Skill Version #### Parameters - `--skill-id: string` (path parameter) Unique identifier for the skill. The format and length of IDs may change over time. - `--version: string` (path parameter) Identifies the skill version by its version ID. Requests carrying the `skills-2025-10-02` beta header address versions by their Unix epoch timestamp instead (e.g., "1759178010641129"). - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_deleted_skill_version: object` - `type: "skill_version_deleted"` Deleted object type. For Skill Versions, this is always `"skill_version_deleted"`. - `id: string` Unique identifier for this Skill Version. The id addresses the version in paths and pins it in references. #### Example ```bash ant beta:skills:versions delete \ --api-key my-anthropic-api-key \ --skill-id skill_id \ --version version ``` ##### Response (200) ```json { "id": "id", "type": "skill_version_deleted" } ``` ## Beta › User Profiles ### Create User Profile `$ ant beta:user-profiles create` **POST** `/v1/user_profiles` Create User Profile #### Parameters - `--access-type: optional "application" or "passthrough"` How the platform uses the API for this entity. `application` (default): the profile represents an individual end-user of the platform's product. `passthrough`: the profile identifies a company the platform resells Claude access to. - `--external-id: optional string` Platform's own identifier for this user. Not enforced unique. Maximum 255 characters. Accepted under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; under `user-profiles-2026-09-04` send `external_user_details.reference_id` instead. minLength: 1, maxLength: 255 - `--external-user-details: optional object` Details about the entity this profile represents, as the platform states them. Every field is optional. Accepted under the `user-profiles-2026-09-04` beta header only. - `--external-user-onboarded-at: optional string` When the entity this profile represents opened its account with the platform, in RFC 3339 format: for an `application` profile, when the end-user signed up; for a `passthrough` profile, when the company became the platform's customer. Must be a complete timestamp no more than 1 minute in the future. Optional. Accepted under the `user-profiles-2026-08-18` beta header; under `user-profiles-2026-09-04` send `external_user_details.onboarded_at` instead. format: date-time - `--metadata: optional map[string]` 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. - `--name: optional string` Optional for all profiles. Real-world name of the entity this profile represents (company or individual); for a company the platform resells Claude access to (`access_type` `passthrough`), that company's name where known. Maximum 255 characters. minLength: 1, maxLength: 255 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `user-profiles-2026-03-24`, `user-profiles-2026-08-18`, or `user-profiles-2026-09-04` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_user_profile: object` A record of an entity that the platform serves through the API, such as an end-user of the platform's product or a company that the platform resells Claude access to. A Messages, Message Batches or token counting request can send a profile's `id` in the `anthropic-user-profile-id` header to attribute the request to that entity. - `type: "user_profile"` Object type. Always `user_profile`. - `id: string` Unique identifier for this user profile, prefixed `uprof_`. - `created_at: string` When this user profile was created, in RFC 3339 format. format: date-time - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `trust_grants: map[BetaUserProfileTrustGrant]` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `status: "active" or "pending" or "rejected"` Status of the trust grant. - `"active"` - `"pending"` - `"rejected"` - `updated_at: string` When this user profile was last modified, in RFC 3339 format. Trust-grant status changes also bump this timestamp. format: date-time - `access_type: optional "application" or "passthrough"` How the platform uses the API for this entity: `application` (default) or `passthrough`. Present under the `user-profiles-2026-08-18` and later beta headers. - `"application"` The user profile represents an individual end-user of a product that the platform builds on the API. New profiles get this value by default. - `"passthrough"` The user profile represents a company that the platform resells Claude access to. - `external_id: optional string` Platform's own identifier for this user. Not enforced unique. Present under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; under `user-profiles-2026-09-04` the value is `external_user_details.reference_id`. - `external_user_details: optional object` Details about the entity this profile represents, as the platform states them; not verified by Anthropic. Present under the `user-profiles-2026-09-04` beta header, with every field present and `null` until the platform supplies a value; the earlier beta headers serve `reference_id` as the top-level `external_id`, and `user-profiles-2026-08-18` serves `onboarded_at` as `external_user_onboarded_at`. - `account_status: "active" or "suspended" or "blocked"` The status of the entity's account on the platform: `active`, `suspended` or `blocked`. `null` until the platform supplies one. - `"active"` The platform has neither restricted nor barred the account of the entity that the user profile represents. - `"suspended"` The platform has restricted the account of the entity that the user profile represents and may restore it. - `"blocked"` The platform has barred the account of the entity that the user profile represents. - `country: string` The country the platform associates with the entity, as an ISO 3166-1 alpha-2 code. `null` until the platform supplies one. - `email_hash: string` The platform-computed hash of the entity's email address. `null` until the platform supplies one. - `entity_type: "individual" or "business" or "non_profit" or "government"` What kind of entity the profile represents: `individual`, `business`, `non_profit` or `government`. `null` until the platform supplies one. - `"individual"` - `"business"` - `"non_profit"` - `"government"` - `name_hash: string` The platform-computed hash of the entity's name. `null` until the platform supplies one. - `onboarded_at: string` When the entity opened its account with the platform, as stated by the platform, in RFC 3339 format (UTC). `null` until the platform supplies one. format: date-time - `reference_id: string` The platform's own reference for the entity. `null` until the platform supplies one. - `external_user_onboarded_at: optional string` When the entity this profile represents opened its account with the platform, as stated by the platform, in RFC 3339 format (UTC). `null` until the platform supplies one. Present under the `user-profiles-2026-08-18` beta header; under `user-profiles-2026-09-04` the value is `external_user_details.onboarded_at`. format: date-time - `name: optional string` Real-world name of the entity this profile represents (company or individual). For a company the platform resells Claude access to (`access_type` `passthrough`) this is that company's name. #### Example ```bash ant beta:user-profiles create \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "trust_grants": { "cyber": { "status": "active" } }, "type": "user_profile", "updated_at": "2026-03-15T10:00:00Z", "access_type": "application", "external_id": "user_12345", "external_user_details": { "account_status": "active", "country": "country", "email_hash": "email_hash", "entity_type": "individual", "name_hash": "name_hash", "onboarded_at": "2019-12-27T18:11:19.117Z", "reference_id": "reference_id" }, "external_user_onboarded_at": "2024-11-02T08:15:00Z", "name": "Example User" } ``` ### List User Profiles `$ ant beta:user-profiles list` **GET** `/v1/user_profiles` List User Profiles #### Parameters - `--limit: optional number` (query parameter) The maximum number of user profiles to return, from 1 to 100. Defaults to 20. format: int32 - `--order: optional "asc" or "desc"` (query parameter) The sort direction, applied to the field that `order_by` selects. Defaults to `desc`. - `--order-by: optional "created_at" or "name"` (query parameter) The field to sort user profiles by, in the direction that `order` sets. Defaults to `created_at`. - `--page: optional string` (query parameter) The cursor for the page to return, taken from `next_page` in a previous response. Leave it out to get the first page. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `user-profiles-2026-03-24`, `user-profiles-2026-08-18`, or `user-profiles-2026-09-04` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaListUserProfilesResponse: object` A page of user profiles, sorted by the request's `order_by` and `order`. - `data: array of BetaUserProfile` User profiles on this page. - `type: "user_profile"` Object type. Always `user_profile`. - `id: string` Unique identifier for this user profile, prefixed `uprof_`. - `created_at: string` When this user profile was created, in RFC 3339 format. format: date-time - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `trust_grants: map[BetaUserProfileTrustGrant]` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `status: "active" or "pending" or "rejected"` Status of the trust grant. - `"active"` - `"pending"` - `"rejected"` - `updated_at: string` When this user profile was last modified, in RFC 3339 format. Trust-grant status changes also bump this timestamp. format: date-time - `access_type: optional "application" or "passthrough"` How the platform uses the API for this entity: `application` (default) or `passthrough`. Present under the `user-profiles-2026-08-18` and later beta headers. - `"application"` The user profile represents an individual end-user of a product that the platform builds on the API. New profiles get this value by default. - `"passthrough"` The user profile represents a company that the platform resells Claude access to. - `external_id: optional string` Platform's own identifier for this user. Not enforced unique. Present under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; under `user-profiles-2026-09-04` the value is `external_user_details.reference_id`. - `external_user_details: optional object` Details about the entity this profile represents, as the platform states them; not verified by Anthropic. Present under the `user-profiles-2026-09-04` beta header, with every field present and `null` until the platform supplies a value; the earlier beta headers serve `reference_id` as the top-level `external_id`, and `user-profiles-2026-08-18` serves `onboarded_at` as `external_user_onboarded_at`. - `account_status: "active" or "suspended" or "blocked"` The status of the entity's account on the platform: `active`, `suspended` or `blocked`. `null` until the platform supplies one. - `"active"` The platform has neither restricted nor barred the account of the entity that the user profile represents. - `"suspended"` The platform has restricted the account of the entity that the user profile represents and may restore it. - `"blocked"` The platform has barred the account of the entity that the user profile represents. - `country: string` The country the platform associates with the entity, as an ISO 3166-1 alpha-2 code. `null` until the platform supplies one. - `email_hash: string` The platform-computed hash of the entity's email address. `null` until the platform supplies one. - `entity_type: "individual" or "business" or "non_profit" or "government"` What kind of entity the profile represents: `individual`, `business`, `non_profit` or `government`. `null` until the platform supplies one. - `"individual"` - `"business"` - `"non_profit"` - `"government"` - `name_hash: string` The platform-computed hash of the entity's name. `null` until the platform supplies one. - `onboarded_at: string` When the entity opened its account with the platform, as stated by the platform, in RFC 3339 format (UTC). `null` until the platform supplies one. format: date-time - `reference_id: string` The platform's own reference for the entity. `null` until the platform supplies one. - `external_user_onboarded_at: optional string` When the entity this profile represents opened its account with the platform, as stated by the platform, in RFC 3339 format (UTC). `null` until the platform supplies one. Present under the `user-profiles-2026-08-18` beta header; under `user-profiles-2026-09-04` the value is `external_user_details.onboarded_at`. format: date-time - `name: optional string` Real-world name of the entity this profile represents (company or individual). For a company the platform resells Claude access to (`access_type` `passthrough`) this is that company's name. - `next_page: string` Cursor for the next page, or `null` when there are no more results. #### Example ```bash ant beta:user-profiles list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "trust_grants": { "cyber": { "status": "active" } }, "type": "user_profile", "updated_at": "2026-03-15T10:00:00Z", "access_type": "application", "external_id": "user_12345", "external_user_details": { "account_status": "active", "country": "country", "email_hash": "email_hash", "entity_type": "individual", "name_hash": "name_hash", "onboarded_at": "2019-12-27T18:11:19.117Z", "reference_id": "reference_id" }, "external_user_onboarded_at": "2024-11-02T08:15:00Z", "name": "Example User" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ### Get User Profile `$ ant beta:user-profiles retrieve` **GET** `/v1/user_profiles/{user_profile_id}` Get User Profile #### Parameters - `--user-profile-id: string` (path parameter) The ID of the user profile to get (`uprof_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `user-profiles-2026-03-24`, `user-profiles-2026-08-18`, or `user-profiles-2026-09-04` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_user_profile: object` A record of an entity that the platform serves through the API, such as an end-user of the platform's product or a company that the platform resells Claude access to. A Messages, Message Batches or token counting request can send a profile's `id` in the `anthropic-user-profile-id` header to attribute the request to that entity. - `type: "user_profile"` Object type. Always `user_profile`. - `id: string` Unique identifier for this user profile, prefixed `uprof_`. - `created_at: string` When this user profile was created, in RFC 3339 format. format: date-time - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `trust_grants: map[BetaUserProfileTrustGrant]` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `status: "active" or "pending" or "rejected"` Status of the trust grant. - `"active"` - `"pending"` - `"rejected"` - `updated_at: string` When this user profile was last modified, in RFC 3339 format. Trust-grant status changes also bump this timestamp. format: date-time - `access_type: optional "application" or "passthrough"` How the platform uses the API for this entity: `application` (default) or `passthrough`. Present under the `user-profiles-2026-08-18` and later beta headers. - `"application"` The user profile represents an individual end-user of a product that the platform builds on the API. New profiles get this value by default. - `"passthrough"` The user profile represents a company that the platform resells Claude access to. - `external_id: optional string` Platform's own identifier for this user. Not enforced unique. Present under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; under `user-profiles-2026-09-04` the value is `external_user_details.reference_id`. - `external_user_details: optional object` Details about the entity this profile represents, as the platform states them; not verified by Anthropic. Present under the `user-profiles-2026-09-04` beta header, with every field present and `null` until the platform supplies a value; the earlier beta headers serve `reference_id` as the top-level `external_id`, and `user-profiles-2026-08-18` serves `onboarded_at` as `external_user_onboarded_at`. - `account_status: "active" or "suspended" or "blocked"` The status of the entity's account on the platform: `active`, `suspended` or `blocked`. `null` until the platform supplies one. - `"active"` The platform has neither restricted nor barred the account of the entity that the user profile represents. - `"suspended"` The platform has restricted the account of the entity that the user profile represents and may restore it. - `"blocked"` The platform has barred the account of the entity that the user profile represents. - `country: string` The country the platform associates with the entity, as an ISO 3166-1 alpha-2 code. `null` until the platform supplies one. - `email_hash: string` The platform-computed hash of the entity's email address. `null` until the platform supplies one. - `entity_type: "individual" or "business" or "non_profit" or "government"` What kind of entity the profile represents: `individual`, `business`, `non_profit` or `government`. `null` until the platform supplies one. - `"individual"` - `"business"` - `"non_profit"` - `"government"` - `name_hash: string` The platform-computed hash of the entity's name. `null` until the platform supplies one. - `onboarded_at: string` When the entity opened its account with the platform, as stated by the platform, in RFC 3339 format (UTC). `null` until the platform supplies one. format: date-time - `reference_id: string` The platform's own reference for the entity. `null` until the platform supplies one. - `external_user_onboarded_at: optional string` When the entity this profile represents opened its account with the platform, as stated by the platform, in RFC 3339 format (UTC). `null` until the platform supplies one. Present under the `user-profiles-2026-08-18` beta header; under `user-profiles-2026-09-04` the value is `external_user_details.onboarded_at`. format: date-time - `name: optional string` Real-world name of the entity this profile represents (company or individual). For a company the platform resells Claude access to (`access_type` `passthrough`) this is that company's name. #### Example ```bash ant beta:user-profiles retrieve \ --api-key my-anthropic-api-key \ --user-profile-id uprof_011CZkZCu8hGbp5mYRQgUmz9 ``` ##### Response (200) ```json { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "trust_grants": { "cyber": { "status": "active" } }, "type": "user_profile", "updated_at": "2026-03-15T10:00:00Z", "access_type": "application", "external_id": "user_12345", "external_user_details": { "account_status": "active", "country": "country", "email_hash": "email_hash", "entity_type": "individual", "name_hash": "name_hash", "onboarded_at": "2019-12-27T18:11:19.117Z", "reference_id": "reference_id" }, "external_user_onboarded_at": "2024-11-02T08:15:00Z", "name": "Example User" } ``` ### Update User Profile `$ ant beta:user-profiles update` **POST** `/v1/user_profiles/{user_profile_id}` Update User Profile #### Parameters - `--user-profile-id: string` (path parameter) The ID of the user profile to update (`uprof_...`). - `--access-type: optional "application" or "passthrough"` If present, replaces the stored access type. Omit to leave unchanged. - `--external-id: optional string` If present, replaces the stored external_id. Omit to leave unchanged. Maximum 255 characters. Accepted under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; under `user-profiles-2026-09-04` send `external_user_details.reference_id` instead. minLength: 1, maxLength: 255 - `--external-user-details: optional object` Details about the entity this profile represents, as the platform states them. Each field sent replaces the stored value; omit a field to leave it unchanged. Once set, a value cannot be cleared and `null` is rejected. Accepted under the `user-profiles-2026-09-04` beta header only. - `--external-user-onboarded-at: optional string` If present, replaces the stored account creation time. Omit to leave unchanged; once set, the value cannot be cleared and `null` is rejected. Must be a complete RFC 3339 timestamp no more than 1 minute in the future. Accepted under the `user-profiles-2026-08-18` beta header; under `user-profiles-2026-09-04` send `external_user_details.onboarded_at` instead. format: date-time - `--metadata: optional map[string]` 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. - `--name: optional string` If present, replaces the stored name. Omit to leave unchanged. Maximum 255 characters. minLength: 1, maxLength: 255 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `user-profiles-2026-03-24`, `user-profiles-2026-08-18`, or `user-profiles-2026-09-04` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_user_profile: object` A record of an entity that the platform serves through the API, such as an end-user of the platform's product or a company that the platform resells Claude access to. A Messages, Message Batches or token counting request can send a profile's `id` in the `anthropic-user-profile-id` header to attribute the request to that entity. - `type: "user_profile"` Object type. Always `user_profile`. - `id: string` Unique identifier for this user profile, prefixed `uprof_`. - `created_at: string` When this user profile was created, in RFC 3339 format. format: date-time - `metadata: map[string]` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `trust_grants: map[BetaUserProfileTrustGrant]` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `status: "active" or "pending" or "rejected"` Status of the trust grant. - `"active"` - `"pending"` - `"rejected"` - `updated_at: string` When this user profile was last modified, in RFC 3339 format. Trust-grant status changes also bump this timestamp. format: date-time - `access_type: optional "application" or "passthrough"` How the platform uses the API for this entity: `application` (default) or `passthrough`. Present under the `user-profiles-2026-08-18` and later beta headers. - `"application"` The user profile represents an individual end-user of a product that the platform builds on the API. New profiles get this value by default. - `"passthrough"` The user profile represents a company that the platform resells Claude access to. - `external_id: optional string` Platform's own identifier for this user. Not enforced unique. Present under the `user-profiles-2026-03-24` and `user-profiles-2026-08-18` beta headers; under `user-profiles-2026-09-04` the value is `external_user_details.reference_id`. - `external_user_details: optional object` Details about the entity this profile represents, as the platform states them; not verified by Anthropic. Present under the `user-profiles-2026-09-04` beta header, with every field present and `null` until the platform supplies a value; the earlier beta headers serve `reference_id` as the top-level `external_id`, and `user-profiles-2026-08-18` serves `onboarded_at` as `external_user_onboarded_at`. - `account_status: "active" or "suspended" or "blocked"` The status of the entity's account on the platform: `active`, `suspended` or `blocked`. `null` until the platform supplies one. - `"active"` The platform has neither restricted nor barred the account of the entity that the user profile represents. - `"suspended"` The platform has restricted the account of the entity that the user profile represents and may restore it. - `"blocked"` The platform has barred the account of the entity that the user profile represents. - `country: string` The country the platform associates with the entity, as an ISO 3166-1 alpha-2 code. `null` until the platform supplies one. - `email_hash: string` The platform-computed hash of the entity's email address. `null` until the platform supplies one. - `entity_type: "individual" or "business" or "non_profit" or "government"` What kind of entity the profile represents: `individual`, `business`, `non_profit` or `government`. `null` until the platform supplies one. - `"individual"` - `"business"` - `"non_profit"` - `"government"` - `name_hash: string` The platform-computed hash of the entity's name. `null` until the platform supplies one. - `onboarded_at: string` When the entity opened its account with the platform, as stated by the platform, in RFC 3339 format (UTC). `null` until the platform supplies one. format: date-time - `reference_id: string` The platform's own reference for the entity. `null` until the platform supplies one. - `external_user_onboarded_at: optional string` When the entity this profile represents opened its account with the platform, as stated by the platform, in RFC 3339 format (UTC). `null` until the platform supplies one. Present under the `user-profiles-2026-08-18` beta header; under `user-profiles-2026-09-04` the value is `external_user_details.onboarded_at`. format: date-time - `name: optional string` Real-world name of the entity this profile represents (company or individual). For a company the platform resells Claude access to (`access_type` `passthrough`) this is that company's name. #### Example ```bash ant beta:user-profiles update \ --api-key my-anthropic-api-key \ --user-profile-id uprof_011CZkZCu8hGbp5mYRQgUmz9 ``` ##### Response (200) ```json { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "trust_grants": { "cyber": { "status": "active" } }, "type": "user_profile", "updated_at": "2026-03-15T10:00:00Z", "access_type": "application", "external_id": "user_12345", "external_user_details": { "account_status": "active", "country": "country", "email_hash": "email_hash", "entity_type": "individual", "name_hash": "name_hash", "onboarded_at": "2019-12-27T18:11:19.117Z", "reference_id": "reference_id" }, "external_user_onboarded_at": "2024-11-02T08:15:00Z", "name": "Example User" } ``` ### Create Enrollment URL `$ ant beta:user-profiles create-enrollment-url` **POST** `/v1/user_profiles/{user_profile_id}/enrollment_url` Create Enrollment URL #### Parameters - `--user-profile-id: string` (path parameter) The ID of the user profile to create an enrollment URL for (`uprof_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `user-profiles-2026-03-24`, `user-profiles-2026-08-18`, or `user-profiles-2026-09-04` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_user_profile_enrollment_url: object` A URL to give to the entity that a user profile represents, so that the entity can enroll for a trust grant. - `type: "enrollment_url"` Object type. Always `enrollment_url`. - `expires_at: string` When this enrollment URL expires, in RFC 3339 format. format: date-time - `url: string` Enrollment URL to send to the end user. Valid until `expires_at`. #### Example ```bash ant beta:user-profiles create-enrollment-url \ --api-key my-anthropic-api-key \ --user-profile-id uprof_011CZkZCu8hGbp5mYRQgUmz9 ``` ##### Response (200) ```json { "expires_at": "2026-03-15T10:15:00Z", "type": "enrollment_url", "url": "https://platform.claude.com/user-profiles/enrollment/M3J0bGJxZ2ppMnptbnB1" } ``` ## Beta › Dreams ### Create a Dream `$ ant beta:dreams create` **POST** `/v1/dreams` Start an asynchronous job that uses past sessions to produce a reorganized version of a memory store and get back the dream to poll for the result. By default the dream writes its result to a new memory store and doesn't change the input memory store. The response has `status` set to `pending` and an empty `outputs` array. Poll the dream until `status` is `completed`, `failed`, or `canceled`. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#create-a-dream) to learn more about creating dreams. #### Parameters - `--input: array of BetaDreamInput` The memory store and sessions for the dream to read, as exactly one `memory_store` entry and exactly one `sessions` entry. - `--model: string or BetaDreamModelConfigParam` The model that runs a dream, given as a model ID or as an object with `id` and `speed`. In the object form, `speed` can only be `standard`. The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#limits) lists the supported models. - `--instructions: optional string` Guidance that steers how the dream reads the sessions and organizes the output memory store, from 1 to 4,096 characters. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#steer-with-instructions) for what kinds of instructions work well. minLength: 1, maxLength: 4096 - `--output-behavior: optional BetaOutputBehaviorCreateNew or BetaOutputBehaviorUpdateExisting` Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_dream: object` An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store. By default the dream writes its result to a new memory store and doesn't change the input memory store. With `output_behavior` set to `update_existing`, it writes its result into the input memory store instead. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#how-it-works) for what a dream reads and produces. - `type: "dream"` - `id: string` The unique ID of the dream (`drm_...`). - `archived_at: string` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. format: date-time - `created_at: string` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. format: date-time - `ended_at: string` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. format: date-time - `error: object` Why the dream failed, or `null` if `status` isn't `failed`. - `type: string` A code for why the dream failed, such as `timeout` or `internal_error`. The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#errors) lists common error codes and when they occur. - `message: string` A human-readable explanation of why the dream failed. - `inputs: array of BetaDreamInput` The sources that the dream reads, from the request that created it. - `beta_dream_memory_store_input: object` The memory store that a dream reads, given as an entry in `inputs`. With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it. - `type: "memory_store"` - `memory_store_id: string` The ID of the memory store for the dream to read (`memstore_...`). The memory store must be in the same workspace as the dream and must not be archived. minLength: 1 - `beta_dream_sessions_input: object` The sessions that a dream reads, given as an entry in `inputs`. - `type: "sessions"` - `session_ids: array of string` The IDs of the sessions whose transcripts the dream reads (`sesn_...`). Give 1 to 100 IDs, with no duplicates. Each session must be in the same workspace as the dream. Responses list the IDs in sorted order. The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#limits) lists all the limits on a dream. - `instructions: string` The guidance given when the dream was created, or `null` if none was given. - `model: object` The model that runs a dream, from the request that created it. The dream uses this model for all of its work. The response always gives the model as an object, even if the request gave only a model ID. - `id: string` The ID of the model that runs the dream, as given in the request that created it. minLength: 1, maxLength: 256 - `speed: optional "standard" or "fast"` How fast the model generates output for the dream. Always `standard`. - `"standard"` - `"fast"` - `output_behavior: BetaOutputBehaviorCreateNew or BetaOutputBehaviorUpdateExisting` Where the dream writes its result, as set in the request that created the dream. If that request left out `output_behavior`, the dream used the `create_new` behavior. - `beta_output_behavior_create_new: object` Write the result to a new memory store that starts as a copy of the input memory store. This is the default. The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store. - `type: "create_new"` - `beta_output_behavior_update_existing: object` Write the result into the input memory store instead of a new memory store. The credential must be allowed to write memory stores, or the request returns a 403 error. While another `update_existing` dream on the same memory store hasn't fully stopped, the request returns a 409 error. - `type: "update_existing"` - `memory_store_id: string` The ID of the memory store for the dream to write its result to (`memstore_...`). It must be the memory store in the `memory_store` entry of `inputs`. minLength: 1 - `outputs: array of BetaDreamOutput` The memory store that holds the dream's result, as a one-item array, or an empty array until the dream records that memory store. The array is empty while the dream is `pending` and for a short time after it starts `running`. It can stay empty if the dream fails or is canceled before then. The memory store holds the complete result only once `status` is `completed`. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#use-the-output) for how to review and use the result. - `type: "memory_store"` - `memory_store_id: string` The ID of the memory store that the dream writes its result to (`memstore_...`). With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store. - `session_id: string` The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started. Stream that session's events to follow what the dream reads and writes. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#watch-the-pipeline-run) for how to watch a running dream. - `status: "pending" or "running" or "completed" or 2 more` Where a dream is in its lifecycle. `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#lifecycle) for what each status means. - `"pending"` The dream is waiting to start and hasn't read its inputs yet. `outputs` is empty and every `usage` count is zero. - `"running"` The dream is reading its inputs and writing its result. `usage` updates while the dream has this status. - `"completed"` The dream finished and its output memory store holds the complete result. - `"failed"` The dream stopped with an error, which `error` describes. If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped. - `"canceled"` A cancel request stopped the dream before it reached `completed` or `failed`. If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel. - `usage: object` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. - `cache_creation_input_tokens: number` The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations. format: int32 - `cache_read_input_tokens: number` The dream's input tokens that were read from the prompt cache. format: int32 - `input_tokens: number` The dream's input tokens that weren't read from or written to the prompt cache. format: int32 - `output_tokens: number` The tokens that the model generated for the dream. format: int32 #### Example ```bash ant beta:dreams create \ --api-key my-anthropic-api-key \ --input '{memory_store_id: x, type: memory_store}' \ --model string ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "ended_at": "2019-12-27T18:11:19.117Z", "error": { "message": "message", "type": "type" }, "inputs": [ { "memory_store_id": "x", "type": "memory_store" } ], "instructions": "instructions", "model": { "id": "x", "speed": "standard" }, "output_behavior": { "type": "create_new" }, "outputs": [ { "memory_store_id": "memory_store_id", "type": "memory_store" } ], "session_id": "session_id", "status": "pending", "type": "dream", "usage": { "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ``` ### List Dreams `$ ant beta:dreams list` **GET** `/v1/dreams` List the dreams in the workspace, newest first. Archived dreams are left out unless `include_archived` is `true`. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#list-dreams) for how to page through dreams. #### Parameters - `--created-at-gt: optional string` (query parameter) Return only dreams created after this time (exclusive), in RFC 3339. format: date-time - `--created-at-lt: optional string` (query parameter) Return only dreams created before this time (exclusive), in RFC 3339. format: date-time - `--include-archived: optional boolean` (query parameter) Whether to include archived dreams. Defaults to `false`. - `--limit: optional number` (query parameter) The maximum number of dreams to return, from 1 to 100. Defaults to 20. format: int32 - `--page: optional string` (query parameter) The cursor for the page to return, taken from `next_page` in a previous response. Leave it out to get the first page. - `--status: optional array of BetaDreamStatus` (query parameter) Return only dreams that have one of these statuses. Repeat the parameter to give more than one status. Leave it out to return dreams of every status. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaListDreamsResponse: object` A page of dreams, newest first. - `data: array of BetaDream` The dreams on this page, newest first. - `type: "dream"` - `id: string` The unique ID of the dream (`drm_...`). - `archived_at: string` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. format: date-time - `created_at: string` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. format: date-time - `ended_at: string` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. format: date-time - `error: object` Why the dream failed, or `null` if `status` isn't `failed`. - `type: string` A code for why the dream failed, such as `timeout` or `internal_error`. The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#errors) lists common error codes and when they occur. - `message: string` A human-readable explanation of why the dream failed. - `inputs: array of BetaDreamInput` The sources that the dream reads, from the request that created it. - `beta_dream_memory_store_input: object` The memory store that a dream reads, given as an entry in `inputs`. With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it. - `type: "memory_store"` - `memory_store_id: string` The ID of the memory store for the dream to read (`memstore_...`). The memory store must be in the same workspace as the dream and must not be archived. minLength: 1 - `beta_dream_sessions_input: object` The sessions that a dream reads, given as an entry in `inputs`. - `type: "sessions"` - `session_ids: array of string` The IDs of the sessions whose transcripts the dream reads (`sesn_...`). Give 1 to 100 IDs, with no duplicates. Each session must be in the same workspace as the dream. Responses list the IDs in sorted order. The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#limits) lists all the limits on a dream. - `instructions: string` The guidance given when the dream was created, or `null` if none was given. - `model: object` The model that runs a dream, from the request that created it. The dream uses this model for all of its work. The response always gives the model as an object, even if the request gave only a model ID. - `id: string` The ID of the model that runs the dream, as given in the request that created it. minLength: 1, maxLength: 256 - `speed: optional "standard" or "fast"` How fast the model generates output for the dream. Always `standard`. - `"standard"` - `"fast"` - `output_behavior: BetaOutputBehaviorCreateNew or BetaOutputBehaviorUpdateExisting` Where the dream writes its result, as set in the request that created the dream. If that request left out `output_behavior`, the dream used the `create_new` behavior. - `beta_output_behavior_create_new: object` Write the result to a new memory store that starts as a copy of the input memory store. This is the default. The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store. - `type: "create_new"` - `beta_output_behavior_update_existing: object` Write the result into the input memory store instead of a new memory store. The credential must be allowed to write memory stores, or the request returns a 403 error. While another `update_existing` dream on the same memory store hasn't fully stopped, the request returns a 409 error. - `type: "update_existing"` - `memory_store_id: string` The ID of the memory store for the dream to write its result to (`memstore_...`). It must be the memory store in the `memory_store` entry of `inputs`. minLength: 1 - `outputs: array of BetaDreamOutput` The memory store that holds the dream's result, as a one-item array, or an empty array until the dream records that memory store. The array is empty while the dream is `pending` and for a short time after it starts `running`. It can stay empty if the dream fails or is canceled before then. The memory store holds the complete result only once `status` is `completed`. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#use-the-output) for how to review and use the result. - `type: "memory_store"` - `memory_store_id: string` The ID of the memory store that the dream writes its result to (`memstore_...`). With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store. - `session_id: string` The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started. Stream that session's events to follow what the dream reads and writes. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#watch-the-pipeline-run) for how to watch a running dream. - `status: "pending" or "running" or "completed" or 2 more` Where a dream is in its lifecycle. `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#lifecycle) for what each status means. - `"pending"` The dream is waiting to start and hasn't read its inputs yet. `outputs` is empty and every `usage` count is zero. - `"running"` The dream is reading its inputs and writing its result. `usage` updates while the dream has this status. - `"completed"` The dream finished and its output memory store holds the complete result. - `"failed"` The dream stopped with an error, which `error` describes. If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped. - `"canceled"` A cancel request stopped the dream before it reached `completed` or `failed`. If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel. - `usage: object` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. - `cache_creation_input_tokens: number` The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations. format: int32 - `cache_read_input_tokens: number` The dream's input tokens that were read from the prompt cache. format: int32 - `input_tokens: number` The dream's input tokens that weren't read from or written to the prompt cache. format: int32 - `output_tokens: number` The tokens that the model generated for the dream. format: int32 - `next_page: string` The cursor for the next page, or `null` if this is the last page. Pass it as `page` to get the next page. #### Example ```bash ant beta:dreams list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "ended_at": "2019-12-27T18:11:19.117Z", "error": { "message": "message", "type": "type" }, "inputs": [ { "memory_store_id": "x", "type": "memory_store" } ], "instructions": "instructions", "model": { "id": "x", "speed": "standard" }, "output_behavior": { "type": "create_new" }, "outputs": [ { "memory_store_id": "memory_store_id", "type": "memory_store" } ], "session_id": "session_id", "status": "pending", "type": "dream", "usage": { "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ], "next_page": "next_page" } ``` ### Get a Dream `$ ant beta:dreams retrieve` **GET** `/v1/dreams/{dream_id}` Get a dream by ID to check its status, output memory store, and token usage. Archived dreams are returned too. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#track-progress) for how to poll a dream and what each status means. #### Parameters - `--dream-id: string` (path parameter) The ID of the dream to get (`drm_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_dream: object` An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store. By default the dream writes its result to a new memory store and doesn't change the input memory store. With `output_behavior` set to `update_existing`, it writes its result into the input memory store instead. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#how-it-works) for what a dream reads and produces. - `type: "dream"` - `id: string` The unique ID of the dream (`drm_...`). - `archived_at: string` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. format: date-time - `created_at: string` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. format: date-time - `ended_at: string` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. format: date-time - `error: object` Why the dream failed, or `null` if `status` isn't `failed`. - `type: string` A code for why the dream failed, such as `timeout` or `internal_error`. The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#errors) lists common error codes and when they occur. - `message: string` A human-readable explanation of why the dream failed. - `inputs: array of BetaDreamInput` The sources that the dream reads, from the request that created it. - `beta_dream_memory_store_input: object` The memory store that a dream reads, given as an entry in `inputs`. With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it. - `type: "memory_store"` - `memory_store_id: string` The ID of the memory store for the dream to read (`memstore_...`). The memory store must be in the same workspace as the dream and must not be archived. minLength: 1 - `beta_dream_sessions_input: object` The sessions that a dream reads, given as an entry in `inputs`. - `type: "sessions"` - `session_ids: array of string` The IDs of the sessions whose transcripts the dream reads (`sesn_...`). Give 1 to 100 IDs, with no duplicates. Each session must be in the same workspace as the dream. Responses list the IDs in sorted order. The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#limits) lists all the limits on a dream. - `instructions: string` The guidance given when the dream was created, or `null` if none was given. - `model: object` The model that runs a dream, from the request that created it. The dream uses this model for all of its work. The response always gives the model as an object, even if the request gave only a model ID. - `id: string` The ID of the model that runs the dream, as given in the request that created it. minLength: 1, maxLength: 256 - `speed: optional "standard" or "fast"` How fast the model generates output for the dream. Always `standard`. - `"standard"` - `"fast"` - `output_behavior: BetaOutputBehaviorCreateNew or BetaOutputBehaviorUpdateExisting` Where the dream writes its result, as set in the request that created the dream. If that request left out `output_behavior`, the dream used the `create_new` behavior. - `beta_output_behavior_create_new: object` Write the result to a new memory store that starts as a copy of the input memory store. This is the default. The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store. - `type: "create_new"` - `beta_output_behavior_update_existing: object` Write the result into the input memory store instead of a new memory store. The credential must be allowed to write memory stores, or the request returns a 403 error. While another `update_existing` dream on the same memory store hasn't fully stopped, the request returns a 409 error. - `type: "update_existing"` - `memory_store_id: string` The ID of the memory store for the dream to write its result to (`memstore_...`). It must be the memory store in the `memory_store` entry of `inputs`. minLength: 1 - `outputs: array of BetaDreamOutput` The memory store that holds the dream's result, as a one-item array, or an empty array until the dream records that memory store. The array is empty while the dream is `pending` and for a short time after it starts `running`. It can stay empty if the dream fails or is canceled before then. The memory store holds the complete result only once `status` is `completed`. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#use-the-output) for how to review and use the result. - `type: "memory_store"` - `memory_store_id: string` The ID of the memory store that the dream writes its result to (`memstore_...`). With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store. - `session_id: string` The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started. Stream that session's events to follow what the dream reads and writes. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#watch-the-pipeline-run) for how to watch a running dream. - `status: "pending" or "running" or "completed" or 2 more` Where a dream is in its lifecycle. `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#lifecycle) for what each status means. - `"pending"` The dream is waiting to start and hasn't read its inputs yet. `outputs` is empty and every `usage` count is zero. - `"running"` The dream is reading its inputs and writing its result. `usage` updates while the dream has this status. - `"completed"` The dream finished and its output memory store holds the complete result. - `"failed"` The dream stopped with an error, which `error` describes. If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped. - `"canceled"` A cancel request stopped the dream before it reached `completed` or `failed`. If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel. - `usage: object` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. - `cache_creation_input_tokens: number` The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations. format: int32 - `cache_read_input_tokens: number` The dream's input tokens that were read from the prompt cache. format: int32 - `input_tokens: number` The dream's input tokens that weren't read from or written to the prompt cache. format: int32 - `output_tokens: number` The tokens that the model generated for the dream. format: int32 #### Example ```bash ant beta:dreams retrieve \ --api-key my-anthropic-api-key \ --dream-id dream_id ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "ended_at": "2019-12-27T18:11:19.117Z", "error": { "message": "message", "type": "type" }, "inputs": [ { "memory_store_id": "x", "type": "memory_store" } ], "instructions": "instructions", "model": { "id": "x", "speed": "standard" }, "output_behavior": { "type": "create_new" }, "outputs": [ { "memory_store_id": "memory_store_id", "type": "memory_store" } ], "session_id": "session_id", "status": "pending", "type": "dream", "usage": { "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ``` ### Cancel a Dream `$ ant beta:dreams cancel` **POST** `/v1/dreams/{dream_id}/cancel` Stop a `pending` or `running` dream. The response shows `status` as `canceled`, unless the dream reached `completed` or `failed` first. `usage` can keep changing after the response. Canceling a `canceled` dream returns it unchanged. Canceling a `completed` or `failed` dream returns a 400 error. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#cancel-a-dream) to learn more about canceling dreams. #### Parameters - `--dream-id: string` (path parameter) The ID of the dream to cancel (`drm_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_dream: object` An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store. By default the dream writes its result to a new memory store and doesn't change the input memory store. With `output_behavior` set to `update_existing`, it writes its result into the input memory store instead. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#how-it-works) for what a dream reads and produces. - `type: "dream"` - `id: string` The unique ID of the dream (`drm_...`). - `archived_at: string` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. format: date-time - `created_at: string` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. format: date-time - `ended_at: string` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. format: date-time - `error: object` Why the dream failed, or `null` if `status` isn't `failed`. - `type: string` A code for why the dream failed, such as `timeout` or `internal_error`. The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#errors) lists common error codes and when they occur. - `message: string` A human-readable explanation of why the dream failed. - `inputs: array of BetaDreamInput` The sources that the dream reads, from the request that created it. - `beta_dream_memory_store_input: object` The memory store that a dream reads, given as an entry in `inputs`. With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it. - `type: "memory_store"` - `memory_store_id: string` The ID of the memory store for the dream to read (`memstore_...`). The memory store must be in the same workspace as the dream and must not be archived. minLength: 1 - `beta_dream_sessions_input: object` The sessions that a dream reads, given as an entry in `inputs`. - `type: "sessions"` - `session_ids: array of string` The IDs of the sessions whose transcripts the dream reads (`sesn_...`). Give 1 to 100 IDs, with no duplicates. Each session must be in the same workspace as the dream. Responses list the IDs in sorted order. The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#limits) lists all the limits on a dream. - `instructions: string` The guidance given when the dream was created, or `null` if none was given. - `model: object` The model that runs a dream, from the request that created it. The dream uses this model for all of its work. The response always gives the model as an object, even if the request gave only a model ID. - `id: string` The ID of the model that runs the dream, as given in the request that created it. minLength: 1, maxLength: 256 - `speed: optional "standard" or "fast"` How fast the model generates output for the dream. Always `standard`. - `"standard"` - `"fast"` - `output_behavior: BetaOutputBehaviorCreateNew or BetaOutputBehaviorUpdateExisting` Where the dream writes its result, as set in the request that created the dream. If that request left out `output_behavior`, the dream used the `create_new` behavior. - `beta_output_behavior_create_new: object` Write the result to a new memory store that starts as a copy of the input memory store. This is the default. The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store. - `type: "create_new"` - `beta_output_behavior_update_existing: object` Write the result into the input memory store instead of a new memory store. The credential must be allowed to write memory stores, or the request returns a 403 error. While another `update_existing` dream on the same memory store hasn't fully stopped, the request returns a 409 error. - `type: "update_existing"` - `memory_store_id: string` The ID of the memory store for the dream to write its result to (`memstore_...`). It must be the memory store in the `memory_store` entry of `inputs`. minLength: 1 - `outputs: array of BetaDreamOutput` The memory store that holds the dream's result, as a one-item array, or an empty array until the dream records that memory store. The array is empty while the dream is `pending` and for a short time after it starts `running`. It can stay empty if the dream fails or is canceled before then. The memory store holds the complete result only once `status` is `completed`. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#use-the-output) for how to review and use the result. - `type: "memory_store"` - `memory_store_id: string` The ID of the memory store that the dream writes its result to (`memstore_...`). With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store. - `session_id: string` The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started. Stream that session's events to follow what the dream reads and writes. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#watch-the-pipeline-run) for how to watch a running dream. - `status: "pending" or "running" or "completed" or 2 more` Where a dream is in its lifecycle. `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#lifecycle) for what each status means. - `"pending"` The dream is waiting to start and hasn't read its inputs yet. `outputs` is empty and every `usage` count is zero. - `"running"` The dream is reading its inputs and writing its result. `usage` updates while the dream has this status. - `"completed"` The dream finished and its output memory store holds the complete result. - `"failed"` The dream stopped with an error, which `error` describes. If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped. - `"canceled"` A cancel request stopped the dream before it reached `completed` or `failed`. If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel. - `usage: object` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. - `cache_creation_input_tokens: number` The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations. format: int32 - `cache_read_input_tokens: number` The dream's input tokens that were read from the prompt cache. format: int32 - `input_tokens: number` The dream's input tokens that weren't read from or written to the prompt cache. format: int32 - `output_tokens: number` The tokens that the model generated for the dream. format: int32 #### Example ```bash ant beta:dreams cancel \ --api-key my-anthropic-api-key \ --dream-id dream_id ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "ended_at": "2019-12-27T18:11:19.117Z", "error": { "message": "message", "type": "type" }, "inputs": [ { "memory_store_id": "x", "type": "memory_store" } ], "instructions": "instructions", "model": { "id": "x", "speed": "standard" }, "output_behavior": { "type": "create_new" }, "outputs": [ { "memory_store_id": "memory_store_id", "type": "memory_store" } ], "session_id": "session_id", "status": "pending", "type": "dream", "usage": { "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ``` ### Archive a Dream `$ ant beta:dreams archive` **POST** `/v1/dreams/{dream_id}/archive` Hide a `completed`, `failed`, or `canceled` dream from the default list of dreams. Archiving a `pending` or `running` dream returns a 400 error, so cancel it first. Archiving an archived dream returns it unchanged. An archived dream can still be fetched by ID. Archiving can't be undone. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#archive-a-dream) to learn more about archiving dreams. #### Parameters - `--dream-id: string` (path parameter) The ID of the dream to archive (`drm_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `dreaming-2026-04-21` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_dream: object` An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store. By default the dream writes its result to a new memory store and doesn't change the input memory store. With `output_behavior` set to `update_existing`, it writes its result into the input memory store instead. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#how-it-works) for what a dream reads and produces. - `type: "dream"` - `id: string` The unique ID of the dream (`drm_...`). - `archived_at: string` When the dream was archived, in RFC 3339, or `null` if it hasn't been archived. format: date-time - `created_at: string` When the dream was created, in RFC 3339. Lists of dreams are sorted by this time, newest first. format: date-time - `ended_at: string` When the dream reached `completed`, `failed`, or `canceled`, in RFC 3339, or `null` if it is still `pending` or `running`. format: date-time - `error: object` Why the dream failed, or `null` if `status` isn't `failed`. - `type: string` A code for why the dream failed, such as `timeout` or `internal_error`. The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#errors) lists common error codes and when they occur. - `message: string` A human-readable explanation of why the dream failed. - `inputs: array of BetaDreamInput` The sources that the dream reads, from the request that created it. - `beta_dream_memory_store_input: object` The memory store that a dream reads, given as an entry in `inputs`. With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it. - `type: "memory_store"` - `memory_store_id: string` The ID of the memory store for the dream to read (`memstore_...`). The memory store must be in the same workspace as the dream and must not be archived. minLength: 1 - `beta_dream_sessions_input: object` The sessions that a dream reads, given as an entry in `inputs`. - `type: "sessions"` - `session_ids: array of string` The IDs of the sessions whose transcripts the dream reads (`sesn_...`). Give 1 to 100 IDs, with no duplicates. Each session must be in the same workspace as the dream. Responses list the IDs in sorted order. The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#limits) lists all the limits on a dream. - `instructions: string` The guidance given when the dream was created, or `null` if none was given. - `model: object` The model that runs a dream, from the request that created it. The dream uses this model for all of its work. The response always gives the model as an object, even if the request gave only a model ID. - `id: string` The ID of the model that runs the dream, as given in the request that created it. minLength: 1, maxLength: 256 - `speed: optional "standard" or "fast"` How fast the model generates output for the dream. Always `standard`. - `"standard"` - `"fast"` - `output_behavior: BetaOutputBehaviorCreateNew or BetaOutputBehaviorUpdateExisting` Where the dream writes its result, as set in the request that created the dream. If that request left out `output_behavior`, the dream used the `create_new` behavior. - `beta_output_behavior_create_new: object` Write the result to a new memory store that starts as a copy of the input memory store. This is the default. The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store. - `type: "create_new"` - `beta_output_behavior_update_existing: object` Write the result into the input memory store instead of a new memory store. The credential must be allowed to write memory stores, or the request returns a 403 error. While another `update_existing` dream on the same memory store hasn't fully stopped, the request returns a 409 error. - `type: "update_existing"` - `memory_store_id: string` The ID of the memory store for the dream to write its result to (`memstore_...`). It must be the memory store in the `memory_store` entry of `inputs`. minLength: 1 - `outputs: array of BetaDreamOutput` The memory store that holds the dream's result, as a one-item array, or an empty array until the dream records that memory store. The array is empty while the dream is `pending` and for a short time after it starts `running`. It can stay empty if the dream fails or is canceled before then. The memory store holds the complete result only once `status` is `completed`. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#use-the-output) for how to review and use the result. - `type: "memory_store"` - `memory_store_id: string` The ID of the memory store that the dream writes its result to (`memstore_...`). With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store. - `session_id: string` The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started. Stream that session's events to follow what the dream reads and writes. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#watch-the-pipeline-run) for how to watch a running dream. - `status: "pending" or "running" or "completed" or 2 more` Where a dream is in its lifecycle. `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again. See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams?sdk_languages=cli#lifecycle) for what each status means. - `"pending"` The dream is waiting to start and hasn't read its inputs yet. `outputs` is empty and every `usage` count is zero. - `"running"` The dream is reading its inputs and writing its result. `usage` updates while the dream has this status. - `"completed"` The dream finished and its output memory store holds the complete result. - `"failed"` The dream stopped with an error, which `error` describes. If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped. - `"canceled"` A cancel request stopped the dream before it reached `completed` or `failed`. If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel. - `usage: object` The dream's token counts, which stop changing once its `status` is `completed` or `failed`. After a cancel, they can keep changing. - `cache_creation_input_tokens: number` The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations. format: int32 - `cache_read_input_tokens: number` The dream's input tokens that were read from the prompt cache. format: int32 - `input_tokens: number` The dream's input tokens that weren't read from or written to the prompt cache. format: int32 - `output_tokens: number` The tokens that the model generated for the dream. format: int32 #### Example ```bash ant beta:dreams archive \ --api-key my-anthropic-api-key \ --dream-id dream_id ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "ended_at": "2019-12-27T18:11:19.117Z", "error": { "message": "message", "type": "type" }, "inputs": [ { "memory_store_id": "x", "type": "memory_store" } ], "instructions": "instructions", "model": { "id": "x", "speed": "standard" }, "output_behavior": { "type": "create_new" }, "outputs": [ { "memory_store_id": "memory_store_id", "type": "memory_store" } ], "session_id": "session_id", "status": "pending", "type": "dream", "usage": { "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ``` ## Beta › Tunnels ### Create Tunnel `$ ant beta:tunnels create` **POST** `/v1/tunnels` The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window. Creates a tunnel. Creation allocates a fresh hostname and provisions the tunnel; it is not idempotent. The new tunnel rejects MCP traffic until at least one CA certificate is added. #### Parameters - `--display-name: optional string` Optional human-readable name for the tunnel (1-255 characters). minLength: 1, maxLength: 255 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_tunnel: object` An MCP tunnel. - `type: "tunnel"` - `id: string` Unique identifier for the tunnel, prefixed with `tnl_`. - `archived_at: string` RFC 3339 datetime string indicating when the tunnel was archived. Null if it is not archived. format: date-time - `created_at: string` RFC 3339 datetime string indicating when the tunnel was created. format: date-time - `display_name: string` Human-readable name for the tunnel (1-255 characters). Null if unset. - `domain: string` Anthropic-assigned hostname for the tunnel. MCP server URLs whose host is a subdomain of this value are routed through the tunnel. Globally unique and never reused, even after the tunnel is archived. #### Example ```bash ant beta:tunnels create \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "display_name": "display_name", "domain": "domain", "type": "tunnel" } ``` ### Get Tunnel `$ ant beta:tunnels retrieve` **GET** `/v1/tunnels/{tunnel_id}` The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window. Fetches a tunnel by ID. #### Parameters - `--tunnel-id: string` (path parameter) ID of the tunnel (`tnl_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_tunnel: object` An MCP tunnel. - `type: "tunnel"` - `id: string` Unique identifier for the tunnel, prefixed with `tnl_`. - `archived_at: string` RFC 3339 datetime string indicating when the tunnel was archived. Null if it is not archived. format: date-time - `created_at: string` RFC 3339 datetime string indicating when the tunnel was created. format: date-time - `display_name: string` Human-readable name for the tunnel (1-255 characters). Null if unset. - `domain: string` Anthropic-assigned hostname for the tunnel. MCP server URLs whose host is a subdomain of this value are routed through the tunnel. Globally unique and never reused, even after the tunnel is archived. #### Example ```bash ant beta:tunnels retrieve \ --api-key my-anthropic-api-key \ --tunnel-id tunnel_id ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "display_name": "display_name", "domain": "domain", "type": "tunnel" } ``` ### List Tunnels `$ ant beta:tunnels list` **GET** `/v1/tunnels` The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window. Lists tunnels. Results are ordered by creation time, newest first; archived tunnels are excluded unless include_archived is set. #### Parameters - `--include-archived: optional boolean` (query parameter) Whether to include archived tunnels in the results. Defaults to false. - `--limit: optional number` (query parameter) Maximum number of tunnels to return per page. Defaults to 20, maximum 1000. format: int32 - `--page: optional string` (query parameter) Opaque pagination cursor from a previous `list_tunnels` response. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaListTunnelsResponse: object` A paginated list of tunnels. - `data: array of BetaTunnel` List of tunnels, ordered by created_at descending. - `type: "tunnel"` - `id: string` Unique identifier for the tunnel, prefixed with `tnl_`. - `archived_at: string` RFC 3339 datetime string indicating when the tunnel was archived. Null if it is not archived. format: date-time - `created_at: string` RFC 3339 datetime string indicating when the tunnel was created. format: date-time - `display_name: string` Human-readable name for the tunnel (1-255 characters). Null if unset. - `domain: string` Anthropic-assigned hostname for the tunnel. MCP server URLs whose host is a subdomain of this value are routed through the tunnel. Globally unique and never reused, even after the tunnel is archived. - `next_page: string` Pagination cursor for the next page, or null if no more results. #### Example ```bash ant beta:tunnels list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "display_name": "display_name", "domain": "domain", "type": "tunnel" } ], "next_page": "next_page" } ``` ### Archive Tunnel `$ ant beta:tunnels archive` **POST** `/v1/tunnels/{tunnel_id}/archive` The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window. Archives a tunnel. Archival is irreversible: every non-archived certificate on the tunnel is archived in the same operation, the hostname is retired and never re-allocated, and the tunnel token is invalidated. Retrying against an already-archived tunnel returns the existing record unchanged. #### Parameters - `--tunnel-id: string` (path parameter) ID of the tunnel (`tnl_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_tunnel: object` An MCP tunnel. - `type: "tunnel"` - `id: string` Unique identifier for the tunnel, prefixed with `tnl_`. - `archived_at: string` RFC 3339 datetime string indicating when the tunnel was archived. Null if it is not archived. format: date-time - `created_at: string` RFC 3339 datetime string indicating when the tunnel was created. format: date-time - `display_name: string` Human-readable name for the tunnel (1-255 characters). Null if unset. - `domain: string` Anthropic-assigned hostname for the tunnel. MCP server URLs whose host is a subdomain of this value are routed through the tunnel. Globally unique and never reused, even after the tunnel is archived. #### Example ```bash ant beta:tunnels archive \ --api-key my-anthropic-api-key \ --tunnel-id tunnel_id ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "display_name": "display_name", "domain": "domain", "type": "tunnel" } ``` ### Reveal Tunnel Token `$ ant beta:tunnels reveal-token` **POST** `/v1/tunnels/{tunnel_id}/reveal_token` The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window. Reveals a tunnel's connector token. The value is fetched live on each call; Anthropic does not store it. Repeated calls return the same value until the token is rotated. Exposed as POST so the token does not appear in intermediary access logs. #### Parameters - `--tunnel-id: string` (path parameter) ID of the tunnel (`tnl_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_tunnel_token: object` A tunnel's connector token. - `type: "tunnel_token"` - `id: string` Stable identifier for the current token value. Changes when the token is rotated. - `tunnel_token: string` The connector token used to run the tunnel. Treat as a credential. #### Example ```bash ant beta:tunnels reveal-token \ --api-key my-anthropic-api-key \ --tunnel-id tunnel_id ``` ##### Response (200) ```json { "id": "id", "tunnel_token": "tunnel_token", "type": "tunnel_token" } ``` ### Rotate Tunnel Token `$ ant beta:tunnels rotate-token` **POST** `/v1/tunnels/{tunnel_id}/rotate_token` The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window. Rotates a tunnel's connector token. Rotation invalidates the current token for new connections and returns a fresh value; established connections are not severed. A connector restarted after rotation must use the new value. #### Parameters - `--tunnel-id: string` (path parameter) ID of the tunnel (`tnl_...`). - `--reason: optional string` Optional free-text reason for the rotation, recorded for audit. maxLength: 1024 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_tunnel_token: object` A tunnel's connector token. - `type: "tunnel_token"` - `id: string` Stable identifier for the current token value. Changes when the token is rotated. - `tunnel_token: string` The connector token used to run the tunnel. Treat as a credential. #### Example ```bash ant beta:tunnels rotate-token \ --api-key my-anthropic-api-key \ --tunnel-id tunnel_id ``` ##### Response (200) ```json { "id": "id", "tunnel_token": "tunnel_token", "type": "tunnel_token" } ``` ## Beta › Tunnels › Certificates ### Create Tunnel Certificate `$ ant beta:tunnels:certificates create` **POST** `/v1/tunnels/{tunnel_id}/certificates` The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window. Registers a public CA certificate on a tunnel. Anthropic verifies the gateway's server certificate against this CA when it terminates the inner TLS session. A tunnel holds at most two non-archived certificates. #### Parameters - `--tunnel-id: string` (path parameter) ID of the tunnel (`tnl_...`). - `--ca-certificate-pem: string` PEM-encoded X.509 CA certificate. Must contain exactly one certificate and no private-key material. Maximum 8KB. maxLength: 8192 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_tunnel_certificate: object` A CA certificate attached to a tunnel. - `type: "tunnel_certificate"` - `id: string` Unique identifier for the certificate, prefixed with `tcrt_`. - `archived_at: string` RFC 3339 datetime string indicating when the certificate was archived. Null if it is still in the trusted set. format: date-time - `created_at: string` RFC 3339 datetime string indicating when the certificate was registered. format: date-time - `expires_at: string` RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire. format: date-time - `fingerprint: string` Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. - `tunnel_id: string` ID of the tunnel the certificate is registered against. #### Example ```bash ant beta:tunnels:certificates create \ --api-key my-anthropic-api-key \ --tunnel-id tunnel_id \ --ca-certificate-pem ca_certificate_pem ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "expires_at": "2019-12-27T18:11:19.117Z", "fingerprint": "fingerprint", "tunnel_id": "tunnel_id", "type": "tunnel_certificate" } ``` ### Get Tunnel Certificate `$ ant beta:tunnels:certificates retrieve` **GET** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}` The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window. Fetches a tunnel certificate by ID. #### Parameters - `--tunnel-id: string` (path parameter) ID of the tunnel (`tnl_...`). - `--certificate-id: string` (path parameter) ID of the certificate (`tcrt_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_tunnel_certificate: object` A CA certificate attached to a tunnel. - `type: "tunnel_certificate"` - `id: string` Unique identifier for the certificate, prefixed with `tcrt_`. - `archived_at: string` RFC 3339 datetime string indicating when the certificate was archived. Null if it is still in the trusted set. format: date-time - `created_at: string` RFC 3339 datetime string indicating when the certificate was registered. format: date-time - `expires_at: string` RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire. format: date-time - `fingerprint: string` Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. - `tunnel_id: string` ID of the tunnel the certificate is registered against. #### Example ```bash ant beta:tunnels:certificates retrieve \ --api-key my-anthropic-api-key \ --tunnel-id tunnel_id \ --certificate-id certificate_id ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "expires_at": "2019-12-27T18:11:19.117Z", "fingerprint": "fingerprint", "tunnel_id": "tunnel_id", "type": "tunnel_certificate" } ``` ### List Tunnel Certificates `$ ant beta:tunnels:certificates list` **GET** `/v1/tunnels/{tunnel_id}/certificates` The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window. Lists the certificates registered on a tunnel. Archived certificates are excluded unless include_archived is set. #### Parameters - `--tunnel-id: string` (path parameter) ID of the tunnel (`tnl_...`). - `--include-archived: optional boolean` (query parameter) Whether to include archived certificates in the results. Defaults to false. - `--limit: optional number` (query parameter) Maximum number of certificates to return per page. Defaults to 20, maximum 1000. format: int32 - `--page: optional string` (query parameter) Opaque pagination cursor from a previous `list_tunnel_certificates` response. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `BetaListTunnelCertificatesResponse: object` The tunnel's certificates. - `data: array of BetaTunnelCertificate` List of certificates, ordered by created_at descending. - `type: "tunnel_certificate"` - `id: string` Unique identifier for the certificate, prefixed with `tcrt_`. - `archived_at: string` RFC 3339 datetime string indicating when the certificate was archived. Null if it is still in the trusted set. format: date-time - `created_at: string` RFC 3339 datetime string indicating when the certificate was registered. format: date-time - `expires_at: string` RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire. format: date-time - `fingerprint: string` Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. - `tunnel_id: string` ID of the tunnel the certificate is registered against. - `next_page: string` Pagination cursor for the next page, or null if no more results. #### Example ```bash ant beta:tunnels:certificates list \ --api-key my-anthropic-api-key \ --tunnel-id tunnel_id ``` ##### Response (200) ```json { "data": [ { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "expires_at": "2019-12-27T18:11:19.117Z", "fingerprint": "fingerprint", "tunnel_id": "tunnel_id", "type": "tunnel_certificate" } ], "next_page": "next_page" } ``` ### Archive Tunnel Certificate `$ ant beta:tunnels:certificates archive` **POST** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}/archive` The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window. Archives a tunnel certificate, removing it from the set Anthropic trusts for the tunnel. The certificate record is retained. Archiving the last non-archived certificate is permitted; the tunnel rejects MCP traffic until a new certificate is added. #### Parameters - `--tunnel-id: string` (path parameter) ID of the tunnel (`tnl_...`). - `--certificate-id: string` (path parameter) ID of the certificate to archive (`tcrt_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `mcp-tunnels-2026-06-22` in this header. - `--workspace-id: optional string` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. #### Returns - `beta_tunnel_certificate: object` A CA certificate attached to a tunnel. - `type: "tunnel_certificate"` - `id: string` Unique identifier for the certificate, prefixed with `tcrt_`. - `archived_at: string` RFC 3339 datetime string indicating when the certificate was archived. Null if it is still in the trusted set. format: date-time - `created_at: string` RFC 3339 datetime string indicating when the certificate was registered. format: date-time - `expires_at: string` RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire. format: date-time - `fingerprint: string` Lowercase hex SHA-256 fingerprint of the certificate's DER encoding. - `tunnel_id: string` ID of the tunnel the certificate is registered against. #### Example ```bash ant beta:tunnels:certificates archive \ --api-key my-anthropic-api-key \ --tunnel-id tunnel_id \ --certificate-id certificate_id ``` ##### Response (200) ```json { "id": "id", "archived_at": "2019-12-27T18:11:19.117Z", "created_at": "2019-12-27T18:11:19.117Z", "expires_at": "2019-12-27T18:11:19.117Z", "fingerprint": "fingerprint", "tunnel_id": "tunnel_id", "type": "tunnel_certificate" } ``` ## Beta › Organization ### Get Current Organization `$ ant beta:organization retrieve` **GET** `/v1/organizations/me` Retrieve information about the organization associated with the authenticated API key. #### Returns - `beta_organization: object` - `type: "organization"` Object type. For Organizations, this is always `"organization"`. - `id: string` ID of the Organization. format: uuid - `name: string` Name of the Organization. #### Example ```bash ant beta:organization retrieve \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "id": "12345678-1234-5678-1234-567812345678", "name": "Organization Name", "type": "organization" } ``` ## Beta › Organization › API Keys ### List API Keys `$ ant beta:organization:api-keys list` **GET** `/v1/organizations/api_keys` List API Keys #### Parameters - `--after-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - `--before-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - `--created-by-user-id: optional string` (query parameter) Filter by the ID of the User who created the object. - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--status: optional "active" or "archived" or "expired" or "inactive"` (query parameter) Filter by API key status. - `--workspace-id: optional string` (query parameter) Filter by Workspace ID. #### Returns - `BetaListResponse_ApiKey_: object` - `data: array of BetaAPIKey` - `type: "api_key"` Object type. For API Keys, this is always `"api_key"`. - `id: string` ID of the API key. - `created_at: string` RFC 3339 datetime string indicating when the API Key was created. format: date-time - `created_by: object` The ID and type of the actor that created the API key, or `null` when the creator is not recorded (legacy, workload-identity-federated, or system-created keys). - `type: "service_account" or "user"` Type of the actor that created the object. - `"service_account"` - `"user"` - `id: string` ID of the actor that created the object. - `expires_at: string` RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires. format: date-time - `name: string` Name of the API key. - `partial_key_hint: string` Partially redacted hint for the API key. - `principal: BetaAPIKeyUserActor or BetaAPIKeyServiceAccountActor` The principal the API key acts as (a User or a Service Account), or `null` if the API key is not bound to a principal. - `beta_api_key_user_actor: object` - `type: "user_actor"` Principal type. Always `"user_actor"` for a User. - `user_id: string` ID of the User the API key acts as. - `beta_api_key_service_account_actor: object` - `type: "service_account_actor"` Principal type. Always `"service_account_actor"` for a Service Account. - `service_account_id: string` ID of the Service Account the API key acts as. - `scope: BetaAPIKeyOrganizationScope or BetaAPIKeyWorkspaceScope` Where the API key belongs: its Workspace (`{"type": "workspace", "workspace_id": "wrkspc_..."}`, with the Workspace's real ID even when it is the organization's default Workspace), or the organization (`{"type": "organization"}`) for a principal-bound API key that has no Workspace. - `beta_api_key_organization_scope: object` - `type: "organization"` Scope type. Always `"organization"`: the API key has no Workspace. Only a principal-bound API key can have this scope. - `beta_api_key_workspace_scope: object` - `type: "workspace"` Scope type. Always `"workspace"`: the API key belongs to one Workspace. - `workspace_id: string` ID of the Workspace the API key belongs to. Unlike the deprecated top-level `workspace_id`, this is the Workspace's real ID even for the organization's default Workspace. - `status: "active" or "archived" or "expired" or "inactive"` Status of the API key. - `"active"` - `"archived"` - `"expired"` - `"inactive"` - `workspace_id: string` **Deprecated**: Use `scope` instead. `workspace_id` is `null` both for an API key in the default Workspace and for a principal-bound API key that has no Workspace. Deprecated: use `scope` instead. ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace. Also `null` for a principal-bound API key that has no Workspace; `scope` tells the two apart. - `first_id: string` First ID in the `data` list. Can be used as the `before_id` for the previous page. - `has_more: boolean` Indicates if there are more results in the requested page direction. - `last_id: string` Last ID in the `data` list. Can be used as the `after_id` for the next page. #### Example ```bash ant beta:organization:api-keys list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "created_at": "2024-10-30T23:58:27.427722Z", "created_by": { "id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "type": "user" }, "expires_at": "2024-10-30T23:58:27.427722Z", "name": "Developer Key", "partial_key_hint": "sk-ant-api03-R2D...igAA", "principal": { "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "scope": { "type": "workspace", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "status": "active", "type": "api_key", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ### Retrieve API Key (Admin API) `$ ant beta:organization:api-keys retrieve` **GET** `/v1/organizations/api_keys/{api_key_id}` Retrieve information about a single API key in your organization, looked up by its ID. This Admin API endpoint requires an Admin API key, is intended for programmatic key management, and never returns the key's secret value. To view or create your own API keys, go to [API keys](https://platform.claude.com/settings/keys) in the Claude Console. #### Parameters - `--api-key-id: string` (path parameter) ID of the API key. #### Returns - `beta_api_key: object` - `type: "api_key"` Object type. For API Keys, this is always `"api_key"`. - `id: string` ID of the API key. - `created_at: string` RFC 3339 datetime string indicating when the API Key was created. format: date-time - `created_by: object` The ID and type of the actor that created the API key, or `null` when the creator is not recorded (legacy, workload-identity-federated, or system-created keys). - `type: "service_account" or "user"` Type of the actor that created the object. - `"service_account"` - `"user"` - `id: string` ID of the actor that created the object. - `expires_at: string` RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires. format: date-time - `name: string` Name of the API key. - `partial_key_hint: string` Partially redacted hint for the API key. - `principal: BetaAPIKeyUserActor or BetaAPIKeyServiceAccountActor` The principal the API key acts as (a User or a Service Account), or `null` if the API key is not bound to a principal. - `beta_api_key_user_actor: object` - `type: "user_actor"` Principal type. Always `"user_actor"` for a User. - `user_id: string` ID of the User the API key acts as. - `beta_api_key_service_account_actor: object` - `type: "service_account_actor"` Principal type. Always `"service_account_actor"` for a Service Account. - `service_account_id: string` ID of the Service Account the API key acts as. - `scope: BetaAPIKeyOrganizationScope or BetaAPIKeyWorkspaceScope` Where the API key belongs: its Workspace (`{"type": "workspace", "workspace_id": "wrkspc_..."}`, with the Workspace's real ID even when it is the organization's default Workspace), or the organization (`{"type": "organization"}`) for a principal-bound API key that has no Workspace. - `beta_api_key_organization_scope: object` - `type: "organization"` Scope type. Always `"organization"`: the API key has no Workspace. Only a principal-bound API key can have this scope. - `beta_api_key_workspace_scope: object` - `type: "workspace"` Scope type. Always `"workspace"`: the API key belongs to one Workspace. - `workspace_id: string` ID of the Workspace the API key belongs to. Unlike the deprecated top-level `workspace_id`, this is the Workspace's real ID even for the organization's default Workspace. - `status: "active" or "archived" or "expired" or "inactive"` Status of the API key. - `"active"` - `"archived"` - `"expired"` - `"inactive"` - `workspace_id: string` **Deprecated**: Use `scope` instead. `workspace_id` is `null` both for an API key in the default Workspace and for a principal-bound API key that has no Workspace. Deprecated: use `scope` instead. ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace. Also `null` for a principal-bound API key that has no Workspace; `scope` tells the two apart. #### Example ```bash ant beta:organization:api-keys retrieve \ --api-key my-anthropic-api-key \ --api-key-id api_key_id ``` ##### Response (200) ```json { "id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "created_at": "2024-10-30T23:58:27.427722Z", "created_by": { "id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "type": "user" }, "expires_at": "2024-10-30T23:58:27.427722Z", "name": "Developer Key", "partial_key_hint": "sk-ant-api03-R2D...igAA", "principal": { "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "scope": { "type": "workspace", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "status": "active", "type": "api_key", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } ``` ### Update API Key `$ ant beta:organization:api-keys update` **POST** `/v1/organizations/api_keys/{api_key_id}` Update API Key #### Parameters - `--api-key-id: string` (path parameter) ID of the API key. - `--name: optional string` Name of the API key. minLength: 1, maxLength: 500 - `--status: optional "active" or "archived" or "inactive"` Status of the API key. #### Returns - `beta_api_key: object` - `type: "api_key"` Object type. For API Keys, this is always `"api_key"`. - `id: string` ID of the API key. - `created_at: string` RFC 3339 datetime string indicating when the API Key was created. format: date-time - `created_by: object` The ID and type of the actor that created the API key, or `null` when the creator is not recorded (legacy, workload-identity-federated, or system-created keys). - `type: "service_account" or "user"` Type of the actor that created the object. - `"service_account"` - `"user"` - `id: string` ID of the actor that created the object. - `expires_at: string` RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires. format: date-time - `name: string` Name of the API key. - `partial_key_hint: string` Partially redacted hint for the API key. - `principal: BetaAPIKeyUserActor or BetaAPIKeyServiceAccountActor` The principal the API key acts as (a User or a Service Account), or `null` if the API key is not bound to a principal. - `beta_api_key_user_actor: object` - `type: "user_actor"` Principal type. Always `"user_actor"` for a User. - `user_id: string` ID of the User the API key acts as. - `beta_api_key_service_account_actor: object` - `type: "service_account_actor"` Principal type. Always `"service_account_actor"` for a Service Account. - `service_account_id: string` ID of the Service Account the API key acts as. - `scope: BetaAPIKeyOrganizationScope or BetaAPIKeyWorkspaceScope` Where the API key belongs: its Workspace (`{"type": "workspace", "workspace_id": "wrkspc_..."}`, with the Workspace's real ID even when it is the organization's default Workspace), or the organization (`{"type": "organization"}`) for a principal-bound API key that has no Workspace. - `beta_api_key_organization_scope: object` - `type: "organization"` Scope type. Always `"organization"`: the API key has no Workspace. Only a principal-bound API key can have this scope. - `beta_api_key_workspace_scope: object` - `type: "workspace"` Scope type. Always `"workspace"`: the API key belongs to one Workspace. - `workspace_id: string` ID of the Workspace the API key belongs to. Unlike the deprecated top-level `workspace_id`, this is the Workspace's real ID even for the organization's default Workspace. - `status: "active" or "archived" or "expired" or "inactive"` Status of the API key. - `"active"` - `"archived"` - `"expired"` - `"inactive"` - `workspace_id: string` **Deprecated**: Use `scope` instead. `workspace_id` is `null` both for an API key in the default Workspace and for a principal-bound API key that has no Workspace. Deprecated: use `scope` instead. ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace. Also `null` for a principal-bound API key that has no Workspace; `scope` tells the two apart. #### Example ```bash ant beta:organization:api-keys update \ --api-key my-anthropic-api-key \ --api-key-id api_key_id ``` ##### Response (200) ```json { "id": "apikey_01Rj2N8SVvo6BePZj99NhmiT", "created_at": "2024-10-30T23:58:27.427722Z", "created_by": { "id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "type": "user" }, "expires_at": "2024-10-30T23:58:27.427722Z", "name": "Developer Key", "partial_key_hint": "sk-ant-api03-R2D...igAA", "principal": { "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "scope": { "type": "workspace", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "status": "active", "type": "api_key", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } ``` ## Beta › Organization › External Keys ### Create External Key `$ ant beta:organization:external-keys create` **POST** `/v1/organizations/external_keys` Create an external key config owned by the caller's organization. #### Parameters - `--provider-config: BetaAWSExternalKeyConfig or BetaGCPExternalKeyConfig or BetaAzureExternalKeyConfigParam` KMS provider identity and auth coordinates. - `--display-name: optional string` Human-friendly display name. minLength: 1, maxLength: 255 - `--geo: optional "us"` Data residency geo. Only `us` is supported. #### Returns - `beta_external_key: object` CMEK external key config belonging to the caller's organization. Configs are organization-scoped. Workspaces attach to a config; once any workspace references it, the provider fields become effectively immutable (existing encrypted data needs the config for decrypt). - `type: "external_key"` - `id: string` Identifier of the external key config. A tagged ID prefixed `ekey_`, or — for organizations on the Claude Platform on AWS — the AWS KMS key ARN. - `attachment: BetaExternalKeyAttachedAttachment or BetaExternalKeyUnattachedAttachment` Whether any workspace uses this config to encrypt its data — counting live and archived workspaces (an archived workspace's data remains encrypted under the config), excluding deleted ones. Only an attached config is used by the encryption path; an `unattached` config is inert and can be deleted. - `beta_external_key_attached_attachment: object` - `type: "attached"` - `beta_external_key_unattached_attachment: object` - `type: "unattached"` - `created_at: string` format: date-time - `display_name: string` Human-friendly display name. Null if none was set. - `geo: string` Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips. - `provider_config: BetaAWSExternalKeyConfig or BetaGCPExternalKeyConfig or BetaAzureExternalKeyConfig` KMS provider identity and auth coordinates. - `beta_aws_external_key_config: object` - `type: "aws"` - `kms_arn: string` Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected. maxLength: 2048 - `region: optional string` AWS region. Derived from `kms_arn` if omitted. - `role_arn: optional string` **Deprecated** IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored. - `beta_gcp_external_key_config: object` - `type: "gcp"` - `key_name: string` Full resource name of the Cloud KMS key. - `beta_azure_external_key_config: object` - `type: "azure"` - `key_name: string` Name of the key within the vault. - `tenant_id: string` Azure AD tenant ID. - `vault_uri: string` Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`. - `client_id: optional string` Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory. - `updated_at: string` format: date-time #### Example ```bash ant beta:organization:external-keys create \ --api-key my-anthropic-api-key \ --provider-config '{kms_arn: arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222, type: aws}' ``` ##### Response (200) ```json { "id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "attachment": { "type": "attached" }, "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "prod-us-key", "geo": "us", "provider_config": { "kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222", "type": "aws", "region": "us-east-1", "role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek" }, "type": "external_key", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### List External Keys `$ ant beta:organization:external-keys list` **GET** `/v1/organizations/external_keys` List external key configs in the caller's organization. Results are ordered by creation time (newest first). Use the `next_page` cursor from the response to fetch subsequent pages. #### Parameters - `--limit: optional number` (query parameter) Number of results per page. minimum: 1, maximum: 100 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. #### Returns - `BetaExternalKeyListResponse: object` Opaque-cursor page of external keys, ordered by creation time (newest first). - `data: array of BetaExternalKey` - `type: "external_key"` - `id: string` Identifier of the external key config. A tagged ID prefixed `ekey_`, or — for organizations on the Claude Platform on AWS — the AWS KMS key ARN. - `attachment: BetaExternalKeyAttachedAttachment or BetaExternalKeyUnattachedAttachment` Whether any workspace uses this config to encrypt its data — counting live and archived workspaces (an archived workspace's data remains encrypted under the config), excluding deleted ones. Only an attached config is used by the encryption path; an `unattached` config is inert and can be deleted. - `beta_external_key_attached_attachment: object` - `type: "attached"` - `beta_external_key_unattached_attachment: object` - `type: "unattached"` - `created_at: string` format: date-time - `display_name: string` Human-friendly display name. Null if none was set. - `geo: string` Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips. - `provider_config: BetaAWSExternalKeyConfig or BetaGCPExternalKeyConfig or BetaAzureExternalKeyConfig` KMS provider identity and auth coordinates. - `beta_aws_external_key_config: object` - `type: "aws"` - `kms_arn: string` Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected. maxLength: 2048 - `region: optional string` AWS region. Derived from `kms_arn` if omitted. - `role_arn: optional string` **Deprecated** IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored. - `beta_gcp_external_key_config: object` - `type: "gcp"` - `key_name: string` Full resource name of the Cloud KMS key. - `beta_azure_external_key_config: object` - `type: "azure"` - `key_name: string` Name of the key within the vault. - `tenant_id: string` Azure AD tenant ID. - `vault_uri: string` Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`. - `client_id: optional string` Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory. - `updated_at: string` format: date-time - `next_page: string` Opaque cursor for the next page, or null if no more results. Pass as `?page=` to fetch the next page. #### Example ```bash ant beta:organization:external-keys list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "attachment": { "type": "attached" }, "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "prod-us-key", "geo": "us", "provider_config": { "kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222", "type": "aws", "region": "us-east-1", "role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek" }, "type": "external_key", "updated_at": "2024-10-30T23:58:27.427722Z" } ], "next_page": "next_page" } ``` ### Get External Key `$ ant beta:organization:external-keys retrieve` **GET** `/v1/organizations/external_keys/{external_key_id}` Retrieve a single external key config in the caller's organization by ID. #### Parameters - `--external-key-id: string` (path parameter) ID of the External Key. maxLength: 2048 #### Returns - `beta_external_key: object` CMEK external key config belonging to the caller's organization. Configs are organization-scoped. Workspaces attach to a config; once any workspace references it, the provider fields become effectively immutable (existing encrypted data needs the config for decrypt). - `type: "external_key"` - `id: string` Identifier of the external key config. A tagged ID prefixed `ekey_`, or — for organizations on the Claude Platform on AWS — the AWS KMS key ARN. - `attachment: BetaExternalKeyAttachedAttachment or BetaExternalKeyUnattachedAttachment` Whether any workspace uses this config to encrypt its data — counting live and archived workspaces (an archived workspace's data remains encrypted under the config), excluding deleted ones. Only an attached config is used by the encryption path; an `unattached` config is inert and can be deleted. - `beta_external_key_attached_attachment: object` - `type: "attached"` - `beta_external_key_unattached_attachment: object` - `type: "unattached"` - `created_at: string` format: date-time - `display_name: string` Human-friendly display name. Null if none was set. - `geo: string` Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips. - `provider_config: BetaAWSExternalKeyConfig or BetaGCPExternalKeyConfig or BetaAzureExternalKeyConfig` KMS provider identity and auth coordinates. - `beta_aws_external_key_config: object` - `type: "aws"` - `kms_arn: string` Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected. maxLength: 2048 - `region: optional string` AWS region. Derived from `kms_arn` if omitted. - `role_arn: optional string` **Deprecated** IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored. - `beta_gcp_external_key_config: object` - `type: "gcp"` - `key_name: string` Full resource name of the Cloud KMS key. - `beta_azure_external_key_config: object` - `type: "azure"` - `key_name: string` Name of the key within the vault. - `tenant_id: string` Azure AD tenant ID. - `vault_uri: string` Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`. - `client_id: optional string` Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory. - `updated_at: string` format: date-time #### Example ```bash ant beta:organization:external-keys retrieve \ --api-key my-anthropic-api-key \ --external-key-id external_key_id ``` ##### Response (200) ```json { "id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "attachment": { "type": "attached" }, "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "prod-us-key", "geo": "us", "provider_config": { "kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222", "type": "aws", "region": "us-east-1", "role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek" }, "type": "external_key", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### Update External Key `$ ant beta:organization:external-keys update` **POST** `/v1/organizations/external_keys/{external_key_id}` Partially update an external key config. Omitted fields are left unchanged. `display_name` is always editable. `geo` and `provider_config` cannot be changed once any workspace references this config, because previously encrypted data requires the original key identity to decrypt. #### Parameters - `--external-key-id: string` (path parameter) ID of the External Key. maxLength: 2048 - `--display-name: optional string` Human-friendly display name. minLength: 1, maxLength: 255 - `--geo: optional "us"` Data residency geo. Only `us` is supported. - `--provider-config: optional BetaAWSExternalKeyConfig or BetaGCPExternalKeyConfig or BetaAzureExternalKeyConfigParam` KMS provider identity and auth coordinates. #### Returns - `beta_external_key: object` CMEK external key config belonging to the caller's organization. Configs are organization-scoped. Workspaces attach to a config; once any workspace references it, the provider fields become effectively immutable (existing encrypted data needs the config for decrypt). - `type: "external_key"` - `id: string` Identifier of the external key config. A tagged ID prefixed `ekey_`, or — for organizations on the Claude Platform on AWS — the AWS KMS key ARN. - `attachment: BetaExternalKeyAttachedAttachment or BetaExternalKeyUnattachedAttachment` Whether any workspace uses this config to encrypt its data — counting live and archived workspaces (an archived workspace's data remains encrypted under the config), excluding deleted ones. Only an attached config is used by the encryption path; an `unattached` config is inert and can be deleted. - `beta_external_key_attached_attachment: object` - `type: "attached"` - `beta_external_key_unattached_attachment: object` - `type: "unattached"` - `created_at: string` format: date-time - `display_name: string` Human-friendly display name. Null if none was set. - `geo: string` Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips. - `provider_config: BetaAWSExternalKeyConfig or BetaGCPExternalKeyConfig or BetaAzureExternalKeyConfig` KMS provider identity and auth coordinates. - `beta_aws_external_key_config: object` - `type: "aws"` - `kms_arn: string` Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected. maxLength: 2048 - `region: optional string` AWS region. Derived from `kms_arn` if omitted. - `role_arn: optional string` **Deprecated** IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored. - `beta_gcp_external_key_config: object` - `type: "gcp"` - `key_name: string` Full resource name of the Cloud KMS key. - `beta_azure_external_key_config: object` - `type: "azure"` - `key_name: string` Name of the key within the vault. - `tenant_id: string` Azure AD tenant ID. - `vault_uri: string` Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`. - `client_id: optional string` Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory. - `updated_at: string` format: date-time #### Example ```bash ant beta:organization:external-keys update \ --api-key my-anthropic-api-key \ --external-key-id external_key_id ``` ##### Response (200) ```json { "id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "attachment": { "type": "attached" }, "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "prod-us-key", "geo": "us", "provider_config": { "kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222", "type": "aws", "region": "us-east-1", "role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek" }, "type": "external_key", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### Delete External Key `$ ant beta:organization:external-keys delete` **DELETE** `/v1/organizations/external_keys/{external_key_id}` Delete an external key config. The request is rejected if any workspace still references this config. #### Parameters - `--external-key-id: string` (path parameter) ID of the External Key. maxLength: 2048 #### Returns - `BetaOrganizationExternalKeyDeleteResponse: object` - `type: "external_key_deleted"` - `id: string` ID of the deleted External Key. #### Example ```bash ant beta:organization:external-keys delete \ --api-key my-anthropic-api-key \ --external-key-id external_key_id ``` ##### Response (200) ```json { "id": "ekey_01AbCdEfGhIjKlMnOpQrStUv", "type": "external_key_deleted" } ``` ### Validate External Key `$ ant beta:organization:external-keys validate` **POST** `/v1/organizations/external_keys/{external_key_id}/validate` Validate an external key config against the customer's KMS. Anthropic performs an encrypt/decrypt roundtrip against the configured KMS key and waits up to 30 seconds for the result. The response status is `success` if the roundtrip succeeded, or `failure` with an error message if it failed or timed out. #### Parameters - `--external-key-id: string` (path parameter) ID of the External Key. maxLength: 2048 #### Returns - `BetaOrganizationExternalKeyValidateResponse: object` Result of a validation roundtrip against the customer's KMS. HTTP 200 for both outcomes — the operation completed; `status` says whether the key works. - `type: "external_key_validation"` - `error: string` Error message when status is `failure`. Null otherwise. - `status: "failure" or "success"` `success` — encrypt/decrypt roundtrip succeeded. `failure` — the roundtrip failed or timed out; see `error`. - `"failure"` - `"success"` #### Example ```bash ant beta:organization:external-keys validate \ --api-key my-anthropic-api-key \ --external-key-id external_key_id ``` ##### Response (200) ```json { "error": "error", "status": "failure", "type": "external_key_validation" } ``` ## Beta › Organization › Federation › Issuers ### Create Federation Issuer `$ ant beta:organization:federation:issuers create` **POST** `/v1/organizations/federation_issuers` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Register an OIDC issuer that Anthropic will trust for workload identity federation in your organization. The `jwks` field controls how the issuer's signing keys are obtained and takes one of three shapes selected by `type`: `discovery` (resolve keys through OIDC discovery), `explicit_url` (fetch keys from a fixed JWKS URL), or `inline` (provide a static key set). When `jwks.type` is `discovery` and no `discovery_base` is set, the issuer URL must be publicly reachable over HTTPS so Anthropic can fetch the discovery document; for `explicit_url` and `inline` modes the issuer URL is only matched as the JWT's `iss` claim and is not fetched. #### Parameters - `--issuer-url: string` The `iss` claim value to match against. minLength: 1 - `--name: string` Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409. minLength: 1, maxLength: 255 - `--check-jti: optional boolean` Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Defaults to true. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement. - `--jwks: optional BetaJWKSDiscovery or BetaJWKSExplicitURL or BetaJWKSInline` How signing keys are obtained. Defaults to OIDC discovery. - `--max-jwt-lifetime-seconds: optional number` Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Defaults to 3600 (1h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected. minimum: 1, maximum: 176400 - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_federation_issuer: object` Registered external OIDC identity provider. Records an external IdP the organization trusts for the RFC 7523 jwt-bearer grant. The `issuer_url` must match the JWT `iss` claim exactly. - `type: "federation_issuer"` - `id: string` Tagged ID of the federation issuer. - `archived_at: string` If set, all rules referencing this issuer reject token exchange. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this issuer. - `check_jti: boolean` Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement. - `created_at: string` When this issuer was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this issuer. - `issuer_url: string` The `iss` claim value. Incoming JWTs must match exactly. - `jwks: BetaJWKSDiscovery or BetaJWKSExplicitURL or BetaJWKSInline` How signing keys are obtained for signature verification. - `beta_jwks_discovery: object` JWKS via the issuer's OIDC discovery document. - `type: "discovery"` - `ca_cert_pem: optional string` Optional custom CA (PEM) for TLS verification of the JWKS fetch. maxLength: 8192 - `discovery_base: optional string` Set when the discovery URL differs from `issuer_url`. - `beta_jwks_explicit_url: object` JWKS fetched from a fixed endpoint. - `type: "explicit_url"` - `url: string` JWKS endpoint. minLength: 1 - `ca_cert_pem: optional string` Optional custom CA (PEM) for TLS verification of the JWKS fetch. maxLength: 8192 - `beta_jwks_inline: object` JWKS supplied directly; no network fetch. - `type: "inline"` - `keys: array of map[unknown]` Inline JWK objects. minItems: 1 - `jwks_polling_disabled_at: string` If set, Anthropic's JWKS poller has paused polling for this issuer after repeated fetch failures. Re-enable by sending `jwks_polling_disabled: false` via the issuer update endpoint (POST) once the upstream JWKS endpoint is fixed. An OAuth caller cannot send this when the issuer backs a rule with any scope other than `workspace:developer` or `workspace:inference`; use a Console session. format: date-time - `max_jwt_lifetime_seconds: number` Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected. - `name: string` Admin-chosen slug identifier. - `poll_status: object` Live state of Anthropic's JWKS polling for this issuer. Populated on both single-issuer retrieval and list responses, including archived issuers. Typically null for inline-key issuers (no polling), or when poll status is temporarily unavailable or polling has not started yet. - `consecutive_failures: number` Consecutive fetch failures since the last success. - `last_fetched_at: string` When the last successful fetch completed. format: date-time - `next_poll_at: string` When the next fetch is scheduled. Null if paused. format: date-time - `updated_at: string` When this issuer was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer. #### Example ```bash ant beta:organization:federation:issuers create \ --api-key my-anthropic-api-key \ --issuer-url x \ --name x ``` ##### Response (200) ```json { "id": "fdis_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "check_jti": true, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "issuer_url": "https://token.actions.githubusercontent.com", "jwks": { "type": "discovery", "ca_cert_pem": "ca_cert_pem", "discovery_base": "discovery_base" }, "jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z", "max_jwt_lifetime_seconds": 0, "name": "github-actions", "poll_status": { "consecutive_failures": 0, "last_fetched_at": "2019-12-27T18:11:19.117Z", "next_poll_at": "2019-12-27T18:11:19.117Z" }, "type": "federation_issuer", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" } ``` ### List Federation Issuers `$ ant beta:organization:federation:issuers list` **GET** `/v1/organizations/federation_issuers` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). List federation issuers in your organization. Archived issuers are excluded unless `include_archived=true`. #### Parameters - `--include-archived: optional boolean` (query parameter) Include archived resources. Defaults to false. - `--limit: optional number` (query parameter) Number of results per page. minimum: 1, maximum: 100 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `BetaFederationIssuerListResponse: object` - `data: array of BetaFederationIssuer` - `type: "federation_issuer"` - `id: string` Tagged ID of the federation issuer. - `archived_at: string` If set, all rules referencing this issuer reject token exchange. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this issuer. - `check_jti: boolean` Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement. - `created_at: string` When this issuer was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this issuer. - `issuer_url: string` The `iss` claim value. Incoming JWTs must match exactly. - `jwks: BetaJWKSDiscovery or BetaJWKSExplicitURL or BetaJWKSInline` How signing keys are obtained for signature verification. - `beta_jwks_discovery: object` JWKS via the issuer's OIDC discovery document. - `type: "discovery"` - `ca_cert_pem: optional string` Optional custom CA (PEM) for TLS verification of the JWKS fetch. maxLength: 8192 - `discovery_base: optional string` Set when the discovery URL differs from `issuer_url`. - `beta_jwks_explicit_url: object` JWKS fetched from a fixed endpoint. - `type: "explicit_url"` - `url: string` JWKS endpoint. minLength: 1 - `ca_cert_pem: optional string` Optional custom CA (PEM) for TLS verification of the JWKS fetch. maxLength: 8192 - `beta_jwks_inline: object` JWKS supplied directly; no network fetch. - `type: "inline"` - `keys: array of map[unknown]` Inline JWK objects. minItems: 1 - `jwks_polling_disabled_at: string` If set, Anthropic's JWKS poller has paused polling for this issuer after repeated fetch failures. Re-enable by sending `jwks_polling_disabled: false` via the issuer update endpoint (POST) once the upstream JWKS endpoint is fixed. An OAuth caller cannot send this when the issuer backs a rule with any scope other than `workspace:developer` or `workspace:inference`; use a Console session. format: date-time - `max_jwt_lifetime_seconds: number` Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected. - `name: string` Admin-chosen slug identifier. - `poll_status: object` Live state of Anthropic's JWKS polling for this issuer. Populated on both single-issuer retrieval and list responses, including archived issuers. Typically null for inline-key issuers (no polling), or when poll status is temporarily unavailable or polling has not started yet. - `consecutive_failures: number` Consecutive fetch failures since the last success. - `last_fetched_at: string` When the last successful fetch completed. format: date-time - `next_poll_at: string` When the next fetch is scheduled. Null if paused. format: date-time - `updated_at: string` When this issuer was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer. - `next_page: string` Opaque cursor for the next page, or null if no more results. #### Example ```bash ant beta:organization:federation:issuers list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "fdis_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "check_jti": true, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "issuer_url": "https://token.actions.githubusercontent.com", "jwks": { "type": "discovery", "ca_cert_pem": "ca_cert_pem", "discovery_base": "discovery_base" }, "jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z", "max_jwt_lifetime_seconds": 0, "name": "github-actions", "poll_status": { "consecutive_failures": 0, "last_fetched_at": "2019-12-27T18:11:19.117Z", "next_poll_at": "2019-12-27T18:11:19.117Z" }, "type": "federation_issuer", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" } ], "next_page": "next_page" } ``` ### Get Federation Issuer `$ ant beta:organization:federation:issuers retrieve` **GET** `/v1/organizations/federation_issuers/{federation_issuer_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Retrieve a federation issuer by its ID (`fdis_...`). #### Parameters - `--federation-issuer-id: string` (path parameter) ID of the federation issuer. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_federation_issuer: object` Registered external OIDC identity provider. Records an external IdP the organization trusts for the RFC 7523 jwt-bearer grant. The `issuer_url` must match the JWT `iss` claim exactly. - `type: "federation_issuer"` - `id: string` Tagged ID of the federation issuer. - `archived_at: string` If set, all rules referencing this issuer reject token exchange. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this issuer. - `check_jti: boolean` Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement. - `created_at: string` When this issuer was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this issuer. - `issuer_url: string` The `iss` claim value. Incoming JWTs must match exactly. - `jwks: BetaJWKSDiscovery or BetaJWKSExplicitURL or BetaJWKSInline` How signing keys are obtained for signature verification. - `beta_jwks_discovery: object` JWKS via the issuer's OIDC discovery document. - `type: "discovery"` - `ca_cert_pem: optional string` Optional custom CA (PEM) for TLS verification of the JWKS fetch. maxLength: 8192 - `discovery_base: optional string` Set when the discovery URL differs from `issuer_url`. - `beta_jwks_explicit_url: object` JWKS fetched from a fixed endpoint. - `type: "explicit_url"` - `url: string` JWKS endpoint. minLength: 1 - `ca_cert_pem: optional string` Optional custom CA (PEM) for TLS verification of the JWKS fetch. maxLength: 8192 - `beta_jwks_inline: object` JWKS supplied directly; no network fetch. - `type: "inline"` - `keys: array of map[unknown]` Inline JWK objects. minItems: 1 - `jwks_polling_disabled_at: string` If set, Anthropic's JWKS poller has paused polling for this issuer after repeated fetch failures. Re-enable by sending `jwks_polling_disabled: false` via the issuer update endpoint (POST) once the upstream JWKS endpoint is fixed. An OAuth caller cannot send this when the issuer backs a rule with any scope other than `workspace:developer` or `workspace:inference`; use a Console session. format: date-time - `max_jwt_lifetime_seconds: number` Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected. - `name: string` Admin-chosen slug identifier. - `poll_status: object` Live state of Anthropic's JWKS polling for this issuer. Populated on both single-issuer retrieval and list responses, including archived issuers. Typically null for inline-key issuers (no polling), or when poll status is temporarily unavailable or polling has not started yet. - `consecutive_failures: number` Consecutive fetch failures since the last success. - `last_fetched_at: string` When the last successful fetch completed. format: date-time - `next_poll_at: string` When the next fetch is scheduled. Null if paused. format: date-time - `updated_at: string` When this issuer was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer. #### Example ```bash ant beta:organization:federation:issuers retrieve \ --api-key my-anthropic-api-key \ --federation-issuer-id federation_issuer_id ``` ##### Response (200) ```json { "id": "fdis_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "check_jti": true, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "issuer_url": "https://token.actions.githubusercontent.com", "jwks": { "type": "discovery", "ca_cert_pem": "ca_cert_pem", "discovery_base": "discovery_base" }, "jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z", "max_jwt_lifetime_seconds": 0, "name": "github-actions", "poll_status": { "consecutive_failures": 0, "last_fetched_at": "2019-12-27T18:11:19.117Z", "next_poll_at": "2019-12-27T18:11:19.117Z" }, "type": "federation_issuer", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" } ``` ### Update Federation Issuer `$ ant beta:organization:federation:issuers update` **POST** `/v1/organizations/federation_issuers/{federation_issuer_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Partially update a federation issuer. Setting `jwks` replaces the full JWKS shape at once. Archived issuers cannot be updated; this returns 400. Create a new issuer instead. Updating an issuer that backs a rule with a scope outside `workspace:developer` or `workspace:inference` requires a Console session. #### Parameters - `--federation-issuer-id: string` (path parameter) ID of the federation issuer to update. - `--check-jti: optional boolean` Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement. - `--issuer-url: optional string` Replaces the `iss` claim value to match against. For discovery-mode issuers without a `discovery_base`, this is also the URL Anthropic fetches the OIDC discovery document and signing keys from, so changing it repoints the JWKS source. Changing the issuer URL to a well-known shared platform is rejected while any live rule under this issuer would not constrain tenant identity. minLength: 1 - `--jwks: optional BetaJWKSDiscovery or BetaJWKSExplicitURL or BetaJWKSInline` Replaces the entire JWKS configuration. - `--jwks-polling-disabled: optional boolean` Only `false` is accepted, to re-enable polling after the system pauses it. Polling is paused automatically; sending `true` is rejected. - `--max-jwt-lifetime-seconds: optional number` Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected. minimum: 1, maximum: 176400 - `--name: optional string` Replaces the slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409. minLength: 1, maxLength: 255 - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_federation_issuer: object` Registered external OIDC identity provider. Records an external IdP the organization trusts for the RFC 7523 jwt-bearer grant. The `issuer_url` must match the JWT `iss` claim exactly. - `type: "federation_issuer"` - `id: string` Tagged ID of the federation issuer. - `archived_at: string` If set, all rules referencing this issuer reject token exchange. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this issuer. - `check_jti: boolean` Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement. - `created_at: string` When this issuer was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this issuer. - `issuer_url: string` The `iss` claim value. Incoming JWTs must match exactly. - `jwks: BetaJWKSDiscovery or BetaJWKSExplicitURL or BetaJWKSInline` How signing keys are obtained for signature verification. - `beta_jwks_discovery: object` JWKS via the issuer's OIDC discovery document. - `type: "discovery"` - `ca_cert_pem: optional string` Optional custom CA (PEM) for TLS verification of the JWKS fetch. maxLength: 8192 - `discovery_base: optional string` Set when the discovery URL differs from `issuer_url`. - `beta_jwks_explicit_url: object` JWKS fetched from a fixed endpoint. - `type: "explicit_url"` - `url: string` JWKS endpoint. minLength: 1 - `ca_cert_pem: optional string` Optional custom CA (PEM) for TLS verification of the JWKS fetch. maxLength: 8192 - `beta_jwks_inline: object` JWKS supplied directly; no network fetch. - `type: "inline"` - `keys: array of map[unknown]` Inline JWK objects. minItems: 1 - `jwks_polling_disabled_at: string` If set, Anthropic's JWKS poller has paused polling for this issuer after repeated fetch failures. Re-enable by sending `jwks_polling_disabled: false` via the issuer update endpoint (POST) once the upstream JWKS endpoint is fixed. An OAuth caller cannot send this when the issuer backs a rule with any scope other than `workspace:developer` or `workspace:inference`; use a Console session. format: date-time - `max_jwt_lifetime_seconds: number` Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected. - `name: string` Admin-chosen slug identifier. - `poll_status: object` Live state of Anthropic's JWKS polling for this issuer. Populated on both single-issuer retrieval and list responses, including archived issuers. Typically null for inline-key issuers (no polling), or when poll status is temporarily unavailable or polling has not started yet. - `consecutive_failures: number` Consecutive fetch failures since the last success. - `last_fetched_at: string` When the last successful fetch completed. format: date-time - `next_poll_at: string` When the next fetch is scheduled. Null if paused. format: date-time - `updated_at: string` When this issuer was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer. #### Example ```bash ant beta:organization:federation:issuers update \ --api-key my-anthropic-api-key \ --federation-issuer-id federation_issuer_id ``` ##### Response (200) ```json { "id": "fdis_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "check_jti": true, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "issuer_url": "https://token.actions.githubusercontent.com", "jwks": { "type": "discovery", "ca_cert_pem": "ca_cert_pem", "discovery_base": "discovery_base" }, "jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z", "max_jwt_lifetime_seconds": 0, "name": "github-actions", "poll_status": { "consecutive_failures": 0, "last_fetched_at": "2019-12-27T18:11:19.117Z", "next_poll_at": "2019-12-27T18:11:19.117Z" }, "type": "federation_issuer", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" } ``` ### Archive Federation Issuer `$ ant beta:organization:federation:issuers archive` **POST** `/v1/organizations/federation_issuers/{federation_issuer_id}/archive` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Archive a federation issuer. Idempotent; re-archiving returns the issuer with its original `archived_at`. Rejected with 400 if any live (non-archived) federation rule still references the issuer; archive those rules first (a rule's issuer cannot be changed), or recreate them against another issuer. #### Parameters - `--federation-issuer-id: string` (path parameter) ID of the federation issuer to archive. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_federation_issuer: object` Registered external OIDC identity provider. Records an external IdP the organization trusts for the RFC 7523 jwt-bearer grant. The `issuer_url` must match the JWT `iss` claim exactly. - `type: "federation_issuer"` - `id: string` Tagged ID of the federation issuer. - `archived_at: string` If set, all rules referencing this issuer reject token exchange. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this issuer. - `check_jti: boolean` Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement. - `created_at: string` When this issuer was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this issuer. - `issuer_url: string` The `iss` claim value. Incoming JWTs must match exactly. - `jwks: BetaJWKSDiscovery or BetaJWKSExplicitURL or BetaJWKSInline` How signing keys are obtained for signature verification. - `beta_jwks_discovery: object` JWKS via the issuer's OIDC discovery document. - `type: "discovery"` - `ca_cert_pem: optional string` Optional custom CA (PEM) for TLS verification of the JWKS fetch. maxLength: 8192 - `discovery_base: optional string` Set when the discovery URL differs from `issuer_url`. - `beta_jwks_explicit_url: object` JWKS fetched from a fixed endpoint. - `type: "explicit_url"` - `url: string` JWKS endpoint. minLength: 1 - `ca_cert_pem: optional string` Optional custom CA (PEM) for TLS verification of the JWKS fetch. maxLength: 8192 - `beta_jwks_inline: object` JWKS supplied directly; no network fetch. - `type: "inline"` - `keys: array of map[unknown]` Inline JWK objects. minItems: 1 - `jwks_polling_disabled_at: string` If set, Anthropic's JWKS poller has paused polling for this issuer after repeated fetch failures. Re-enable by sending `jwks_polling_disabled: false` via the issuer update endpoint (POST) once the upstream JWKS endpoint is fixed. An OAuth caller cannot send this when the issuer backs a rule with any scope other than `workspace:developer` or `workspace:inference`; use a Console session. format: date-time - `max_jwt_lifetime_seconds: number` Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected. - `name: string` Admin-chosen slug identifier. - `poll_status: object` Live state of Anthropic's JWKS polling for this issuer. Populated on both single-issuer retrieval and list responses, including archived issuers. Typically null for inline-key issuers (no polling), or when poll status is temporarily unavailable or polling has not started yet. - `consecutive_failures: number` Consecutive fetch failures since the last success. - `last_fetched_at: string` When the last successful fetch completed. format: date-time - `next_poll_at: string` When the next fetch is scheduled. Null if paused. format: date-time - `updated_at: string` When this issuer was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer. #### Example ```bash ant beta:organization:federation:issuers archive \ --api-key my-anthropic-api-key \ --federation-issuer-id federation_issuer_id ``` ##### Response (200) ```json { "id": "fdis_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "check_jti": true, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "issuer_url": "https://token.actions.githubusercontent.com", "jwks": { "type": "discovery", "ca_cert_pem": "ca_cert_pem", "discovery_base": "discovery_base" }, "jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z", "max_jwt_lifetime_seconds": 0, "name": "github-actions", "poll_status": { "consecutive_failures": 0, "last_fetched_at": "2019-12-27T18:11:19.117Z", "next_poll_at": "2019-12-27T18:11:19.117Z" }, "type": "federation_issuer", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" } ``` ## Beta › Organization › Federation › Rules ### Create Federation Rule `$ ant beta:organization:federation:rules create` **POST** `/v1/organizations/federation_rules` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Create a federation rule owned by your organization. The referenced issuer and the target service account must already exist in the same organization; invalid references are rejected with a 400 error. The workspace reference is validated. Membership is not checked at rule creation: token exchange resolves a single enabled workspace per call and is rejected unless the target service account is a member of that workspace (it is implicitly a member of the default workspace). Rules on well-known shared issuers (GitHub Actions, GitLab, Buildkite, Terraform Cloud, Google) must constrain tenant identity via an identity-bearing claim, a tenant-pinning subject prefix (such as `repo:YOUR_ORG/...`), or a CEL condition referencing one of those identity claims (e.g. `claims.repository_owner`). OAuth callers may only manage rules whose `oauth_scope` is `workspace:developer` or `workspace:inference`; other scopes require a Console session. #### Parameters - `--issuer-id: string` Tagged ID of the federation issuer. - `--match: object` Conditions the verified JWT must satisfy for this rule to apply. At least one of `subject_prefix` (other than a wildcard-only value like `*`), `claims`, or `condition` is required; `audience` alone is not sufficient. - `--name: string` Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409. minLength: 1, maxLength: 255 - `--oauth-scope: string` Space-separated OAuth scopes. OAuth callers may only set `workspace:developer` or `workspace:inference`; other scopes (such as `org:admin`) require a Console session. minLength: 1 - `--target: object` Identity that tokens minted via this rule act as. Currently always a `service_account` target. - `--applies-to-all-workspaces: optional boolean` When true, enable this rule for every workspace in the org (including workspaces created later). - `--attributes: optional map[string]` CEL expressions `{name: expr}` extracting named values from claims. Not yet supported; any non-empty value is rejected with 400. - `--description: optional string` Optional free-text description. maxLength: 2000 - `--token-lifetime-seconds: optional number` Lifetime in seconds for access tokens minted via this rule (60-86400). Defaults to 3600 (1h). Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds. minimum: 60, maximum: 86400 - `--workspace-id: optional string` Tagged ID of the workspace to enable this rule for. Required unless `applies_to_all_workspaces` is true. Additional workspaces can be added via the `/federation_rules/{federation_rule_id}/workspaces` sub-resource. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_federation_rule: object` Authorization rule binding an external OIDC identity to Anthropic. Evaluates the match conditions and mints an OAuth access token for the resolved target, scoped to a single workspace where the rule is enabled (chosen by the caller at exchange time when the rule is enabled for more than one). For rules enabled via `workspace_ids` or `applies_to_all_workspaces`, the target service account must be a member of that workspace (it is implicitly a member of the default workspace); rules carrying only the legacy `workspace_id` binding do not enforce this. - `type: "federation_rule"` - `id: string` Tagged ID of the federation rule. - `applies_to_all_workspaces: boolean` When true, this rule is enabled for every workspace in the org (including ones created after the rule). `workspace_ids` is ignored at exchange time. - `archived_at: string` If set, this rule is archived and rejects token exchange. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this rule. - `attributes: map[string]` CEL expressions extracting named values from claims. Not yet supported; always null. - `created_at: string` When this rule was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this rule. - `description: string` Optional free-text description. - `issuer_id: string` Tagged ID of the issuer whose tokens this rule accepts. - `issuer_name: string` Issuer's display name at read time. - `match: object` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass. - `audience: optional string` Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default. maxLength: 1024 - `claims: optional map[string]` Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims. - `condition: optional string` CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400. maxLength: 4096 - `subject_prefix: optional string` Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`. maxLength: 1024 - `name: string` Admin-chosen slug identifier. - `oauth_scope: string` Space-separated OAuth scopes granted on the minted token. - `target: object` What this rule targets. Check `type` before reading the other fields. Tokens minted via a rule whose target `type` is `service_account` act as that service account. - `type: "service_account"` - `service_account_id: string` Tagged ID of the service account to mint tokens for. - `service_account_name: optional string` Service account's display name at read time. Ignored on writes. - `token_lifetime_seconds: number` Lifetime in seconds of access tokens minted via this rule. Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds. - `updated_at: string` When this rule was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule. - `workspace_id: string` Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement. - `workspace_ids: array of string` Tagged IDs of the workspaces this rule is enabled for. May be empty for older rules that only carry the legacy `workspace_id` binding. Ignored at exchange time when `applies_to_all_workspaces` is true (the list may still be non-empty). #### Example ```bash ant beta:organization:federation:rules create \ --api-key my-anthropic-api-key \ --issuer-id issuer_id \ --match '{}' \ --name x \ --oauth-scope x \ --target '{service_account_id: svac_01SDCCSbTxrXDpWc1phhtcfK, type: service_account}' ``` ##### Response (200) ```json { "id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK", "applies_to_all_workspaces": true, "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "attributes": { "foo": "string" }, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "issuer_id": "issuer_id", "issuer_name": "issuer_name", "match": { "audience": "audience", "claims": { "foo": "string" }, "condition": "condition", "subject_prefix": "subject_prefix" }, "name": "prod-deploy-pipeline", "oauth_scope": "oauth_scope", "target": { "service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "type": "service_account", "service_account_name": "service_account_name" }, "token_lifetime_seconds": 0, "type": "federation_rule", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id", "workspace_id": "workspace_id", "workspace_ids": [ "string" ] } ``` ### List Federation Rules `$ ant beta:organization:federation:rules list` **GET** `/v1/organizations/federation_rules` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). List federation rules in your organization. Optionally filter by issuer with `issuer_id`. Archived rules are excluded unless `include_archived=true`. #### Parameters - `--include-archived: optional boolean` (query parameter) Include archived resources. Defaults to false. - `--issuer-id: optional string` (query parameter) Filter to rules referencing this federation issuer. - `--limit: optional number` (query parameter) Number of results per page. minimum: 1, maximum: 100 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `BetaFederationRuleListResponse: object` - `data: array of BetaFederationRule` - `type: "federation_rule"` - `id: string` Tagged ID of the federation rule. - `applies_to_all_workspaces: boolean` When true, this rule is enabled for every workspace in the org (including ones created after the rule). `workspace_ids` is ignored at exchange time. - `archived_at: string` If set, this rule is archived and rejects token exchange. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this rule. - `attributes: map[string]` CEL expressions extracting named values from claims. Not yet supported; always null. - `created_at: string` When this rule was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this rule. - `description: string` Optional free-text description. - `issuer_id: string` Tagged ID of the issuer whose tokens this rule accepts. - `issuer_name: string` Issuer's display name at read time. - `match: object` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass. - `audience: optional string` Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default. maxLength: 1024 - `claims: optional map[string]` Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims. - `condition: optional string` CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400. maxLength: 4096 - `subject_prefix: optional string` Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`. maxLength: 1024 - `name: string` Admin-chosen slug identifier. - `oauth_scope: string` Space-separated OAuth scopes granted on the minted token. - `target: object` What this rule targets. Check `type` before reading the other fields. Tokens minted via a rule whose target `type` is `service_account` act as that service account. - `type: "service_account"` - `service_account_id: string` Tagged ID of the service account to mint tokens for. - `service_account_name: optional string` Service account's display name at read time. Ignored on writes. - `token_lifetime_seconds: number` Lifetime in seconds of access tokens minted via this rule. Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds. - `updated_at: string` When this rule was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule. - `workspace_id: string` Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement. - `workspace_ids: array of string` Tagged IDs of the workspaces this rule is enabled for. May be empty for older rules that only carry the legacy `workspace_id` binding. Ignored at exchange time when `applies_to_all_workspaces` is true (the list may still be non-empty). - `next_page: string` Opaque cursor for the next page, or null if no more results. #### Example ```bash ant beta:organization:federation:rules list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK", "applies_to_all_workspaces": true, "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "attributes": { "foo": "string" }, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "issuer_id": "issuer_id", "issuer_name": "issuer_name", "match": { "audience": "audience", "claims": { "foo": "string" }, "condition": "condition", "subject_prefix": "subject_prefix" }, "name": "prod-deploy-pipeline", "oauth_scope": "oauth_scope", "target": { "service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "type": "service_account", "service_account_name": "service_account_name" }, "token_lifetime_seconds": 0, "type": "federation_rule", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id", "workspace_id": "workspace_id", "workspace_ids": [ "string" ] } ], "next_page": "next_page" } ``` ### Get Federation Rule `$ ant beta:organization:federation:rules retrieve` **GET** `/v1/organizations/federation_rules/{federation_rule_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Retrieve a federation rule by its ID (`fdrl_...`). #### Parameters - `--federation-rule-id: string` (path parameter) ID of the federation rule. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_federation_rule: object` Authorization rule binding an external OIDC identity to Anthropic. Evaluates the match conditions and mints an OAuth access token for the resolved target, scoped to a single workspace where the rule is enabled (chosen by the caller at exchange time when the rule is enabled for more than one). For rules enabled via `workspace_ids` or `applies_to_all_workspaces`, the target service account must be a member of that workspace (it is implicitly a member of the default workspace); rules carrying only the legacy `workspace_id` binding do not enforce this. - `type: "federation_rule"` - `id: string` Tagged ID of the federation rule. - `applies_to_all_workspaces: boolean` When true, this rule is enabled for every workspace in the org (including ones created after the rule). `workspace_ids` is ignored at exchange time. - `archived_at: string` If set, this rule is archived and rejects token exchange. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this rule. - `attributes: map[string]` CEL expressions extracting named values from claims. Not yet supported; always null. - `created_at: string` When this rule was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this rule. - `description: string` Optional free-text description. - `issuer_id: string` Tagged ID of the issuer whose tokens this rule accepts. - `issuer_name: string` Issuer's display name at read time. - `match: object` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass. - `audience: optional string` Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default. maxLength: 1024 - `claims: optional map[string]` Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims. - `condition: optional string` CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400. maxLength: 4096 - `subject_prefix: optional string` Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`. maxLength: 1024 - `name: string` Admin-chosen slug identifier. - `oauth_scope: string` Space-separated OAuth scopes granted on the minted token. - `target: object` What this rule targets. Check `type` before reading the other fields. Tokens minted via a rule whose target `type` is `service_account` act as that service account. - `type: "service_account"` - `service_account_id: string` Tagged ID of the service account to mint tokens for. - `service_account_name: optional string` Service account's display name at read time. Ignored on writes. - `token_lifetime_seconds: number` Lifetime in seconds of access tokens minted via this rule. Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds. - `updated_at: string` When this rule was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule. - `workspace_id: string` Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement. - `workspace_ids: array of string` Tagged IDs of the workspaces this rule is enabled for. May be empty for older rules that only carry the legacy `workspace_id` binding. Ignored at exchange time when `applies_to_all_workspaces` is true (the list may still be non-empty). #### Example ```bash ant beta:organization:federation:rules retrieve \ --api-key my-anthropic-api-key \ --federation-rule-id federation_rule_id ``` ##### Response (200) ```json { "id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK", "applies_to_all_workspaces": true, "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "attributes": { "foo": "string" }, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "issuer_id": "issuer_id", "issuer_name": "issuer_name", "match": { "audience": "audience", "claims": { "foo": "string" }, "condition": "condition", "subject_prefix": "subject_prefix" }, "name": "prod-deploy-pipeline", "oauth_scope": "oauth_scope", "target": { "service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "type": "service_account", "service_account_name": "service_account_name" }, "token_lifetime_seconds": 0, "type": "federation_rule", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id", "workspace_id": "workspace_id", "workspace_ids": [ "string" ] } ``` ### Update Federation Rule `$ ant beta:organization:federation:rules update` **POST** `/v1/organizations/federation_rules/{federation_rule_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Partially update a federation rule. `issuer_id` is immutable. `match` and `target` are replaced as whole objects when set. Referenced service accounts and workspaces must exist in your organization; invalid references are rejected with a 400 error. Archived rules cannot be updated; this returns 400. Create a new rule instead. Rules on well-known shared issuers (GitHub Actions, GitLab, Buildkite, Terraform Cloud, Google) must constrain tenant identity via an identity-bearing claim, a tenant-pinning subject prefix (such as `repo:YOUR_ORG/...`), or a CEL condition referencing one of those identity claims (e.g. `claims.repository_owner`). On these issuers the requirement is re-checked on every update; if an existing rule's stored match does not yet constrain tenant identity, any update (even a rename or description change) must also supply a conforming `match` in the same request. OAuth callers may only manage rules whose `oauth_scope` is `workspace:developer` or `workspace:inference`; other scopes require a Console session. #### Parameters - `--federation-rule-id: string` (path parameter) ID of the federation rule to update. - `--applies-to-all-workspaces: optional boolean` When true, enables this rule for every workspace in the org (including workspaces created later). Setting `false` is rejected with 400 if no workspace would remain enabled; a rule with only a legacy `workspace_id` binding continues to mint. - `--attributes: optional map[string]` Replaces the CEL expressions `{name: expr}` extracting named values from claims. Send null to clear them. Not yet supported; any non-empty value is rejected with 400. - `--description: optional string` Replaces the description. Omit to leave unchanged; send `null` to clear (the field is stored as an empty string). maxLength: 2000 - `--match: optional object` Replaces the entire match object. All populated matcher fields must pass. - `--name: optional string` Replaces the slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409. minLength: 1, maxLength: 255 - `--oauth-scope: optional string` Replaces the space-separated OAuth scopes granted on minted tokens. OAuth callers may only set `workspace:developer` or `workspace:inference`; other scopes (such as `org:admin`) require a Console session. minLength: 1 - `--target: optional object` Replaces the entire target object. Currently always a `service_account` target. - `--token-lifetime-seconds: optional number` Replaces the lifetime in seconds for access tokens minted via this rule (60-86400). Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds. minimum: 60, maximum: 86400 - `--workspace-id: optional string` Replaces the existing single workspace enablement (the previous one is removed). Rejected with 400 if the rule is enabled for more than one workspace; use the `/federation_rules/{federation_rule_id}/workspaces` sub-resource instead. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_federation_rule: object` Authorization rule binding an external OIDC identity to Anthropic. Evaluates the match conditions and mints an OAuth access token for the resolved target, scoped to a single workspace where the rule is enabled (chosen by the caller at exchange time when the rule is enabled for more than one). For rules enabled via `workspace_ids` or `applies_to_all_workspaces`, the target service account must be a member of that workspace (it is implicitly a member of the default workspace); rules carrying only the legacy `workspace_id` binding do not enforce this. - `type: "federation_rule"` - `id: string` Tagged ID of the federation rule. - `applies_to_all_workspaces: boolean` When true, this rule is enabled for every workspace in the org (including ones created after the rule). `workspace_ids` is ignored at exchange time. - `archived_at: string` If set, this rule is archived and rejects token exchange. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this rule. - `attributes: map[string]` CEL expressions extracting named values from claims. Not yet supported; always null. - `created_at: string` When this rule was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this rule. - `description: string` Optional free-text description. - `issuer_id: string` Tagged ID of the issuer whose tokens this rule accepts. - `issuer_name: string` Issuer's display name at read time. - `match: object` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass. - `audience: optional string` Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default. maxLength: 1024 - `claims: optional map[string]` Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims. - `condition: optional string` CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400. maxLength: 4096 - `subject_prefix: optional string` Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`. maxLength: 1024 - `name: string` Admin-chosen slug identifier. - `oauth_scope: string` Space-separated OAuth scopes granted on the minted token. - `target: object` What this rule targets. Check `type` before reading the other fields. Tokens minted via a rule whose target `type` is `service_account` act as that service account. - `type: "service_account"` - `service_account_id: string` Tagged ID of the service account to mint tokens for. - `service_account_name: optional string` Service account's display name at read time. Ignored on writes. - `token_lifetime_seconds: number` Lifetime in seconds of access tokens minted via this rule. Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds. - `updated_at: string` When this rule was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule. - `workspace_id: string` Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement. - `workspace_ids: array of string` Tagged IDs of the workspaces this rule is enabled for. May be empty for older rules that only carry the legacy `workspace_id` binding. Ignored at exchange time when `applies_to_all_workspaces` is true (the list may still be non-empty). #### Example ```bash ant beta:organization:federation:rules update \ --api-key my-anthropic-api-key \ --federation-rule-id federation_rule_id ``` ##### Response (200) ```json { "id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK", "applies_to_all_workspaces": true, "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "attributes": { "foo": "string" }, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "issuer_id": "issuer_id", "issuer_name": "issuer_name", "match": { "audience": "audience", "claims": { "foo": "string" }, "condition": "condition", "subject_prefix": "subject_prefix" }, "name": "prod-deploy-pipeline", "oauth_scope": "oauth_scope", "target": { "service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "type": "service_account", "service_account_name": "service_account_name" }, "token_lifetime_seconds": 0, "type": "federation_rule", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id", "workspace_id": "workspace_id", "workspace_ids": [ "string" ] } ``` ### Archive Federation Rule `$ ant beta:organization:federation:rules archive` **POST** `/v1/organizations/federation_rules/{federation_rule_id}/archive` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Archive a federation rule. Token exchange through this rule stops immediately. Idempotent; re-archiving returns the rule with its original `archived_at`. Archiving clears the rule's workspace targeting (`workspace_id` and `workspace_ids` are emptied). Tokens already minted before archive remain valid until they expire. OAuth callers may only manage rules whose `oauth_scope` is `workspace:developer` or `workspace:inference`; other scopes require a Console session. #### Parameters - `--federation-rule-id: string` (path parameter) ID of the federation rule to archive. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_federation_rule: object` Authorization rule binding an external OIDC identity to Anthropic. Evaluates the match conditions and mints an OAuth access token for the resolved target, scoped to a single workspace where the rule is enabled (chosen by the caller at exchange time when the rule is enabled for more than one). For rules enabled via `workspace_ids` or `applies_to_all_workspaces`, the target service account must be a member of that workspace (it is implicitly a member of the default workspace); rules carrying only the legacy `workspace_id` binding do not enforce this. - `type: "federation_rule"` - `id: string` Tagged ID of the federation rule. - `applies_to_all_workspaces: boolean` When true, this rule is enabled for every workspace in the org (including ones created after the rule). `workspace_ids` is ignored at exchange time. - `archived_at: string` If set, this rule is archived and rejects token exchange. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this rule. - `attributes: map[string]` CEL expressions extracting named values from claims. Not yet supported; always null. - `created_at: string` When this rule was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this rule. - `description: string` Optional free-text description. - `issuer_id: string` Tagged ID of the issuer whose tokens this rule accepts. - `issuer_name: string` Issuer's display name at read time. - `match: object` Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass. - `audience: optional string` Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default. maxLength: 1024 - `claims: optional map[string]` Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims. - `condition: optional string` CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400. maxLength: 4096 - `subject_prefix: optional string` Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`. maxLength: 1024 - `name: string` Admin-chosen slug identifier. - `oauth_scope: string` Space-separated OAuth scopes granted on the minted token. - `target: object` What this rule targets. Check `type` before reading the other fields. Tokens minted via a rule whose target `type` is `service_account` act as that service account. - `type: "service_account"` - `service_account_id: string` Tagged ID of the service account to mint tokens for. - `service_account_name: optional string` Service account's display name at read time. Ignored on writes. - `token_lifetime_seconds: number` Lifetime in seconds of access tokens minted via this rule. Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds. - `updated_at: string` When this rule was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this rule. - `workspace_id: string` Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement. - `workspace_ids: array of string` Tagged IDs of the workspaces this rule is enabled for. May be empty for older rules that only carry the legacy `workspace_id` binding. Ignored at exchange time when `applies_to_all_workspaces` is true (the list may still be non-empty). #### Example ```bash ant beta:organization:federation:rules archive \ --api-key my-anthropic-api-key \ --federation-rule-id federation_rule_id ``` ##### Response (200) ```json { "id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK", "applies_to_all_workspaces": true, "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "attributes": { "foo": "string" }, "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "issuer_id": "issuer_id", "issuer_name": "issuer_name", "match": { "audience": "audience", "claims": { "foo": "string" }, "condition": "condition", "subject_prefix": "subject_prefix" }, "name": "prod-deploy-pipeline", "oauth_scope": "oauth_scope", "target": { "service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "type": "service_account", "service_account_name": "service_account_name" }, "token_lifetime_seconds": 0, "type": "federation_rule", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id", "workspace_id": "workspace_id", "workspace_ids": [ "string" ] } ``` ## Beta › Organization › Federation › Rules › Workspaces ### Add Federation Rule Workspace `$ ant beta:organization:federation:rules:workspaces add` **POST** `/v1/organizations/federation_rules/{federation_rule_id}/workspaces` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Enable a federation rule for a workspace. Idempotent; re-enabling returns the existing enablement. The rule and workspace must both belong to your organization. Membership of the rule's target service account in this workspace is not checked at enablement: token exchange into this workspace is rejected unless the target is a member (it is implicitly a member of the default workspace). Archived rules are rejected with 400. OAuth callers may only manage rules whose `oauth_scope` is `workspace:developer` or `workspace:inference`; other scopes require a Console session. #### Parameters - `--federation-rule-id: string` (path parameter) ID of the federation rule. - `--workspace-id: string` Tagged ID of the workspace to enable this rule for. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_federation_rule_workspace: object` - `type: "federation_rule_workspace"` - `created_at: string` When this workspace was enabled for the rule. format: date-time - `created_by_actor_id: string` Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known. - `federation_rule_id: string` Tagged ID of the federation rule. - `workspace_id: string` Tagged ID of the workspace this rule is enabled for. - `workspace_name: string` Workspace display name. Populated when listing; null in the enable response. #### Example ```bash ant beta:organization:federation:rules:workspaces add \ --api-key my-anthropic-api-key \ --federation-rule-id federation_rule_id \ --workspace-id workspace_id ``` ##### Response (200) ```json { "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "federation_rule_id": "federation_rule_id", "type": "federation_rule_workspace", "workspace_id": "workspace_id", "workspace_name": "workspace_name" } ``` ### List Federation Rule Workspaces `$ ant beta:organization:federation:rules:workspaces list` **GET** `/v1/organizations/federation_rules/{federation_rule_id}/workspaces` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). List workspaces where this federation rule is enabled. Returns all workspace enablements in a single response; the `limit` and `page` parameters are accepted but have no effect, and `next_page` is always `null`. Returns explicit per-workspace enablements only; for rules with `applies_to_all_workspaces` or a legacy single `workspace_id`, check those fields on the rule itself. #### Parameters - `--federation-rule-id: string` (path parameter) ID of the federation rule. - `--limit: optional number` (query parameter) Number of results per page. minimum: 1, maximum: 100 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `BetaFederationRuleWorkspaceListResponse: object` - `data: array of BetaFederationRuleWorkspace` - `type: "federation_rule_workspace"` - `created_at: string` When this workspace was enabled for the rule. format: date-time - `created_by_actor_id: string` Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known. - `federation_rule_id: string` Tagged ID of the federation rule. - `workspace_id: string` Tagged ID of the workspace this rule is enabled for. - `workspace_name: string` Workspace display name. Populated when listing; null in the enable response. - `next_page: string` Opaque cursor for the next page; null when there are no more results. #### Example ```bash ant beta:organization:federation:rules:workspaces list \ --api-key my-anthropic-api-key \ --federation-rule-id federation_rule_id ``` ##### Response (200) ```json { "data": [ { "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "federation_rule_id": "federation_rule_id", "type": "federation_rule_workspace", "workspace_id": "workspace_id", "workspace_name": "workspace_name" } ], "next_page": "next_page" } ``` ### Remove Federation Rule Workspace `$ ant beta:organization:federation:rules:workspaces remove` **DELETE** `/v1/organizations/federation_rules/{federation_rule_id}/workspaces/{workspace_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Disable a federation rule for a workspace. Idempotent; succeeds even if the enablement was already removed. OAuth callers may only manage rules whose `oauth_scope` is `workspace:developer` or `workspace:inference`; other scopes require a Console session. #### Parameters - `--federation-rule-id: string` (path parameter) ID of the federation rule. - `--workspace-id: string` (path parameter) ID of the workspace to disable for. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `BetaOrganizationFederationRuleWorkspaceRemoveResponse: object` - `type: "federation_rule_workspace_deleted"` - `federation_rule_id: string` Tagged ID of the federation rule. - `workspace_id: string` Tagged ID of the workspace named in the delete request. Removal is idempotent. #### Example ```bash ant beta:organization:federation:rules:workspaces remove \ --api-key my-anthropic-api-key \ --federation-rule-id federation_rule_id \ --workspace-id workspace_id ``` ##### Response (200) ```json { "federation_rule_id": "federation_rule_id", "type": "federation_rule_workspace_deleted", "workspace_id": "workspace_id" } ``` ## Beta › Organization › Invites ### Create Invite `$ ant beta:organization:invites create` **POST** `/v1/organizations/invites` Invite a user to join the organization by email. On plans that draw members from a finite pool of purchased seats, the invite automatically consumes a seat from the lowest tier with availability; there is no seat-tier parameter. When no seat is free the request fails with a 400 error rather than purchasing a seat. #### Parameters - `--email: string` Email of the User. format: email - `--role: "billing" or "claude_code_user" or "developer" or 2 more` Role for the invited User. The accepted values depend on the organization type. Console and API organizations accept `user`, `developer`, `billing`, and `claude_code_user`; `admin` cannot be assigned through the API. Claude Enterprise organizations accept `user` and `managed`; inviting with the `managed` role requires the `write:rbac_groups` scope in addition to `write:members`. - `--rbac-group-id: optional array of string` RBAC group IDs to assign to the User when the Invite is accepted. A non-empty array is accepted only for a Claude Enterprise organization with RBAC groups, and requires the key to carry the `write:rbac_groups` scope. maxItems: 100 #### Returns - `beta_organization_invite: object` - `type: "invite"` Object type. For Invites, this is always `"invite"`. - `id: string` ID of the Invite. - `accepted_at: string` RFC 3339 datetime string indicating when the Invite was accepted, or null. format: date-time - `email: string` Email of the User being invited. - `expires_at: string` RFC 3339 datetime string indicating when the Invite expires. format: date-time - `invited_at: string` RFC 3339 datetime string indicating when the Invite was created. format: date-time - `rbac_group_ids: array of string` RBAC group IDs recorded on the Invite (Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none. - `role: "admin" or "billing" or "claude_code_user" or 6 more` Organization role of the User. - `"admin"` - `"billing"` - `"claude_code_user"` - `"developer"` - `"managed"` - `"membership_admin"` - `"owner"` - `"primary_owner"` - `"user"` - `status: "accepted" or "deleted" or "expired" or "pending"` Status of the Invite. - `"accepted"` - `"deleted"` - `"expired"` - `"pending"` #### Example ```bash ant beta:organization:invites create \ --api-key my-anthropic-api-key \ --email user@emaildomain.com \ --role user ``` ##### Response (200) ```json { "id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu", "accepted_at": "2019-12-27T18:11:19.117Z", "email": "user@emaildomain.com", "expires_at": "2024-11-20T23:58:27.427722Z", "invited_at": "2024-10-30T23:58:27.427722Z", "rbac_group_ids": [ "string" ], "role": "admin", "status": "pending", "type": "invite" } ``` ### List Invites `$ ant beta:organization:invites list` **GET** `/v1/organizations/invites` List the organization's invites. #### Parameters - `--after-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - `--before-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - `--email: optional string` (query parameter) Filter by the email address the Invite was sent to. Matches the same way as the Users list's `email` filter (normalized, case-insensitive). format: email - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--role: optional array of string` (query parameter) Filter to items whose `role` equals one of the supplied values. Repeatable; values are OR'ed together. Accepted values depend on the organization type: Console and API organizations accept `user`, `developer`, `billing`, `admin`, and `claude_code_user`; Claude Enterprise organizations accept `user`, `owner`, `primary_owner`, `membership_admin`, and `managed`. - `--status: optional array of "accepted" or "expired" or "pending"` (query parameter) Filter by Invite status. Repeatable; values are OR'ed together. Omit to return `pending`, `accepted`, and `expired` Invites alike. #### Returns - `BetaListResponse_InviteSchema_: object` - `data: array of BetaOrganizationInvite` - `type: "invite"` Object type. For Invites, this is always `"invite"`. - `id: string` ID of the Invite. - `accepted_at: string` RFC 3339 datetime string indicating when the Invite was accepted, or null. format: date-time - `email: string` Email of the User being invited. - `expires_at: string` RFC 3339 datetime string indicating when the Invite expires. format: date-time - `invited_at: string` RFC 3339 datetime string indicating when the Invite was created. format: date-time - `rbac_group_ids: array of string` RBAC group IDs recorded on the Invite (Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none. - `role: "admin" or "billing" or "claude_code_user" or 6 more` Organization role of the User. - `"admin"` - `"billing"` - `"claude_code_user"` - `"developer"` - `"managed"` - `"membership_admin"` - `"owner"` - `"primary_owner"` - `"user"` - `status: "accepted" or "deleted" or "expired" or "pending"` Status of the Invite. - `"accepted"` - `"deleted"` - `"expired"` - `"pending"` - `first_id: string` First ID in the `data` list. Can be used as the `before_id` for the previous page. - `has_more: boolean` Indicates if there are more results in the requested page direction. - `last_id: string` Last ID in the `data` list. Can be used as the `after_id` for the next page. #### Example ```bash ant beta:organization:invites list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu", "accepted_at": "2019-12-27T18:11:19.117Z", "email": "user@emaildomain.com", "expires_at": "2024-11-20T23:58:27.427722Z", "invited_at": "2024-10-30T23:58:27.427722Z", "rbac_group_ids": [ "string" ], "role": "admin", "status": "pending", "type": "invite" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ### Get Invite `$ ant beta:organization:invites retrieve` **GET** `/v1/organizations/invites/{invite_id}` Retrieve an invite by ID. #### Parameters - `--invite-id: string` (path parameter) ID of the Invite. #### Returns - `beta_organization_invite: object` - `type: "invite"` Object type. For Invites, this is always `"invite"`. - `id: string` ID of the Invite. - `accepted_at: string` RFC 3339 datetime string indicating when the Invite was accepted, or null. format: date-time - `email: string` Email of the User being invited. - `expires_at: string` RFC 3339 datetime string indicating when the Invite expires. format: date-time - `invited_at: string` RFC 3339 datetime string indicating when the Invite was created. format: date-time - `rbac_group_ids: array of string` RBAC group IDs recorded on the Invite (Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none. - `role: "admin" or "billing" or "claude_code_user" or 6 more` Organization role of the User. - `"admin"` - `"billing"` - `"claude_code_user"` - `"developer"` - `"managed"` - `"membership_admin"` - `"owner"` - `"primary_owner"` - `"user"` - `status: "accepted" or "deleted" or "expired" or "pending"` Status of the Invite. - `"accepted"` - `"deleted"` - `"expired"` - `"pending"` #### Example ```bash ant beta:organization:invites retrieve \ --api-key my-anthropic-api-key \ --invite-id invite_id ``` ##### Response (200) ```json { "id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu", "accepted_at": "2019-12-27T18:11:19.117Z", "email": "user@emaildomain.com", "expires_at": "2024-11-20T23:58:27.427722Z", "invited_at": "2024-10-30T23:58:27.427722Z", "rbac_group_ids": [ "string" ], "role": "admin", "status": "pending", "type": "invite" } ``` ### Delete Invite `$ ant beta:organization:invites delete` **DELETE** `/v1/organizations/invites/{invite_id}` Delete a pending invite. #### Parameters - `--invite-id: string` (path parameter) ID of the Invite. #### Returns - `BetaOrganizationInviteDeleteResponse: object` - `type: "invite_deleted"` Deleted object type. For Invites, this is always `"invite_deleted"`. - `id: string` ID of the Invite. #### Example ```bash ant beta:organization:invites delete \ --api-key my-anthropic-api-key \ --invite-id invite_id ``` ##### Response (200) ```json { "id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu", "type": "invite_deleted" } ``` ## Beta › Organization › Service Accounts ### Create Service Account `$ ant beta:organization:service-accounts create` **POST** `/v1/organizations/service_accounts` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Create a service account. A service account is a named workload identity that federation rules target. `organization_role` is `developer` (default) or `admin`; a rule may only be created or retargeted to grant `org:admin` scope when the target's `organization_role` is `admin`. Creating an `admin`-role service account requires an interactive credential (a user OAuth token or a Console session) — a workload may only create `developer`-role service accounts. #### Parameters - `--name: string` Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409. minLength: 1, maxLength: 255 - `--description: optional string` Optional free-text description. maxLength: 2000 - `--organization-role: optional "admin" or "developer"` Org-level role. Defaults to `developer`. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_service_account: object` Named non-human identity within the caller's organization. A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules). - `type: "service_account"` - `id: string` Tagged ID of the service account. - `archived_at: string` If set, this service account is archived. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this service account. - `created_at: string` When this service account was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this service account. - `description: string` Optional free-text description. - `name: string` Admin-chosen slug identifier. - `organization_role: "admin" or "developer"` Org-level role. A federation rule may only be created or retargeted to grant `org:admin` scope when this is `admin`. A rule granting `org:admin` whose target is later demoted to `developer` is rejected at token exchange. Rules granting `org:admin` are managed in the Console. - `"admin"` - `"developer"` - `updated_at: string` When this service account was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this service account. #### Example ```bash ant beta:organization:service-accounts create \ --api-key my-anthropic-api-key \ --name ci-deploy-bot ``` ##### Response (200) ```json { "id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "name": "ci-deploy-bot", "organization_role": "admin", "type": "service_account", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" } ``` ### List Service Accounts `$ ant beta:organization:service-accounts list` **GET** `/v1/organizations/service_accounts` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). List service accounts in the caller's organization. Results are ordered by creation time, newest first. Use `limit` and the `next_page` cursor to paginate; set `include_archived=true` to include archived service accounts. #### Parameters - `--include-archived: optional boolean` (query parameter) Include archived resources. Defaults to false. - `--limit: optional number` (query parameter) Number of results per page. minimum: 1, maximum: 100 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `BetaServiceAccountListResponse: object` - `data: array of BetaServiceAccount` - `type: "service_account"` - `id: string` Tagged ID of the service account. - `archived_at: string` If set, this service account is archived. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this service account. - `created_at: string` When this service account was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this service account. - `description: string` Optional free-text description. - `name: string` Admin-chosen slug identifier. - `organization_role: "admin" or "developer"` Org-level role. A federation rule may only be created or retargeted to grant `org:admin` scope when this is `admin`. A rule granting `org:admin` whose target is later demoted to `developer` is rejected at token exchange. Rules granting `org:admin` are managed in the Console. - `"admin"` - `"developer"` - `updated_at: string` When this service account was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this service account. - `next_page: string` Opaque cursor for the next page, or null if no more results. #### Example ```bash ant beta:organization:service-accounts list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "name": "ci-deploy-bot", "organization_role": "admin", "type": "service_account", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" } ], "next_page": "next_page" } ``` ### Get Service Account `$ ant beta:organization:service-accounts retrieve` **GET** `/v1/organizations/service_accounts/{service_account_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Retrieve a service account by its ID (`svac_...`). #### Parameters - `--service-account-id: string` (path parameter) ID of the service account. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_service_account: object` Named non-human identity within the caller's organization. A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules). - `type: "service_account"` - `id: string` Tagged ID of the service account. - `archived_at: string` If set, this service account is archived. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this service account. - `created_at: string` When this service account was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this service account. - `description: string` Optional free-text description. - `name: string` Admin-chosen slug identifier. - `organization_role: "admin" or "developer"` Org-level role. A federation rule may only be created or retargeted to grant `org:admin` scope when this is `admin`. A rule granting `org:admin` whose target is later demoted to `developer` is rejected at token exchange. Rules granting `org:admin` are managed in the Console. - `"admin"` - `"developer"` - `updated_at: string` When this service account was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this service account. #### Example ```bash ant beta:organization:service-accounts retrieve \ --api-key my-anthropic-api-key \ --service-account-id service_account_id ``` ##### Response (200) ```json { "id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "name": "ci-deploy-bot", "organization_role": "admin", "type": "service_account", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" } ``` ### Update Service Account `$ ant beta:organization:service-accounts update` **POST** `/v1/organizations/service_accounts/{service_account_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Update a service account. Only `description` and `organization_role` are mutable; `name` cannot be changed. Archived service accounts cannot be updated; this returns 400. Setting `organization_role` to `admin` (even when unchanged) requires an interactive credential (a user OAuth token or a Console session). #### Parameters - `--service-account-id: string` (path parameter) ID of the service account to update. - `--description: optional string` Replaces the description. Omit to leave unchanged; send `null` to clear (the field is stored as an empty string). maxLength: 2000 - `--organization-role: optional "admin" or "developer"` Replaces the org-level role. Omit or send `null` to leave unchanged. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_service_account: object` Named non-human identity within the caller's organization. A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules). - `type: "service_account"` - `id: string` Tagged ID of the service account. - `archived_at: string` If set, this service account is archived. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this service account. - `created_at: string` When this service account was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this service account. - `description: string` Optional free-text description. - `name: string` Admin-chosen slug identifier. - `organization_role: "admin" or "developer"` Org-level role. A federation rule may only be created or retargeted to grant `org:admin` scope when this is `admin`. A rule granting `org:admin` whose target is later demoted to `developer` is rejected at token exchange. Rules granting `org:admin` are managed in the Console. - `"admin"` - `"developer"` - `updated_at: string` When this service account was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this service account. #### Example ```bash ant beta:organization:service-accounts update \ --api-key my-anthropic-api-key \ --service-account-id service_account_id ``` ##### Response (200) ```json { "id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "name": "ci-deploy-bot", "organization_role": "admin", "type": "service_account", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" } ``` ### Archive Service Account `$ ant beta:organization:service-accounts archive` **POST** `/v1/organizations/service_accounts/{service_account_id}/archive` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Archive a service account. Idempotent; re-archiving returns the service account with its original `archived_at`. Rejected with 400 if any live (non-archived) federation rule still targets this service account, same as issuer archival; archive those rules first or change their target to another service account. #### Parameters - `--service-account-id: string` (path parameter) ID of the service account to archive. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_service_account: object` Named non-human identity within the caller's organization. A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules). - `type: "service_account"` - `id: string` Tagged ID of the service account. - `archived_at: string` If set, this service account is archived. format: date-time - `archived_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that archived this service account. - `created_at: string` When this service account was created. format: date-time - `created_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that created this service account. - `description: string` Optional free-text description. - `name: string` Admin-chosen slug identifier. - `organization_role: "admin" or "developer"` Org-level role. A federation rule may only be created or retargeted to grant `org:admin` scope when this is `admin`. A rule granting `org:admin` whose target is later demoted to `developer` is rejected at token exchange. Rules granting `org:admin` are managed in the Console. - `"admin"` - `"developer"` - `updated_at: string` When this service account was last updated. format: date-time - `updated_by_actor_id: string` Tagged ID (`user_`/`svac_`) of the actor that last updated this service account. #### Example ```bash ant beta:organization:service-accounts archive \ --api-key my-anthropic-api-key \ --service-account-id service_account_id ``` ##### Response (200) ```json { "id": "svac_01SDCCSbTxrXDpWc1phhtcfK", "archived_at": "2019-12-27T18:11:19.117Z", "archived_by_actor_id": "archived_by_actor_id", "created_at": "2024-10-30T23:58:27.427722Z", "created_by_actor_id": "created_by_actor_id", "description": "description", "name": "ci-deploy-bot", "organization_role": "admin", "type": "service_account", "updated_at": "2024-10-30T23:58:27.427722Z", "updated_by_actor_id": "updated_by_actor_id" } ``` ## Beta › Organization › Service Accounts › Workspaces ### Add Workspace To Service Account `$ ant beta:organization:service-accounts:workspaces add` **POST** `/v1/organizations/service_accounts/{service_account_id}/workspaces` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Add a service account to a workspace with the given `workspace_role`. Mirror of `POST /workspaces/{workspace_id}/service_accounts`, addressed from the service-account side; both create the same membership. If the service account is already an explicit member of the workspace, its `workspace_role` is replaced with the value supplied here. Archived workspaces return 400. Archived service accounts cannot be added and are rejected. #### Parameters - `--service-account-id: string` (path parameter) ID of the service account. - `--workspace-id: string` Tagged workspace ID to add the service account to. - `--workspace-role: "workspace_admin" or "workspace_developer" or "workspace_restricted_developer" or "workspace_user"` Role to assign to the service account in this workspace. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_service_account_workspace_member: object` - `type: "service_account_workspace_member"` - `created_by_actor_id: string` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `implicit: boolean` True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed. - `service_account_id: string` Tagged service account ID (`svac_...`). - `workspace_id: string` Tagged workspace ID (`wrkspc_...`). - `workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. - `"workspace_admin"` - `"workspace_billing"` - `"workspace_developer"` - `"workspace_restricted_developer"` - `"workspace_user"` #### Example ```bash ant beta:organization:service-accounts:workspaces add \ --api-key my-anthropic-api-key \ --service-account-id service_account_id \ --workspace-id workspace_id \ --workspace-role workspace_admin ``` ##### Response (200) ```json { "created_by_actor_id": "created_by_actor_id", "implicit": true, "service_account_id": "service_account_id", "type": "service_account_workspace_member", "workspace_id": "workspace_id", "workspace_role": "workspace_admin" } ``` ### List Workspaces For Service Account `$ ant beta:organization:service-accounts:workspaces list` **GET** `/v1/organizations/service_accounts/{service_account_id}/workspaces` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). List the workspaces a service account is a member of. Each entry includes the service account's `workspace_role` in that workspace. Use `limit` and the `next_page` cursor to paginate. When the service account has no explicit default-workspace membership, the implicit (`implicit: true`) membership is returned as the first entry on the first page; with `limit=1` the first page may return up to 2 entries (the implicit entry plus one explicit membership) so a pagination cursor can be derived. Memberships are returned only while the service account is active. Without a `page` cursor, an archived service account returns an empty list. A `page` cursor that does not match an active membership returns a 400 invalid-request error. A cursor stops matching when the membership is removed, the workspace is deleted, or the service account is archived. Restart pagination from the first page to recover. #### Parameters - `--service-account-id: string` (path parameter) ID of the service account. - `--limit: optional number` (query parameter) Number of results per page. minimum: 1, maximum: 100 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `BetaServiceAccountWorkspaceMemberListResponse: object` - `data: array of BetaServiceAccountWorkspaceMember` - `type: "service_account_workspace_member"` - `created_by_actor_id: string` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `implicit: boolean` True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed. - `service_account_id: string` Tagged service account ID (`svac_...`). - `workspace_id: string` Tagged workspace ID (`wrkspc_...`). - `workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. - `"workspace_admin"` - `"workspace_billing"` - `"workspace_developer"` - `"workspace_restricted_developer"` - `"workspace_user"` - `next_page: string` Opaque cursor for the next page, or null if no more results. #### Example ```bash ant beta:organization:service-accounts:workspaces list \ --api-key my-anthropic-api-key \ --service-account-id service_account_id ``` ##### Response (200) ```json { "data": [ { "created_by_actor_id": "created_by_actor_id", "implicit": true, "service_account_id": "service_account_id", "type": "service_account_workspace_member", "workspace_id": "workspace_id", "workspace_role": "workspace_admin" } ], "next_page": "next_page" } ``` ### Remove Workspace From Service Account `$ ant beta:organization:service-accounts:workspaces remove` **DELETE** `/v1/organizations/service_accounts/{service_account_id}/workspaces/{workspace_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Remove a service account from a workspace. Mirror of `DELETE /workspaces/{workspace_id}/service_accounts/{service_account_id}`, addressed from the service-account side. Removal is idempotent (returns 200 even if the membership was already removed). A DELETE against the implicit default-workspace membership returns 200 but is a no-op and the membership persists; deleting an explicit default-workspace row reverts to the implicit `workspace_user` membership. Archived workspaces return 400. #### Parameters - `--service-account-id: string` (path parameter) ID of the service account. - `--workspace-id: string` (path parameter) ID of the workspace. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `BetaOrganizationServiceAccountWorkspaceRemoveResponse: object` - `type: "service_account_workspace_member_deleted"` - `service_account_id: string` Tagged service account ID (`svac_...`) named in the delete request. Removal is idempotent; see the endpoint description for the implicit-membership no-op. - `workspace_id: string` Tagged workspace ID (`wrkspc_...`) named in the delete request. #### Example ```bash ant beta:organization:service-accounts:workspaces remove \ --api-key my-anthropic-api-key \ --service-account-id service_account_id \ --workspace-id workspace_id ``` ##### Response (200) ```json { "service_account_id": "service_account_id", "type": "service_account_workspace_member_deleted", "workspace_id": "workspace_id" } ``` ## Beta › Organization › Users ### List Users `$ ant beta:organization:users list` **GET** `/v1/organizations/users` List the organization's members. #### Parameters - `--after-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - `--before-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - `--email: optional string` (query parameter) Filter by user email. format: email - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--role: optional array of string` (query parameter) Filter to items whose `role` equals one of the supplied values. Repeatable; values are OR'ed together. Accepted values depend on the organization type: Console and API organizations accept `user`, `developer`, `billing`, `admin`, and `claude_code_user`; Claude Enterprise organizations accept `user`, `owner`, `primary_owner`, `membership_admin`, and `managed`. #### Returns - `BetaListResponse_User_: object` - `data: array of BetaOrganizationUser` - `type: "user"` Object type. For Users, this is always `"user"`. - `id: string` ID of the User. - `added_at: string` RFC 3339 datetime string indicating when the User joined the Organization. format: date-time - `email: string` Email of the User. - `name: string` Name of the User. - `role: "admin" or "billing" or "claude_code_user" or 6 more` Organization role of the User. - `"admin"` - `"billing"` - `"claude_code_user"` - `"developer"` - `"managed"` - `"membership_admin"` - `"owner"` - `"primary_owner"` - `"user"` - `first_id: string` First ID in the `data` list. Can be used as the `before_id` for the previous page. - `has_more: boolean` Indicates if there are more results in the requested page direction. - `last_id: string` Last ID in the `data` list. Can be used as the `after_id` for the next page. #### Example ```bash ant beta:organization:users list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "added_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "name": "Jane Doe", "role": "admin", "type": "user" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ### Get User `$ ant beta:organization:users retrieve` **GET** `/v1/organizations/users/{user_id}` Retrieve a member of the organization by user ID. #### Parameters - `--user-id: string` (path parameter) ID of the User. #### Returns - `beta_organization_user: object` - `type: "user"` Object type. For Users, this is always `"user"`. - `id: string` ID of the User. - `added_at: string` RFC 3339 datetime string indicating when the User joined the Organization. format: date-time - `email: string` Email of the User. - `name: string` Name of the User. - `role: "admin" or "billing" or "claude_code_user" or 6 more` Organization role of the User. - `"admin"` - `"billing"` - `"claude_code_user"` - `"developer"` - `"managed"` - `"membership_admin"` - `"owner"` - `"primary_owner"` - `"user"` #### Example ```bash ant beta:organization:users retrieve \ --api-key my-anthropic-api-key \ --user-id user_id ``` ##### Response (200) ```json { "id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "added_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "name": "Jane Doe", "role": "admin", "type": "user" } ``` ### Update User `$ ant beta:organization:users update` **POST** `/v1/organizations/users/{user_id}` Update a member's organization role. #### Parameters - `--user-id: string` (path parameter) ID of the User. - `--role: "billing" or "claude_code_user" or "developer" or 2 more` New role for the User. The accepted values depend on the organization type. Console and API organizations accept `user`, `developer`, `billing`, and `claude_code_user`; `admin` cannot be assigned through the API. Claude Enterprise organizations accept `user` and `managed`; changing a User's role to `managed` requires the `write:rbac_groups` scope in addition to `write:members`. #### Returns - `beta_organization_user: object` - `type: "user"` Object type. For Users, this is always `"user"`. - `id: string` ID of the User. - `added_at: string` RFC 3339 datetime string indicating when the User joined the Organization. format: date-time - `email: string` Email of the User. - `name: string` Name of the User. - `role: "admin" or "billing" or "claude_code_user" or 6 more` Organization role of the User. - `"admin"` - `"billing"` - `"claude_code_user"` - `"developer"` - `"managed"` - `"membership_admin"` - `"owner"` - `"primary_owner"` - `"user"` #### Example ```bash ant beta:organization:users update \ --api-key my-anthropic-api-key \ --user-id user_id \ --role user ``` ##### Response (200) ```json { "id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "added_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "name": "Jane Doe", "role": "admin", "type": "user" } ``` ### Remove User `$ ant beta:organization:users remove` **DELETE** `/v1/organizations/users/{user_id}` Remove a member from the organization. #### Parameters - `--user-id: string` (path parameter) ID of the User. #### Returns - `BetaOrganizationUserRemoveResponse: object` - `type: "user_deleted"` Deleted object type. For Users, this is always `"user_deleted"`. - `id: string` ID of the User. #### Example ```bash ant beta:organization:users remove \ --api-key my-anthropic-api-key \ --user-id user_id ``` ##### Response (200) ```json { "id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "type": "user_deleted" } ``` ## Beta › Organization › Workspaces ### List Workspaces `$ ant beta:organization:workspaces list` **GET** `/v1/organizations/workspaces` List Workspaces #### Parameters - `--after-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - `--before-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - `--include-archived: optional boolean` (query parameter) Whether to include Workspaces that have been archived in the response - `--include-default: optional boolean` (query parameter) Whether to include the organization's default Workspace in the response - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 #### Returns - `BetaListResponse_Workspace_: object` - `data: array of BetaWorkspace` - `type: "workspace"` Object type. For Workspaces, this is always `"workspace"`. - `id: string` ID of the Workspace. - `archived_at: string` RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived. format: date-time - `compartment_id: string` Identifier for this Workspace's encryption compartment. When you configure a customer-managed encryption key (CMEK) on AWS, reference this value in your KMS key-policy condition so the key is scoped to this compartment. On GCP and Azure, Anthropic enforces the compartment binding automatically; you do not need to reference this value in your key configuration. See the CMEK integration guide for the required key configuration; unless your organization is on Claude Platform on AWS, it includes a separate value used during key validation. On Claude Platform on AWS there is no separate validation value: the key is validated against this Workspace's own value when it is attached, so if your key policy uses the compartment condition, add this value to it before attaching the key. - `created_at: string` RFC 3339 datetime string indicating when the Workspace was created. format: date-time - `data_residency: object` Data residency configuration. - `allowed_inference_geos: array of BetaAllowedInferenceGeo or "unrestricted"` Permitted inference geo values. 'unrestricted' means all geos are allowed. - `geos: array of BetaAllowedInferenceGeo` - `"global"` - `"us"` - `unrestricted: "unrestricted"` - `default_inference_geo: "global" or "us"` Default inference geo applied when requests omit the parameter. - `"global"` - `"us"` - `workspace_geo: "us"` Geographic region for workspace data storage. Immutable after creation. - `display_color: string` Hex color code representing the Workspace in the Anthropic Console. - `external_key_id: string` ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same. - `name: string` Name of the Workspace. - `tags: map[string]` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. - `first_id: string` First ID in the `data` list. Can be used as the `before_id` for the previous page. - `has_more: boolean` Indicates if there are more results in the requested page direction. - `last_id: string` Last ID in the `data` list. Can be used as the `after_id` for the next page. #### Example ```bash ant beta:organization:workspaces list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "archived_at": "2024-11-01T23:59:27.427722Z", "compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c", "created_at": "2024-10-30T23:58:27.427722Z", "data_residency": { "allowed_inference_geos": "unrestricted", "default_inference_geo": "global", "workspace_geo": "us" }, "display_color": "#6C5BB9", "external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "name": "Workspace Name", "tags": { "env": "prod", "team": "platform" }, "type": "workspace" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ### Create Workspace `$ ant beta:organization:workspaces create` **POST** `/v1/organizations/workspaces` Create Workspace #### Parameters - `--name: string` Name of the Workspace. minLength: 1, maxLength: 255 - `--data-residency: optional object` Data residency configuration for the workspace. If omitted, defaults to `workspace_geo: "us"`, `allowed_inference_geos: "unrestricted"`, and `default_inference_geo: "global"`. - `--display-color: optional string` Hex color code representing the Workspace in the Anthropic Console. maxLength: 7, pattern: ^#[0-9A-Fa-f]{6}$ - `--external-key-id: optional string` ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same. - `--tags: optional map[string]` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_workspace: object` - `type: "workspace"` Object type. For Workspaces, this is always `"workspace"`. - `id: string` ID of the Workspace. - `archived_at: string` RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived. format: date-time - `compartment_id: string` Identifier for this Workspace's encryption compartment. When you configure a customer-managed encryption key (CMEK) on AWS, reference this value in your KMS key-policy condition so the key is scoped to this compartment. On GCP and Azure, Anthropic enforces the compartment binding automatically; you do not need to reference this value in your key configuration. See the CMEK integration guide for the required key configuration; unless your organization is on Claude Platform on AWS, it includes a separate value used during key validation. On Claude Platform on AWS there is no separate validation value: the key is validated against this Workspace's own value when it is attached, so if your key policy uses the compartment condition, add this value to it before attaching the key. - `created_at: string` RFC 3339 datetime string indicating when the Workspace was created. format: date-time - `data_residency: object` Data residency configuration. - `allowed_inference_geos: array of BetaAllowedInferenceGeo or "unrestricted"` Permitted inference geo values. 'unrestricted' means all geos are allowed. - `geos: array of BetaAllowedInferenceGeo` - `"global"` - `"us"` - `unrestricted: "unrestricted"` - `default_inference_geo: "global" or "us"` Default inference geo applied when requests omit the parameter. - `"global"` - `"us"` - `workspace_geo: "us"` Geographic region for workspace data storage. Immutable after creation. - `display_color: string` Hex color code representing the Workspace in the Anthropic Console. - `external_key_id: string` ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same. - `name: string` Name of the Workspace. - `tags: map[string]` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. #### Example ```bash ant beta:organization:workspaces create \ --api-key my-anthropic-api-key \ --name x ``` ##### Response (200) ```json { "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "archived_at": "2024-11-01T23:59:27.427722Z", "compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c", "created_at": "2024-10-30T23:58:27.427722Z", "data_residency": { "allowed_inference_geos": "unrestricted", "default_inference_geo": "global", "workspace_geo": "us" }, "display_color": "#6C5BB9", "external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "name": "Workspace Name", "tags": { "env": "prod", "team": "platform" }, "type": "workspace" } ``` ### Get Workspace `$ ant beta:organization:workspaces retrieve` **GET** `/v1/organizations/workspaces/{workspace_id}` Get Workspace #### Parameters - `--workspace-id: string` (path parameter) ID of the Workspace. #### Returns - `beta_workspace: object` - `type: "workspace"` Object type. For Workspaces, this is always `"workspace"`. - `id: string` ID of the Workspace. - `archived_at: string` RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived. format: date-time - `compartment_id: string` Identifier for this Workspace's encryption compartment. When you configure a customer-managed encryption key (CMEK) on AWS, reference this value in your KMS key-policy condition so the key is scoped to this compartment. On GCP and Azure, Anthropic enforces the compartment binding automatically; you do not need to reference this value in your key configuration. See the CMEK integration guide for the required key configuration; unless your organization is on Claude Platform on AWS, it includes a separate value used during key validation. On Claude Platform on AWS there is no separate validation value: the key is validated against this Workspace's own value when it is attached, so if your key policy uses the compartment condition, add this value to it before attaching the key. - `created_at: string` RFC 3339 datetime string indicating when the Workspace was created. format: date-time - `data_residency: object` Data residency configuration. - `allowed_inference_geos: array of BetaAllowedInferenceGeo or "unrestricted"` Permitted inference geo values. 'unrestricted' means all geos are allowed. - `geos: array of BetaAllowedInferenceGeo` - `"global"` - `"us"` - `unrestricted: "unrestricted"` - `default_inference_geo: "global" or "us"` Default inference geo applied when requests omit the parameter. - `"global"` - `"us"` - `workspace_geo: "us"` Geographic region for workspace data storage. Immutable after creation. - `display_color: string` Hex color code representing the Workspace in the Anthropic Console. - `external_key_id: string` ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same. - `name: string` Name of the Workspace. - `tags: map[string]` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. #### Example ```bash ant beta:organization:workspaces retrieve \ --api-key my-anthropic-api-key \ --workspace-id workspace_id ``` ##### Response (200) ```json { "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "archived_at": "2024-11-01T23:59:27.427722Z", "compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c", "created_at": "2024-10-30T23:58:27.427722Z", "data_residency": { "allowed_inference_geos": "unrestricted", "default_inference_geo": "global", "workspace_geo": "us" }, "display_color": "#6C5BB9", "external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "name": "Workspace Name", "tags": { "env": "prod", "team": "platform" }, "type": "workspace" } ``` ### Update Workspace `$ ant beta:organization:workspaces update` **POST** `/v1/organizations/workspaces/{workspace_id}` Update Workspace #### Parameters - `--workspace-id: string` (path parameter) - `--data-residency: optional object` Data residency configuration for the workspace. - `--display-color: optional string` Hex color code representing the Workspace in the Anthropic Console. maxLength: 7, pattern: ^#[0-9A-Fa-f]{6}$ - `--external-key-id: optional string` ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same. - `--name: optional string` Name of the Workspace. minLength: 1, maxLength: 255 - `--tags: optional map[string]` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. #### Returns - `beta_workspace: object` - `type: "workspace"` Object type. For Workspaces, this is always `"workspace"`. - `id: string` ID of the Workspace. - `archived_at: string` RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived. format: date-time - `compartment_id: string` Identifier for this Workspace's encryption compartment. When you configure a customer-managed encryption key (CMEK) on AWS, reference this value in your KMS key-policy condition so the key is scoped to this compartment. On GCP and Azure, Anthropic enforces the compartment binding automatically; you do not need to reference this value in your key configuration. See the CMEK integration guide for the required key configuration; unless your organization is on Claude Platform on AWS, it includes a separate value used during key validation. On Claude Platform on AWS there is no separate validation value: the key is validated against this Workspace's own value when it is attached, so if your key policy uses the compartment condition, add this value to it before attaching the key. - `created_at: string` RFC 3339 datetime string indicating when the Workspace was created. format: date-time - `data_residency: object` Data residency configuration. - `allowed_inference_geos: array of BetaAllowedInferenceGeo or "unrestricted"` Permitted inference geo values. 'unrestricted' means all geos are allowed. - `geos: array of BetaAllowedInferenceGeo` - `"global"` - `"us"` - `unrestricted: "unrestricted"` - `default_inference_geo: "global" or "us"` Default inference geo applied when requests omit the parameter. - `"global"` - `"us"` - `workspace_geo: "us"` Geographic region for workspace data storage. Immutable after creation. - `display_color: string` Hex color code representing the Workspace in the Anthropic Console. - `external_key_id: string` ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same. - `name: string` Name of the Workspace. - `tags: map[string]` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. #### Example ```bash ant beta:organization:workspaces update \ --api-key my-anthropic-api-key \ --workspace-id workspace_id ``` ##### Response (200) ```json { "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "archived_at": "2024-11-01T23:59:27.427722Z", "compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c", "created_at": "2024-10-30T23:58:27.427722Z", "data_residency": { "allowed_inference_geos": "unrestricted", "default_inference_geo": "global", "workspace_geo": "us" }, "display_color": "#6C5BB9", "external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "name": "Workspace Name", "tags": { "env": "prod", "team": "platform" }, "type": "workspace" } ``` ### Archive Workspace `$ ant beta:organization:workspaces archive` **POST** `/v1/organizations/workspaces/{workspace_id}/archive` Archive Workspace #### Parameters - `--workspace-id: string` (path parameter) #### Returns - `beta_workspace: object` - `type: "workspace"` Object type. For Workspaces, this is always `"workspace"`. - `id: string` ID of the Workspace. - `archived_at: string` RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived. format: date-time - `compartment_id: string` Identifier for this Workspace's encryption compartment. When you configure a customer-managed encryption key (CMEK) on AWS, reference this value in your KMS key-policy condition so the key is scoped to this compartment. On GCP and Azure, Anthropic enforces the compartment binding automatically; you do not need to reference this value in your key configuration. See the CMEK integration guide for the required key configuration; unless your organization is on Claude Platform on AWS, it includes a separate value used during key validation. On Claude Platform on AWS there is no separate validation value: the key is validated against this Workspace's own value when it is attached, so if your key policy uses the compartment condition, add this value to it before attaching the key. - `created_at: string` RFC 3339 datetime string indicating when the Workspace was created. format: date-time - `data_residency: object` Data residency configuration. - `allowed_inference_geos: array of BetaAllowedInferenceGeo or "unrestricted"` Permitted inference geo values. 'unrestricted' means all geos are allowed. - `geos: array of BetaAllowedInferenceGeo` - `"global"` - `"us"` - `unrestricted: "unrestricted"` - `default_inference_geo: "global" or "us"` Default inference geo applied when requests omit the parameter. - `"global"` - `"us"` - `workspace_geo: "us"` Geographic region for workspace data storage. Immutable after creation. - `display_color: string` Hex color code representing the Workspace in the Anthropic Console. - `external_key_id: string` ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same. - `name: string` Name of the Workspace. - `tags: map[string]` User-defined tags as string key-value pairs. Keys may not begin with `anthropic`. #### Example ```bash ant beta:organization:workspaces archive \ --api-key my-anthropic-api-key \ --workspace-id workspace_id ``` ##### Response (200) ```json { "id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "archived_at": "2024-11-01T23:59:27.427722Z", "compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c", "created_at": "2024-10-30T23:58:27.427722Z", "data_residency": { "allowed_inference_geos": "unrestricted", "default_inference_geo": "global", "workspace_geo": "us" }, "display_color": "#6C5BB9", "external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK", "name": "Workspace Name", "tags": { "env": "prod", "team": "platform" }, "type": "workspace" } ``` ## Beta › Organization › Workspaces › Rate Limits ### List Workspace Rate Limits `$ ant beta:organization:workspaces:rate-limits list` **GET** `/v1/organizations/workspaces/{workspace_id}/rate_limits` List a workspace's rate limits. By default, returns only the groups and limiter types that have a workspace-level override. With `include_inherited=true`, returns every group with organization-level limits the workspace can see, listing for each the values it inherits from the organization as well as its own overrides. Each value's `source` says which it is. When `limit` is omitted, every matching entry is returned in a single page; when `limit` truncates the result, follow `next_page` to fetch the remaining entries. #### Parameters - `--workspace-id: string` (path parameter) The ID of the workspace. - `--group-type: optional "batch" or "files" or "model_group" or 3 more` (query parameter) Filter by group type. - `--include-inherited: optional boolean` (query parameter) Also list the limiter values the workspace inherits from the organization, including groups with no workspace-level override. - `--limit: optional number` (query parameter) Maximum number of items to return per page. Ranges from `1` to `1000`. When omitted, every remaining entry is returned in a single page and `next_page` is `null`. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. #### Returns - `BetaWorkspaceRateLimitListResponse: object` - `data: array of BetaWorkspaceRateLimit` Rate-limit entries for the workspace: one per group with at least one override, or, with `include_inherited` set to `true`, one per group the workspace can see that has organization-level limits. - `type: "workspace_rate_limit"` Object type. Always `workspace_rate_limit` for workspace rate-limit entries. - `group: BetaOrganizationRateLimitModelGroup or BetaOrganizationRateLimitBatchGroup or BetaOrganizationRateLimitTokenCountGroup or 3 more` The rate-limit group this entry's limits apply to. Its `type` equals `group_type`. - `beta_organization_rate_limit_model_group: object` - `type: "model_group"` Always `model_group`: a family of models. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `display_name: string` Human-readable name of the model group (for example, `Claude Sonnet 4.x`). For display only; it may change. - `beta_organization_rate_limit_batch_group: object` - `type: "batch"` Always `batch`: the Message Batches API. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `beta_organization_rate_limit_token_count_group: object` - `type: "token_count"` Always `token_count`: the Token Count API. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `beta_organization_rate_limit_files_group: object` - `type: "files"` Always `files`: the Files API. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `beta_organization_rate_limit_skills_group: object` - `type: "skills"` Always `skills`: the Skills API. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `beta_organization_rate_limit_web_search_group: object` - `type: "web_search"` Always `web_search`: the Messages API web search tool. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `limits: array of BetaWorkspaceRateLimitValue` The workspace's limiter values for this group. By default only the limiter types with a workspace-level override are listed. With `include_inherited` set to `true`, the limiter types the workspace inherits from the organization are listed too, each marked by `source`. - `type: string` The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`). - `org_limit: number` The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type. - `source: BetaWorkspaceRateLimitWorkspaceSource or BetaWorkspaceRateLimitOrganizationSource` Where `value` comes from. `organization` values are listed only when `include_inherited` is `true`, and then `value` equals `org_limit`. - `beta_workspace_rate_limit_workspace_source: object` - `type: "workspace"` Always `workspace`: a workspace-level override is stored. - `beta_workspace_rate_limit_organization_source: object` - `type: "organization"` Always `organization`: no workspace-level override is stored, so the organization's value applies. - `value: number` The workspace's value for this limiter type: the workspace-level override when `source.type` is `workspace`, otherwise the organization's value. - `models: array of string` Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`. - `rate_limit_id: string` The `id` of the organization's RateLimit entry this entry applies to. - `workspace_id: string` ID of the Workspace this entry applies to. - `group_type: "batch" or "files" or "model_group" or 3 more` **Deprecated**: Use `group.type` instead. `group_type` is still returned and always equals `group.type`. Deprecated: use `group.type` instead. The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`. Always equal to `group.type`. - `"batch"` - `"files"` - `"model_group"` - `"skills"` - `"token_count"` - `"web_search"` - `next_page: string` Opaque cursor for the next page of results, or `null` when no entries remain beyond this response. #### Example ```bash ant beta:organization:workspaces:rate-limits list \ --api-key my-anthropic-api-key \ --workspace-id workspace_id ``` ##### Response (200) ```json { "data": [ { "group": { "id": "id", "display_name": "display_name", "type": "model_group" }, "group_type": "batch", "limits": [ { "org_limit": 0, "source": { "type": "workspace" }, "type": "type", "value": 0 } ], "models": [ "string" ], "rate_limit_id": "rate_limit_id", "type": "workspace_rate_limit", "workspace_id": "workspace_id" } ], "next_page": "next_page" } ``` ## Beta › Organization › Workspaces › Members ### List Workspace Members `$ ant beta:organization:workspaces:members list` **GET** `/v1/organizations/workspaces/{workspace_id}/members` List Workspace Members #### Parameters - `--workspace-id: string` (path parameter) ID of the Workspace. - `--after-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - `--before-id: optional string` (query parameter) ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 #### Returns - `BetaListResponse_WorkspaceMemberSchema_: object` - `data: array of BetaWorkspaceMember` - `type: "workspace_member"` Object type. For Workspace Members, this is always `"workspace_member"`. - `user_id: string` ID of the User. - `workspace_id: string` ID of the Workspace. - `workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` Role of the Workspace Member. - `"workspace_admin"` - `"workspace_billing"` - `"workspace_developer"` - `"workspace_restricted_developer"` - `"workspace_user"` - `first_id: string` First ID in the `data` list. Can be used as the `before_id` for the previous page. - `has_more: boolean` Indicates if there are more results in the requested page direction. - `last_id: string` Last ID in the `data` list. Can be used as the `after_id` for the next page. #### Example ```bash ant beta:organization:workspaces:members list \ --api-key my-anthropic-api-key \ --workspace-id workspace_id ``` ##### Response (200) ```json { "data": [ { "type": "workspace_member", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "workspace_role": "workspace_admin" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ### Create Workspace Member `$ ant beta:organization:workspaces:members add` **POST** `/v1/organizations/workspaces/{workspace_id}/members` Create Workspace Member #### Parameters - `--workspace-id: string` (path parameter) ID of the Workspace. - `--user-id: string` ID of the User. - `--workspace-role: "workspace_admin" or "workspace_developer" or "workspace_restricted_developer" or "workspace_user"` Role of the new Workspace Member. Cannot be `workspace_billing`. #### Returns - `beta_workspace_member: object` - `type: "workspace_member"` Object type. For Workspace Members, this is always `"workspace_member"`. - `user_id: string` ID of the User. - `workspace_id: string` ID of the Workspace. - `workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` Role of the Workspace Member. - `"workspace_admin"` - `"workspace_billing"` - `"workspace_developer"` - `"workspace_restricted_developer"` - `"workspace_user"` #### Example ```bash ant beta:organization:workspaces:members add \ --api-key my-anthropic-api-key \ --workspace-id workspace_id \ --user-id user_01WCz1FkmYMm4gnmykNKUu3Q \ --workspace-role workspace_admin ``` ##### Response (200) ```json { "type": "workspace_member", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "workspace_role": "workspace_admin" } ``` ### Get Workspace Member `$ ant beta:organization:workspaces:members retrieve` **GET** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}` Get Workspace Member #### Parameters - `--workspace-id: string` (path parameter) ID of the Workspace. - `--user-id: string` (path parameter) ID of the User. #### Returns - `beta_workspace_member: object` - `type: "workspace_member"` Object type. For Workspace Members, this is always `"workspace_member"`. - `user_id: string` ID of the User. - `workspace_id: string` ID of the Workspace. - `workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` Role of the Workspace Member. - `"workspace_admin"` - `"workspace_billing"` - `"workspace_developer"` - `"workspace_restricted_developer"` - `"workspace_user"` #### Example ```bash ant beta:organization:workspaces:members retrieve \ --api-key my-anthropic-api-key \ --workspace-id workspace_id \ --user-id user_id ``` ##### Response (200) ```json { "type": "workspace_member", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "workspace_role": "workspace_admin" } ``` ### Update Workspace Member `$ ant beta:organization:workspaces:members update` **POST** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}` Update Workspace Member #### Parameters - `--workspace-id: string` (path parameter) ID of the Workspace. - `--user-id: string` (path parameter) ID of the User. - `--workspace-role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` New workspace role for the User. #### Returns - `beta_workspace_member: object` - `type: "workspace_member"` Object type. For Workspace Members, this is always `"workspace_member"`. - `user_id: string` ID of the User. - `workspace_id: string` ID of the Workspace. - `workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` Role of the Workspace Member. - `"workspace_admin"` - `"workspace_billing"` - `"workspace_developer"` - `"workspace_restricted_developer"` - `"workspace_user"` #### Example ```bash ant beta:organization:workspaces:members update \ --api-key my-anthropic-api-key \ --workspace-id workspace_id \ --user-id user_id \ --workspace-role workspace_admin ``` ##### Response (200) ```json { "type": "workspace_member", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", "workspace_role": "workspace_admin" } ``` ### Delete Workspace Member `$ ant beta:organization:workspaces:members remove` **DELETE** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}` Delete Workspace Member #### Parameters - `--workspace-id: string` (path parameter) ID of the Workspace. - `--user-id: string` (path parameter) ID of the User. #### Returns - `BetaOrganizationWorkspaceMemberRemoveResponse: object` - `type: "workspace_member_deleted"` Deleted object type. For Workspace Members, this is always `"workspace_member_deleted"`. - `user_id: string` ID of the User. - `workspace_id: string` ID of the Workspace. #### Example ```bash ant beta:organization:workspaces:members remove \ --api-key my-anthropic-api-key \ --workspace-id workspace_id \ --user-id user_id ``` ##### Response (200) ```json { "type": "workspace_member_deleted", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } ``` ## Beta › Organization › Workspaces › Service Accounts ### List Service Account Workspace Members `$ ant beta:organization:workspaces:service-accounts list` **GET** `/v1/organizations/workspaces/{workspace_id}/service_accounts` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). List the service accounts that are members of a workspace. Each entry includes the service account's `workspace_role`. Use `limit` and the `next_page` cursor to paginate. Archived workspaces return 400; use `GET /service_accounts/{id}/workspaces` to audit memberships of an archived workspace. The implicit default-workspace membership is not included in this list. Memberships of archived service accounts are omitted from the results. #### Parameters - `--workspace-id: string` (path parameter) ID of the workspace. - `--limit: optional number` (query parameter) Number of results per page. minimum: 1, maximum: 100 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `BetaServiceAccountWorkspaceMemberListResponse: object` - `data: array of BetaServiceAccountWorkspaceMember` - `type: "service_account_workspace_member"` - `created_by_actor_id: string` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `implicit: boolean` True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed. - `service_account_id: string` Tagged service account ID (`svac_...`). - `workspace_id: string` Tagged workspace ID (`wrkspc_...`). - `workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. - `"workspace_admin"` - `"workspace_billing"` - `"workspace_developer"` - `"workspace_restricted_developer"` - `"workspace_user"` - `next_page: string` Opaque cursor for the next page, or null if no more results. #### Example ```bash ant beta:organization:workspaces:service-accounts list \ --api-key my-anthropic-api-key \ --workspace-id workspace_id ``` ##### Response (200) ```json { "data": [ { "created_by_actor_id": "created_by_actor_id", "implicit": true, "service_account_id": "service_account_id", "type": "service_account_workspace_member", "workspace_id": "workspace_id", "workspace_role": "workspace_admin" } ], "next_page": "next_page" } ``` ### Create Service Account Workspace Member `$ ant beta:organization:workspaces:service-accounts add` **POST** `/v1/organizations/workspaces/{workspace_id}/service_accounts` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Add a service account to a workspace with the given `workspace_role`. The role determines what the service account can do in the workspace and which workspace-scoped permissions it can be granted when authenticating through federation. Every service account is already an implicit `workspace_user` member of the default workspace; adding it explicitly assigns a chosen role. If the service account is already an explicit member of the workspace, its `workspace_role` is replaced with the value supplied here. Archived workspaces return 400. Archived service accounts cannot be added and are rejected. #### Parameters - `--workspace-id: string` (path parameter) ID of the workspace. - `--service-account-id: string` Tagged service account ID to add. - `--workspace-role: "workspace_admin" or "workspace_developer" or "workspace_restricted_developer" or "workspace_user"` Role to assign to the service account in this workspace. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_service_account_workspace_member: object` - `type: "service_account_workspace_member"` - `created_by_actor_id: string` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `implicit: boolean` True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed. - `service_account_id: string` Tagged service account ID (`svac_...`). - `workspace_id: string` Tagged workspace ID (`wrkspc_...`). - `workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. - `"workspace_admin"` - `"workspace_billing"` - `"workspace_developer"` - `"workspace_restricted_developer"` - `"workspace_user"` #### Example ```bash ant beta:organization:workspaces:service-accounts add \ --api-key my-anthropic-api-key \ --workspace-id workspace_id \ --service-account-id service_account_id \ --workspace-role workspace_admin ``` ##### Response (200) ```json { "created_by_actor_id": "created_by_actor_id", "implicit": true, "service_account_id": "service_account_id", "type": "service_account_workspace_member", "workspace_id": "workspace_id", "workspace_role": "workspace_admin" } ``` ### Get Service Account Workspace Member `$ ant beta:organization:workspaces:service-accounts retrieve` **GET** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Retrieve a service account's membership in a workspace. Returns the membership record, including the service account's `workspace_role` in this workspace. Archived workspaces return 400. For the default workspace, returns the implicit (`implicit: true`) membership when no explicit membership exists; an explicitly added membership is returned with its assigned role. An archived service account returns 404. #### Parameters - `--workspace-id: string` (path parameter) ID of the workspace. - `--service-account-id: string` (path parameter) ID of the service account. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_service_account_workspace_member: object` - `type: "service_account_workspace_member"` - `created_by_actor_id: string` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `implicit: boolean` True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed. - `service_account_id: string` Tagged service account ID (`svac_...`). - `workspace_id: string` Tagged workspace ID (`wrkspc_...`). - `workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. - `"workspace_admin"` - `"workspace_billing"` - `"workspace_developer"` - `"workspace_restricted_developer"` - `"workspace_user"` #### Example ```bash ant beta:organization:workspaces:service-accounts retrieve \ --api-key my-anthropic-api-key \ --workspace-id workspace_id \ --service-account-id service_account_id ``` ##### Response (200) ```json { "created_by_actor_id": "created_by_actor_id", "implicit": true, "service_account_id": "service_account_id", "type": "service_account_workspace_member", "workspace_id": "workspace_id", "workspace_role": "workspace_admin" } ``` ### Update Service Account Workspace Member `$ ant beta:organization:workspaces:service-accounts update` **POST** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Change a service account's role in a workspace. The new `workspace_role` replaces the current one. Only explicit memberships can be updated; to set a role on the implicit default-workspace membership, add the service account explicitly with `POST /workspaces/{workspace_id}/service_accounts`. Archived workspaces return 400. Archived service accounts cannot be updated and are rejected. #### Parameters - `--workspace-id: string` (path parameter) ID of the workspace. - `--service-account-id: string` (path parameter) ID of the service account. - `--workspace-role: "workspace_admin" or "workspace_developer" or "workspace_restricted_developer" or "workspace_user"` New role for the service account in this workspace. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_service_account_workspace_member: object` - `type: "service_account_workspace_member"` - `created_by_actor_id: string` Tagged ID (`user_...`/`svac_...`) of the actor who created this membership. - `implicit: boolean` True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed. - `service_account_id: string` Tagged service account ID (`svac_...`). - `workspace_id: string` Tagged workspace ID (`wrkspc_...`). - `workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more` Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role. - `"workspace_admin"` - `"workspace_billing"` - `"workspace_developer"` - `"workspace_restricted_developer"` - `"workspace_user"` #### Example ```bash ant beta:organization:workspaces:service-accounts update \ --api-key my-anthropic-api-key \ --workspace-id workspace_id \ --service-account-id service_account_id \ --workspace-role workspace_admin ``` ##### Response (200) ```json { "created_by_actor_id": "created_by_actor_id", "implicit": true, "service_account_id": "service_account_id", "type": "service_account_workspace_member", "workspace_id": "workspace_id", "workspace_role": "workspace_admin" } ``` ### Delete Service Account Workspace Member `$ ant beta:organization:workspaces:service-accounts remove` **DELETE** `/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}` **Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](https://platform.claude.com/docs/en/manage-claude/wif-admin-api?sdk_languages=cli). Remove a service account from a workspace. Removal is idempotent (returns 200 even if the membership was already removed). A DELETE against the implicit default-workspace membership returns 200 but is a no-op and the membership persists; deleting an explicit default-workspace row reverts to the implicit `workspace_user` membership. Archived workspaces return 400. #### Parameters - `--workspace-id: string` (path parameter) ID of the workspace. - `--service-account-id: string` (path parameter) ID of the service account. - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `BetaOrganizationWorkspaceServiceAccountRemoveResponse: object` - `type: "service_account_workspace_member_deleted"` - `service_account_id: string` Tagged service account ID (`svac_...`) named in the delete request. Removal is idempotent; see the endpoint description for the implicit-membership no-op. - `workspace_id: string` Tagged workspace ID (`wrkspc_...`) named in the delete request. #### Example ```bash ant beta:organization:workspaces:service-accounts remove \ --api-key my-anthropic-api-key \ --workspace-id workspace_id \ --service-account-id service_account_id ``` ##### Response (200) ```json { "service_account_id": "service_account_id", "type": "service_account_workspace_member_deleted", "workspace_id": "workspace_id" } ``` ## Beta › Organization › Rate Limits ### List Organization Rate Limits `$ ant beta:organization:rate-limits list` **GET** `/v1/organizations/rate_limits` List Messages API rate limits for your organization. Each entry corresponds to one rate-limit group (either a model family or an API-surface category such as the Message Batches API or the web search tool) and contains the set of limiter values that apply to it. When `limit` is omitted, every matching entry is returned in a single page; when `limit` truncates the result, follow `next_page` to fetch the remaining entries. #### Parameters - `--group-type: optional "batch" or "files" or "model_group" or 3 more` (query parameter) Filter by group type. - `--limit: optional number` (query parameter) Maximum number of items to return per page. Ranges from `1` to `1000`. When omitted, every remaining entry is returned in a single page and `next_page` is `null`. minimum: 1, maximum: 1000 - `--model: optional string` (query parameter) Filter to the single entry containing this model. Accepts full model names and aliases. Returns 404 if the model is not found or has no rate limits for this organization. - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. #### Returns - `BetaRateLimitListResponse: object` - `data: array of BetaOrganizationRateLimit` Rate-limit entries for the organization, one per group. - `type: "rate_limit"` Object type. Always `rate_limit` for organization rate-limit entries. - `id: string` Identifier of this rate-limit entry. It is stable within the organization and differs between organizations; the group's own identifier is `group.id`. - `group: BetaOrganizationRateLimitModelGroup or BetaOrganizationRateLimitBatchGroup or BetaOrganizationRateLimitTokenCountGroup or 3 more` The rate-limit group this entry's limits apply to. Its `type` equals `group_type`. - `beta_organization_rate_limit_model_group: object` - `type: "model_group"` Always `model_group`: a family of models. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `display_name: string` Human-readable name of the model group (for example, `Claude Sonnet 4.x`). For display only; it may change. - `beta_organization_rate_limit_batch_group: object` - `type: "batch"` Always `batch`: the Message Batches API. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `beta_organization_rate_limit_token_count_group: object` - `type: "token_count"` Always `token_count`: the Token Count API. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `beta_organization_rate_limit_files_group: object` - `type: "files"` Always `files`: the Files API. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `beta_organization_rate_limit_skills_group: object` - `type: "skills"` Always `skills`: the Skills API. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `beta_organization_rate_limit_web_search_group: object` - `type: "web_search"` Always `web_search`: the Messages API web search tool. - `id: string` Opaque identifier of the rate-limit group (for example, `rlg_01VPTCmyiu5ZLsWkcxYG2pY8`). It is the same in every organization and never changes, unlike the entry's own identifier, which differs per organization. - `limits: array of BetaOrganizationRateLimitValue` The limiter values that apply to this group. - `type: string` The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`). - `value: number` The configured limit value for this limiter type. - `models: array of string` Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`. - `group_type: "batch" or "files" or "model_group" or 3 more` **Deprecated**: Use `group.type` instead. `group_type` is still returned and always equals `group.type`. Deprecated: use `group.type` instead. The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`. Always equal to `group.type`. - `"batch"` - `"files"` - `"model_group"` - `"skills"` - `"token_count"` - `"web_search"` - `next_page: string` Opaque cursor for the next page of results, or `null` when no entries remain beyond this response. #### Example ```bash ant beta:organization:rate-limits list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "id", "group": { "id": "id", "display_name": "display_name", "type": "model_group" }, "group_type": "batch", "limits": [ { "type": "type", "value": 0 } ], "models": [ "string" ], "type": "rate_limit" } ], "next_page": "next_page" } ``` ## Beta › Organization › Compliance Settings ### Get Compliance Settings `$ ant beta:organization:compliance-settings retrieve` **GET** `/v1/organizations/compliance_settings` Retrieve your organization's Compliance Settings. Compliance Settings is a singleton resource: there is exactly one per organization, addressed without an identifier. The `state` field reflects whether the Compliance API is enabled. An organization with a parent organization reads the state inherited from the parent's configuration. #### Returns - `beta_compliance_settings: object` - `type: "compliance_settings"` - `state: BetaComplianceSettingsStateEnabled or BetaComplianceSettingsStateDisabled` Whether the Compliance API is enabled for this organization. - `beta_compliance_settings_state_enabled: object` - `type: "enabled"` - `beta_compliance_settings_state_disabled: object` - `type: "disabled"` #### Example ```bash ant beta:organization:compliance-settings retrieve \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "state": { "type": "enabled" }, "type": "compliance_settings" } ``` ### Update Compliance Settings `$ ant beta:organization:compliance-settings update` **POST** `/v1/organizations/compliance_settings` Update your organization's Compliance Settings. Setting `state` to `enabled` turns on the Compliance API and begins capturing organization activity events. Setting it to `disabled` turns both off. `state` reflects whether the Compliance API is enabled. A request that sets `state` to its current value succeeds and leaves the resource unchanged. A `disabled` request stays in effect until a later `enabled` request or the organization's next provisioning action that enables Access Transparency: enabling Access Transparency also enables the Compliance API, which serves its activity events, so such provisioning (including re-runs) re-enables the Compliance API even after a `disabled` request. Automated provisioning never disables compliance settings. #### Parameters - `--state: BetaComplianceSettingsStateEnabledParam or BetaComplianceSettingsStateDisabledParam` Desired state. Accepts the string shorthand "enabled" or "disabled" in place of the object form; the response always returns the canonical object form. #### Returns - `beta_compliance_settings: object` - `type: "compliance_settings"` - `state: BetaComplianceSettingsStateEnabled or BetaComplianceSettingsStateDisabled` Whether the Compliance API is enabled for this organization. - `beta_compliance_settings_state_enabled: object` - `type: "enabled"` - `beta_compliance_settings_state_disabled: object` - `type: "disabled"` #### Example ```bash ant beta:organization:compliance-settings update \ --api-key my-anthropic-api-key \ --state '{type: enabled}' ``` ##### Response (200) ```json { "state": { "type": "enabled" }, "type": "compliance_settings" } ``` ## Beta › Organization › Analytics › Summaries ### Get Activity Summaries `$ ant beta:organization:analytics:summaries list` **GET** `/v1/organizations/analytics/summaries` Get organization-wide activity summaries for a date range. Returns one entry per day from `starting_date` (inclusive) to `ending_date` (exclusive) in `data`, the same `data` / `next_page` envelope as the other analytics list endpoints; the series is currently returned in full, so `next_page` is always null. Data is typically available with a 1-day lag and may be revised by a few percent over the following days: when `ending_date` is omitted it defaults to the most recent available day + 1, so the last entry covers the most recent available day. The series can be scoped to an RBAC group via `filter[]=rbac_group_id:{id}`. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. #### Parameters - `--starting-date: string` (query parameter) UTC date in YYYY-MM-DD format. Start of the date range (inclusive). Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date - `--ending-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. End of the date range (exclusive). Data is typically available with a 1-day lag, so this can be at most today — which is also the default when omitted, making the last entry cover the most recent available day. Data may be revised by a few percent over the following days. The range may span at most 366 days. format: date - `--filter: optional array of string` (query parameter) Filters as `dimension:value`. Only `rbac_group_id` is supported (e.g. `filter[]=rbac_group_id:{id}`); repeat the param to OR across groups. Scopes the whole day series to members of the matching group(s), re-aggregated from member-level activity — org-wide seat/invite fields and the adoption rates derived from them are null on scoped rows. `rbac_group_id` accepts the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each UTC day (time-of-usage attribution). At most 100 entries. maxItems: 100 - `--limit: optional number` (query parameter) Number of results per page (1-1000, default 100). The day series (at most 366 entries) is currently returned in full in a single page, so `limit` does not yet shorten it. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. `next_page` is currently always null, so there is never a cursor to send. #### Returns - `BetaAnalyticsActivitySummaryResponse: object` Response for GET /v1/organizations/analytics/summaries. - `data: array of BetaAnalyticsSingleDayActivitySummary` One entry per day in the requested range, ascending by date. - `assigned_seat_count: number` Number of seats currently assigned to members. Null when the response is scoped to an RBAC group — seat assignment is org-wide and has no per-group analogue. - `cowork_daily_active_user_count: number` Number of users with Cowork activity on the requested day - `cowork_monthly_active_user_count: number` Number of users with Cowork activity in the 30-day rolling window - `cowork_weekly_active_user_count: number` Number of users with Cowork activity in the 7-day rolling window - `daily_active_user_count: number` Number of users with token consumption on the requested day - `daily_adoption_rate: number` Percentage of assigned seats with activity on the requested day (`DAU / assigned_seat_count * 100`). Null when the response is scoped to an RBAC group. - `ending_at: string` End of the aggregation period (exclusive), UTC midnight in RFC 3339 format (e.g. `2026-01-16T00:00:00Z`). format: date-time - `monthly_active_user_count: number` Number of users with token consumption in the 30-day rolling window - `monthly_adoption_rate: number` Percentage of assigned seats with activity in the 30-day rolling window (`MAU / assigned_seat_count * 100`). Null when the response is scoped to an RBAC group. - `pending_invite_count: number` Number of pending invitations to join the organization. Null when the response is scoped to an RBAC group. - `starting_at: string` Start of the aggregation period (inclusive), UTC midnight in RFC 3339 format (e.g. `2026-01-15T00:00:00Z`). format: date-time - `weekly_active_user_count: number` Number of users with token consumption in the 7-day rolling window - `weekly_adoption_rate: number` Percentage of assigned seats with activity in the 7-day rolling window (`WAU / assigned_seat_count * 100`). Null when the response is scoped to an RBAC group. - `chat_cowork_unified_daily_active_user_count: optional number` Number of users with activity in Chat and Cowork unified on the requested day. Omitted from the response on deployments that do not offer Chat and Cowork unified. - `chat_cowork_unified_monthly_active_user_count: optional number` Number of users with activity in Chat and Cowork unified in the 28-day rolling window (30 days when the request filters by `rbac_group_id`). Omitted from the response on deployments that do not offer Chat and Cowork unified. - `chat_cowork_unified_weekly_active_user_count: optional number` Number of users with activity in Chat and Cowork unified in the 7-day rolling window. Omitted from the response on deployments that do not offer Chat and Cowork unified. - `chat_daily_active_user_count: optional number` Number of users with claude.ai (chat) activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization. - `chat_monthly_active_user_count: optional number` Number of users with claude.ai (chat) activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization. - `chat_weekly_active_user_count: optional number` Number of users with claude.ai (chat) activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization. - `claude_code_daily_active_user_count: optional number` Number of users with Claude Code activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization. - `claude_code_monthly_active_user_count: optional number` Number of users with Claude Code activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization. - `claude_code_weekly_active_user_count: optional number` Number of users with Claude Code activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization. - `claude_design_daily_active_user_count: optional number` Number of users with Claude Design activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization. - `claude_design_monthly_active_user_count: optional number` Number of users with Claude Design activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization. - `claude_design_weekly_active_user_count: optional number` Number of users with Claude Design activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization. - `office_agent_daily_active_user_count: optional number` Number of users with Claude in Office activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization. - `office_agent_monthly_active_user_count: optional number` Number of users with Claude in Office activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization. - `office_agent_weekly_active_user_count: optional number` Number of users with Claude in Office activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization. - `science_daily_active_user_count: optional number` Number of users with Claude Science activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization. - `science_entitled_user_count: optional number` Number of users with a Claude Science seat entitlement (per-seat RBAC) at the time of the daily snapshot. The funnel top; independent of the org-level Claude Science toggle. Null when the response is scoped to an RBAC group — entitlement is org-wide and has no per-group analogue. Omitted from the response while the per-product breakdown is not enabled for this organization. - `science_monthly_active_user_count: optional number` Number of users with Claude Science activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization. - `science_weekly_active_user_count: optional number` Number of users with Claude Science activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization. - `next_page: string` Opaque cursor for the next page, or null if no more results. Currently always null: the day series is returned in full. #### Example ```bash ant beta:organization:analytics:summaries list \ --api-key my-anthropic-api-key \ --starting-date ''\''2019-12-27'\''' ``` ##### Response (200) ```json { "data": [ { "assigned_seat_count": 0, "cowork_daily_active_user_count": 0, "cowork_monthly_active_user_count": 0, "cowork_weekly_active_user_count": 0, "daily_active_user_count": 0, "daily_adoption_rate": 0, "ending_at": "2019-12-27T18:11:19.117Z", "monthly_active_user_count": 0, "monthly_adoption_rate": 0, "pending_invite_count": 0, "starting_at": "2019-12-27T18:11:19.117Z", "weekly_active_user_count": 0, "weekly_adoption_rate": 0, "chat_cowork_unified_daily_active_user_count": 0, "chat_cowork_unified_monthly_active_user_count": 0, "chat_cowork_unified_weekly_active_user_count": 0, "chat_daily_active_user_count": 0, "chat_monthly_active_user_count": 0, "chat_weekly_active_user_count": 0, "claude_code_daily_active_user_count": 0, "claude_code_monthly_active_user_count": 0, "claude_code_weekly_active_user_count": 0, "claude_design_daily_active_user_count": 0, "claude_design_monthly_active_user_count": 0, "claude_design_weekly_active_user_count": 0, "office_agent_daily_active_user_count": 0, "office_agent_monthly_active_user_count": 0, "office_agent_weekly_active_user_count": 0, "science_daily_active_user_count": 0, "science_entitled_user_count": 0, "science_monthly_active_user_count": 0, "science_weekly_active_user_count": 0 } ], "next_page": "next_page", "summaries": [ { "assigned_seat_count": 0, "cowork_daily_active_user_count": 0, "cowork_monthly_active_user_count": 0, "cowork_weekly_active_user_count": 0, "daily_active_user_count": 0, "daily_adoption_rate": 0, "ending_at": "2019-12-27T18:11:19.117Z", "monthly_active_user_count": 0, "monthly_adoption_rate": 0, "pending_invite_count": 0, "starting_at": "2019-12-27T18:11:19.117Z", "weekly_active_user_count": 0, "weekly_adoption_rate": 0, "chat_cowork_unified_daily_active_user_count": 0, "chat_cowork_unified_monthly_active_user_count": 0, "chat_cowork_unified_weekly_active_user_count": 0, "chat_daily_active_user_count": 0, "chat_monthly_active_user_count": 0, "chat_weekly_active_user_count": 0, "claude_code_daily_active_user_count": 0, "claude_code_monthly_active_user_count": 0, "claude_code_weekly_active_user_count": 0, "claude_design_daily_active_user_count": 0, "claude_design_monthly_active_user_count": 0, "claude_design_weekly_active_user_count": 0, "office_agent_daily_active_user_count": 0, "office_agent_monthly_active_user_count": 0, "office_agent_weekly_active_user_count": 0, "science_daily_active_user_count": 0, "science_entitled_user_count": 0, "science_monthly_active_user_count": 0, "science_weekly_active_user_count": 0 } ] } ``` ## Beta › Organization › Analytics › Users ### List User Activity `$ ant beta:organization:analytics:users list` **GET** `/v1/organizations/analytics/users` Get per-user activity for a given day, with cursor-based pagination. Returns activity metrics for each user in the organization, sorted by email address. Use `group_by[]` for per-RBAC-group aggregates, or `filter[]` to scope results to specific members, groups, or a chat project. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. #### Parameters - `--date: optional string` (query parameter) UTC date in YYYY-MM-DD format. The day to get user activity for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date - `--ending-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`. format: date - `--filter: optional array of string` (query parameter) Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `project_id`, `rbac_group_id`, `user_id`. Value forms: `project_id` takes a tagged project id (`claude_proj_...`); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries. A `project_id` filter limits each member's row to their claude.ai chat activity in that project and cannot be combined with `group_by[]` or an `rbac_group_id` filter. On these rows, every count in `chat_cowork_unified_metrics.sessions` is 0, because sessions are not measured per project. On any day a member sent a chat message in Chat and Cowork unified, all of that member's project activity for the day is counted in `chat_cowork_unified_metrics.chat` instead of `chat_metrics`. maxItems: 100 - `--group-by: optional array of "rbac_group_id"` (query parameter) Dimensions to break results out by (e.g. `group_by[]=rbac_group_id`). Supported on this endpoint: `rbac_group_id`. Rows are already per-member, so the one supported grouping aggregates them per RBAC group instead. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries. maxItems: 100 - `--limit: optional number` (query parameter) Number of results per page (1-1000, default 100). minimum: 1, maximum: 1000 - `--order: optional "asc" or "desc"` (query parameter) Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted. - `--order-by: optional string` (query parameter) Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set). - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--starting-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date #### Returns - `BetaAnalyticsUsersResponse: object` Response for GET /v1/organizations/analytics/users. - `data: array of BetaAnalyticsUserActivity` - `chat_metrics: object` Claude.ai activity metrics for a single user on a given day. - `connectors_used_count: number` Number of MCP connector invocations. - `distinct_artifacts_created_count: number` Number of distinct artifacts created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it. - `distinct_connectors_used_count: number` Distinct claude.ai connectors this user used. Excludes calls whose connector could not be identified and all calls from organizations with zero data retention. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_conversation_count: number` Number of distinct conversations the user participated in. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_files_uploaded_count: number` Number of distinct files uploaded. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_projects_created_count: number` Number of distinct projects created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it. - `distinct_projects_used_count: number` Number of distinct projects used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_shared_artifacts_viewed_count: number` Number of distinct shared artifacts the user viewed. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_skills_used_count: number` Number of distinct skills used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `message_count: number` Number of messages sent - `shared_conversations_viewed_count: number` Number of times the user opened a shared conversation in a project - `thinking_message_count: number` Number of messages that used extended thinking - `claude_code_metrics: object` Claude Code activity metrics for a single user on a given day. - `core_metrics: object` Core Claude Code activity metrics for a single user on a given day. - `artifacts_created_count: number` Number of artifacts created in Claude Code sessions: an artifact counts once, on the day a session first saves it. Counted from 2026-08-17; 0 on earlier days. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it. - `commit_count: number` Number of commits made via Claude Code - `distinct_session_count: number` Number of distinct Claude Code sessions. On aggregated rows and in date-range mode: summed per-day distinct counts. A session essentially never spans a UTC day, so the sum is in practice the true distinct count. - `lines_of_code: object` Lines of code added and removed via Claude Code. - `added_count: number` Lines of code added - `removed_count: number` Lines of code removed - `pull_request_count: number` Number of pull requests created via Claude Code - `tool_actions: object` Per-tool accepted/rejected counts for Claude Code file modification tools. - `edit_tool: object` Accepted/rejected counts for a single Claude Code tool type. - `accepted_count: number` Number of tool proposals accepted - `rejected_count: number` Number of tool proposals rejected - `multi_edit_tool: object` Accepted/rejected counts for a single Claude Code tool type. - `accepted_count: number` Number of tool proposals accepted - `rejected_count: number` Number of tool proposals rejected - `notebook_edit_tool: object` Accepted/rejected counts for a single Claude Code tool type. - `accepted_count: number` Number of tool proposals accepted - `rejected_count: number` Number of tool proposals rejected - `write_tool: object` Accepted/rejected counts for a single Claude Code tool type. - `accepted_count: number` Number of tool proposals accepted - `rejected_count: number` Number of tool proposals rejected - `cowork_metrics: object` Cowork activity metrics for a single user on a given day. - `action_count: number` Number of tool actions completed in Cowork sessions - `artifacts_created_count: number` Number of artifacts created in Cowork sessions: an artifact counts once, on the day a session first saves it. Counted from 2026-08-17; 0 on earlier days. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it. - `connectors_used_count: number` Total number of connector invocations in Cowork sessions - `dispatch_turn_count: number` Number of Dispatch (background agent) turns completed - `distinct_connectors_used_count: number` Number of distinct connectors used in Cowork sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_session_count: number` Number of distinct Cowork sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_skills_used_count: number` Number of distinct skills used in Cowork sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `message_count: number` Number of messages sent in Cowork sessions - `skills_used_count: number` Total number of skill invocations in Cowork sessions - `distinct_plugins_used_count: optional number` Number of distinct plugins used in Cowork sessions. Null while Cowork plugin-use metrics are not enabled for this organization. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `edit_tool_count: optional number` Number of successful Edit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization. - `file_edit_count: optional number` Number of successful file-edit tool calls (Edit, MultiEdit, Write, NotebookEdit) in Cowork sessions. Null, never 0, while the file-edit metrics are not enabled for this organization. - `multi_edit_tool_count: optional number` Number of successful MultiEdit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization. - `notebook_edit_tool_count: optional number` Number of successful NotebookEdit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization. - `plugins_used_count: optional number` Total number of plugin invocations in Cowork sessions. Null while Cowork plugin-use metrics are not enabled for this organization. - `sessions_with_file_edits_count: optional number` Number of distinct Cowork sessions with at least one successful file-edit tool call. Null while the file-edit metrics are not enabled for this organization. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `write_tool_count: optional number` Number of successful Write tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization. - `design_metrics: object` Claude Design activity metrics for a single user on a given day. - `distinct_projects_created_count: number` Number of distinct Claude Design projects created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it. - `distinct_projects_used_count: number` Number of distinct Claude Design projects the user worked in. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_session_count: number` Number of distinct Claude Design sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `message_count: number` Number of messages sent in Claude Design sessions - `office_metrics: object` Office Agent activity metrics for a single user on a given day, broken out by Office product. - `excel: object` Office Agent activity metrics for a single user on a given day within one Office product. - `connectors_used_count: number` Number of MCP connector invocations - `distinct_connectors_used_count: number` Number of distinct MCP connectors used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_session_count: number` Number of distinct Office Agent sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_skills_used_count: number` Number of distinct skills used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `message_count: number` Number of messages sent - `skills_used_count: number` Number of skill invocations - `outlook: object` Office Agent activity metrics for a single user on a given day within one Office product. - `connectors_used_count: number` Number of MCP connector invocations - `distinct_connectors_used_count: number` Number of distinct MCP connectors used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_session_count: number` Number of distinct Office Agent sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_skills_used_count: number` Number of distinct skills used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `message_count: number` Number of messages sent - `skills_used_count: number` Number of skill invocations - `powerpoint: object` Office Agent activity metrics for a single user on a given day within one Office product. - `connectors_used_count: number` Number of MCP connector invocations - `distinct_connectors_used_count: number` Number of distinct MCP connectors used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_session_count: number` Number of distinct Office Agent sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_skills_used_count: number` Number of distinct skills used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `message_count: number` Number of messages sent - `skills_used_count: number` Number of skill invocations - `word: object` Office Agent activity metrics for a single user on a given day within one Office product. - `connectors_used_count: number` Number of MCP connector invocations - `distinct_connectors_used_count: number` Number of distinct MCP connectors used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_session_count: number` Number of distinct Office Agent sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_skills_used_count: number` Number of distinct skills used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `message_count: number` Number of messages sent - `skills_used_count: number` Number of skill invocations - `science_metrics: object` Claude Science activity metrics for a single user on a given day. - `delegation_count: number` Number of delegations (handoffs to a specialized agent) in Claude Science sessions - `distinct_session_count: number` Number of distinct Claude Science sessions. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `message_count: number` Number of messages sent in Claude Science sessions - `remote_compute_job_count: number` Number of remote compute jobs launched from Claude Science sessions - `skills_used_count: number` Total number of skill invocations in Claude Science sessions - `web_search_count: number` Number of web searches performed - `chat_cowork_unified_metrics: optional object` Activity recorded while the member had Chat and Cowork unified (Cowork's features inside claude.ai chat) turned on, split into `chat` (chat activity) and `sessions` (Cowork activity). Omitted from the response on deployments that do not offer Chat and Cowork unified. - `chat: object` Chat activity recorded while members had Chat and Cowork unified turned on. - `connectors_used_count: number` Same measure as `chat_metrics.connectors_used_count`, for activity recorded while members had Chat and Cowork unified turned on. - `distinct_artifacts_created_count: number` Same measure as `chat_metrics.distinct_artifacts_created_count`, for activity recorded while members had Chat and Cowork unified turned on. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it. - `distinct_connectors_used_count: number` Same measure as `chat_metrics.distinct_connectors_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_conversation_count: number` Same measure as `chat_metrics.distinct_conversation_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_files_uploaded_count: number` Same measure as `chat_metrics.distinct_files_uploaded_count`, for activity recorded while members had Chat and Cowork unified turned on. It counts uploaded files as well as files Claude created and images returned by Claude's tools, such as screenshots. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_projects_created_count: number` Same measure as `chat_metrics.distinct_projects_created_count`, for activity recorded while members had Chat and Cowork unified turned on. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it. - `distinct_projects_used_count: number` Same measure as `chat_metrics.distinct_projects_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_shared_artifacts_viewed_count: number` Always null: shared-artifact views are not currently measured. - `distinct_skills_used_count: number` Same measure as `chat_metrics.distinct_skills_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `message_count: number` Same measure as `chat_metrics.message_count`, for activity recorded while members had Chat and Cowork unified turned on. - `shared_conversations_viewed_count: number` Same measure as `chat_metrics.shared_conversations_viewed_count`, for activity recorded while members had Chat and Cowork unified turned on. - `thinking_message_count: number` Same measure as `chat_metrics.thinking_message_count`, for activity recorded while members had Chat and Cowork unified turned on. - `sessions: object` Cowork session activity recorded while members had Chat and Cowork unified turned on. - `action_count: number` Same measure as `cowork_metrics.action_count`, for activity recorded while members had Chat and Cowork unified turned on. - `artifacts_created_count: number` Same measure as `cowork_metrics.artifacts_created_count`, for activity recorded while members had Chat and Cowork unified turned on. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it. - `connectors_used_count: number` Same measure as `cowork_metrics.connectors_used_count`, for activity recorded while members had Chat and Cowork unified turned on. - `dispatch_turn_count: number` Same measure as `cowork_metrics.dispatch_turn_count`, for activity recorded while members had Chat and Cowork unified turned on. - `distinct_connectors_used_count: number` Same measure as `cowork_metrics.distinct_connectors_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_plugins_used_count: number` Same measure as `cowork_metrics.distinct_plugins_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_session_count: number` Same measure as `cowork_metrics.distinct_session_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_skills_used_count: number` Same measure as `cowork_metrics.distinct_skills_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `edit_tool_count: number` Same measure as `cowork_metrics.edit_tool_count`, for activity recorded while members had Chat and Cowork unified turned on. - `file_edit_count: number` Same measure as `cowork_metrics.file_edit_count`, for activity recorded while members had Chat and Cowork unified turned on. - `message_count: number` Same measure as `cowork_metrics.message_count`, for activity recorded while members had Chat and Cowork unified turned on. - `multi_edit_tool_count: number` Same measure as `cowork_metrics.multi_edit_tool_count`, for activity recorded while members had Chat and Cowork unified turned on. Claude no longer has a multi-edit tool, so expect 0 when not null; each edit is now a separate Edit tool call, counted in `edit_tool_count` and `file_edit_count`. - `notebook_edit_tool_count: number` Same measure as `cowork_metrics.notebook_edit_tool_count`, for activity recorded while members had Chat and Cowork unified turned on. - `plugins_used_count: number` Same measure as `cowork_metrics.plugins_used_count`, for activity recorded while members had Chat and Cowork unified turned on. - `sessions_with_file_edits_count: number` Same measure as `cowork_metrics.sessions_with_file_edits_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `skills_used_count: number` Same measure as `cowork_metrics.skills_used_count`, for activity recorded while members had Chat and Cowork unified turned on. - `write_tool_count: number` Same measure as `cowork_metrics.write_tool_count`, for activity recorded while members had Chat and Cowork unified turned on. - `distinct_user_count: optional number` Number of distinct active users represented by this row. Only set for grouped rollups (`group_by[]`); null for per-user rows. In date-range mode, recomputed as an exact distinct count of the group's active members over the requested window, never a sum of per-day values. - `last_activity_date: optional string` Most recent UTC day (YYYY-MM-DD) on which the user had any counted activity, within the requested window: equal to the requested `date` in single-day mode, and to the latest active day from `starting_date` (inclusive) to `ending_date` (exclusive) in date-range rollup mode — never a day earlier than the window start. On filtered requests (`filter[]`) only days matching the filter count: with `filter[]=rbac_group_id:{id}` it is the last day the user was active while a member of that group, consistent with the row's other metrics. On grouped (`group_by[]`) rows it is the latest day any member of the group was active (the requested `date` in single-day mode). Omitted from the response while last-activity reporting is not enabled for this organization. format: date - `rbac_group_id: optional string` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `rbac_group_name: optional string` Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key. - `user: optional object` The user this row describes. Null on rows aggregated across users. - `type: "user"` Object type. Always `user`. - `id: string` Tagged user identifier (e.g. `user_...`) - `email_address: string` Email address of the user - `next_page: string` Opaque cursor for the next page, or null if no more results #### Example ```bash ant beta:organization:analytics:users list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "chat_metrics": { "connectors_used_count": 0, "distinct_artifacts_created_count": 0, "distinct_connectors_used_count": 0, "distinct_conversation_count": 0, "distinct_files_uploaded_count": 0, "distinct_projects_created_count": 0, "distinct_projects_used_count": 0, "distinct_shared_artifacts_viewed_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "shared_conversations_viewed_count": 0, "thinking_message_count": 0 }, "claude_code_metrics": { "core_metrics": { "artifacts_created_count": 0, "commit_count": 0, "distinct_session_count": 0, "lines_of_code": { "added_count": 0, "removed_count": 0 }, "pull_request_count": 0 }, "tool_actions": { "edit_tool": { "accepted_count": 0, "rejected_count": 0 }, "multi_edit_tool": { "accepted_count": 0, "rejected_count": 0 }, "notebook_edit_tool": { "accepted_count": 0, "rejected_count": 0 }, "write_tool": { "accepted_count": 0, "rejected_count": 0 } } }, "cowork_metrics": { "action_count": 0, "artifacts_created_count": 0, "connectors_used_count": 0, "dispatch_turn_count": 0, "distinct_connectors_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "skills_used_count": 0, "distinct_plugins_used_count": 0, "edit_tool_count": 0, "file_edit_count": 0, "multi_edit_tool_count": 0, "notebook_edit_tool_count": 0, "plugins_used_count": 0, "sessions_with_file_edits_count": 0, "write_tool_count": 0 }, "design_metrics": { "distinct_projects_created_count": 0, "distinct_projects_used_count": 0, "distinct_session_count": 0, "message_count": 0 }, "office_metrics": { "excel": { "connectors_used_count": 0, "distinct_connectors_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "skills_used_count": 0 }, "outlook": { "connectors_used_count": 0, "distinct_connectors_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "skills_used_count": 0 }, "powerpoint": { "connectors_used_count": 0, "distinct_connectors_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "skills_used_count": 0 }, "word": { "connectors_used_count": 0, "distinct_connectors_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "skills_used_count": 0 } }, "science_metrics": { "delegation_count": 0, "distinct_session_count": 0, "message_count": 0, "remote_compute_job_count": 0, "skills_used_count": 0 }, "web_search_count": 0, "chat_cowork_unified_metrics": { "chat": { "connectors_used_count": 0, "distinct_artifacts_created_count": 0, "distinct_connectors_used_count": 0, "distinct_conversation_count": 0, "distinct_files_uploaded_count": 0, "distinct_projects_created_count": 0, "distinct_projects_used_count": 0, "distinct_shared_artifacts_viewed_count": 0, "distinct_skills_used_count": 0, "message_count": 0, "shared_conversations_viewed_count": 0, "thinking_message_count": 0 }, "sessions": { "action_count": 0, "artifacts_created_count": 0, "connectors_used_count": 0, "dispatch_turn_count": 0, "distinct_connectors_used_count": 0, "distinct_plugins_used_count": 0, "distinct_session_count": 0, "distinct_skills_used_count": 0, "edit_tool_count": 0, "file_edit_count": 0, "message_count": 0, "multi_edit_tool_count": 0, "notebook_edit_tool_count": 0, "plugins_used_count": 0, "sessions_with_file_edits_count": 0, "skills_used_count": 0, "write_tool_count": 0 } }, "distinct_user_count": 0, "last_activity_date": "2019-12-27", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "user": { "id": "id", "email_address": "email_address", "type": "user" } } ], "next_page": "next_page" } ``` ## Beta › Organization › Analytics › Apps › Chat › Projects ### Get Chat Project Usage `$ ant beta:organization:analytics:apps:chat:projects list` **GET** `/v1/organizations/analytics/apps/chat/projects` Get per-project activity for a given day, with cursor-based pagination. Returns activity metrics for each project in the organization, sorted by project ID. Use `group_by[]` to break projects out per member or per RBAC group, and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. #### Parameters - `--date: optional string` (query parameter) UTC date in YYYY-MM-DD format. The day to get project activity for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date - `--ending-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`. format: date - `--filter: optional array of string` (query parameter) Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `project_id`, `rbac_group_id`, `user_id`. Value forms: `project_id` takes a tagged project id (`claude_proj_...`); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries. maxItems: 100 - `--group-by: optional array of "rbac_group_id" or "user_id"` (query parameter) Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `rbac_group_id`, `user_id`. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries. maxItems: 100 - `--limit: optional number` (query parameter) Number of results per page (1-1000, default 100). minimum: 1, maximum: 1000 - `--order: optional "asc" or "desc"` (query parameter) Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted. - `--order-by: optional string` (query parameter) Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set). - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--starting-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date #### Returns - `BetaAnalyticsProjectsResponse: object` Response for GET /v1/organizations/analytics/apps/chat/projects. - `data: array of BetaAnalyticsProjectActivity` - `distinct_user_count: number` Number of distinct users who used the project on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values. - `message_count: number` Number of messages sent in the project on the requested day - `project_id: string` Tagged project identifier (e.g. `claude_proj_...`) - `project_name: string` Name of the project - `created_at: optional string` Project creation timestamp in RFC 3339 format. Null if the project was deleted before attribution was recorded. format: date-time - `created_by: optional object` User who created the project. Null if the project was deleted before attribution was recorded, or if the creator's account no longer exists. - `type: "user"` Object type. Always `user`. - `id: string` Tagged user identifier (e.g. `user_...`) - `email_address: string` Email address of the user - `distinct_conversation_count: optional number` Number of distinct conversations in the project. Null on aggregated rows where a distinct count cannot be computed. - `product: optional string` Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, `office_agent`, or `chat_cowork_unified` (Chat and Cowork unified). These are the canonical Cost & Usage product names; an `office_agent` row's per-surface breakdown is in its `office_metrics`. On `/plugins` only `cowork`, `claude_code` and `chat_cowork_unified` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, `cowork` and `chat_cowork_unified` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`. - `rbac_group_id: optional string` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `rbac_group_name: optional string` Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key. - `user_id: optional string` Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`. - `next_page: string` Opaque cursor for the next page, or null if no more results #### Example ```bash ant beta:organization:analytics:apps:chat:projects list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "distinct_user_count": 0, "message_count": 0, "project_id": "project_id", "project_name": "project_name", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "email_address": "email_address", "type": "user" }, "distinct_conversation_count": 0, "product": "product", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "user_id": "user_id" } ], "next_page": "next_page" } ``` ## Beta › Organization › Analytics › Connectors ### Get Connector Usage `$ ant beta:organization:analytics:connectors list` **GET** `/v1/organizations/analytics/connectors` Get per-connector usage for a given day, with cursor-based pagination. Returns connector usage metrics for the organization, sorted by connector name. Connector names are normalized from their various sources — for example, "Atlassian MCP server" and "mcp-atlassian" both appear as "atlassian". Use `group_by[]` to break usage out per member, per RBAC group, or per product surface, and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. #### Parameters - `--date: optional string` (query parameter) UTC date in YYYY-MM-DD format. The day to get connector usage for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date - `--ending-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`. format: date - `--filter: optional array of string` (query parameter) Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `connector_name`, `product`, `rbac_group_id`, `user_id`. Value forms: `connector_name` matches case-insensitively, a display name such as 'GitHub MCP' also matches its normalized stored form ('github'), and for rows whose `connector_name` is an opaque connector id the connector's display name (`connector_display_name`) also matches; `product` is one of `chat_cowork_unified`, `chat`, `claude_code`, `cowork`, or `office_agent`; `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries. `chat_cowork_unified` is accepted as a `product` value only on deployments that offer Chat and Cowork unified. maxItems: 100 - `--group-by: optional array of "product" or "rbac_group_id" or "user_id"` (query parameter) Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries. maxItems: 100 - `--limit: optional number` (query parameter) Number of results per page (1-1000, default 100). minimum: 1, maximum: 1000 - `--order: optional "asc" or "desc"` (query parameter) Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted. - `--order-by: optional string` (query parameter) Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set). - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--starting-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date #### Returns - `BetaAnalyticsConnectorsResponse: object` Response for GET /v1/organizations/analytics/connectors. - `data: array of BetaAnalyticsConnectorActivity` - `chat_metrics: object` Claude.ai activity metrics for a single connector on a given day. - `distinct_conversation_connector_used_count: number` Number of distinct conversations in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `claude_code_metrics: object` Claude Code activity metrics for a single connector on a given day. - `distinct_session_connector_used_count: number` Number of distinct Claude Code sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `connector_name: string` Name of the connector. Some rows carry an opaque connector id here instead of a readable name; `connector_display_name` holds the resolved name for those rows. - `cowork_metrics: object` Cowork activity metrics for a single connector on a given day. - `distinct_session_connector_used_count: number` Number of distinct Cowork sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_user_count: number` Number of distinct users who used the connector on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values. - `office_metrics: object` Office Agent activity metrics for a single connector on a given day, broken out by Office product. - `excel: object` Office Agent activity metrics for a single connector on a given day within one Office product. - `distinct_session_connector_used_count: number` Number of distinct Office Agent sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `outlook: object` Office Agent activity metrics for a single connector on a given day within one Office product. - `distinct_session_connector_used_count: number` Number of distinct Office Agent sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `powerpoint: object` Office Agent activity metrics for a single connector on a given day within one Office product. - `distinct_session_connector_used_count: number` Number of distinct Office Agent sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `word: object` Office Agent activity metrics for a single connector on a given day within one Office product. - `distinct_session_connector_used_count: number` Number of distinct Office Agent sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `chat_cowork_unified_metrics: optional object` Connector use recorded while members had Chat and Cowork unified (Cowork's features inside claude.ai chat) turned on, split into chat conversations and Cowork sessions. A count is null in date-range mode where it cannot be computed. Omitted from the response on deployments that do not offer Chat and Cowork unified. - `chat: object` A connector's use in chat conversations recorded while members had Chat and Cowork unified turned on. - `distinct_conversation_connector_used_count: number` Same measure as `chat_metrics.distinct_conversation_connector_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `sessions: object` A connector's use in Cowork sessions recorded while members had Chat and Cowork unified turned on. - `distinct_session_connector_used_count: number` Same measure as `cowork_metrics.distinct_session_connector_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `connector_display_name: optional string` Human-readable display name for rows whose `connector_name` is an opaque connector id rather than a readable name, resolved at request time from the organization's connectors (including connectors that have since been removed). `connector_name` remains the row's stable key for sorting and pagination, and `filter[]=connector_name:{value}` also matches these rows by display name. Display names are not unique, and the same connector's claude.ai usage can appear under a separate row with a readable `connector_name`. Null when `connector_name` is already a readable name, when the id cannot be resolved to one of the organization's connectors, or when display-name resolution is not enabled for this organization. - `individual_auth_distinct_user_count: optional number` Number of distinct users whose use of this connector on the requested day ran on their own individual credential, connected through their own consent flow. Companion bucket to `managed_auth_distinct_user_count`, which carries the measurement, attribution, and null rules. Users whose requests used no stored credential count in neither bucket. - `managed_auth_distinct_user_count: optional number` Number of distinct users whose use of this connector on the requested day ran on Enterprise Managed Auth (an organization-managed credential provisioned through the organization's identity provider), read from the token record each request used. Null, never 0, when managed-auth reporting is not enabled for the organization, the value cannot be attributed to the row, no credentialed requests and no managed-token mint events (a managed credential being provisioned for a user's use of the connector) were observed that day, or the day predates 2026-07-01, the first day the backing data exists (forward-only data, no backfill). When credentialed requests or mint events were observed and attributed, both managed-auth fields populate, reporting 0 for a bucket with no users; the two counts are independent, not a partition — a user whose requests that day used both kinds of credential counts in both. Mint events carry user but not surface attribution, so they count as observed auth activity on `user_id` and `rbac_group_id` cuts — attributed to the user the credential was provisioned for — but never on a cut that references `product` (group or filter). Date-range rollup mode (`starting_date`/`ending_date`) computes both fields exactly over the window — distinct users with at least one qualifying day — when the whole window starts on or after 2026-07-01, with the null-versus-0 and mint-event rules applying with the window in place of the day; a range starting earlier reports every managed-auth field as null, never a partial-window value. - `product: optional string` Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, `office_agent`, or `chat_cowork_unified` (Chat and Cowork unified). These are the canonical Cost & Usage product names; an `office_agent` row's per-surface breakdown is in its `office_metrics`. On `/plugins` only `cowork`, `claude_code` and `chat_cowork_unified` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, `cowork` and `chat_cowork_unified` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`. - `rbac_group_id: optional string` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `rbac_group_name: optional string` Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key. - `read_call_count: optional number` Number of connector tool calls on the requested day whose trusted read-only annotation marked them read-only. Call count, not distinct users. Every call recorded on a classified surface lands in exactly one of `read_call_count`, `write_call_count`, or `unclassified_call_count`, so the three sum to the day's classified calls. Classification is forward-only per surface: claude.ai from 2026-06-01, Claude Code from 2026-05-30, Claude in Office from 2026-05-29, Cowork from 2026-06-02 (Cowork clients predating annotation forwarding land in `unclassified_call_count`). Null, never 0, when the value cannot be stated: the read/write split is not enabled for this organization, or the day predates 2026-05-29. For a date-range total, sum the per-day values, but treat a window that extends before 2026-05-29 as null rather than summing only its covered days — date-range rollup mode (`starting_date`/`ending_date`) applies both rules server-side. - `unclassified_call_count: optional number` Number of connector tool calls on the requested day with no trusted read-only annotation — the annotation is optional in the MCP spec and is discarded when connector access controls are active, so unclassified calls are common. This field shows how much of the day's classified activity the read/write split actually covers. Call count, not distinct users. One of the three call-classification buckets; see `read_call_count` for the per-surface data-start dates, null conditions, and date-range guidance. - `user_id: optional string` Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`. - `write_call_count: optional number` Number of connector tool calls on the requested day whose trusted read-only annotation marked them not read-only. Call count, not distinct users. One of the three call-classification buckets; see `read_call_count` for the per-surface data-start dates, null conditions, and date-range guidance. - `next_page: string` Opaque cursor for the next page, or null if no more results #### Example ```bash ant beta:organization:analytics:connectors list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "chat_metrics": { "distinct_conversation_connector_used_count": 0 }, "claude_code_metrics": { "distinct_session_connector_used_count": 0 }, "connector_name": "connector_name", "cowork_metrics": { "distinct_session_connector_used_count": 0 }, "distinct_user_count": 0, "office_metrics": { "excel": { "distinct_session_connector_used_count": 0 }, "outlook": { "distinct_session_connector_used_count": 0 }, "powerpoint": { "distinct_session_connector_used_count": 0 }, "word": { "distinct_session_connector_used_count": 0 } }, "chat_cowork_unified_metrics": { "chat": { "distinct_conversation_connector_used_count": 0 }, "sessions": { "distinct_session_connector_used_count": 0 } }, "connector_display_name": "connector_display_name", "individual_auth_distinct_user_count": 0, "managed_auth_distinct_user_count": 0, "product": "product", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "read_call_count": 0, "unclassified_call_count": 0, "user_id": "user_id", "write_call_count": 0 } ], "next_page": "next_page" } ``` ## Beta › Organization › Analytics › Plugins ### Get Plugin Usage `$ ant beta:organization:analytics:plugins list` **GET** `/v1/organizations/analytics/plugins` Get per-plugin install + invocation usage for a given day, with pagination. Returns plugin usage metrics for the organization across Cowork and Claude Code, sorted by plugin name. The `plugin_name` value `third-party` is an aggregate bucket, not a plugin: it collects plugin activity, from either surface, for which the reporting client did not provide a plugin name — so an organization's own plugins can contribute both to their own named rows and to this bucket. Use `group_by[]` to break usage out per member, per RBAC group, or per product surface (Cowork / Claude Code), and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Requires an API key with the `read:analytics` scope. `starting_date` / `ending_date` select range-rollup mode like `/skills`. #### Parameters - `--date: optional string` (query parameter) UTC date in YYYY-MM-DD format. The day to get plugin usage for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date - `--ending-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`. format: date - `--filter: optional array of string` (query parameter) Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `plugin_name`, `product`, `rbac_group_id`, `user_id`. Value forms: `plugin_name` matches case-insensitively; `product` is `chat_cowork_unified`, `claude_code`, or `cowork` (the only surfaces with plugin attribution); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries. `chat_cowork_unified` is accepted as a `product` value only on deployments that offer Chat and Cowork unified. maxItems: 100 - `--group-by: optional array of "product" or "rbac_group_id" or "user_id"` (query parameter) Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. On this endpoint `product` takes the values `chat_cowork_unified`, `claude_code`, or `cowork` only (the surfaces with plugin attribution). Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries. maxItems: 100 - `--limit: optional number` (query parameter) Number of results per page (1-1000, default 100). minimum: 1, maximum: 1000 - `--order: optional "asc" or "desc"` (query parameter) Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted. - `--order-by: optional string` (query parameter) Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set). - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--starting-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date #### Returns - `BetaAnalyticsPluginsResponse: object` Response for GET /v1/organizations/analytics/plugins. - `data: array of BetaAnalyticsPluginActivity` - `claude_code_metrics: object` Claude Code activity metrics for a single plugin on a given day. - `distinct_session_plugin_used_count: number` Number of distinct Claude Code sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed. - `cowork_metrics: object` Cowork activity metrics for a single plugin on a given day. - `distinct_session_plugin_used_count: number` Number of distinct Cowork sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed. - `distinct_user_count: number` Number of distinct users with recorded install or invocation activity for the plugin on the requested day (install-only users count), or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values. - `install_count: number` Number of distinct users who installed the plugin on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values. - `invocation_count: number` Number of plugin invocations on the requested day - `plugin_name: string` Name of the plugin - `chat_cowork_unified_metrics: optional object` Plugin use recorded while members had Chat and Cowork unified (Cowork's features inside claude.ai chat) turned on. A count is null in date-range mode where it cannot be computed. Omitted from the response on deployments that do not offer Chat and Cowork unified. - `distinct_session_plugin_used_count: number` Same measure as `cowork_metrics.distinct_session_plugin_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Null on aggregated rows where a distinct count cannot be computed. - `plugin_id: optional string` Stable plugin identifier when available (e.g. `serena@claude-plugins-official`). Null for third-party Claude Code plugins (redacted at the source) and Cowork slash commands that carry only a hashed id. - `product: optional string` Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, `office_agent`, or `chat_cowork_unified` (Chat and Cowork unified). These are the canonical Cost & Usage product names; an `office_agent` row's per-surface breakdown is in its `office_metrics`. On `/plugins` only `cowork`, `claude_code` and `chat_cowork_unified` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, `cowork` and `chat_cowork_unified` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`. - `rbac_group_id: optional string` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `rbac_group_name: optional string` Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key. - `user_id: optional string` Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`. - `next_page: string` Opaque cursor for the next page, or null if no more results #### Example ```bash ant beta:organization:analytics:plugins list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "claude_code_metrics": { "distinct_session_plugin_used_count": 0 }, "cowork_metrics": { "distinct_session_plugin_used_count": 0 }, "distinct_user_count": 0, "install_count": 0, "invocation_count": 0, "plugin_name": "plugin_name", "chat_cowork_unified_metrics": { "distinct_session_plugin_used_count": 0 }, "plugin_id": "plugin_id", "product": "product", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "user_id": "user_id" } ], "next_page": "next_page" } ``` ## Beta › Organization › Analytics › Skills ### Get Skill Usage `$ ant beta:organization:analytics:skills list` **GET** `/v1/organizations/analytics/skills` Get per-skill usage for a given day, with cursor-based pagination. Returns skill usage metrics for the organization, sorted by skill name. Use `group_by[]` to break usage out per member, per RBAC group, or per product surface, and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. #### Parameters - `--date: optional string` (query parameter) UTC date in YYYY-MM-DD format. The day to get skill usage for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date - `--ending-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`. format: date - `--filter: optional array of string` (query parameter) Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `product`, `rbac_group_id`, `share_status`, `skill_name`, `user_id`. Value forms: `product` is one of `chat_cowork_unified`, `chat`, `claude_code`, `cowork`, or `office_agent`; `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `share_status` is one of `organization`, `private`, or `public`; `skill_name` matches case-insensitively; `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries. `chat_cowork_unified` is accepted as a `product` value only on deployments that offer Chat and Cowork unified. maxItems: 100 - `--group-by: optional array of "product" or "rbac_group_id" or "user_id"` (query parameter) Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries. maxItems: 100 - `--limit: optional number` (query parameter) Number of results per page (1-1000, default 100). minimum: 1, maximum: 1000 - `--order: optional "asc" or "desc"` (query parameter) Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted. - `--order-by: optional string` (query parameter) Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set). - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--starting-date: optional string` (query parameter) UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date #### Returns - `BetaAnalyticsSkillsResponse: object` Response for GET /v1/organizations/analytics/skills. - `data: array of BetaAnalyticsSkillActivity` - `chat_metrics: object` Claude.ai activity metrics for a single skill on a given day. - `distinct_conversation_skill_used_count: number` Number of distinct conversations in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `claude_code_metrics: object` Claude Code activity metrics for a single skill on a given day. - `distinct_session_skill_used_count: number` Number of distinct Claude Code sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `cowork_metrics: object` Cowork activity metrics for a single skill on a given day. - `distinct_session_skill_used_count: number` Number of distinct Cowork sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `distinct_user_count: number` Number of distinct users who used the skill on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. - `office_metrics: object` Office Agent activity metrics for a single skill on a given day, broken out by Office product. - `excel: object` Office Agent activity metrics for a single skill on a given day within one Office product. - `distinct_session_skill_used_count: number` Number of distinct Office Agent sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `outlook: object` Office Agent activity metrics for a single skill on a given day within one Office product. - `distinct_session_skill_used_count: number` Number of distinct Office Agent sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `powerpoint: object` Office Agent activity metrics for a single skill on a given day within one Office product. - `distinct_session_skill_used_count: number` Number of distinct Office Agent sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `word: object` Office Agent activity metrics for a single skill on a given day within one Office product. - `distinct_session_skill_used_count: number` Number of distinct Office Agent sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `skill_name: string` Name of the skill - `attributed_list_price: optional string` List-price (rate-card) value of the member requests attributed to this skill, as a decimal string in the minor unit of `currency` (cents for USD), from Claude Code, Cowork, and Office Agent request-level attribution — the value of requests that involved the skill, not the skill's incremental cost. Unlike `estimated_overage_spend` this reflects usage value regardless of how it was funded — seat-covered usage counts — but it is undiscounted and does not tie to billed spend or the organization's spend reporting. claude.ai chat usage carries no request-level attribution and contributes nothing: the field is null on `chat` product rows and on `office_agent` product cuts dated before 2026-06-18 (the Office Agent attribution data-start), and on ungrouped rows it covers the Claude Code + Cowork + Office Agent share only (null when no attributable usage exists). Also null under the same conditions as `estimated_overage_spend` (spend reporting not enabled for this organization, `office_agent` product cuts before the 2026-06-18 data-start). "0" means attributable usage existed but none was attributed to this skill. Addable across days: date-range rollup mode returns the window's sum. On `group_by[]` and `filter[]` shapes both amounts can total below the ungrouped value for the same skill over the same date or range: spend attributed to a member–skill pair with no counted usage on that day is excluded from those cuts. - `chat_cowork_unified_metrics: optional object` Skill use recorded while members had Chat and Cowork unified (Cowork's features inside claude.ai chat) turned on, split into chat conversations and Cowork sessions. A count is null in date-range mode where it cannot be computed. Omitted from the response on deployments that do not offer Chat and Cowork unified. - `chat: object` A skill's use in chat conversations recorded while members had Chat and Cowork unified turned on. - `distinct_conversation_skill_used_count: number` Same measure as `chat_metrics.distinct_conversation_skill_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `sessions: object` A skill's use in Cowork sessions recorded while members had Chat and Cowork unified turned on. - `distinct_session_skill_used_count: number` Same measure as `cowork_metrics.distinct_session_skill_used_count`, for activity recorded while members had Chat and Cowork unified turned on. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed. - `currency: optional string` Currency for this row's monetary fields (`estimated_overage_spend` and `attributed_list_price`), as an uppercase ISO-4217 code. Always "USD" when either amount is populated; null whenever both amounts are null. - `enable_count: optional number` Distinct accounts that enabled this skill on the requested day (claude.ai only — the skill analog of plugin `install_count`). The count is org-wide: null when enable reporting is not enabled for this organization, or when the request scopes to `user_id` / `rbac_group_id` / `product` via `group_by[]` or `filter[]` (an org-wide count would be misleading on per-cut rows). A distinct count, not an event count: summing across days double-counts members who enable the skill on more than one day, so it is also null in date-range rollup mode (`starting_date`/`ending_date`). - `estimated_overage_spend: optional string` Estimated overage spend attributed to this skill, as a decimal string in the minor unit of `currency` (cents for USD; "1250" is $12.50, fractional cents possible) — an allocation of each member's daily post-discount, pre-credit metered overage spend (the same cost basis as the organization's spend reporting and the Cost & Usage API, so per-skill figures are directly comparable; spend with no skill attribution — including any member-day without skill invocations — is not represented, so skill rows sum to at most those totals) across the skills the member used. Overage only: usage covered by included seat allowances bills nothing and allocates $0 here — see `attributed_list_price` for the funding-independent usage-value companion. Claude Code, Cowork, and Office Agent spend use request-level skill attribution; claude.ai chat spend is approximated proportionally to skill-invoking messages. An estimate, not a billing number — and the cost of the requests/messages that involved the skill, not the skill's incremental cost (the same request would still have cost something without the skill active). "0" means no overage spend was attributed; null when spend reporting is not enabled for this organization, on `office_agent` product cuts dated before 2026-06-18 (the Office Agent attribution data-start). Addable across days: date-range rollup mode (`starting_date`/`ending_date`) returns the window's sum. With `group_by[]=user_id` each row carries the user's own attributed spend. On `group_by[]` and `filter[]` shapes both amounts can total below the ungrouped value for the same skill over the same date or range: spend attributed to a member–skill pair with no counted usage on that day is excluded from those cuts. - `invocation_count: optional number` Total number of times this skill was invoked on the requested day (the skill analog of plugin `invocation_count`). Unlike `distinct_user_count` — which answers '\# of users' — this is the true '# of uses'. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Null when invocation reporting is not enabled for this organization. Sum across a date range for total uses in the window — date-range rollup mode (`starting_date`/`ending_date`) returns this sum directly. - `product: optional string` Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, `office_agent`, or `chat_cowork_unified` (Chat and Cowork unified). These are the canonical Cost & Usage product names; an `office_agent` row's per-surface breakdown is in its `office_metrics`. On `/plugins` only `cowork`, `claude_code` and `chat_cowork_unified` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, `cowork` and `chat_cowork_unified` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`. - `rbac_group_id: optional string` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `rbac_group_name: optional string` Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key. - `share_status: optional "organization" or "private" or "public"` Skill share status (claude.ai only): one of `private`, `organization`, or `public`. Null for skills used only in Claude Code or Office (no per-skill share-status concept) and when share-status reporting is not yet available for the organization. Filterable via `filter[]=share_status:{value}`. - `"organization"` - `"private"` - `"public"` - `skill_display_name: optional string` Human-readable display name for rows whose `skill_name` is an opaque skill id (user/organization skill types and plugin-delivered skills, whose user-defined names usage reports generally withhold). Organization-shared skills and skills delivered by the organization's own plugins (its plugin marketplaces and its library) resolve; plugin skill names are shown without their 'plugin:' prefix. The literal 'unknown' bucket row gets a fixed 'Unknown skill' label. For a member's own skill (private or personal-plugin) it is null, except when the skill's owner used it from Claude Code or Cowork in the requested period: then it shows the name that client reported at the time. Apart from that, the names of members' own skills are not disclosed to analytics-key holders. Also null for Anthropic-provided plugin skills (not resolved), for an organization skill or plugin whose name can no longer be found (for example, one since deleted), when `skill_name` is already a display name, or when display-name resolution is not enabled for this organization. - `user_id: optional string` Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`. - `next_page: string` Opaque cursor for the next page, or null if no more results #### Example ```bash ant beta:organization:analytics:skills list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "chat_metrics": { "distinct_conversation_skill_used_count": 0 }, "claude_code_metrics": { "distinct_session_skill_used_count": 0 }, "cowork_metrics": { "distinct_session_skill_used_count": 0 }, "distinct_user_count": 0, "office_metrics": { "excel": { "distinct_session_skill_used_count": 0 }, "outlook": { "distinct_session_skill_used_count": 0 }, "powerpoint": { "distinct_session_skill_used_count": 0 }, "word": { "distinct_session_skill_used_count": 0 } }, "skill_name": "skill_name", "attributed_list_price": "attributed_list_price", "chat_cowork_unified_metrics": { "chat": { "distinct_conversation_skill_used_count": 0 }, "sessions": { "distinct_session_skill_used_count": 0 } }, "currency": "currency", "enable_count": 0, "estimated_overage_spend": "estimated_overage_spend", "invocation_count": 0, "product": "product", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "share_status": "organization", "skill_display_name": "skill_display_name", "user_id": "user_id" } ], "next_page": "next_page" } ``` ## Beta › Organization › Analytics › Artifacts ### Get Artifact Activity `$ ant beta:organization:analytics:artifacts list` **GET** `/v1/organizations/analytics/artifacts` Get artifact-creation activity for a given day, broken out by MIME type. Returns the full (`artifact_type`, `is_shared`) cube for the organization; `next_page` is null except for grouped queries, which paginate. The cube can be broken out per product, per member, or per RBAC group via `group_by[]`, and scoped via `filter[]`. Requires an API key with the `read:analytics` scope. #### Parameters - `--date: string` (query parameter) UTC date in YYYY-MM-DD format. The day to get artifact activity for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01. format: date - `--filter: optional array of string` (query parameter) Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `artifact_type`, `is_shared`, `product`, `rbac_group_id`, `user_id`. Value forms: `artifact_type` is a canonical artifact MIME type (e.g. `text/markdown`) or `other`; `is_shared` is `true` or `false`; `product` is `chat_cowork_unified`, `chat`, `claude_code`, or `cowork` (the surfaces that create artifacts); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries. `chat_cowork_unified` is accepted as a `product` value only on deployments that offer Chat and Cowork unified. maxItems: 100 - `--group-by: optional array of "product" or "rbac_group_id" or "user_id"` (query parameter) Dimensions to break results out by: `product`, `user_id` and/or `rbac_group_id`. The ungrouped artifact-type cube is finite and returned in full; grouped queries multiply the cube and paginate via `next_page`. `product` takes the values `chat_cowork_unified`, `chat`, `claude_code`, or `cowork` (the surfaces that create artifacts). `rbac_group_id` attributes a user to every group they held at any point during the requested UTC day, so grouped rows are not an exclusive partition. At most 100 entries. maxItems: 100 - `--limit: optional number` (query parameter) Maximum rows to return (1-1000, default 100). The ungrouped artifact-type cube is finite and returned in full; `limit` is the page size only when `group_by[]` multiplies the cube. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. Only valid with `group_by[]` — the ungrouped cube is never paginated. #### Returns - `BetaAnalyticsArtifactsResponse: object` Response for GET /v1/organizations/analytics/artifacts. `next_page` is null on ungrouped queries — the artifact-type cube is finite and returned in full. Grouped queries (`group_by[]` on `product` / `user_id` / `rbac_group_id`) multiply the cube and paginate like the other analytics list endpoints. - `data: array of BetaAnalyticsArtifactActivity` - `artifact_type: string` Canonical artifact MIME type (e.g. `text/markdown`, `application/vnd.ant.react`, `image/svg+xml`), or `other`. Claude Code and Cowork artifacts report as `text/html`. - `artifacts_created_count: number` Number of artifacts created in this bucket on the requested day - `distinct_user_count: number` Number of distinct users who created artifacts in this bucket on the requested day - `is_shared: boolean` Whether the artifacts in this bucket have ever been shared (a Claude Code / Cowork artifact is shared once anyone beyond its creator may open it: named members, the whole organization, or anyone with the link). - `published_artifacts_created_count: number` Number of those artifacts that have been published (for Claude Code / Cowork artifacts: open to anyone with the link); never exceeds `artifacts_created_count` - `product: optional string` Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, `office_agent`, or `chat_cowork_unified` (Chat and Cowork unified). These are the canonical Cost & Usage product names; an `office_agent` row's per-surface breakdown is in its `office_metrics`. On `/plugins` only `cowork`, `claude_code` and `chat_cowork_unified` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, `cowork` and `chat_cowork_unified` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`. - `rbac_group_id: optional string` Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`. - `rbac_group_name: optional string` Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key. - `user_id: optional string` Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`. - `next_page: string` Cursor for the next page of a grouped query; always null for the ungrouped artifact-type cube, which is returned in full. #### Example ```bash ant beta:organization:analytics:artifacts list \ --api-key my-anthropic-api-key \ --date ''\''2019-12-27'\''' ``` ##### Response (200) ```json { "data": [ { "artifact_type": "artifact_type", "artifacts_created_count": 0, "distinct_user_count": 0, "is_shared": true, "published_artifacts_created_count": 0, "product": "product", "rbac_group_id": "rbac_group_id", "rbac_group_name": "rbac_group_name", "user_id": "user_id" } ], "next_page": "next_page" } ``` ## Beta › Organization › Analytics › Usage Report ### Get Token Usage Over Time `$ ant beta:organization:analytics:usage-report list` **GET** `/v1/organizations/analytics/usage_report` Get token usage over time across a date range. Returns token usage bucketed by minute, hour, or day, optionally broken down by product, model, context window, inference region, or speed. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. #### Parameters - `--starting-at: string` (query parameter) Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z. format: date-time - `--bucket-width: optional "1d" or "1h" or "1m"` (query parameter) Time bucket granularity. - `--claude-tag-category: optional array of BetaAnalyticsClaudeTagCategory` (query parameter) Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values. maxItems: 100 - `--claude-tag-user-id: optional array of string` (query parameter) Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values. maxItems: 100 - `--context-window: optional array of BetaAnalyticsContextWindow` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. maxItems: 100 - `--ending-at: optional string` (query parameter) End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days. format: date-time - `--group-by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 6 more` (query parameter) Dimensions to break each time bucket out by. Defaults to no grouping (one total per bucket). Each bucket reports at most its top 100 groups; a group beyond that cap has no row in that bucket (there is no remainder row), so grouped buckets are not exhaustive when a dimension has more than 100 distinct values. maxItems: 100 - `--inference-geo: optional array of BetaAnalyticsInferenceGeoFilter` (query parameter) Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values. maxItems: 100 - `--limit: optional number` (query parameter) Maximum number of time buckets per page. Defaults and caps vary by `bucket_width` (`1d`: default 7, max 31; `1h`: default 24, max 168; `1m`: default 60, max 256). minimum: 1 - `--model: optional array of string` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. maxItems: 100 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--product: optional array of BetaAnalyticsProductFilter` (query parameter) Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values. maxItems: 100 - `--rbac-group-id: optional array of string` (query parameter) Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches. maxItems: 100 - `--slack-channel-id: optional array of string` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. maxItems: 100 - `--speed: optional array of "fast" or "standard"` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. maxItems: 100 - `--user-id: optional array of string` (query parameter) Filter to specific users by tagged user ID. maxItems: 100 #### Returns - `BetaAnalyticsUsageBucketedResponse: object` - `data: array of BetaAnalyticsUsageReportTimeBucket` Time buckets for this page, oldest first: one per `bucket_width` interval, including intervals with no data (their `results` list is empty). A page holds at most `limit` buckets. - `ending_at: string` End of the time bucket (exclusive) in RFC 3339 format. format: date-time - `results: array of BetaAnalyticsUsageBucketedResult` Rows for this time bucket. Empty when the bucket has no data; otherwise a single combined row when `group_by[]` is omitted, or one row per group (subject to the per-bucket group cap described on the `group_by[]` parameter). - `cache_creation: object` The number of input tokens for cache creation. - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. - `claude_tag_category: "dm" or "engaged" or "monitoring" or 2 more` Claude Tag (Claude in Slack) spend category: `engaged` (a person addressed Claude in a channel or thread), `proactive` (Claude responded without being addressed), `scheduled` (a scheduled routine ran), `monitoring` (Claude watching a channel it was asked to monitor), or `dm` (direct messages with Claude). Populated only when `claude_tag_category` is in `group_by[]`; null for usage that is not Claude Tag. Direct-message usage is billed to the individual user and is reported under that user's product, not under `claude-tag`. New categories may be added over time. - `"dm"` - `"engaged"` - `"monitoring"` - `"proactive"` - `"scheduled"` - `claude_tag_user_id: string` Slack user ID (for example `U0123ABCDEF`) of the member the Claude Tag (Claude in Slack) usage is attributed to, not a claude.ai user ID. Populated only when `claude_tag_user_id` is in `group_by[]`; null for usage that is not Claude Tag and for Claude Tag usage that is not attributed to a single user (for example `monitoring`, and `proactive` usage Claude initiated), so per-user rows can sum to less than the Claude Tag total. Cannot be combined with `group_by[]=rbac_group_id` or the `rbac_group_ids[]` filter. - `context_window: "0-200k" or "200k-1M"` Context-window pricing tier of the usage or cost. Null unless `context_window` is in `group_by[]`; it can also be null on grouped rows with no context-window tier, such as code execution. - `"0-200k"` - `"200k-1M"` - `inference_geo: "global" or "us"` Inference region of the usage or cost. Null unless `inference_geo` is in `group_by[]`; it can also be null on grouped rows where the region is not set (the rows that `inference_geos[]=not_available` matches). - `"global"` - `"us"` - `model: string` Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5-5`). Null unless `model` is in `group_by[]`; it can also be null on grouped rows whose usage or cost is not attributed to a specific model, such as code execution. - `output_tokens: number` The number of output tokens generated. - `product: string` Product surface that produced the usage or cost. Null unless product is in `group_by[]`; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include `chat`, `claude_code`, `cowork`, `office_agent`, `claude_in_chrome`, `claude_design`, `claude-tag`, and `chat_cowork_unified`. `claude-tag` is Claude Tag, the Claude product in Slack. `chat_cowork_unified` is Chat and Cowork unified, Cowork's features inside claude.ai chat: chat and Cowork usage by a member who has it turned on is reported under this value instead of `chat` or `cowork`. It is accepted as a filter only on deployments that offer Chat and Cowork unified. Some unattributed usage is reported as "other". - `rbac_group_id: string` RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has one id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query without `group_by[]`. - `requests: number` Number of API requests in this row's scope. For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`). - `server_tool_use: object` Server-side tool usage metrics. - `web_search_requests: number` The number of web search requests made. - `slack_channel_id: string` Slack channel the usage originated from. Populated only when `slack_channel_id` is in `group_by[]`; null for usage outside Slack (and for rows recorded before channel attribution was enabled). - `speed: "fast" or "standard"` Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`. - `"fast"` - `"standard"` - `uncached_input_tokens: number` The number of uncached input tokens processed. - `starting_at: string` Start of the time bucket (inclusive) in RFC 3339 format. format: date-time - `data_refreshed_at: string` RFC 3339 timestamp of the export this response was served from. Null when no export yet covers any part of the requested range, in which case every bucket's `results` list is empty. Buckets beyond this watermark are incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours. Values can be revised as late events arrive and reconciliation runs, until about 7 days after the end of the calendar month the usage falls in; for example, values for October 1 can change until about November 7. format: date-time - `has_more: boolean` Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it. - `next_page: string` Opaque cursor for the next page, or null when `has_more` is false. Pass it as the `page` parameter, keeping the other parameters unchanged. A cursor can expire after the underlying data refreshes; the request then returns HTTP 410 and pagination must restart from the first page. - `organization_id: string` ID of the Organization. #### Example ```bash ant beta:organization:analytics:usage-report list \ --api-key my-anthropic-api-key \ --starting-at ''\''2019-12-27T18:11:19.117Z'\''' ``` ##### Response (200) ```json { "data": [ { "ending_at": "2019-12-27T18:11:19.117Z", "results": [ { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "inference_geo": "global", "model": "claude-opus-5-5", "output_tokens": 0, "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "requests": 0, "server_tool_use": { "web_search_requests": 10 }, "slack_channel_id": "C0123ABCDEF", "speed": "fast", "uncached_input_tokens": 0 } ], "starting_at": "2019-12-27T18:11:19.117Z" } ], "data_refreshed_at": "2019-12-27T18:11:19.117Z", "has_more": true, "next_page": "next_page", "organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF" } ``` ## Beta › Organization › Analytics › User Usage Report ### Get Per-User Token Usage `$ ant beta:organization:analytics:user-usage-report list` **GET** `/v1/organizations/analytics/user_usage_report` Get per-user token usage across a date range. Returns one row per user, ranked by the chosen token metric. Use this to see which users consume the most tokens. Only usage attributable to a seat user is included; for organization-wide totals including direct API-key and automation traffic, use the bucketed `/v1/organizations/analytics/usage_report` endpoint. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. #### Parameters - `--starting-at: string` (query parameter) Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z. format: date-time - `--bucket-width: optional "1d" or "1h" or "1m"` (query parameter) Time-bucket granularity. When set, each row's `starting_at` and `ending_at` are populated and one actor may span several rows (one per time bucket with usage). The time bucket counts toward `limit`, so one page can return multiple rows for the same actor. `ending_at` is required when `bucket_width` is set, and with `bucket_width="1m"` the range may span at most 24 hours. When omitted, each row aggregates the full `[starting_at, ending_at)` range. - `--claude-tag-category: optional array of BetaAnalyticsClaudeTagCategory` (query parameter) Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values. maxItems: 100 - `--claude-tag-user-id: optional array of string` (query parameter) Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values. maxItems: 100 - `--context-window: optional array of BetaAnalyticsContextWindow` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. maxItems: 100 - `--ending-at: optional string` (query parameter) End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days. format: date-time - `--exclude-deleted-users: optional boolean` (query parameter) If true, omit rows for users who are deleted (`deleted: true`). A page may contain fewer than `limit` rows; use `has_more` and `next_page` to paginate as usual. - `--group-by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 6 more` (query parameter) Break each actor's row out by the given dimensions. Accepts the same values as the bucketed `/usage_report` endpoint. `limit` bounds (actor × time bucket × dimension) rows — with dimensions or `bucket_width` present, one actor may span several rows. maxItems: 100 - `--inference-geo: optional array of BetaAnalyticsInferenceGeoFilter` (query parameter) Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values. maxItems: 100 - `--limit: optional number` (query parameter) Number of rows per page (1-1000, default 20). One row per actor unless `group_by[]` or `bucket_width` splits an actor across rows; `cost_type`/`token_type` fan-out rows (cost endpoint only) are the exception — they do not count toward this limit, so `data` can exceed it. minimum: 1, maximum: 1000 - `--model: optional array of string` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. maxItems: 100 - `--order: optional "asc" or "desc"` (query parameter) Sort direction. Defaults to `desc`. - `--order-by: optional "output_tokens" or "requests" or "total_tokens" or "uncached_input_tokens"` (query parameter) Metric to rank actors by. Defaults to `total_tokens`. - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--product: optional array of BetaAnalyticsProductFilter` (query parameter) Product surfaces to include. Defaults to all products. maxItems: 100 - `--rbac-group-id: optional array of string` (query parameter) Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches. maxItems: 100 - `--slack-channel-id: optional array of string` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. maxItems: 100 - `--speed: optional array of "fast" or "standard"` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. maxItems: 100 - `--user-id: optional array of string` (query parameter) Filter to specific users by tagged user ID. maxItems: 100 #### Returns - `BetaAnalyticsUsageUsersResponse: object` - `data: array of BetaAnalyticsUsageUsersItem` Rows for this page, ranked by `order_by` in the `order` direction. One row per user, or several per user when `group_by[]` or `bucket_width` breaks that user's usage or cost out across rows. Rows split out by `cost_type` or `token_type` (cost endpoint only) stay adjacent and are ranked as one unit. - `actor: object` The user this row's usage or cost is attributed to. Always a `user_actor`. - `type: "user_actor"` Actor type. Always `"user_actor"`. - `deleted: boolean` True when the account has been deleted, or when the user is no longer a member of the organization or its associated organizations (for example, their membership was removed or they were deprovisioned via your identity provider). `email_address` stays populated for removed users and is null when the account has been deleted. `name` follows the rules described on that field. The `user_id` is still populated for reconciliation. - `email_address: string` The user's email address, including for users who are no longer members of the organization or its associated organizations. Null when the account has been deleted (check `deleted`) and for system-minted service accounts, which have no person's mailbox behind them (check `name`). - `name: string` The user's full name. Null when the user has not set a name. Returns `"Deleted User"` when the account itself has been deleted, or when the user is no longer a member of the organization or its associated organizations and the organization has chosen to hide the names of removed users. Otherwise, the name stays populated for removed users. Rows for system-minted service accounts render the service name (for example, `"Claude Security"` for usage by Anthropic's security-patching service) or null. - `user_id: string` Tagged user ID. - `cache_creation: object` The number of input tokens for cache creation. - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. minimum: 0 - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. minimum: 0 - `cache_read_input_tokens: number` The number of input tokens read from the cache. - `claude_tag_category: "dm" or "engaged" or "monitoring" or 2 more` Claude Tag (Claude in Slack) spend category: `engaged` (a person addressed Claude in a channel or thread), `proactive` (Claude responded without being addressed), `scheduled` (a scheduled routine ran), `monitoring` (Claude watching a channel it was asked to monitor), or `dm` (direct messages with Claude). Populated only when `claude_tag_category` is in `group_by[]`; null for usage that is not Claude Tag. Direct-message usage is billed to the individual user and is reported under that user's product, not under `claude-tag`. New categories may be added over time. - `"dm"` - `"engaged"` - `"monitoring"` - `"proactive"` - `"scheduled"` - `claude_tag_user_id: string` Slack user ID (for example `U0123ABCDEF`) of the member the Claude Tag (Claude in Slack) usage is attributed to, not a claude.ai user ID. Populated only when `claude_tag_user_id` is in `group_by[]`; null for usage that is not Claude Tag and for Claude Tag usage that is not attributed to a single user (for example `monitoring`, and `proactive` usage Claude initiated), so per-user rows can sum to less than the Claude Tag total. Cannot be combined with `group_by[]=rbac_group_id` or the `rbac_group_ids[]` filter. - `context_window: "0-200k" or "200k-1M"` Context-window pricing tier of the usage or cost. Null unless `context_window` is in `group_by[]`; it can also be null on grouped rows with no context-window tier, such as code execution. - `"0-200k"` - `"200k-1M"` - `ending_at: string` End of the row's UTC time bucket (exclusive), as an RFC 3339 timestamp; equal to `starting_at` plus one `bucket_width`. Null unless `bucket_width` is set. format: date-time - `inference_geo: "global" or "us"` Inference region of the usage or cost. Null unless `inference_geo` is in `group_by[]`; it can also be null on grouped rows where the region is not set (the rows that `inference_geos[]=not_available` matches). - `"global"` - `"us"` - `model: string` Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5-5`). Null unless `model` is in `group_by[]`; it can also be null on grouped rows whose usage or cost is not attributed to a specific model, such as code execution. - `output_tokens: number` The number of output tokens generated. - `product: string` Product surface that produced the usage or cost. Null unless product is in `group_by[]`; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include `chat`, `claude_code`, `cowork`, `office_agent`, `claude_in_chrome`, `claude_design`, `claude-tag`, and `chat_cowork_unified`. `claude-tag` is Claude Tag, the Claude product in Slack. `chat_cowork_unified` is Chat and Cowork unified, Cowork's features inside claude.ai chat: chat and Cowork usage by a member who has it turned on is reported under this value instead of `chat` or `cowork`. It is accepted as a filter only on deployments that offer Chat and Cowork unified. Some unattributed usage is reported as "other". - `rbac_group_id: string` RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has one id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query without `group_by[]`. - `requests: number` Number of API requests in this row's scope. For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`). - `server_tool_use: object` Server-side tool usage metrics. - `web_search_requests: number` The number of web search requests made. - `slack_channel_id: string` Slack channel the usage originated from. Populated only when `slack_channel_id` is in `group_by[]`; null for usage outside Slack (and for rows recorded before channel attribution was enabled). - `speed: "fast" or "standard"` Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`. - `"fast"` - `"standard"` - `starting_at: string` Start of the row's UTC time bucket (inclusive), as an RFC 3339 timestamp. Null unless `bucket_width` is set; without `bucket_width`, each row aggregates the full requested range. format: date-time - `total_tokens: number` Total token count across all token types. This is the value the default `order_by` (`total_tokens`) sorts on. - `uncached_input_tokens: number` The number of uncached input tokens processed. - `data_refreshed_at: string` RFC 3339 timestamp of the export this response was served from. Null when no export yet covers any part of the requested range, in which case `data` is empty. Data beyond this watermark is incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours. Values can be revised as late events arrive and reconciliation runs, until about 7 days after the end of the calendar month the usage falls in; for example, values for October 1 can change until about November 7. format: date-time - `has_more: boolean` Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it. - `next_page: string` Opaque cursor for the next page, or null when `has_more` is false. Pass it as the `page` parameter, keeping the other parameters unchanged. A cursor can expire after the underlying data refreshes; the request then returns HTTP 410 and pagination must restart from the first page. - `organization_id: string` ID of the Organization. #### Example ```bash ant beta:organization:analytics:user-usage-report list \ --api-key my-anthropic-api-key \ --starting-at ''\''2019-12-27T18:11:19.117Z'\''' ``` ##### Response (200) ```json { "data": [ { "actor": { "deleted": true, "email": "jane@example.com", "email_address": "jane@example.com", "name": "Jane Smith", "type": "user_actor", "user_id": "user_01AbCdEfGhIjKlMnOpQrSt" }, "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 3200000, "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "ending_at": "2019-12-27T18:11:19.117Z", "inference_geo": "global", "model": "claude-opus-5-5", "output_tokens": 891000, "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "requests": 128, "server_tool_use": { "web_search_requests": 10 }, "slack_channel_id": "C0123ABCDEF", "speed": "fast", "starting_at": "2019-12-27T18:11:19.117Z", "total_tokens": 5377000, "uncached_input_tokens": 1284500 } ], "data_refreshed_at": "2019-12-27T18:11:19.117Z", "has_more": true, "next_page": "next_page", "organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF" } ``` ## Beta › Organization › Analytics › Cost Report ### Get Cost Over Time `$ ant beta:organization:analytics:cost-report list` **GET** `/v1/organizations/analytics/cost_report` Get cost in USD over time across a date range. Returns cost bucketed by minute, hour, or day, optionally broken down by product, model, context window, inference region, speed, cost type, or token type. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. #### Parameters - `--starting-at: string` (query parameter) Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z. format: date-time - `--bucket-width: optional "1d" or "1h" or "1m"` (query parameter) Time bucket granularity. - `--claude-tag-category: optional array of BetaAnalyticsClaudeTagCategory` (query parameter) Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values. maxItems: 100 - `--claude-tag-user-id: optional array of string` (query parameter) Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values. maxItems: 100 - `--context-window: optional array of BetaAnalyticsContextWindow` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. maxItems: 100 - `--ending-at: optional string` (query parameter) End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days. format: date-time - `--group-by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 8 more` (query parameter) Dimensions to break each time bucket out by. Defaults to no grouping (one total per bucket). Each bucket reports at most its top 100 groups; a group beyond that cap has no row in that bucket (there is no remainder row), so grouped buckets are not exhaustive when a dimension has more than 100 distinct values. maxItems: 100 - `--inference-geo: optional array of BetaAnalyticsInferenceGeoFilter` (query parameter) Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values. maxItems: 100 - `--limit: optional number` (query parameter) Maximum number of time buckets per page. Defaults and caps vary by `bucket_width` (`1d`: default 7, max 31; `1h`: default 24, max 168; `1m`: default 60, max 256). minimum: 1 - `--model: optional array of string` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. maxItems: 100 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--product: optional array of BetaAnalyticsProductFilter` (query parameter) Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values. maxItems: 100 - `--rbac-group-id: optional array of string` (query parameter) Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches. maxItems: 100 - `--slack-channel-id: optional array of string` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. maxItems: 100 - `--speed: optional array of "fast" or "standard"` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. maxItems: 100 - `--user-id: optional array of string` (query parameter) Filter to specific users by tagged user ID. maxItems: 100 #### Returns - `BetaAnalyticsCostBucketedResponse: object` - `data: array of BetaAnalyticsCostReportTimeBucket` Time buckets for this page, oldest first: one per `bucket_width` interval, including intervals with no data (their `results` list is empty). A page holds at most `limit` buckets. - `ending_at: string` End of the time bucket (exclusive) in RFC 3339 format. format: date-time - `results: array of BetaAnalyticsCostBucketedResult` Rows for this time bucket. Empty when the bucket has no data; otherwise a single combined row when `group_by[]` is omitted, or one row per group (subject to the per-bucket group cap described on the `group_by[]` parameter). - `amount: string` Amount (post-discount, pre-credit) in fractional cents. - `claude_tag_category: "dm" or "engaged" or "monitoring" or 2 more` Claude Tag (Claude in Slack) spend category: `engaged` (a person addressed Claude in a channel or thread), `proactive` (Claude responded without being addressed), `scheduled` (a scheduled routine ran), `monitoring` (Claude watching a channel it was asked to monitor), or `dm` (direct messages with Claude). Populated only when `claude_tag_category` is in `group_by[]`; null for usage that is not Claude Tag. Direct-message usage is billed to the individual user and is reported under that user's product, not under `claude-tag`. New categories may be added over time. - `"dm"` - `"engaged"` - `"monitoring"` - `"proactive"` - `"scheduled"` - `claude_tag_user_id: string` Slack user ID (for example `U0123ABCDEF`) of the member the Claude Tag (Claude in Slack) usage is attributed to, not a claude.ai user ID. Populated only when `claude_tag_user_id` is in `group_by[]`; null for usage that is not Claude Tag and for Claude Tag usage that is not attributed to a single user (for example `monitoring`, and `proactive` usage Claude initiated), so per-user rows can sum to less than the Claude Tag total. Cannot be combined with `group_by[]=rbac_group_id` or the `rbac_group_ids[]` filter. - `context_window: "0-200k" or "200k-1M"` Context-window pricing tier of the usage or cost. Null unless `context_window` is in `group_by[]`; it can also be null on grouped rows with no context-window tier, such as code execution. - `"0-200k"` - `"200k-1M"` - `cost_type: "code_execution" or "tokens" or "web_search"` Cost component when `group_by[]=cost_type`; null otherwise (amount is the combined total). - `"code_execution"` - `"tokens"` - `"web_search"` - `currency: string` Currency code for the cost amount. Currently always `"USD"`. - `inference_geo: "global" or "us"` Inference region of the usage or cost. Null unless `inference_geo` is in `group_by[]`; it can also be null on grouped rows where the region is not set (the rows that `inference_geos[]=not_available` matches). - `"global"` - `"us"` - `list_amount: string` List-price amount (pre-discount) in fractional cents. - `model: string` Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5-5`). Null unless `model` is in `group_by[]`; it can also be null on grouped rows whose usage or cost is not attributed to a specific model, such as code execution. - `product: string` Product surface that produced the usage or cost. Null unless product is in `group_by[]`; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include `chat`, `claude_code`, `cowork`, `office_agent`, `claude_in_chrome`, `claude_design`, `claude-tag`, and `chat_cowork_unified`. `claude-tag` is Claude Tag, the Claude product in Slack. `chat_cowork_unified` is Chat and Cowork unified, Cowork's features inside claude.ai chat: chat and Cowork usage by a member who has it turned on is reported under this value instead of `chat` or `cowork`. It is accepted as a filter only on deployments that offer Chat and Cowork unified. Some unattributed usage is reported as "other". - `rbac_group_id: string` RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has one id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query without `group_by[]`. - `requests: number` Number of API requests in this row's scope. Null when `group_by` includes `cost_type` or `token_type` (the count has no per-component attribution; read it from the ungrouped response). For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`). - `slack_channel_id: string` Slack channel the usage originated from. Populated only when `slack_channel_id` is in `group_by[]`; null for usage outside Slack (and for rows recorded before channel attribution was enabled). - `speed: "fast" or "standard"` Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`. - `"fast"` - `"standard"` - `token_type: "cache_creation.ephemeral_1h_input_tokens" or "cache_creation.ephemeral_5m_input_tokens" or "cache_read_input_tokens" or 2 more` Token type when `group_by[]=token_type` and `cost_type=tokens`; null otherwise. - `"cache_creation.ephemeral_1h_input_tokens"` - `"cache_creation.ephemeral_5m_input_tokens"` - `"cache_read_input_tokens"` - `"output_tokens"` - `"uncached_input_tokens"` - `starting_at: string` Start of the time bucket (inclusive) in RFC 3339 format. format: date-time - `data_refreshed_at: string` RFC 3339 timestamp of the export this response was served from. Null when no export yet covers any part of the requested range, in which case every bucket's `results` list is empty. Buckets beyond this watermark are incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours. Values can be revised as late events arrive and reconciliation runs, until about 7 days after the end of the calendar month the usage falls in; for example, values for October 1 can change until about November 7. format: date-time - `has_more: boolean` Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it. - `next_page: string` Opaque cursor for the next page, or null when `has_more` is false. Pass it as the `page` parameter, keeping the other parameters unchanged. A cursor can expire after the underlying data refreshes; the request then returns HTTP 410 and pagination must restart from the first page. - `organization_id: string` ID of the Organization. #### Example ```bash ant beta:organization:analytics:cost-report list \ --api-key my-anthropic-api-key \ --starting-at ''\''2019-12-27T18:11:19.117Z'\''' ``` ##### Response (200) ```json { "data": [ { "ending_at": "2019-12-27T18:11:19.117Z", "results": [ { "amount": "amount", "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "cost_type": "code_execution", "currency": "USD", "inference_geo": "global", "list_amount": "list_amount", "model": "claude-opus-5-5", "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "requests": 0, "slack_channel_id": "C0123ABCDEF", "speed": "fast", "token_type": "cache_creation.ephemeral_1h_input_tokens" } ], "starting_at": "2019-12-27T18:11:19.117Z" } ], "data_refreshed_at": "2019-12-27T18:11:19.117Z", "has_more": true, "next_page": "next_page", "organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF" } ``` ## Beta › Organization › Analytics › User Cost Report ### Get Per-User Cost `$ ant beta:organization:analytics:user-cost-report list` **GET** `/v1/organizations/analytics/user_cost_report` Get per-user cost in USD across a date range. Returns one row per user, ranked by spend. Use this to see which users account for the most cost. Only cost attributable to a seat user is included; for organization-wide totals including direct API-key and automation traffic, use the bucketed `/v1/organizations/analytics/cost_report` endpoint. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope. #### Parameters - `--starting-at: string` (query parameter) Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z. format: date-time - `--bucket-width: optional "1d" or "1h" or "1m"` (query parameter) Time-bucket granularity. When set, each row's `starting_at` and `ending_at` are populated and one actor may span several rows (one per time bucket with usage). The time bucket counts toward `limit`, so one page can return multiple rows for the same actor. `ending_at` is required when `bucket_width` is set, and with `bucket_width="1m"` the range may span at most 24 hours. When omitted, each row aggregates the full `[starting_at, ending_at)` range. - `--claude-tag-category: optional array of BetaAnalyticsClaudeTagCategory` (query parameter) Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values. maxItems: 100 - `--claude-tag-user-id: optional array of string` (query parameter) Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values. maxItems: 100 - `--context-window: optional array of BetaAnalyticsContextWindow` (query parameter) Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values. maxItems: 100 - `--ending-at: optional string` (query parameter) End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days. format: date-time - `--exclude-deleted-users: optional boolean` (query parameter) If true, omit rows for users who are deleted (`deleted: true`). A page may contain fewer than `limit` rows; use `has_more` and `next_page` to paginate as usual. - `--group-by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 8 more` (query parameter) Break each actor's row out by the given dimensions. Accepts the same values as the bucketed `/cost_report` endpoint. The `product`, `model`, `context_window`, `inference_geo`, and `speed` dimensions — and the time bucket, when `bucket_width` is set — count toward `limit`. `cost_type` and `token_type` do not: `cost_type` returns one row per cost component (tokens, web search, code execution); `token_type` returns one row per token type, each with `cost_type: "tokens"`; combining both returns the per-token-type rows plus the web-search and code-execution rows. A page can therefore contain more rows than `limit` when `cost_type` or `token_type` is requested. maxItems: 100 - `--inference-geo: optional array of BetaAnalyticsInferenceGeoFilter` (query parameter) Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values. maxItems: 100 - `--limit: optional number` (query parameter) Number of rows per page (1-1000, default 20). One row per actor unless `group_by[]` or `bucket_width` splits an actor across rows; `cost_type`/`token_type` fan-out rows (cost endpoint only) are the exception — they do not count toward this limit, so `data` can exceed it. minimum: 1, maximum: 1000 - `--model: optional array of string` (query parameter) Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values. maxItems: 100 - `--order: optional "asc" or "desc"` (query parameter) Sort direction. Defaults to `desc`. - `--order-by: optional "amount" or "list_amount"` (query parameter) Metric to rank actors by. Defaults to `amount`. - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--product: optional array of BetaAnalyticsProductFilter` (query parameter) Product surfaces to include. Defaults to all products. maxItems: 100 - `--rbac-group-id: optional array of string` (query parameter) Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches. maxItems: 100 - `--slack-channel-id: optional array of string` (query parameter) Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values. maxItems: 100 - `--speed: optional array of "fast" or "standard"` (query parameter) Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values. maxItems: 100 - `--user-id: optional array of string` (query parameter) Filter to specific users by tagged user ID. maxItems: 100 #### Returns - `BetaAnalyticsCostUsersResponse: object` - `data: array of BetaAnalyticsCostUsersItem` Rows for this page, ranked by `order_by` in the `order` direction. One row per user, or several per user when `group_by[]` or `bucket_width` breaks that user's usage or cost out across rows. Rows split out by `cost_type` or `token_type` (cost endpoint only) stay adjacent and are ranked as one unit. - `actor: object` The user this row's usage or cost is attributed to. Always a `user_actor`. - `type: "user_actor"` Actor type. Always `"user_actor"`. - `deleted: boolean` True when the account has been deleted, or when the user is no longer a member of the organization or its associated organizations (for example, their membership was removed or they were deprovisioned via your identity provider). `email_address` stays populated for removed users and is null when the account has been deleted. `name` follows the rules described on that field. The `user_id` is still populated for reconciliation. - `email_address: string` The user's email address, including for users who are no longer members of the organization or its associated organizations. Null when the account has been deleted (check `deleted`) and for system-minted service accounts, which have no person's mailbox behind them (check `name`). - `name: string` The user's full name. Null when the user has not set a name. Returns `"Deleted User"` when the account itself has been deleted, or when the user is no longer a member of the organization or its associated organizations and the organization has chosen to hide the names of removed users. Otherwise, the name stays populated for removed users. Rows for system-minted service accounts render the service name (for example, `"Claude Security"` for usage by Anthropic's security-patching service) or null. - `user_id: string` Tagged user ID. - `amount: string` Amount (post-discount, pre-credit) in fractional cents (minor units). - `claude_tag_category: "dm" or "engaged" or "monitoring" or 2 more` Claude Tag (Claude in Slack) spend category: `engaged` (a person addressed Claude in a channel or thread), `proactive` (Claude responded without being addressed), `scheduled` (a scheduled routine ran), `monitoring` (Claude watching a channel it was asked to monitor), or `dm` (direct messages with Claude). Populated only when `claude_tag_category` is in `group_by[]`; null for usage that is not Claude Tag. Direct-message usage is billed to the individual user and is reported under that user's product, not under `claude-tag`. New categories may be added over time. - `"dm"` - `"engaged"` - `"monitoring"` - `"proactive"` - `"scheduled"` - `claude_tag_user_id: string` Slack user ID (for example `U0123ABCDEF`) of the member the Claude Tag (Claude in Slack) usage is attributed to, not a claude.ai user ID. Populated only when `claude_tag_user_id` is in `group_by[]`; null for usage that is not Claude Tag and for Claude Tag usage that is not attributed to a single user (for example `monitoring`, and `proactive` usage Claude initiated), so per-user rows can sum to less than the Claude Tag total. Cannot be combined with `group_by[]=rbac_group_id` or the `rbac_group_ids[]` filter. - `context_window: "0-200k" or "200k-1M"` Context-window pricing tier of the usage or cost. Null unless `context_window` is in `group_by[]`; it can also be null on grouped rows with no context-window tier, such as code execution. - `"0-200k"` - `"200k-1M"` - `cost_type: "code_execution" or "tokens" or "web_search"` Cost component breakdown; null when returning the combined total. - `"code_execution"` - `"tokens"` - `"web_search"` - `currency: string` Currency code for the cost amount. Currently always `"USD"`. - `ending_at: string` End of the row's UTC time bucket (exclusive), as an RFC 3339 timestamp; equal to `starting_at` plus one `bucket_width`. Null unless `bucket_width` is set. format: date-time - `inference_geo: "global" or "us"` Inference region of the usage or cost. Null unless `inference_geo` is in `group_by[]`; it can also be null on grouped rows where the region is not set (the rows that `inference_geos[]=not_available` matches). - `"global"` - `"us"` - `list_amount: string` List-price amount (pre-discount) in fractional cents. - `model: string` Model that produced the usage or cost, as a model name in the form the `models[]` filter accepts (for example, `claude-opus-5-5`). Null unless `model` is in `group_by[]`; it can also be null on grouped rows whose usage or cost is not attributed to a specific model, such as code execution. - `product: string` Product surface that produced the usage or cost. Null unless product is in `group_by[]`; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include `chat`, `claude_code`, `cowork`, `office_agent`, `claude_in_chrome`, `claude_design`, `claude-tag`, and `chat_cowork_unified`. `claude-tag` is Claude Tag, the Claude product in Slack. `chat_cowork_unified` is Chat and Cowork unified, Cowork's features inside claude.ai chat: chat and Cowork usage by a member who has it turned on is reported under this value instead of `chat` or `cowork`. It is accepted as a filter only on deployments that offer Chat and Cowork unified. Some unattributed usage is reported as "other". - `rbac_group_id: string` RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has one id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query without `group_by[]`. - `requests: number` Number of API requests in this row's scope. Null when `group_by` includes `cost_type` or `token_type` (the count has no per-component attribution; read it from the ungrouped response). For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`). - `slack_channel_id: string` Slack channel the usage originated from. Populated only when `slack_channel_id` is in `group_by[]`; null for usage outside Slack (and for rows recorded before channel attribution was enabled). - `speed: "fast" or "standard"` Inference speed mode of the usage or cost: `fast` or `standard`. Null unless `speed` is in `group_by[]`. - `"fast"` - `"standard"` - `starting_at: string` Start of the row's UTC time bucket (inclusive), as an RFC 3339 timestamp. Null unless `bucket_width` is set; without `bucket_width`, each row aggregates the full requested range. format: date-time - `token_type: "cache_creation.ephemeral_1h_input_tokens" or "cache_creation.ephemeral_5m_input_tokens" or "cache_read_input_tokens" or 2 more` Token type when `cost_type` is `tokens`; null otherwise. - `"cache_creation.ephemeral_1h_input_tokens"` - `"cache_creation.ephemeral_5m_input_tokens"` - `"cache_read_input_tokens"` - `"output_tokens"` - `"uncached_input_tokens"` - `data_refreshed_at: string` RFC 3339 timestamp of the export this response was served from. Null when no export yet covers any part of the requested range, in which case `data` is empty. Data beyond this watermark is incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours. Values can be revised as late events arrive and reconciliation runs, until about 7 days after the end of the calendar month the usage falls in; for example, values for October 1 can change until about November 7. format: date-time - `has_more: boolean` Whether another page is available. When true, pass `next_page` as the `page` parameter to fetch it. - `next_page: string` Opaque cursor for the next page, or null when `has_more` is false. Pass it as the `page` parameter, keeping the other parameters unchanged. A cursor can expire after the underlying data refreshes; the request then returns HTTP 410 and pagination must restart from the first page. - `organization_id: string` ID of the Organization. #### Example ```bash ant beta:organization:analytics:user-cost-report list \ --api-key my-anthropic-api-key \ --starting-at ''\''2019-12-27T18:11:19.117Z'\''' ``` ##### Response (200) ```json { "data": [ { "actor": { "deleted": true, "email": "jane@example.com", "email_address": "jane@example.com", "name": "Jane Smith", "type": "user_actor", "user_id": "user_01AbCdEfGhIjKlMnOpQrSt" }, "amount": "41280.000000", "claude_tag_category": "dm", "claude_tag_user_id": "U0123ABCDEF", "context_window": "0-200k", "cost_type": "code_execution", "currency": "USD", "ending_at": "2019-12-27T18:11:19.117Z", "inference_geo": "global", "list_amount": "51600.000000", "model": "claude-opus-5-5", "product": "chat", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "requests": 128, "slack_channel_id": "C0123ABCDEF", "speed": "fast", "starting_at": "2019-12-27T18:11:19.117Z", "token_type": "cache_creation.ephemeral_1h_input_tokens" } ], "data_refreshed_at": "2019-12-27T18:11:19.117Z", "has_more": true, "next_page": "next_page", "organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF" } ``` ## Beta › Organization › Spend Limits ### Set Spend Limit `$ ant beta:organization:spend-limits set` **POST** `/v1/organizations/spend_limits` Set a spend limit. Upsert keyed on (scope, period): setting a limit that already exists overwrites it in place. A Claude Enterprise organization sets `user` limits. Its seat-tier, group, and organization-level defaults are configured in claude.ai. A Claude Console organization sets `organization` and `workspace` limits, which are monthly and always carry an amount. Setting those limits is in an early access preview. To request access, contact your Anthropic account team. #### Parameters - `--amount: string` Limit amount as a non-negative integer decimal string in the minor unit of the organization's billing currency (cents for USD): "50000" is $500.00. `null` sets an explicit no-limit override for this scope and `period` only — each period resolves independently, so caps for other periods still apply. - `--scope: BetaSpendLimitUserScope or BetaSpendLimitOrganizationScope or BetaSpendLimitWorkspaceScope` What the limit applies to. Claude Enterprise organizations set `user` limits. Claude Console organizations set `organization` and `workspace` limits. Any other combination returns 400. Setting `organization` and `workspace` limits through the API is in an early access preview. To request access, contact your Anthropic account team. - `--period: optional "daily" or "monthly" or "weekly"` - `--beta: optional array of AnthropicBeta` (header parameter) Optional header to specify the beta version(s) you want to use. #### Returns - `beta_spend_limit: object` A configured spend limit: a cap on metered spend for one scope and period. - `type: "spend_limit"` Object type. Always `spend_limit`. - `id: string` Unique tagged ID of the spend limit (`spl_...`). - `amount: string` Limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD): "50000" is $500.00. `null` means no numeric cap is configured at this scope — see the effective report for whether a limit applies. - `created_at: string` RFC 3339 datetime at which the spend limit was created. format: date-time - `currency: string` ISO 4217 code of the organization's billing currency; the unit for `amount`. - `is_enabled: boolean` Read-only. `false` when extra usage is switched off for this organization (`organization` limit); `amount` is kept and applies again when it's switched back on. Always `true` for other limits. - `period: "daily" or "monthly" or "weekly"` Length of the window the limit resets over. `amount` caps spend within each period. - `"daily"` - `"monthly"` - `"weekly"` - `scope: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` What the limit applies to. A tagged union on `type`; each variant carries the identifier for its scope. - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `type: "user"` Scope type. Always `user` for this scope. - `user_id: string` Tagged ID of the member the spend limit applies to. - `beta_spend_limit_seat_tier_scope: object` - `type: "seat_tier"` - `seat_tier: string` - `beta_spend_limit_rbac_group_scope: object` - `type: "rbac_group"` - `rbac_group_id: string` - `beta_spend_limit_organization_service_scope: object` - `type: "organization_service"` - `service: string` - `beta_spend_limit_organization_scope: object` - `type: "organization"` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `type: "workspace"` Scope type. Always `workspace` for this scope. - `workspace_id: string` Tagged ID of the workspace the spend limit applies to. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `type: "usage_tier"` Scope type. Always `usage_tier` for this scope. - `updated_at: string` RFC 3339 datetime at which the spend limit was last modified. format: date-time #### Example ```bash ant beta:organization:spend-limits set \ --api-key my-anthropic-api-key \ --amount 50000 \ --scope '{type: user, user_id: user_01WCz1FkmYMm4gnmykNKUu3Q}' ``` ##### Response (200) ```json { "id": "id", "amount": "50000", "created_at": "2019-12-27T18:11:19.117Z", "currency": "USD", "is_enabled": true, "period": "daily", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "type": "spend_limit", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### Get Spend Limit `$ ant beta:organization:spend-limits retrieve` **GET** `/v1/organizations/spend_limits/{spend_limit_id}` Retrieve a spend limit by ID. #### Parameters - `--spend-limit-id: string` (path parameter) ID of the Spend Limit. #### Returns - `beta_spend_limit: object` A configured spend limit: a cap on metered spend for one scope and period. - `type: "spend_limit"` Object type. Always `spend_limit`. - `id: string` Unique tagged ID of the spend limit (`spl_...`). - `amount: string` Limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD): "50000" is $500.00. `null` means no numeric cap is configured at this scope — see the effective report for whether a limit applies. - `created_at: string` RFC 3339 datetime at which the spend limit was created. format: date-time - `currency: string` ISO 4217 code of the organization's billing currency; the unit for `amount`. - `is_enabled: boolean` Read-only. `false` when extra usage is switched off for this organization (`organization` limit); `amount` is kept and applies again when it's switched back on. Always `true` for other limits. - `period: "daily" or "monthly" or "weekly"` Length of the window the limit resets over. `amount` caps spend within each period. - `"daily"` - `"monthly"` - `"weekly"` - `scope: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` What the limit applies to. A tagged union on `type`; each variant carries the identifier for its scope. - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `type: "user"` Scope type. Always `user` for this scope. - `user_id: string` Tagged ID of the member the spend limit applies to. - `beta_spend_limit_seat_tier_scope: object` - `type: "seat_tier"` - `seat_tier: string` - `beta_spend_limit_rbac_group_scope: object` - `type: "rbac_group"` - `rbac_group_id: string` - `beta_spend_limit_organization_service_scope: object` - `type: "organization_service"` - `service: string` - `beta_spend_limit_organization_scope: object` - `type: "organization"` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `type: "workspace"` Scope type. Always `workspace` for this scope. - `workspace_id: string` Tagged ID of the workspace the spend limit applies to. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `type: "usage_tier"` Scope type. Always `usage_tier` for this scope. - `updated_at: string` RFC 3339 datetime at which the spend limit was last modified. format: date-time #### Example ```bash ant beta:organization:spend-limits retrieve \ --api-key my-anthropic-api-key \ --spend-limit-id spend_limit_id ``` ##### Response (200) ```json { "id": "id", "amount": "50000", "created_at": "2019-12-27T18:11:19.117Z", "currency": "USD", "is_enabled": true, "period": "daily", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "type": "spend_limit", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ### Delete Spend Limit `$ ant beta:organization:spend-limits delete` **DELETE** `/v1/organizations/spend_limits/{spend_limit_id}` Delete a spend limit. For a Claude Enterprise organization, this deletes a per-user override, and the member falls back to any inherited spend limit at that period. Its seat-tier, group, and organization-level rows cannot be deleted via this endpoint. A Claude Console organization deletes its organization and workspace limits, but not its `usage_tier` limit. Deleting organization and workspace limits through the API is in an early access preview. #### Parameters - `--spend-limit-id: string` (path parameter) ID of the Spend Limit. #### Returns - `BetaOrganizationSpendLimitDeleteResponse: object` - `type: "spend_limit_deleted"` - `id: string` #### Example ```bash ant beta:organization:spend-limits delete \ --api-key my-anthropic-api-key \ --spend-limit-id spend_limit_id ``` ##### Response (200) ```json { "id": "id", "type": "spend_limit_deleted" } ``` ### List Spend Limits `$ ant beta:organization:spend-limits list` **GET** `/v1/organizations/spend_limits` List the organization's spend limits. Limits are grouped by scope type, in the order `organization`, `seat_tier`, `rbac_group`, `organization_service`, `user`; within a type they come in a fixed order that is not creation order. Supported for Claude Enterprise organizations only, not for Claude Console organizations. #### Parameters - `--limit: optional number` (query parameter) Maximum number of limits per page. Defaults to `20`. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--scope-type: optional array of "organization" or "organization_service" or "rbac_group" or 3 more` (query parameter) Return only limits with these scope types. Omit for all. maxItems: 100 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `spend-limit-reads-2026-09-26` in this header. #### Returns - `BetaListSpendLimitsResponse: object` - `data: array of BetaSpendLimit` - `type: "spend_limit"` Object type. Always `spend_limit`. - `id: string` Unique tagged ID of the spend limit (`spl_...`). - `amount: string` Limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD): "50000" is $500.00. `null` means no numeric cap is configured at this scope — see the effective report for whether a limit applies. - `created_at: string` RFC 3339 datetime at which the spend limit was created. format: date-time - `currency: string` ISO 4217 code of the organization's billing currency; the unit for `amount`. - `is_enabled: boolean` Read-only. `false` when extra usage is switched off for this organization (`organization` limit); `amount` is kept and applies again when it's switched back on. Always `true` for other limits. - `period: "daily" or "monthly" or "weekly"` Length of the window the limit resets over. `amount` caps spend within each period. - `"daily"` - `"monthly"` - `"weekly"` - `scope: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` What the limit applies to. A tagged union on `type`; each variant carries the identifier for its scope. - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `type: "user"` Scope type. Always `user` for this scope. - `user_id: string` Tagged ID of the member the spend limit applies to. - `beta_spend_limit_seat_tier_scope: object` - `type: "seat_tier"` - `seat_tier: string` - `beta_spend_limit_rbac_group_scope: object` - `type: "rbac_group"` - `rbac_group_id: string` - `beta_spend_limit_organization_service_scope: object` - `type: "organization_service"` - `service: string` - `beta_spend_limit_organization_scope: object` - `type: "organization"` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `type: "workspace"` Scope type. Always `workspace` for this scope. - `workspace_id: string` Tagged ID of the workspace the spend limit applies to. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `type: "usage_tier"` Scope type. Always `usage_tier` for this scope. - `updated_at: string` RFC 3339 datetime at which the spend limit was last modified. format: date-time - `next_page: string` #### Example ```bash ant beta:organization:spend-limits list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "id", "amount": "50000", "created_at": "2019-12-27T18:11:19.117Z", "currency": "USD", "is_enabled": true, "period": "daily", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "type": "spend_limit", "updated_at": "2019-12-27T18:11:19.117Z" } ], "next_page": "next_page" } ``` ## Beta › Organization › Spend Limits › Effective ### List Effective Spend Limits `$ ant beta:organization:spend-limits:effective list` **GET** `/v1/organizations/spend_limits/effective` List each member's effective spend limit and period-to-date spend. Returns one row per (member, period) the member resolves a spend limit for, with the `source` scope the spend limit was inherited from. Paginates by member, so a member's periods never split across pages. Supported for Claude Enterprise organizations only, not for Claude Console organizations. #### Parameters - `--limit: optional number` (query parameter) Maximum number of members per page. A member's period rows never split across pages, so a page may carry more rows than this. Defaults to `20`. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page` field. - `--period: optional array of "daily" or "monthly" or "weekly"` (query parameter) Restrict the report to these limit periods. Omit to return one row per period each member resolves a spend limit for. maxItems: 3 - `--user-id: optional array of string` (query parameter) Restrict the report to these members, by tagged user ID (`user_...`). At most 100 entries. maxItems: 100 #### Returns - `BetaListEffectiveSpendLimitsResponse: object` - `data: array of BetaSpendSummary` - `actor: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `type: "user_actor"` Actor type. Always `user_actor`. - `deleted: boolean` True only when the underlying account has been deleted. - `email_address: string` The user's email address. Null when the account is unavailable or has been deleted. - `name: string` The user's current display name. Null when the account is unavailable, has been deleted, or has no name set. - `user_id: string` Tagged ID of the user. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `type: "scoped_api_key_actor"` - `scoped_api_key_id: string` - `amount: string` Effective limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD). `null` means no limit applies for this row's `period` — each period resolves independently, so another period may still cap this member. - `currency: string` ISO 4217 code of the organization's billing currency; the unit for `amount` and `period_to_date_spend`. - `period: "daily" or "monthly" or "weekly"` Period this row's effective limit and spend are reported for. - `"daily"` - `"monthly"` - `"weekly"` - `period_to_date_spend: string` The member's spend so far in the current period, as a non-negative decimal string in the minor unit of `currency` (cents for USD). May carry fractional minor units up to three decimal places (e.g. `"12050.5"`) — metered usage is not rounded to whole cents. Reads as `"0"` when the spend reading is temporarily unavailable. - `scope: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `type: "user"` Scope type. Always `user` for this scope. - `user_id: string` Tagged ID of the member the spend limit applies to. - `beta_spend_limit_seat_tier_scope: object` - `type: "seat_tier"` - `seat_tier: string` - `beta_spend_limit_rbac_group_scope: object` - `type: "rbac_group"` - `rbac_group_id: string` - `beta_spend_limit_organization_service_scope: object` - `type: "organization_service"` - `service: string` - `beta_spend_limit_organization_scope: object` - `type: "organization"` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `type: "workspace"` Scope type. Always `workspace` for this scope. - `workspace_id: string` Tagged ID of the workspace the spend limit applies to. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `type: "usage_tier"` Scope type. Always `usage_tier` for this scope. - `source: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `beta_spend_limit_seat_tier_scope: object` - `beta_spend_limit_rbac_group_scope: object` - `beta_spend_limit_organization_service_scope: object` - `beta_spend_limit_organization_scope: object` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `spend_limit_id: string` - `next_page: string` #### Example ```bash ant beta:organization:spend-limits:effective list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "amount": "50000", "currency": "USD", "period": "daily", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "source": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_limit_id": "spend_limit_id" } ], "next_page": "next_page" } ``` ## Beta › Organization › Spend Limits › Increase Requests ### List Spend Limit Increase Requests `$ ant beta:organization:spend-limits:increase-requests list` **GET** `/v1/organizations/spend_limit_increase_requests` List spend limit increase requests, most recent first. Pending requests include a live `spend_summary` for the requester. Requests whose requester is no longer a member are excluded. #### Parameters - `--actor-id: optional array of string` (query parameter) Filter by requester, as `user_...` tagged IDs. - `--limit: optional number` (query parameter) minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. - `--status: optional array of BetaSpendLimitIncreaseRequestStatus` (query parameter) Filter by status. Omit to return all. #### Returns - `BetaSpendLimitIncreaseRequestListResponse: object` - `data: array of BetaSpendLimitIncreaseRequest` - `type: "spend_limit_increase_request"` - `id: string` - `actor: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `type: "user_actor"` Actor type. Always `user_actor`. - `deleted: boolean` True only when the underlying account has been deleted. - `email_address: string` The user's email address. Null when the account is unavailable or has been deleted. - `name: string` The user's current display name. Null when the account is unavailable, has been deleted, or has no name set. - `user_id: string` Tagged ID of the user. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `type: "scoped_api_key_actor"` - `scoped_api_key_id: string` - `created_at: string` format: date-time - `period: "daily" or "monthly" or "weekly"` - `"daily"` - `"monthly"` - `"weekly"` - `resolved_at: string` format: date-time - `resolved_by: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `spend_summary: object` Per-member effective-limit report row (`GET /spend_limits/effective`). - `actor: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `amount: string` Effective limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD). `null` means no limit applies for this row's `period` — each period resolves independently, so another period may still cap this member. - `currency: string` ISO 4217 code of the organization's billing currency; the unit for `amount` and `period_to_date_spend`. - `period: "daily" or "monthly" or "weekly"` Period this row's effective limit and spend are reported for. - `"daily"` - `"monthly"` - `"weekly"` - `period_to_date_spend: string` The member's spend so far in the current period, as a non-negative decimal string in the minor unit of `currency` (cents for USD). May carry fractional minor units up to three decimal places (e.g. `"12050.5"`) — metered usage is not rounded to whole cents. Reads as `"0"` when the spend reading is temporarily unavailable. - `scope: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `type: "user"` Scope type. Always `user` for this scope. - `user_id: string` Tagged ID of the member the spend limit applies to. - `beta_spend_limit_seat_tier_scope: object` - `type: "seat_tier"` - `seat_tier: string` - `beta_spend_limit_rbac_group_scope: object` - `type: "rbac_group"` - `rbac_group_id: string` - `beta_spend_limit_organization_service_scope: object` - `type: "organization_service"` - `service: string` - `beta_spend_limit_organization_scope: object` - `type: "organization"` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `type: "workspace"` Scope type. Always `workspace` for this scope. - `workspace_id: string` Tagged ID of the workspace the spend limit applies to. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `type: "usage_tier"` Scope type. Always `usage_tier` for this scope. - `source: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `beta_spend_limit_seat_tier_scope: object` - `beta_spend_limit_rbac_group_scope: object` - `beta_spend_limit_organization_service_scope: object` - `beta_spend_limit_organization_scope: object` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `spend_limit_id: string` - `status: "approved" or "denied" or "pending"` - `"approved"` - `"denied"` - `"pending"` - `next_page: string` #### Example ```bash ant beta:organization:spend-limits:increase-requests list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "id", "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "created_at": "2019-12-27T18:11:19.117Z", "period": "daily", "resolved_at": "2019-12-27T18:11:19.117Z", "resolved_by": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_summary": { "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "amount": "50000", "currency": "USD", "period": "daily", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "source": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_limit_id": "spend_limit_id" }, "status": "approved", "type": "spend_limit_increase_request" } ], "next_page": "next_page" } ``` ### Get Spend Limit Increase Request `$ ant beta:organization:spend-limits:increase-requests retrieve` **GET** `/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}` Retrieve a spend limit increase request. While `pending`, the response includes a live `spend_summary` for the requester at the request's period. #### Parameters - `--spend-limit-increase-request-id: string` (path parameter) ID of the spend limit increase request. #### Returns - `beta_spend_limit_increase_request: object` - `type: "spend_limit_increase_request"` - `id: string` - `actor: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `type: "user_actor"` Actor type. Always `user_actor`. - `deleted: boolean` True only when the underlying account has been deleted. - `email_address: string` The user's email address. Null when the account is unavailable or has been deleted. - `name: string` The user's current display name. Null when the account is unavailable, has been deleted, or has no name set. - `user_id: string` Tagged ID of the user. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `type: "scoped_api_key_actor"` - `scoped_api_key_id: string` - `created_at: string` format: date-time - `period: "daily" or "monthly" or "weekly"` - `"daily"` - `"monthly"` - `"weekly"` - `resolved_at: string` format: date-time - `resolved_by: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `spend_summary: object` Per-member effective-limit report row (`GET /spend_limits/effective`). - `actor: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `amount: string` Effective limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD). `null` means no limit applies for this row's `period` — each period resolves independently, so another period may still cap this member. - `currency: string` ISO 4217 code of the organization's billing currency; the unit for `amount` and `period_to_date_spend`. - `period: "daily" or "monthly" or "weekly"` Period this row's effective limit and spend are reported for. - `"daily"` - `"monthly"` - `"weekly"` - `period_to_date_spend: string` The member's spend so far in the current period, as a non-negative decimal string in the minor unit of `currency` (cents for USD). May carry fractional minor units up to three decimal places (e.g. `"12050.5"`) — metered usage is not rounded to whole cents. Reads as `"0"` when the spend reading is temporarily unavailable. - `scope: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `type: "user"` Scope type. Always `user` for this scope. - `user_id: string` Tagged ID of the member the spend limit applies to. - `beta_spend_limit_seat_tier_scope: object` - `type: "seat_tier"` - `seat_tier: string` - `beta_spend_limit_rbac_group_scope: object` - `type: "rbac_group"` - `rbac_group_id: string` - `beta_spend_limit_organization_service_scope: object` - `type: "organization_service"` - `service: string` - `beta_spend_limit_organization_scope: object` - `type: "organization"` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `type: "workspace"` Scope type. Always `workspace` for this scope. - `workspace_id: string` Tagged ID of the workspace the spend limit applies to. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `type: "usage_tier"` Scope type. Always `usage_tier` for this scope. - `source: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `beta_spend_limit_seat_tier_scope: object` - `beta_spend_limit_rbac_group_scope: object` - `beta_spend_limit_organization_service_scope: object` - `beta_spend_limit_organization_scope: object` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `spend_limit_id: string` - `status: "approved" or "denied" or "pending"` - `"approved"` - `"denied"` - `"pending"` #### Example ```bash ant beta:organization:spend-limits:increase-requests retrieve \ --api-key my-anthropic-api-key \ --spend-limit-increase-request-id spend_limit_increase_request_id ``` ##### Response (200) ```json { "id": "id", "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "created_at": "2019-12-27T18:11:19.117Z", "period": "daily", "resolved_at": "2019-12-27T18:11:19.117Z", "resolved_by": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_summary": { "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "amount": "50000", "currency": "USD", "period": "daily", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "source": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_limit_id": "spend_limit_id" }, "status": "approved", "type": "spend_limit_increase_request" } ``` ### Approve Spend Limit Increase Request `$ ant beta:organization:spend-limits:increase-requests approve` **POST** `/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}/approve` Approve a pending spend limit increase request. Writes a per-user spend limit at `amount` for the requester and transitions the request to `approved`. `period` defaults to the period the member was blocked on. Anthropic emails the requester unless `suppress_notification` is set. #### Parameters - `--spend-limit-increase-request-id: string` (path parameter) ID of the spend limit increase request. - `--amount: string` New per-user spend limit as a non-negative integer decimal string (minor units). - `--period: optional "daily" or "monthly" or "weekly"` - `--suppress-notification: optional boolean` #### Returns - `BetaOrganizationSpendLimitIncreaseRequestApproveResponse: object` - `type: "spend_limit_increase_request"` - `id: string` - `actor: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `type: "user_actor"` Actor type. Always `user_actor`. - `deleted: boolean` True only when the underlying account has been deleted. - `email_address: string` The user's email address. Null when the account is unavailable or has been deleted. - `name: string` The user's current display name. Null when the account is unavailable, has been deleted, or has no name set. - `user_id: string` Tagged ID of the user. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `type: "scoped_api_key_actor"` - `scoped_api_key_id: string` - `created_at: string` format: date-time - `period: "daily" or "monthly" or "weekly"` - `"daily"` - `"monthly"` - `"weekly"` - `resolved_at: string` format: date-time - `resolved_by: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `spend_limit: object` A configured spend limit: a cap on metered spend for one scope and period. - `type: "spend_limit"` Object type. Always `spend_limit`. - `id: string` Unique tagged ID of the spend limit (`spl_...`). - `amount: string` Limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD): "50000" is $500.00. `null` means no numeric cap is configured at this scope — see the effective report for whether a limit applies. - `created_at: string` RFC 3339 datetime at which the spend limit was created. format: date-time - `currency: string` ISO 4217 code of the organization's billing currency; the unit for `amount`. - `is_enabled: boolean` Read-only. `false` when extra usage is switched off for this organization (`organization` limit); `amount` is kept and applies again when it's switched back on. Always `true` for other limits. - `period: "daily" or "monthly" or "weekly"` Length of the window the limit resets over. `amount` caps spend within each period. - `"daily"` - `"monthly"` - `"weekly"` - `scope: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` What the limit applies to. A tagged union on `type`; each variant carries the identifier for its scope. - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `type: "user"` Scope type. Always `user` for this scope. - `user_id: string` Tagged ID of the member the spend limit applies to. - `beta_spend_limit_seat_tier_scope: object` - `type: "seat_tier"` - `seat_tier: string` - `beta_spend_limit_rbac_group_scope: object` - `type: "rbac_group"` - `rbac_group_id: string` - `beta_spend_limit_organization_service_scope: object` - `type: "organization_service"` - `service: string` - `beta_spend_limit_organization_scope: object` - `type: "organization"` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `type: "workspace"` Scope type. Always `workspace` for this scope. - `workspace_id: string` Tagged ID of the workspace the spend limit applies to. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `type: "usage_tier"` Scope type. Always `usage_tier` for this scope. - `updated_at: string` RFC 3339 datetime at which the spend limit was last modified. format: date-time - `spend_summary: object` Per-member effective-limit report row (`GET /spend_limits/effective`). - `actor: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `amount: string` Effective limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD). `null` means no limit applies for this row's `period` — each period resolves independently, so another period may still cap this member. - `currency: string` ISO 4217 code of the organization's billing currency; the unit for `amount` and `period_to_date_spend`. - `period: "daily" or "monthly" or "weekly"` Period this row's effective limit and spend are reported for. - `"daily"` - `"monthly"` - `"weekly"` - `period_to_date_spend: string` The member's spend so far in the current period, as a non-negative decimal string in the minor unit of `currency` (cents for USD). May carry fractional minor units up to three decimal places (e.g. `"12050.5"`) — metered usage is not rounded to whole cents. Reads as `"0"` when the spend reading is temporarily unavailable. - `scope: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `beta_spend_limit_seat_tier_scope: object` - `beta_spend_limit_rbac_group_scope: object` - `beta_spend_limit_organization_service_scope: object` - `beta_spend_limit_organization_scope: object` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `source: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `beta_spend_limit_seat_tier_scope: object` - `beta_spend_limit_rbac_group_scope: object` - `beta_spend_limit_organization_service_scope: object` - `beta_spend_limit_organization_scope: object` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `spend_limit_id: string` - `status: "approved" or "denied" or "pending"` - `"approved"` - `"denied"` - `"pending"` #### Example ```bash ant beta:organization:spend-limits:increase-requests approve \ --api-key my-anthropic-api-key \ --spend-limit-increase-request-id spend_limit_increase_request_id \ --amount 50000 ``` ##### Response (200) ```json { "id": "id", "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "created_at": "2019-12-27T18:11:19.117Z", "period": "daily", "resolved_at": "2019-12-27T18:11:19.117Z", "resolved_by": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_limit": { "id": "id", "amount": "50000", "created_at": "2019-12-27T18:11:19.117Z", "currency": "USD", "is_enabled": true, "period": "daily", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "type": "spend_limit", "updated_at": "2019-12-27T18:11:19.117Z" }, "spend_summary": { "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "amount": "50000", "currency": "USD", "period": "daily", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "source": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_limit_id": "spend_limit_id" }, "status": "approved", "type": "spend_limit_increase_request" } ``` ### Deny Spend Limit Increase Request `$ ant beta:organization:spend-limits:increase-requests deny` **POST** `/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}/deny` Deny a pending spend limit increase request. Idempotent on `denied`; denying an already-`approved` request returns 400. Anthropic emails the requester unless `suppress_notification` is set. #### Parameters - `--spend-limit-increase-request-id: string` (path parameter) ID of the spend limit increase request. - `--suppress-notification: optional boolean` #### Returns - `beta_spend_limit_increase_request: object` - `type: "spend_limit_increase_request"` - `id: string` - `actor: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `type: "user_actor"` Actor type. Always `user_actor`. - `deleted: boolean` True only when the underlying account has been deleted. - `email_address: string` The user's email address. Null when the account is unavailable or has been deleted. - `name: string` The user's current display name. Null when the account is unavailable, has been deleted, or has no name set. - `user_id: string` Tagged ID of the user. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `type: "scoped_api_key_actor"` - `scoped_api_key_id: string` - `created_at: string` format: date-time - `period: "daily" or "monthly" or "weekly"` - `"daily"` - `"monthly"` - `"weekly"` - `resolved_at: string` format: date-time - `resolved_by: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `spend_summary: object` Per-member effective-limit report row (`GET /spend_limits/effective`). - `actor: BetaSpendLimitUserActor or BetaSpendLimitScopedAPIKeyActor` - `beta_spend_limit_user_actor: object` A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts. - `beta_spend_limit_scoped_api_key_actor: object` A scoped Admin API key acting on behalf of the organization. - `amount: string` Effective limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD). `null` means no limit applies for this row's `period` — each period resolves independently, so another period may still cap this member. - `currency: string` ISO 4217 code of the organization's billing currency; the unit for `amount` and `period_to_date_spend`. - `period: "daily" or "monthly" or "weekly"` Period this row's effective limit and spend are reported for. - `"daily"` - `"monthly"` - `"weekly"` - `period_to_date_spend: string` The member's spend so far in the current period, as a non-negative decimal string in the minor unit of `currency` (cents for USD). May carry fractional minor units up to three decimal places (e.g. `"12050.5"`) — metered usage is not rounded to whole cents. Reads as `"0"` when the spend reading is temporarily unavailable. - `scope: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `type: "user"` Scope type. Always `user` for this scope. - `user_id: string` Tagged ID of the member the spend limit applies to. - `beta_spend_limit_seat_tier_scope: object` - `type: "seat_tier"` - `seat_tier: string` - `beta_spend_limit_rbac_group_scope: object` - `type: "rbac_group"` - `rbac_group_id: string` - `beta_spend_limit_organization_service_scope: object` - `type: "organization_service"` - `service: string` - `beta_spend_limit_organization_scope: object` - `type: "organization"` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `type: "workspace"` Scope type. Always `workspace` for this scope. - `workspace_id: string` Tagged ID of the workspace the spend limit applies to. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `type: "usage_tier"` Scope type. Always `usage_tier` for this scope. - `source: BetaSpendLimitUserScope or BetaSpendLimitSeatTierScope or BetaSpendLimitRBACGroupScope or 4 more` - `beta_spend_limit_user_scope: object` Scope selecting a single member of the organization. - `beta_spend_limit_seat_tier_scope: object` - `beta_spend_limit_rbac_group_scope: object` - `beta_spend_limit_organization_service_scope: object` - `beta_spend_limit_organization_scope: object` - `beta_spend_limit_workspace_scope: object` Scope selecting one workspace of a Claude Console organization. - `beta_spend_limit_usage_tier_scope: object` Scope of the monthly spend cap Anthropic sets for a Claude Console organization from its usage tier, or a higher cap Anthropic granted the organization. Read-only; its `created_at` and `updated_at` are the organization's creation time, so `amount` can change while `updated_at` stays the same. - `spend_limit_id: string` - `status: "approved" or "denied" or "pending"` - `"approved"` - `"denied"` - `"pending"` #### Example ```bash ant beta:organization:spend-limits:increase-requests deny \ --api-key my-anthropic-api-key \ --spend-limit-increase-request-id spend_limit_increase_request_id ``` ##### Response (200) ```json { "id": "id", "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "created_at": "2019-12-27T18:11:19.117Z", "period": "daily", "resolved_at": "2019-12-27T18:11:19.117Z", "resolved_by": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_summary": { "actor": { "deleted": true, "email_address": "email_address", "name": "name", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "amount": "50000", "currency": "USD", "period": "daily", "period_to_date_spend": "12050.5", "scope": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "source": { "type": "user", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "spend_limit_id": "spend_limit_id" }, "status": "approved", "type": "spend_limit_increase_request" } ``` ## Beta › Organization › RBAC Groups ### Create RBAC Group `$ ant beta:organization:rbac-groups create` **POST** `/v1/organizations/rbac_groups` Create an RBAC Group in the Claude Enterprise tenant. Groups created via the API have source type `"direct"`. The RBAC Groups API is available to Claude Enterprise organizations only. #### Parameters - `--name: string` Name of the RBAC Group. Not uniqueness-enforced. minLength: 1, maxLength: 255 #### Returns - `beta_rbac_group: object` - `type: "rbac_group"` Object type. For RBAC Groups, this is always `"rbac_group"`. - `id: string` ID of the RBAC Group. - `created_at: string` RFC 3339 timestamp of when the RBAC Group was created. format: date-time - `name: string` Name of the RBAC Group. Not uniqueness-enforced. - `role_ids: array of string` RBAC Role IDs attached to this RBAC Group. Role attachment is managed in the admin settings and is read-only on this API. `null` means role data was temporarily unavailable — retry to distinguish from an empty list. - `source_type: "direct" or "scim"` How the RBAC Group was created: `"direct"` for groups created directly (for example, in the organization's admin settings), `"scim"` for groups provisioned by the identity provider. - `"direct"` - `"scim"` - `updated_at: string` RFC 3339 timestamp of when the RBAC Group was last updated. format: date-time #### Example ```bash ant beta:organization:rbac-groups create \ --api-key my-anthropic-api-key \ --name Engineering ``` ##### Response (200) ```json { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "created_at": "2024-10-30T23:58:27.427722Z", "name": "Engineering", "role_ids": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "roles": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "source_type": "direct", "type": "rbac_group", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### List RBAC Groups `$ ant beta:organization:rbac-groups list` **GET** `/v1/organizations/rbac_groups` List RBAC Groups in the Claude Enterprise tenant. The RBAC Groups API is available to Claude Enterprise organizations only. #### Parameters - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. #### Returns - `BetaRbacGroupList: object` - `data: array of BetaRBACGroup` - `type: "rbac_group"` Object type. For RBAC Groups, this is always `"rbac_group"`. - `id: string` ID of the RBAC Group. - `created_at: string` RFC 3339 timestamp of when the RBAC Group was created. format: date-time - `name: string` Name of the RBAC Group. Not uniqueness-enforced. - `role_ids: array of string` RBAC Role IDs attached to this RBAC Group. Role attachment is managed in the admin settings and is read-only on this API. `null` means role data was temporarily unavailable — retry to distinguish from an empty list. - `source_type: "direct" or "scim"` How the RBAC Group was created: `"direct"` for groups created directly (for example, in the organization's admin settings), `"scim"` for groups provisioned by the identity provider. - `"direct"` - `"scim"` - `updated_at: string` RFC 3339 timestamp of when the RBAC Group was last updated. format: date-time - `has_more: boolean` Indicates if there are more results in the requested page direction. - `next_page: string` Token to provide in as `page` in the subsequent request to retrieve the next page of data. #### Example ```bash ant beta:organization:rbac-groups list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "created_at": "2024-10-30T23:58:27.427722Z", "name": "Engineering", "role_ids": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "roles": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "source_type": "direct", "type": "rbac_group", "updated_at": "2024-10-30T23:58:27.427722Z" } ], "has_more": false, "next_page": "eyJjdXJzb3IiOiAicmJhY19ncm91cF8wMSJ9" } ``` ### Get RBAC Group `$ ant beta:organization:rbac-groups retrieve` **GET** `/v1/organizations/rbac_groups/{rbac_group_id}` Retrieve an RBAC Group by ID. The RBAC Groups API is available to Claude Enterprise organizations only. #### Parameters - `--rbac-group-id: string` (path parameter) ID of the RBAC Group. #### Returns - `beta_rbac_group: object` - `type: "rbac_group"` Object type. For RBAC Groups, this is always `"rbac_group"`. - `id: string` ID of the RBAC Group. - `created_at: string` RFC 3339 timestamp of when the RBAC Group was created. format: date-time - `name: string` Name of the RBAC Group. Not uniqueness-enforced. - `role_ids: array of string` RBAC Role IDs attached to this RBAC Group. Role attachment is managed in the admin settings and is read-only on this API. `null` means role data was temporarily unavailable — retry to distinguish from an empty list. - `source_type: "direct" or "scim"` How the RBAC Group was created: `"direct"` for groups created directly (for example, in the organization's admin settings), `"scim"` for groups provisioned by the identity provider. - `"direct"` - `"scim"` - `updated_at: string` RFC 3339 timestamp of when the RBAC Group was last updated. format: date-time #### Example ```bash ant beta:organization:rbac-groups retrieve \ --api-key my-anthropic-api-key \ --rbac-group-id rbac_group_id ``` ##### Response (200) ```json { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "created_at": "2024-10-30T23:58:27.427722Z", "name": "Engineering", "role_ids": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "roles": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "source_type": "direct", "type": "rbac_group", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### Update RBAC Group `$ ant beta:organization:rbac-groups update` **POST** `/v1/organizations/rbac_groups/{rbac_group_id}` Update an RBAC Group's name. Groups provisioned by an identity provider (source type `"scim"`) cannot be modified via the API while an organization in the tenant uses SCIM provisioning. The RBAC Groups API is available to Claude Enterprise organizations only. #### Parameters - `--rbac-group-id: string` (path parameter) ID of the RBAC Group. - `--name: optional string` Name of the RBAC Group. Not uniqueness-enforced. minLength: 1, maxLength: 255 #### Returns - `beta_rbac_group: object` - `type: "rbac_group"` Object type. For RBAC Groups, this is always `"rbac_group"`. - `id: string` ID of the RBAC Group. - `created_at: string` RFC 3339 timestamp of when the RBAC Group was created. format: date-time - `name: string` Name of the RBAC Group. Not uniqueness-enforced. - `role_ids: array of string` RBAC Role IDs attached to this RBAC Group. Role attachment is managed in the admin settings and is read-only on this API. `null` means role data was temporarily unavailable — retry to distinguish from an empty list. - `source_type: "direct" or "scim"` How the RBAC Group was created: `"direct"` for groups created directly (for example, in the organization's admin settings), `"scim"` for groups provisioned by the identity provider. - `"direct"` - `"scim"` - `updated_at: string` RFC 3339 timestamp of when the RBAC Group was last updated. format: date-time #### Example ```bash ant beta:organization:rbac-groups update \ --api-key my-anthropic-api-key \ --rbac-group-id rbac_group_id ``` ##### Response (200) ```json { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "created_at": "2024-10-30T23:58:27.427722Z", "name": "Engineering", "role_ids": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "roles": [ "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s" ], "source_type": "direct", "type": "rbac_group", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ### Delete RBAC Group `$ ant beta:organization:rbac-groups delete` **DELETE** `/v1/organizations/rbac_groups/{rbac_group_id}` Delete an RBAC Group. Groups provisioned by an identity provider (source type `"scim"`) cannot be deleted via the API while an organization in the tenant uses SCIM provisioning. The RBAC Groups API is available to Claude Enterprise organizations only. #### Parameters - `--rbac-group-id: string` (path parameter) ID of the RBAC Group. #### Returns - `BetaOrganizationRBACGroupDeleteResponse: object` - `type: "rbac_group_deleted"` Deleted object type. For RBAC Groups, this is always `"rbac_group_deleted"`. - `id: string` ID of the RBAC Group. #### Example ```bash ant beta:organization:rbac-groups delete \ --api-key my-anthropic-api-key \ --rbac-group-id rbac_group_id ``` ##### Response (200) ```json { "id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_deleted" } ``` ## Beta › Organization › RBAC Groups › Members ### List RBAC Group Members `$ ant beta:organization:rbac-groups:members list` **GET** `/v1/organizations/rbac_groups/{rbac_group_id}/members` List members of an RBAC Group. The RBAC Groups API is available to Claude Enterprise organizations only. #### Parameters - `--rbac-group-id: string` (path parameter) ID of the RBAC Group. - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. #### Returns - `BetaRbacGroupMemberList: object` - `data: array of BetaRBACGroupMember` - `type: "rbac_group_member"` Object type. For RBAC Group Members, this is always `"rbac_group_member"`. - `created_at: string` RFC 3339 timestamp of when the User was added to the RBAC Group. format: date-time - `email: string` Email of the User. - `rbac_group_id: string` ID of the RBAC Group. - `user_id: string` ID of the User. - `has_more: boolean` Indicates if there are more results in the requested page direction. - `next_page: string` Token to provide in as `page` in the subsequent request to retrieve the next page of data. #### Example ```bash ant beta:organization:rbac-groups:members list \ --api-key my-anthropic-api-key \ --rbac-group-id rbac_group_id ``` ##### Response (200) ```json { "data": [ { "created_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_member", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" } ], "has_more": false, "next_page": "eyJjdXJzb3IiOiAicmJhY19ncm91cF8wMSJ9" } ``` ### Add RBAC Group Member `$ ant beta:organization:rbac-groups:members add` **POST** `/v1/organizations/rbac_groups/{rbac_group_id}/members` Add a User to an RBAC Group. Membership of groups provisioned by an identity provider (source type `"scim"`) cannot be modified via the API while an organization in the tenant uses SCIM provisioning. The RBAC Groups API is available to Claude Enterprise organizations only. #### Parameters - `--rbac-group-id: string` (path parameter) ID of the RBAC Group. - `--user-id: string` ID of the User. #### Returns - `beta_rbac_group_member: object` - `type: "rbac_group_member"` Object type. For RBAC Group Members, this is always `"rbac_group_member"`. - `created_at: string` RFC 3339 timestamp of when the User was added to the RBAC Group. format: date-time - `email: string` Email of the User. - `rbac_group_id: string` ID of the RBAC Group. - `user_id: string` ID of the User. #### Example ```bash ant beta:organization:rbac-groups:members add \ --api-key my-anthropic-api-key \ --rbac-group-id rbac_group_id \ --user-id user_01WCz1FkmYMm4gnmykNKUu3Q ``` ##### Response (200) ```json { "created_at": "2024-10-30T23:58:27.427722Z", "email": "user@emaildomain.com", "group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_member", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" } ``` ### Remove RBAC Group Member `$ ant beta:organization:rbac-groups:members remove` **DELETE** `/v1/organizations/rbac_groups/{rbac_group_id}/members/{user_id}` Remove a User from an RBAC Group. Membership of groups provisioned by an identity provider (source type `"scim"`) cannot be modified via the API while an organization in the tenant uses SCIM provisioning. The RBAC Groups API is available to Claude Enterprise organizations only. #### Parameters - `--rbac-group-id: string` (path parameter) ID of the RBAC Group. - `--user-id: string` (path parameter) ID of the User. #### Returns - `BetaOrganizationRBACGroupMemberRemoveResponse: object` - `type: "rbac_group_member_deleted"` Deleted object type. For RBAC Group Members, this is always `"rbac_group_member_deleted"`. - `rbac_group_id: string` ID of the RBAC Group. - `user_id: string` ID of the User. #### Example ```bash ant beta:organization:rbac-groups:members remove \ --api-key my-anthropic-api-key \ --rbac-group-id rbac_group_id \ --user-id user_id ``` ##### Response (200) ```json { "group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group_member_deleted", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" } ``` ## Beta › Organization › RBAC Roles ### List RBAC Roles `$ ant beta:organization:rbac-roles list` **GET** `/v1/organizations/rbac_roles` List RBAC Roles in the organization. The RBAC Roles API is available to Claude Enterprise organizations only. #### Parameters - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. #### Returns - `BetaRbacRoleList: object` - `data: array of BetaRBACRole` - `type: "rbac_role"` Object type. For RBAC Roles, this is always `"rbac_role"`. - `id: string` ID of the RBAC Role. - `created_at: string` RFC 3339 datetime string indicating when the RBAC Role was created. format: date-time - `display_name: string` Name of the RBAC Role. For a role created by Anthropic, this name can differ from the label claude.ai shows, and Anthropic may change the name. To keep a lasting reference to a role, store its `id`. - `updated_at: string` RFC 3339 datetime string indicating when the RBAC Role was last updated. format: date-time - `name: string` **Deprecated**: Use `display_name` instead; `name` always has the same value. Deprecated: use `display_name` instead. Name of the RBAC Role; always the same value as `display_name`. - `has_more: boolean` Indicates whether there are more results beyond this page. - `next_page: string` Opaque cursor for the next page. Pass as the `page` parameter on the next request. #### Example ```bash ant beta:organization:rbac-roles list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s", "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "Project Editor", "name": "Project Editor", "type": "rbac_role", "updated_at": "2024-10-30T23:58:27.427722Z" } ], "has_more": true, "next_page": "eyJjdXJzb3IiOiAicmJhY19yb2xlXzAxIn0" } ``` ### Get RBAC Role `$ ant beta:organization:rbac-roles retrieve` **GET** `/v1/organizations/rbac_roles/{rbac_role_id}` Retrieve an RBAC Role by ID. The RBAC Roles API is available to Claude Enterprise organizations only. #### Parameters - `--rbac-role-id: string` (path parameter) ID of the RBAC Role. #### Returns - `beta_rbac_role: object` - `type: "rbac_role"` Object type. For RBAC Roles, this is always `"rbac_role"`. - `id: string` ID of the RBAC Role. - `created_at: string` RFC 3339 datetime string indicating when the RBAC Role was created. format: date-time - `display_name: string` Name of the RBAC Role. For a role created by Anthropic, this name can differ from the label claude.ai shows, and Anthropic may change the name. To keep a lasting reference to a role, store its `id`. - `updated_at: string` RFC 3339 datetime string indicating when the RBAC Role was last updated. format: date-time - `name: string` **Deprecated**: Use `display_name` instead; `name` always has the same value. Deprecated: use `display_name` instead. Name of the RBAC Role; always the same value as `display_name`. #### Example ```bash ant beta:organization:rbac-roles retrieve \ --api-key my-anthropic-api-key \ --rbac-role-id rbac_role_id ``` ##### Response (200) ```json { "id": "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s", "created_at": "2024-10-30T23:58:27.427722Z", "display_name": "Project Editor", "name": "Project Editor", "type": "rbac_role", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ## Beta › Organization › RBAC Roles › Permissions ### List RBAC Role Permissions `$ ant beta:organization:rbac-roles:permissions list` **GET** `/v1/organizations/rbac_roles/{rbac_role_id}/permissions` List the permissions an RBAC Role grants. The RBAC Roles API is available to Claude Enterprise organizations only. #### Parameters - `--rbac-role-id: string` (path parameter) ID of the RBAC Role. - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--page: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. #### Returns - `BetaRbacRolePermissionList: object` - `data: array of BetaRBACRolePermission` - `type: "rbac_role_permission"` Object type. For RBAC Role Permissions, this is always `"rbac_role_permission"`. - `action: string` Action the permission grants on the resource. The vocabulary follows the resource: an `organization` grant carries a product-feature entitlement (for example `chat`), an admin-panel permission entitlement (`permission_*`), or a blanket capability-access mode — `capability_access_all` grants every product-feature entitlement, and `capability_access_all_ga` grants the generally-available subset as it stands at permission-check time; neither mode grants model-access entitlements. A consumer enumerating a role's per-feature grants should treat a blanket row as granting every product-feature entitlement it covers, or it will under-report the role's effective access. A `connector_tool` grant carries a tool-access action (`use` or `always_allow`); a `connector_scope` grant carries the scope action `grant` (the role may receive the named OAuth scope when tokens are minted for the connector); `connector` and `all_connectors` grants carry a tool-access action, the scope action, or an authentication-method action (`interactive` or `managed`). - `resource: BetaRBACOrganizationPermissionResource or BetaRBACConnectorToolPermissionResource or BetaRBACConnectorScopePermissionResource or 2 more` What the permission applies to. A tagged union: `type` names the kind of resource and determines which identifier fields are present. - `beta_rbac_organization_permission_resource: object` - `type: "organization"` Kind of resource the permission applies to. - `organization_id: string` UUID of the organization the permission applies to. - `beta_rbac_connector_tool_permission_resource: object` - `type: "connector_tool"` Kind of resource the permission applies to. - `connector_id: string` ID of the connector the permission applies to. - `tool_name: string` Published name of the connector tool the permission applies to. When the published name contains characters outside `[a-zA-Z0-9_-]` (or collides with a reserved form), it is server-encoded into a stable `{prefix}_{32-hex}` form — a shortened readable prefix of the name plus a hash — from which the published name is not recoverable. - `beta_rbac_connector_scope_permission_resource: object` - `type: "connector_scope"` Kind of resource the permission applies to. - `connector_id: string` ID of the connector the permission applies to. - `scope: string` OAuth scope the permission names — the role may receive this scope when tokens are minted for the connector. Subject to the same encoding rule as `tool_name`: a scope containing characters outside `[a-zA-Z0-9_-]` (or colliding with a reserved form) appears server-encoded in a stable `{prefix}_{32-hex}` form. OAuth scopes routinely contain `:` and `/`, so most appear encoded. - `beta_rbac_connector_permission_resource: object` - `type: "connector"` Kind of resource the permission applies to. - `connector_id: string` ID of the connector the permission applies to. - `beta_rbac_all_connectors_permission_resource: object` - `type: "all_connectors"` Kind of resource the permission applies to. - `has_more: boolean` Indicates whether there are more results beyond this page. - `next_page: string` Opaque cursor for the next page. Pass as the `page` parameter on the next request. #### Example ```bash ant beta:organization:rbac-roles:permissions list \ --api-key my-anthropic-api-key \ --rbac-role-id rbac_role_id ``` ##### Response (200) ```json { "data": [ { "action": "use", "resource": { "organization_id": "3c4f5e6d-7a8b-49c0-9d1e-2f3a4b5c6d7e", "type": "organization" }, "type": "rbac_role_permission" } ], "has_more": true, "next_page": "eyJjdXJzb3IiOiAicmJhY19yb2xlXzAxIn0" } ``` ## Beta › Organization › Plugins ### Create Plugin `$ ant beta:organization:plugins create` **POST** `/v1/organizations/plugins` Create an organization-owned Plugin and its first version by uploading the version's files. The upload is `multipart/form-data`: the version's files (`files`, each part sent as `files[]`), with an optional `marketplace_id` and `release_notes`. The manifest's `name` becomes the Plugin's `name`, and `display_name`, `description` and `manifest_version` come from the manifest too. `name` may contain lowercase letters (from any alphabet), digits, and hyphens, up to 64 characters. Uppercase letters, spaces, underscores, and other punctuation are rejected. The `name` must be unique within the marketplace: a name already taken returns a 409 with `error_code` `plugin_name_taken` and, when a Plugin holds it, that Plugin's ID in `details.plugin_id`. A Plugin going into the organization's library marketplace is also refused with a 409 when one of its skills has the name of an organization skill (a skill an administrator uploaded for the whole organization in claude.ai): `error_code` `skill_name_taken`, with that name in `details.skill_name`; rename the skill, or remove the organization skill in claude.ai. A 503 with `error_code` `registration_pending` means the Plugin and its version were stored (their IDs are in `details`) but are not yet usable in claude.ai: do not retry the create (the retry would return `plugin_name_taken`); create a version on the stored Plugin instead, which completes it. For a worked example, see [Create a plugin](https://platform.claude.com/docs/en/manage-claude/plugins-api?sdk_languages=cli#create-a-plugin) in the Plugins API guide. **Accepted credentials:** an Admin API key with the `write:plugins` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--file: array of string` The version's files: one part per file, the part's filename being the file's path within the Plugin (for example `skills/review-pr/SKILL.md`), or a single `.zip` or `.plugin` archive holding them all. On the wire each part is named `files[]`, and a part named plain `files` is not read; with cURL, `-F 'files[]=@SKILL.md;filename=skills/review-pr/SKILL.md'`. The files must include the manifest, `.claude-plugin/plugin.json`. - `--marketplace-id: optional string` ID of the organization-owned plugin marketplace to create the Plugin in (prefixed `marketplace_`). It must be a `manual` marketplace, one whose Plugins are uploaded rather than synchronized from a repository. When omitted, the Plugin is created in the organization's library marketplace, an organization-owned `manual` marketplace created on first use. - `--release-notes: optional string` Release notes stored with the version and shown in its version history in claude.ai; up to 5,000 characters. maxLength: 5000 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_plugin: object` - `type: "plugin"` Always `plugin`. - `id: string` The Plugin's ID. - `components: array of BetaPluginComponent` What the served version contains; null when not enumerated. - `type: "agent" or "cli" or "command" or 3 more` The kind of component. - `"agent"` - `"cli"` - `"command"` - `"hook"` - `"mcp_server"` - `"skill"` - `description: string` What the component declares about itself; always null for MCP servers, hooks, and CLIs. - `name: string` The component's name: a skill's, command's or agent's name, an MCP server's key in the manifest, the event a hook runs on, or a CLI's executable. - `content_scan: object` The served version's content scan; null when it has not been scanned. - `assessment: "fail" or "pass" or "unknown" or "warn"` The scan's verdict; set only when `status` is `completed`. - `"fail"` - `"pass"` - `"unknown"` - `"warn"` - `reason: string` The primary mechanism behind a `warn` or `fail`, such as `credential-exposure` or `guardrail-tampering`; a mechanism this API does not yet name reads as `other`. Null on a `pass`, whenever `assessment` is null, and when no mechanism is reported for the verdict. - `status: "completed" or "errored" or "processing"` `processing` while a scan runs, `completed` when it ran to completion, `errored` when it could not run or its outcome cannot be read. - `"completed"` - `"errored"` - `"processing"` - `created_at: string` RFC 3339. format: date-time - `created_by: BetaPluginUserActor or BetaPluginAPIActor` Who created the Plugin; null when no creator is recorded. - `beta_plugin_user_actor: object` - `type: "user_actor"` A member of the organization. - `email_address: string` The member's email address; may be null, for example when they are no longer a member of the organization. - `user_id: string` The member's User ID. - `beta_plugin_api_actor: object` - `type: "api_actor"` An Admin API key, in the same form the Compliance API activity feed uses for it. - `api_key_id: string` The key's ID. - `description: string` The served version's description. - `display_name: string` The served version's display name. - `latest_version_id: string` The newest version. - `manifest_version: string` The served version's manifest `version`, normalized for display, or `null` (the Plugin Version's `manifest_version` says how and when). - `marketplace_id: string` The ID of the plugin marketplace the Plugin lives in. - `name: string` Lowercase identifier, unique within its plugin marketplace. Fixed for an organization-owned Plugin's lifetime; a member-owned Plugin's changes when its owner renames it in claude.ai, while its `id` stays the same. - `organization_installation_preference: "auto_install" or "available" or "not_available" or "required"` Organization-owned Plugin: the organization-wide installation setting every member gets unless an RBAC Group they belong to holds its own — the Plugin's own setting, or its plugin marketplace's default. Null for a member-owned Plugin, which has shares instead. One of `required`, `auto_install`, `available`, `not_available`; a value this API does not yet name is returned as stored. - `"auto_install"` - `"available"` - `"not_available"` - `"required"` - `organization_installation_preference_inherited: boolean` Organization-owned Plugin: true while it has no organization-wide setting of its own and `organization_installation_preference` is its plugin marketplace's default. Null for a member-owned Plugin. - `owner: BetaPluginOwnerOrganization or BetaPluginOwnerUser` Who owns the Plugin: the organization, or the member whose personal plugin marketplace it lives in. - `beta_plugin_owner_organization: object` - `type: "organization"` The Plugin lives in a plugin marketplace the organization owns. - `beta_plugin_owner_user: object` - `type: "user"` The Plugin lives in one member's personal plugin marketplace. - `user_id: string` The member's User ID. - `reach: "contained" or "privileged" or "remote"` How far the served version reaches, or `null` if it is not classified. `remote` means it declares an MCP server or a CLI. `privileged` means it declares no MCP server or CLI, but declares a hook, monitor, language server, or settings, or has a skill, command, or other Markdown file whose frontmatter pre-approves tools (`allowed-tools` with any value other than an empty one or one that names only `AskUserQuestion`, `TodoWrite`, and `ToolSearch`). Otherwise it is `contained`. If the frontmatter of a skill, command, or other Markdown file that could change the value could not be read, or was past a size limit, the version is `null` or `privileged` (or `remote`, if it declares an MCP server or a CLI), not `contained`. The value is normally worked out when a version is stored, under the rules of that time, so an older version can be `null`, or `contained` where the same files stored today would be `privileged` or `null`. - `"contained"` - `"privileged"` - `"remote"` - `served_version_id: string` The version claude.ai serves to members. - `served_version_pinned: boolean` False while the served version follows each new version; true once it has been pinned to one. - `updated_at: string` RFC 3339. Moves on a new version and on a served-version change; a change to the Plugin's installation settings or shares does not move it. format: date-time #### Example ```bash ant beta:organization:plugins create \ --api-key my-anthropic-api-key \ --file 'Example data' ``` ##### Response (200) ```json { "id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "components": [ { "description": "description", "name": "review-pr", "type": "skill" } ], "content_scan": { "assessment": "warn", "reason": "credential-exposure", "status": "completed" }, "created_at": "2026-03-14T09:26:53.589793Z", "created_by": { "email_address": "user@example.com", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "description": "Reviews pull requests against your team's conventions.", "display_name": "Code Review Helper", "latest_version_id": "pluginver_01KaZmQpRsTuVwXyZ2b4c6d8", "manifest_version": "1.2.0", "marketplace_id": "marketplace_01HxQ3v9KpZ2mTn8RwLc4Ys7", "name": "code-review-helper", "organization_installation_preference": "available", "organization_installation_preference_inherited": true, "owner": { "type": "organization" }, "reach": "contained", "served_version_id": "pluginver_01K9wPcHd4Rm2Tx8Vq6Ln3Sb", "served_version_pinned": true, "type": "plugin", "updated_at": "2026-03-14T09:26:53.589793Z" } ``` ### Get Plugin `$ ant beta:organization:plugins retrieve` **GET** `/v1/organizations/plugins/{plugin_id}` Retrieve a Plugin by ID. **Accepted credentials:** an Admin API key with the `read:plugins` or `read:org_audit` scope, or a Compliance Access Key with the `read:compliance_org_data` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--organization-id: optional string` (query parameter) For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_plugin: object` - `type: "plugin"` Always `plugin`. - `id: string` The Plugin's ID. - `components: array of BetaPluginComponent` What the served version contains; null when not enumerated. - `type: "agent" or "cli" or "command" or 3 more` The kind of component. - `"agent"` - `"cli"` - `"command"` - `"hook"` - `"mcp_server"` - `"skill"` - `description: string` What the component declares about itself; always null for MCP servers, hooks, and CLIs. - `name: string` The component's name: a skill's, command's or agent's name, an MCP server's key in the manifest, the event a hook runs on, or a CLI's executable. - `content_scan: object` The served version's content scan; null when it has not been scanned. - `assessment: "fail" or "pass" or "unknown" or "warn"` The scan's verdict; set only when `status` is `completed`. - `"fail"` - `"pass"` - `"unknown"` - `"warn"` - `reason: string` The primary mechanism behind a `warn` or `fail`, such as `credential-exposure` or `guardrail-tampering`; a mechanism this API does not yet name reads as `other`. Null on a `pass`, whenever `assessment` is null, and when no mechanism is reported for the verdict. - `status: "completed" or "errored" or "processing"` `processing` while a scan runs, `completed` when it ran to completion, `errored` when it could not run or its outcome cannot be read. - `"completed"` - `"errored"` - `"processing"` - `created_at: string` RFC 3339. format: date-time - `created_by: BetaPluginUserActor or BetaPluginAPIActor` Who created the Plugin; null when no creator is recorded. - `beta_plugin_user_actor: object` - `type: "user_actor"` A member of the organization. - `email_address: string` The member's email address; may be null, for example when they are no longer a member of the organization. - `user_id: string` The member's User ID. - `beta_plugin_api_actor: object` - `type: "api_actor"` An Admin API key, in the same form the Compliance API activity feed uses for it. - `api_key_id: string` The key's ID. - `description: string` The served version's description. - `display_name: string` The served version's display name. - `latest_version_id: string` The newest version. - `manifest_version: string` The served version's manifest `version`, normalized for display, or `null` (the Plugin Version's `manifest_version` says how and when). - `marketplace_id: string` The ID of the plugin marketplace the Plugin lives in. - `name: string` Lowercase identifier, unique within its plugin marketplace. Fixed for an organization-owned Plugin's lifetime; a member-owned Plugin's changes when its owner renames it in claude.ai, while its `id` stays the same. - `organization_installation_preference: "auto_install" or "available" or "not_available" or "required"` Organization-owned Plugin: the organization-wide installation setting every member gets unless an RBAC Group they belong to holds its own — the Plugin's own setting, or its plugin marketplace's default. Null for a member-owned Plugin, which has shares instead. One of `required`, `auto_install`, `available`, `not_available`; a value this API does not yet name is returned as stored. - `"auto_install"` - `"available"` - `"not_available"` - `"required"` - `organization_installation_preference_inherited: boolean` Organization-owned Plugin: true while it has no organization-wide setting of its own and `organization_installation_preference` is its plugin marketplace's default. Null for a member-owned Plugin. - `owner: BetaPluginOwnerOrganization or BetaPluginOwnerUser` Who owns the Plugin: the organization, or the member whose personal plugin marketplace it lives in. - `beta_plugin_owner_organization: object` - `type: "organization"` The Plugin lives in a plugin marketplace the organization owns. - `beta_plugin_owner_user: object` - `type: "user"` The Plugin lives in one member's personal plugin marketplace. - `user_id: string` The member's User ID. - `reach: "contained" or "privileged" or "remote"` How far the served version reaches, or `null` if it is not classified. `remote` means it declares an MCP server or a CLI. `privileged` means it declares no MCP server or CLI, but declares a hook, monitor, language server, or settings, or has a skill, command, or other Markdown file whose frontmatter pre-approves tools (`allowed-tools` with any value other than an empty one or one that names only `AskUserQuestion`, `TodoWrite`, and `ToolSearch`). Otherwise it is `contained`. If the frontmatter of a skill, command, or other Markdown file that could change the value could not be read, or was past a size limit, the version is `null` or `privileged` (or `remote`, if it declares an MCP server or a CLI), not `contained`. The value is normally worked out when a version is stored, under the rules of that time, so an older version can be `null`, or `contained` where the same files stored today would be `privileged` or `null`. - `"contained"` - `"privileged"` - `"remote"` - `served_version_id: string` The version claude.ai serves to members. - `served_version_pinned: boolean` False while the served version follows each new version; true once it has been pinned to one. - `updated_at: string` RFC 3339. Moves on a new version and on a served-version change; a change to the Plugin's installation settings or shares does not move it. format: date-time #### Example ```bash ant beta:organization:plugins retrieve \ --api-key my-anthropic-api-key \ --plugin-id plugin_id ``` ##### Response (200) ```json { "id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "components": [ { "description": "description", "name": "review-pr", "type": "skill" } ], "content_scan": { "assessment": "warn", "reason": "credential-exposure", "status": "completed" }, "created_at": "2026-03-14T09:26:53.589793Z", "created_by": { "email_address": "user@example.com", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "description": "Reviews pull requests against your team's conventions.", "display_name": "Code Review Helper", "latest_version_id": "pluginver_01KaZmQpRsTuVwXyZ2b4c6d8", "manifest_version": "1.2.0", "marketplace_id": "marketplace_01HxQ3v9KpZ2mTn8RwLc4Ys7", "name": "code-review-helper", "organization_installation_preference": "available", "organization_installation_preference_inherited": true, "owner": { "type": "organization" }, "reach": "contained", "served_version_id": "pluginver_01K9wPcHd4Rm2Tx8Vq6Ln3Sb", "served_version_pinned": true, "type": "plugin", "updated_at": "2026-03-14T09:26:53.589793Z" } ``` ### Update Plugin `$ ant beta:organization:plugins update` **POST** `/v1/organizations/plugins/{plugin_id}` Change which stored version of an organization-owned Plugin is served to members, for example to roll back to an earlier one. This pins the served version: later uploads are stored but no longer change what is served, and pinning cannot currently be undone, here or in claude.ai. Pass the version as `served_version_id`: an earlier one to roll back, a later one to start serving a version that was stored without being served, or the one already served to pin it without changing what is served. No new version is created. When the organization has content scanning enabled, a version whose scan is still running is refused with a 409 (`error_code` `scan_pending`; retry once the scan finishes) and one whose scan failed, errored or reached no verdict with a 400 (`scan_failed`; a `warn` is accepted). When the Plugin is in the organization's library marketplace, a version other than the one served is also refused with a 409 when one of its skills has a name that an organization skill (one an administrator uploaded for the whole organization in claude.ai) has since taken: `error_code` `skill_name_taken`, with that name in `details.skill_name`. A member-owned Plugin cannot be updated here (403). This endpoint does not write installation settings; they are written at `/v1/organizations/plugins/{plugin_id}/installation_settings/{target}`. **Accepted credentials:** an Admin API key with the `write:plugins` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--served-version-id: string` Serve this version of the Plugin (prefixed `pluginver_`) and pin the served version to it; `latest` is not accepted. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_plugin: object` - `type: "plugin"` Always `plugin`. - `id: string` The Plugin's ID. - `components: array of BetaPluginComponent` What the served version contains; null when not enumerated. - `type: "agent" or "cli" or "command" or 3 more` The kind of component. - `"agent"` - `"cli"` - `"command"` - `"hook"` - `"mcp_server"` - `"skill"` - `description: string` What the component declares about itself; always null for MCP servers, hooks, and CLIs. - `name: string` The component's name: a skill's, command's or agent's name, an MCP server's key in the manifest, the event a hook runs on, or a CLI's executable. - `content_scan: object` The served version's content scan; null when it has not been scanned. - `assessment: "fail" or "pass" or "unknown" or "warn"` The scan's verdict; set only when `status` is `completed`. - `"fail"` - `"pass"` - `"unknown"` - `"warn"` - `reason: string` The primary mechanism behind a `warn` or `fail`, such as `credential-exposure` or `guardrail-tampering`; a mechanism this API does not yet name reads as `other`. Null on a `pass`, whenever `assessment` is null, and when no mechanism is reported for the verdict. - `status: "completed" or "errored" or "processing"` `processing` while a scan runs, `completed` when it ran to completion, `errored` when it could not run or its outcome cannot be read. - `"completed"` - `"errored"` - `"processing"` - `created_at: string` RFC 3339. format: date-time - `created_by: BetaPluginUserActor or BetaPluginAPIActor` Who created the Plugin; null when no creator is recorded. - `beta_plugin_user_actor: object` - `type: "user_actor"` A member of the organization. - `email_address: string` The member's email address; may be null, for example when they are no longer a member of the organization. - `user_id: string` The member's User ID. - `beta_plugin_api_actor: object` - `type: "api_actor"` An Admin API key, in the same form the Compliance API activity feed uses for it. - `api_key_id: string` The key's ID. - `description: string` The served version's description. - `display_name: string` The served version's display name. - `latest_version_id: string` The newest version. - `manifest_version: string` The served version's manifest `version`, normalized for display, or `null` (the Plugin Version's `manifest_version` says how and when). - `marketplace_id: string` The ID of the plugin marketplace the Plugin lives in. - `name: string` Lowercase identifier, unique within its plugin marketplace. Fixed for an organization-owned Plugin's lifetime; a member-owned Plugin's changes when its owner renames it in claude.ai, while its `id` stays the same. - `organization_installation_preference: "auto_install" or "available" or "not_available" or "required"` Organization-owned Plugin: the organization-wide installation setting every member gets unless an RBAC Group they belong to holds its own — the Plugin's own setting, or its plugin marketplace's default. Null for a member-owned Plugin, which has shares instead. One of `required`, `auto_install`, `available`, `not_available`; a value this API does not yet name is returned as stored. - `"auto_install"` - `"available"` - `"not_available"` - `"required"` - `organization_installation_preference_inherited: boolean` Organization-owned Plugin: true while it has no organization-wide setting of its own and `organization_installation_preference` is its plugin marketplace's default. Null for a member-owned Plugin. - `owner: BetaPluginOwnerOrganization or BetaPluginOwnerUser` Who owns the Plugin: the organization, or the member whose personal plugin marketplace it lives in. - `beta_plugin_owner_organization: object` - `type: "organization"` The Plugin lives in a plugin marketplace the organization owns. - `beta_plugin_owner_user: object` - `type: "user"` The Plugin lives in one member's personal plugin marketplace. - `user_id: string` The member's User ID. - `reach: "contained" or "privileged" or "remote"` How far the served version reaches, or `null` if it is not classified. `remote` means it declares an MCP server or a CLI. `privileged` means it declares no MCP server or CLI, but declares a hook, monitor, language server, or settings, or has a skill, command, or other Markdown file whose frontmatter pre-approves tools (`allowed-tools` with any value other than an empty one or one that names only `AskUserQuestion`, `TodoWrite`, and `ToolSearch`). Otherwise it is `contained`. If the frontmatter of a skill, command, or other Markdown file that could change the value could not be read, or was past a size limit, the version is `null` or `privileged` (or `remote`, if it declares an MCP server or a CLI), not `contained`. The value is normally worked out when a version is stored, under the rules of that time, so an older version can be `null`, or `contained` where the same files stored today would be `privileged` or `null`. - `"contained"` - `"privileged"` - `"remote"` - `served_version_id: string` The version claude.ai serves to members. - `served_version_pinned: boolean` False while the served version follows each new version; true once it has been pinned to one. - `updated_at: string` RFC 3339. Moves on a new version and on a served-version change; a change to the Plugin's installation settings or shares does not move it. format: date-time #### Example ```bash ant beta:organization:plugins update \ --api-key my-anthropic-api-key \ --plugin-id plugin_id \ --served-version-id pluginver_01KaZmQpRsTuVwXyZ2b4c6d8 ``` ##### Response (200) ```json { "id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "components": [ { "description": "description", "name": "review-pr", "type": "skill" } ], "content_scan": { "assessment": "warn", "reason": "credential-exposure", "status": "completed" }, "created_at": "2026-03-14T09:26:53.589793Z", "created_by": { "email_address": "user@example.com", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "description": "Reviews pull requests against your team's conventions.", "display_name": "Code Review Helper", "latest_version_id": "pluginver_01KaZmQpRsTuVwXyZ2b4c6d8", "manifest_version": "1.2.0", "marketplace_id": "marketplace_01HxQ3v9KpZ2mTn8RwLc4Ys7", "name": "code-review-helper", "organization_installation_preference": "available", "organization_installation_preference_inherited": true, "owner": { "type": "organization" }, "reach": "contained", "served_version_id": "pluginver_01K9wPcHd4Rm2Tx8Vq6Ln3Sb", "served_version_pinned": true, "type": "plugin", "updated_at": "2026-03-14T09:26:53.589793Z" } ``` ### List Plugins `$ ant beta:organization:plugins list` **GET** `/v1/organizations/plugins` List the Plugins created under the organization, newest first: those in the organization's own plugin marketplaces and those in members' personal plugin marketplaces. Plugins in members' personal marketplaces are listed with the same detail as the organization's own, and their files can be downloaded through the version archive endpoint, which records each such download on the Compliance API activity feed. **Accepted credentials:** an Admin API key with the `read:plugins` or `read:org_audit` scope, or a Compliance Access Key with the `read:compliance_org_data` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--created-at-gt: optional string` (query parameter) RFC 3339 timestamp bound; combine [gte], [gt], [lte], [lt]. format: date-time - `--created-at-gte: optional string` (query parameter) RFC 3339 timestamp bound; combine [gte], [gt], [lte], [lt]. format: date-time - `--created-at-lt: optional string` (query parameter) RFC 3339 timestamp bound; combine [gte], [gt], [lte], [lt]. format: date-time - `--created-at-lte: optional string` (query parameter) RFC 3339 timestamp bound; combine [gte], [gt], [lte], [lt]. format: date-time - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `100`. minimum: 1, maximum: 100 - `--marketplace-id: optional string` (query parameter) Only Plugins in this plugin marketplace (prefixed `marketplace_`). - `--organization-id: optional string` (query parameter) For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. - `--owner-type: optional "organization" or "user"` (query parameter) `organization` for Plugins in the organization's plugin marketplaces, `user` for Plugins in members' personal plugin marketplaces. - `--owner-user-id: optional string` (query parameter) Only Plugins in this member's personal plugin marketplaces (prefixed `user_`); a removed member's ID is accepted. - `--page: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. maxLength: 2048 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `BetaPluginList: object` - `data: array of BetaPlugin` - `type: "plugin"` Always `plugin`. - `id: string` The Plugin's ID. - `components: array of BetaPluginComponent` What the served version contains; null when not enumerated. - `type: "agent" or "cli" or "command" or 3 more` The kind of component. - `"agent"` - `"cli"` - `"command"` - `"hook"` - `"mcp_server"` - `"skill"` - `description: string` What the component declares about itself; always null for MCP servers, hooks, and CLIs. - `name: string` The component's name: a skill's, command's or agent's name, an MCP server's key in the manifest, the event a hook runs on, or a CLI's executable. - `content_scan: object` The served version's content scan; null when it has not been scanned. - `assessment: "fail" or "pass" or "unknown" or "warn"` The scan's verdict; set only when `status` is `completed`. - `"fail"` - `"pass"` - `"unknown"` - `"warn"` - `reason: string` The primary mechanism behind a `warn` or `fail`, such as `credential-exposure` or `guardrail-tampering`; a mechanism this API does not yet name reads as `other`. Null on a `pass`, whenever `assessment` is null, and when no mechanism is reported for the verdict. - `status: "completed" or "errored" or "processing"` `processing` while a scan runs, `completed` when it ran to completion, `errored` when it could not run or its outcome cannot be read. - `"completed"` - `"errored"` - `"processing"` - `created_at: string` RFC 3339. format: date-time - `created_by: BetaPluginUserActor or BetaPluginAPIActor` Who created the Plugin; null when no creator is recorded. - `beta_plugin_user_actor: object` - `type: "user_actor"` A member of the organization. - `email_address: string` The member's email address; may be null, for example when they are no longer a member of the organization. - `user_id: string` The member's User ID. - `beta_plugin_api_actor: object` - `type: "api_actor"` An Admin API key, in the same form the Compliance API activity feed uses for it. - `api_key_id: string` The key's ID. - `description: string` The served version's description. - `display_name: string` The served version's display name. - `latest_version_id: string` The newest version. - `manifest_version: string` The served version's manifest `version`, normalized for display, or `null` (the Plugin Version's `manifest_version` says how and when). - `marketplace_id: string` The ID of the plugin marketplace the Plugin lives in. - `name: string` Lowercase identifier, unique within its plugin marketplace. Fixed for an organization-owned Plugin's lifetime; a member-owned Plugin's changes when its owner renames it in claude.ai, while its `id` stays the same. - `organization_installation_preference: "auto_install" or "available" or "not_available" or "required"` Organization-owned Plugin: the organization-wide installation setting every member gets unless an RBAC Group they belong to holds its own — the Plugin's own setting, or its plugin marketplace's default. Null for a member-owned Plugin, which has shares instead. One of `required`, `auto_install`, `available`, `not_available`; a value this API does not yet name is returned as stored. - `"auto_install"` - `"available"` - `"not_available"` - `"required"` - `organization_installation_preference_inherited: boolean` Organization-owned Plugin: true while it has no organization-wide setting of its own and `organization_installation_preference` is its plugin marketplace's default. Null for a member-owned Plugin. - `owner: BetaPluginOwnerOrganization or BetaPluginOwnerUser` Who owns the Plugin: the organization, or the member whose personal plugin marketplace it lives in. - `beta_plugin_owner_organization: object` - `type: "organization"` The Plugin lives in a plugin marketplace the organization owns. - `beta_plugin_owner_user: object` - `type: "user"` The Plugin lives in one member's personal plugin marketplace. - `user_id: string` The member's User ID. - `reach: "contained" or "privileged" or "remote"` How far the served version reaches, or `null` if it is not classified. `remote` means it declares an MCP server or a CLI. `privileged` means it declares no MCP server or CLI, but declares a hook, monitor, language server, or settings, or has a skill, command, or other Markdown file whose frontmatter pre-approves tools (`allowed-tools` with any value other than an empty one or one that names only `AskUserQuestion`, `TodoWrite`, and `ToolSearch`). Otherwise it is `contained`. If the frontmatter of a skill, command, or other Markdown file that could change the value could not be read, or was past a size limit, the version is `null` or `privileged` (or `remote`, if it declares an MCP server or a CLI), not `contained`. The value is normally worked out when a version is stored, under the rules of that time, so an older version can be `null`, or `contained` where the same files stored today would be `privileged` or `null`. - `"contained"` - `"privileged"` - `"remote"` - `served_version_id: string` The version claude.ai serves to members. - `served_version_pinned: boolean` False while the served version follows each new version; true once it has been pinned to one. - `updated_at: string` RFC 3339. Moves on a new version and on a served-version change; a change to the Plugin's installation settings or shares does not move it. format: date-time - `next_page: string` Token to provide in as `page` in the subsequent request to retrieve the next page of data. A page may hold fewer than `limit` Plugins, even none, while this is set; keep following it until it is null. #### Example ```bash ant beta:organization:plugins list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "components": [ { "description": "description", "name": "review-pr", "type": "skill" } ], "content_scan": { "assessment": "warn", "reason": "credential-exposure", "status": "completed" }, "created_at": "2026-03-14T09:26:53.589793Z", "created_by": { "email_address": "user@example.com", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "description": "Reviews pull requests against your team's conventions.", "display_name": "Code Review Helper", "latest_version_id": "pluginver_01KaZmQpRsTuVwXyZ2b4c6d8", "manifest_version": "1.2.0", "marketplace_id": "marketplace_01HxQ3v9KpZ2mTn8RwLc4Ys7", "name": "code-review-helper", "organization_installation_preference": "available", "organization_installation_preference_inherited": true, "owner": { "type": "organization" }, "reach": "contained", "served_version_id": "pluginver_01K9wPcHd4Rm2Tx8Vq6Ln3Sb", "served_version_pinned": true, "type": "plugin", "updated_at": "2026-03-14T09:26:53.589793Z" } ], "next_page": "page_MjAyNi0wOS0xNlQxNDowNTowOVo" } ``` ### Delete Plugin `$ ant beta:organization:plugins delete` **DELETE** `/v1/organizations/plugins/{plugin_id}` Permanently delete a Plugin and every version it holds, exactly as when an administrator deletes it in claude.ai. The Plugin may belong to the organization or to a member, including a member who has since left the organization. An organization-owned Plugin's installation settings go with it; a member-owned Plugin's shares are withdrawn and its owner no longer has it. To take an organization-owned Plugin out of use reversibly, set its organization-wide installation setting to `not_available` instead (and remove or change any group settings, which override it for their members). Only a Plugin in a `manual` marketplace can be deleted here; one synchronized from a repository is removed by removing it from the repository (400). **Accepted credentials:** an Admin API key with the `write:plugins` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_deleted_plugin: object` - `type: "plugin_deleted"` Always `plugin_deleted`. - `id: string` The deleted Plugin's ID. #### Example ```bash ant beta:organization:plugins delete \ --api-key my-anthropic-api-key \ --plugin-id plugin_id ``` ##### Response (200) ```json { "id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "type": "plugin_deleted" } ``` ## Beta › Organization › Plugins › Versions ### Create Plugin Version `$ ant beta:organization:plugins:versions create` **POST** `/v1/organizations/plugins/{plugin_id}/versions` Add a version to an organization-owned Plugin by uploading the new version's files; it becomes the version served to members unless the Plugin's served version has been pinned. The upload is the same `multipart/form-data` as creating a Plugin: the version's files (`files`, each part sent as `files[]`) and optional `release_notes`. The uploaded manifest's `name` must equal the Plugin's `name`. Returns the stored version; read the Plugin back to see which version it serves. Only a Plugin in a `manual` marketplace takes uploads; a Plugin synchronized from a repository gets its versions from the repository. When the Plugin is in the organization's library marketplace, a version that adds a skill with the name of an organization skill (a skill an administrator uploaded for the whole organization in claude.ai) is refused with a 409: `error_code` `skill_name_taken`, with that name in `details.skill_name`. A 503 with `error_code` `registration_pending` means the version was stored but is not yet usable; a later version create on the Plugin completes it. For a worked example, see [Create a version](https://platform.claude.com/docs/en/manage-claude/plugins-api?sdk_languages=cli#create-a-version) in the Plugins API guide. **Accepted credentials:** an Admin API key with the `write:plugins` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--file: array of string` The version's files: one part per file, the part's filename being the file's path within the Plugin (for example `skills/review-pr/SKILL.md`), or a single `.zip` or `.plugin` archive holding them all. On the wire each part is named `files[]`, and a part named plain `files` is not read; with cURL, `-F 'files[]=@SKILL.md;filename=skills/review-pr/SKILL.md'`. The files must include the manifest, `.claude-plugin/plugin.json`. - `--release-notes: optional string` Release notes stored with the version and shown in its version history in claude.ai; up to 5,000 characters. maxLength: 5000 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_plugin_version: object` - `type: "plugin_version"` Always `plugin_version`. - `id: string` The version's ID. - `components: array of BetaPluginComponent` What the version contains; null when not enumerated. - `type: "agent" or "cli" or "command" or 3 more` The kind of component. - `"agent"` - `"cli"` - `"command"` - `"hook"` - `"mcp_server"` - `"skill"` - `description: string` What the component declares about itself; always null for MCP servers, hooks, and CLIs. - `name: string` The component's name: a skill's, command's or agent's name, an MCP server's key in the manifest, the event a hook runs on, or a CLI's executable. - `content_scan: object` This version's content scan; null when it has not been scanned. - `assessment: "fail" or "pass" or "unknown" or "warn"` The scan's verdict; set only when `status` is `completed`. - `"fail"` - `"pass"` - `"unknown"` - `"warn"` - `reason: string` The primary mechanism behind a `warn` or `fail`, such as `credential-exposure` or `guardrail-tampering`; a mechanism this API does not yet name reads as `other`. Null on a `pass`, whenever `assessment` is null, and when no mechanism is reported for the verdict. - `status: "completed" or "errored" or "processing"` `processing` while a scan runs, `completed` when it ran to completion, `errored` when it could not run or its outcome cannot be read. - `"completed"` - `"errored"` - `"processing"` - `created_at: string` RFC 3339. format: date-time - `created_by: BetaPluginUserActor or BetaPluginAPIActor` Who uploaded this version; null when not recorded. - `beta_plugin_user_actor: object` - `type: "user_actor"` A member of the organization. - `email_address: string` The member's email address; may be null, for example when they are no longer a member of the organization. - `user_id: string` The member's User ID. - `beta_plugin_api_actor: object` - `type: "api_actor"` An Admin API key, in the same form the Compliance API activity feed uses for it. - `api_key_id: string` The key's ID. - `description: string` The manifest's description; null when it declares none. - `display_name: string` The manifest's display name; null when it declares none. - `manifest_version: string` The manifest's `version`, normalized for display: one leading `v` or `V` is dropped, and the result is returned only if it is 1 to 64 characters, starts with a digit, and uses only ASCII letters, digits, `.`, `+`, and `-`; otherwise `null`. For example, `"v1.4.0"` is returned as `"1.4.0"`, and `"latest"` as `null`. For a synchronized plugin, the `version` of its `marketplace.json` entry can take the place of the manifest's `version`. It is also `null` for a version stored before claude.ai began recording this field (August 2026). - `plugin_id: string` The Plugin's ID. - `reach: "contained" or "privileged" or "remote"` How far the version reaches: `remote`, `privileged`, `contained`, or `null`, as defined on the Plugin's `reach`. - `"contained"` - `"privileged"` - `"remote"` - `release_notes: string` As supplied with the upload; null when none were supplied. #### Example ```bash ant beta:organization:plugins:versions create \ --api-key my-anthropic-api-key \ --plugin-id plugin_id \ --file 'Example data' ``` ##### Response (200) ```json { "id": "pluginver_01KaZmQpRsTuVwXyZ2b4c6d8", "components": [ { "description": "description", "name": "review-pr", "type": "skill" } ], "content_scan": { "assessment": "warn", "reason": "credential-exposure", "status": "completed" }, "created_at": "2026-03-14T09:26:53.589793Z", "created_by": { "email_address": "user@example.com", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "description": "Reviews pull requests against your team's conventions.", "display_name": "Code Review Helper", "manifest_version": "1.2.0", "plugin_id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "reach": "contained", "release_notes": "Adds a review checklist for database migrations.", "type": "plugin_version" } ``` ### List Plugin Versions `$ ant beta:organization:plugins:versions list` **GET** `/v1/organizations/plugins/{plugin_id}/versions` List a Plugin's versions, newest first. The first item of the first page is the version the Plugin's `latest_version_id` refers to. **Accepted credentials:** an Admin API key with the `read:plugins` or `read:org_audit` scope, or a Compliance Access Key with the `read:compliance_org_data` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--organization-id: optional string` (query parameter) For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. - `--page: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. maxLength: 2048 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `BetaPluginVersionList: object` - `data: array of BetaPluginVersion` - `type: "plugin_version"` Always `plugin_version`. - `id: string` The version's ID. - `components: array of BetaPluginComponent` What the version contains; null when not enumerated. - `type: "agent" or "cli" or "command" or 3 more` The kind of component. - `"agent"` - `"cli"` - `"command"` - `"hook"` - `"mcp_server"` - `"skill"` - `description: string` What the component declares about itself; always null for MCP servers, hooks, and CLIs. - `name: string` The component's name: a skill's, command's or agent's name, an MCP server's key in the manifest, the event a hook runs on, or a CLI's executable. - `content_scan: object` This version's content scan; null when it has not been scanned. - `assessment: "fail" or "pass" or "unknown" or "warn"` The scan's verdict; set only when `status` is `completed`. - `"fail"` - `"pass"` - `"unknown"` - `"warn"` - `reason: string` The primary mechanism behind a `warn` or `fail`, such as `credential-exposure` or `guardrail-tampering`; a mechanism this API does not yet name reads as `other`. Null on a `pass`, whenever `assessment` is null, and when no mechanism is reported for the verdict. - `status: "completed" or "errored" or "processing"` `processing` while a scan runs, `completed` when it ran to completion, `errored` when it could not run or its outcome cannot be read. - `"completed"` - `"errored"` - `"processing"` - `created_at: string` RFC 3339. format: date-time - `created_by: BetaPluginUserActor or BetaPluginAPIActor` Who uploaded this version; null when not recorded. - `beta_plugin_user_actor: object` - `type: "user_actor"` A member of the organization. - `email_address: string` The member's email address; may be null, for example when they are no longer a member of the organization. - `user_id: string` The member's User ID. - `beta_plugin_api_actor: object` - `type: "api_actor"` An Admin API key, in the same form the Compliance API activity feed uses for it. - `api_key_id: string` The key's ID. - `description: string` The manifest's description; null when it declares none. - `display_name: string` The manifest's display name; null when it declares none. - `manifest_version: string` The manifest's `version`, normalized for display: one leading `v` or `V` is dropped, and the result is returned only if it is 1 to 64 characters, starts with a digit, and uses only ASCII letters, digits, `.`, `+`, and `-`; otherwise `null`. For example, `"v1.4.0"` is returned as `"1.4.0"`, and `"latest"` as `null`. For a synchronized plugin, the `version` of its `marketplace.json` entry can take the place of the manifest's `version`. It is also `null` for a version stored before claude.ai began recording this field (August 2026). - `plugin_id: string` The Plugin's ID. - `reach: "contained" or "privileged" or "remote"` How far the version reaches: `remote`, `privileged`, `contained`, or `null`, as defined on the Plugin's `reach`. - `"contained"` - `"privileged"` - `"remote"` - `release_notes: string` As supplied with the upload; null when none were supplied. - `next_page: string` Token to provide in as `page` in the subsequent request to retrieve the next page of data. #### Example ```bash ant beta:organization:plugins:versions list \ --api-key my-anthropic-api-key \ --plugin-id plugin_id ``` ##### Response (200) ```json { "data": [ { "id": "pluginver_01KaZmQpRsTuVwXyZ2b4c6d8", "components": [ { "description": "description", "name": "review-pr", "type": "skill" } ], "content_scan": { "assessment": "warn", "reason": "credential-exposure", "status": "completed" }, "created_at": "2026-03-14T09:26:53.589793Z", "created_by": { "email_address": "user@example.com", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "description": "Reviews pull requests against your team's conventions.", "display_name": "Code Review Helper", "manifest_version": "1.2.0", "plugin_id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "reach": "contained", "release_notes": "Adds a review checklist for database migrations.", "type": "plugin_version" } ], "next_page": "page_MjAyNi0wOS0xNlQxNDowNTowOVo" } ``` ### Get Plugin Version `$ ant beta:organization:plugins:versions retrieve` **GET** `/v1/organizations/plugins/{plugin_id}/versions/{version}` Retrieve one version of a Plugin by its ID, or the Plugin's newest version. **Accepted credentials:** an Admin API key with the `read:plugins` or `read:org_audit` scope, or a Compliance Access Key with the `read:compliance_org_data` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--version: string` (path parameter) ID of the Plugin Version (prefixed `pluginver_`), or `latest` for the newest one. - `--organization-id: optional string` (query parameter) For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_plugin_version: object` - `type: "plugin_version"` Always `plugin_version`. - `id: string` The version's ID. - `components: array of BetaPluginComponent` What the version contains; null when not enumerated. - `type: "agent" or "cli" or "command" or 3 more` The kind of component. - `"agent"` - `"cli"` - `"command"` - `"hook"` - `"mcp_server"` - `"skill"` - `description: string` What the component declares about itself; always null for MCP servers, hooks, and CLIs. - `name: string` The component's name: a skill's, command's or agent's name, an MCP server's key in the manifest, the event a hook runs on, or a CLI's executable. - `content_scan: object` This version's content scan; null when it has not been scanned. - `assessment: "fail" or "pass" or "unknown" or "warn"` The scan's verdict; set only when `status` is `completed`. - `"fail"` - `"pass"` - `"unknown"` - `"warn"` - `reason: string` The primary mechanism behind a `warn` or `fail`, such as `credential-exposure` or `guardrail-tampering`; a mechanism this API does not yet name reads as `other`. Null on a `pass`, whenever `assessment` is null, and when no mechanism is reported for the verdict. - `status: "completed" or "errored" or "processing"` `processing` while a scan runs, `completed` when it ran to completion, `errored` when it could not run or its outcome cannot be read. - `"completed"` - `"errored"` - `"processing"` - `created_at: string` RFC 3339. format: date-time - `created_by: BetaPluginUserActor or BetaPluginAPIActor` Who uploaded this version; null when not recorded. - `beta_plugin_user_actor: object` - `type: "user_actor"` A member of the organization. - `email_address: string` The member's email address; may be null, for example when they are no longer a member of the organization. - `user_id: string` The member's User ID. - `beta_plugin_api_actor: object` - `type: "api_actor"` An Admin API key, in the same form the Compliance API activity feed uses for it. - `api_key_id: string` The key's ID. - `description: string` The manifest's description; null when it declares none. - `display_name: string` The manifest's display name; null when it declares none. - `manifest_version: string` The manifest's `version`, normalized for display: one leading `v` or `V` is dropped, and the result is returned only if it is 1 to 64 characters, starts with a digit, and uses only ASCII letters, digits, `.`, `+`, and `-`; otherwise `null`. For example, `"v1.4.0"` is returned as `"1.4.0"`, and `"latest"` as `null`. For a synchronized plugin, the `version` of its `marketplace.json` entry can take the place of the manifest's `version`. It is also `null` for a version stored before claude.ai began recording this field (August 2026). - `plugin_id: string` The Plugin's ID. - `reach: "contained" or "privileged" or "remote"` How far the version reaches: `remote`, `privileged`, `contained`, or `null`, as defined on the Plugin's `reach`. - `"contained"` - `"privileged"` - `"remote"` - `release_notes: string` As supplied with the upload; null when none were supplied. #### Example ```bash ant beta:organization:plugins:versions retrieve \ --api-key my-anthropic-api-key \ --plugin-id plugin_id \ --version version ``` ##### Response (200) ```json { "id": "pluginver_01KaZmQpRsTuVwXyZ2b4c6d8", "components": [ { "description": "description", "name": "review-pr", "type": "skill" } ], "content_scan": { "assessment": "warn", "reason": "credential-exposure", "status": "completed" }, "created_at": "2026-03-14T09:26:53.589793Z", "created_by": { "email_address": "user@example.com", "type": "user_actor", "user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q" }, "description": "Reviews pull requests against your team's conventions.", "display_name": "Code Review Helper", "manifest_version": "1.2.0", "plugin_id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "reach": "contained", "release_notes": "Adds a review checklist for database migrations.", "type": "plugin_version" } ``` ### Download Plugin Version Archive `$ ant beta:organization:plugins:versions download` **GET** `/v1/organizations/plugins/{plugin_id}/versions/{version}/content` Download one version's `.zip` archive, exactly as stored. Each download of a Plugin from a member's personal plugin marketplace is recorded on the Compliance API activity feed. The response body is the archive (`Content-Type: application/zip`), sent as an attachment whose filename is derived from the Plugin's name; name saved files from the IDs in the request path, since that filename is not unique. **Accepted credentials:** an Admin API key with the `read:plugins` or `read:org_audit` scope, or a Compliance Access Key with the `read:compliance_org_data` scope. Every read scope above (`read:plugins`, `read:org_audit`, and `read:compliance_org_data`) can download the files of plugins in members' personal marketplaces, including files that claude.ai's admin settings do not show, and a `read:org_audit` or `read:compliance_org_data` key created for all of your parent organization's linked organizations can do this in any organization under it that has access to this API, by passing `organization_id`. Each such download records a `claude_plugin_archive_accessed` event on the Compliance API activity feed, identifying the key, the plugin, the version, and the member. Downloads of organization-owned plugins are not recorded. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--version: string` (path parameter) ID of the Plugin Version (prefixed `pluginver_`). `latest` is not accepted here. - `--organization-id: optional string` (query parameter) For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `unnamed_schema_3: file path` #### Example ```bash ant beta:organization:plugins:versions download \ --api-key my-anthropic-api-key \ --plugin-id plugin_id \ --version version ``` ## Beta › Organization › Plugins › Installation Settings ### List Plugin Installation Settings `$ ant beta:organization:plugins:installation-settings list` **GET** `/v1/organizations/plugins/{plugin_id}/installation_settings` List an organization-owned Plugin's installation settings, which say which members it is for, most recently created first. The list holds the Plugin's own organization-wide setting (absent while the Plugin inherits its marketplace's default) and each RBAC Group's own setting. A member-owned Plugin has shares instead, so this path returns 404 for one. **Accepted credentials:** an Admin API key with the `read:plugins` or `read:org_audit` scope, or a Compliance Access Key with the `read:compliance_org_data` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `100`. minimum: 1, maximum: 100 - `--organization-id: optional string` (query parameter) For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. - `--page: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. maxLength: 2048 - `--target-type: optional "organization" or "rbac_group"` (query parameter) Only settings for this kind of target: `organization` (the organization-wide setting) or `rbac_group` (an RBAC Group's). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `BetaPluginInstallationSettingList: object` - `data: array of BetaPluginInstallationSetting` - `type: "plugin_installation_setting"` Always `plugin_installation_setting`. - `created_at: string` When the target was first given a setting for this Plugin. format: date-time - `installation_preference: "auto_install" or "available" or "not_available" or "required"` The setting the target holds for this Plugin. One of `required`, `auto_install`, `available`, `not_available`; a value this API does not yet name is returned as stored. - `"auto_install"` - `"available"` - `"not_available"` - `"required"` - `plugin_id: string` The Plugin's ID. - `target: BetaPluginTargetOrganization or BetaPluginTargetRBACGroup or BetaPluginTargetOrganizationMember` Whose setting this is: `organization` (the Plugin's own organization-wide setting) or `rbac_group` (one RBAC Group's own setting); `organization_member` does not occur here. - `beta_plugin_target_organization: object` - `type: "organization"` Every member of the organization. - `beta_plugin_target_rbac_group: object` - `type: "rbac_group"` An RBAC Group. - `rbac_group_id: string` The RBAC Group's ID. - `beta_plugin_target_organization_member: object` - `type: "organization_member"` One member of the organization. - `user_id: string` The member's User ID. - `updated_at: string` When its setting last changed. format: date-time - `next_page: string` Token to provide in as `page` in the subsequent request to retrieve the next page of data. #### Example ```bash ant beta:organization:plugins:installation-settings list \ --api-key my-anthropic-api-key \ --plugin-id plugin_id ``` ##### Response (200) ```json { "data": [ { "created_at": "2026-03-14T09:26:53.589793Z", "installation_preference": "required", "plugin_id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "target": { "type": "organization" }, "type": "plugin_installation_setting", "updated_at": "2026-03-14T09:26:53.589793Z" } ], "next_page": "page_MjAyNi0wOS0xNlQxNDowNTowOVo" } ``` ### Set Plugin Installation Setting `$ ant beta:organization:plugins:installation-settings set` **POST** `/v1/organizations/plugins/{plugin_id}/installation_settings/{target}` Set or change an organization-owned Plugin's installation setting for the whole organization or for one RBAC Group. Writing the value a target already holds of its own changes nothing. A member-owned Plugin has shares instead of installation settings, so this path returns 404 for one. Send a Plugin's installation-setting writes one at a time. If several writes for the same Plugin arrive at the same time, the server handles them one after another and can answer some of them with `503` instead of applying them. That `503` carries `x-should-retry: true`, and the write is safe to repeat: wait a second or two, then send it again. **Accepted credentials:** an Admin API key with the `write:plugins` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--target: string` (path parameter) The target whose setting is written: the literal `organization` for the Plugin's organization-wide setting, or an RBAC Group's ID (prefixed `rbac_group_`) for that group's own setting. Writing the `organization` target stops the Plugin from inheriting its marketplace's default, even when the value written equals that default. - `--installation-preference: "auto_install" or "available" or "not_available" or "required"` The installation setting the target is to hold for this Plugin: one of `required`, `auto_install`, `available`, `not_available`. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_plugin_installation_setting: object` The installation setting an organization-owned Plugin holds for one target. It has no ID of its own: it is addressed by the Plugin's ID and the target. - `type: "plugin_installation_setting"` Always `plugin_installation_setting`. - `created_at: string` When the target was first given a setting for this Plugin. format: date-time - `installation_preference: "auto_install" or "available" or "not_available" or "required"` The setting the target holds for this Plugin. One of `required`, `auto_install`, `available`, `not_available`; a value this API does not yet name is returned as stored. - `"auto_install"` - `"available"` - `"not_available"` - `"required"` - `plugin_id: string` The Plugin's ID. - `target: BetaPluginTargetOrganization or BetaPluginTargetRBACGroup or BetaPluginTargetOrganizationMember` Whose setting this is: `organization` (the Plugin's own organization-wide setting) or `rbac_group` (one RBAC Group's own setting); `organization_member` does not occur here. - `beta_plugin_target_organization: object` - `type: "organization"` Every member of the organization. - `beta_plugin_target_rbac_group: object` - `type: "rbac_group"` An RBAC Group. - `rbac_group_id: string` The RBAC Group's ID. - `beta_plugin_target_organization_member: object` - `type: "organization_member"` One member of the organization. - `user_id: string` The member's User ID. - `updated_at: string` When its setting last changed. format: date-time #### Example ```bash ant beta:organization:plugins:installation-settings set \ --api-key my-anthropic-api-key \ --plugin-id plugin_id \ --target target \ --installation-preference required ``` ##### Response (200) ```json { "created_at": "2026-03-14T09:26:53.589793Z", "installation_preference": "required", "plugin_id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "target": { "type": "organization" }, "type": "plugin_installation_setting", "updated_at": "2026-03-14T09:26:53.589793Z" } ``` ### Remove Plugin Installation Setting `$ ant beta:organization:plugins:installation-settings remove` **DELETE** `/v1/organizations/plugins/{plugin_id}/installation_settings/{target}` Remove an organization-owned Plugin's own installation setting for the whole organization or for one RBAC Group. Removing the `organization` target returns the Plugin to its marketplace's default installation setting and leaves the groups' settings in place. Removing a group's setting makes the group's members fall back to the Plugin's organization-wide setting or to the settings of their other groups. A target that holds no setting of its own returns 404 (a Plugin that already inherits its marketplace's default holds no `organization` setting), and so does a member-owned Plugin. A removal counts as one of the Plugin's installation-setting writes: send all of those writes one at a time. If several arrive for the same Plugin at the same time, the server handles them one after another and can answer some of them with `503` and `x-should-retry: true` instead of applying them; wait a second or two and send the removal again. A `404` on the repeat means the setting is already gone. **Accepted credentials:** an Admin API key with the `write:plugins` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--target: string` (path parameter) The target whose own setting is removed: the literal `organization` for the Plugin's organization-wide setting, or an RBAC Group's ID (prefixed `rbac_group_`) for that group's own setting. Removing the `organization` setting returns the Plugin to its marketplace's default. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_deleted_plugin_installation_setting: object` Confirmation that one target's installation setting was removed, naming the Plugin and the target in place of an ID. - `type: "plugin_installation_setting_deleted"` Always `plugin_installation_setting_deleted`. - `plugin_id: string` The Plugin's ID. - `target: BetaPluginTargetOrganization or BetaPluginTargetRBACGroup or BetaPluginTargetOrganizationMember` Whose setting was removed. - `beta_plugin_target_organization: object` - `type: "organization"` Every member of the organization. - `beta_plugin_target_rbac_group: object` - `type: "rbac_group"` An RBAC Group. - `rbac_group_id: string` The RBAC Group's ID. - `beta_plugin_target_organization_member: object` - `type: "organization_member"` One member of the organization. - `user_id: string` The member's User ID. #### Example ```bash ant beta:organization:plugins:installation-settings remove \ --api-key my-anthropic-api-key \ --plugin-id plugin_id \ --target target ``` ##### Response (200) ```json { "plugin_id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "target": { "rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF", "type": "rbac_group" }, "type": "plugin_installation_setting_deleted" } ``` ## Beta › Organization › Plugins › Shares ### List Plugin Shares `$ ant beta:organization:plugins:shares list` **GET** `/v1/organizations/plugins/{plugin_id}/shares` List the shares the owner of a member-owned Plugin has given — to every member of the organization, to an RBAC Group, or to one member — most recently granted first. Shares are read-only in this API: members give and withdraw them in claude.ai, and who gave a share is recorded on the Compliance API activity feed rather than on the share. An organization-owned Plugin has installation settings instead, so this path returns 404 for one. **Accepted credentials:** an Admin API key with the `read:plugins` or `read:org_audit` scope, or a Compliance Access Key with the `read:compliance_org_data` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--plugin-id: string` (path parameter) ID of the Plugin (prefixed `plugin_`). - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `100`. minimum: 1, maximum: 100 - `--organization-id: optional string` (query parameter) For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. - `--page: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. maxLength: 2048 - `--target-type: optional "organization" or "organization_member" or "rbac_group"` (query parameter) Only shares with this kind of target: `organization` (every member), `rbac_group` (one RBAC Group), or `organization_member` (one member). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `BetaPluginShareList: object` - `data: array of BetaPluginShare` - `type: "plugin_share"` Always `plugin_share`. - `granted_at: string` When the share was given; a share whose role is later changed in claude.ai is re-granted and carries the time of that change. format: date-time - `plugin_id: string` The Plugin's ID. - `target: BetaPluginTargetOrganization or BetaPluginTargetRBACGroup or BetaPluginTargetOrganizationMember` Who the Plugin is shared with: `organization` (every member), `rbac_group` (one RBAC Group), or `organization_member` (one member). - `beta_plugin_target_organization: object` - `type: "organization"` Every member of the organization. - `beta_plugin_target_rbac_group: object` - `type: "rbac_group"` An RBAC Group. - `rbac_group_id: string` The RBAC Group's ID. - `beta_plugin_target_organization_member: object` - `type: "organization_member"` One member of the organization. - `user_id: string` The member's User ID. - `next_page: string` Token to provide in as `page` in the subsequent request to retrieve the next page of data. #### Example ```bash ant beta:organization:plugins:shares list \ --api-key my-anthropic-api-key \ --plugin-id plugin_id ``` ##### Response (200) ```json { "data": [ { "granted_at": "2026-03-14T09:26:53.589793Z", "plugin_id": "plugin_01JyHfbRkZvD1gW7oTqXc3Ne", "target": { "type": "organization" }, "type": "plugin_share" } ], "next_page": "page_MjAyNi0wOS0xNlQxNDowNTowOVo" } ``` ## Beta › Organization › Plugin Marketplaces ### List Plugin Marketplaces `$ ant beta:organization:plugin-marketplaces list` **GET** `/v1/organizations/plugin_marketplaces` List the plugin marketplaces Plugins live in, newest first: the organization's own and its members' personal ones. Plugin marketplaces are created, connected to a repository and deleted in claude.ai, not through this API. The organization's library marketplace, the organization-owned `manual` marketplace that uploads go to when no marketplace is named, is created the first time something is put in it and is listed from then on. **Accepted credentials:** an Admin API key with the `read:plugins` or `read:org_audit` scope, or a Compliance Access Key with the `read:compliance_org_data` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--limit: optional number` (query parameter) Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. minimum: 1, maximum: 1000 - `--organization-id: optional string` (query parameter) For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. - `--owner-type: optional "organization" or "user"` (query parameter) `organization` for the organization's plugin marketplaces, `user` for members' personal plugin marketplaces. - `--page: optional string` (query parameter) Optionally set to the `next_page` token from the previous response. maxLength: 2048 - `--source: optional "directory" or "github" or "gitlab" or 2 more` (query parameter) Only plugin marketplaces with this `source`: `manual` for those whose Plugins are uploaded; `github`, `gitlab` or `public_git` for those synchronized from a Git repository. `directory` (Anthropic's catalog) is never listed here. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `BetaPluginMarketplaceList: object` - `data: array of BetaPluginMarketplace` - `type: "plugin_marketplace"` Always `plugin_marketplace`. - `id: string` The plugin marketplace's ID, prefixed `marketplace_`. - `created_at: string` RFC 3339. format: date-time - `default_installation_preference: "auto_install" or "available" or "not_available" or "required"` Organization plugin marketplace: the organization-wide setting every Plugin in it with no setting of its own gets. Null for a member's personal plugin marketplace. One of `required`, `auto_install`, `available`, `not_available`; a value this API does not yet name is returned as stored. - `"auto_install"` - `"available"` - `"not_available"` - `"required"` - `last_sync_ended_at: string` RFC 3339. When the most recent synchronization attempt to finish did so, whatever its outcome; for a repository plugin marketplace no synchronization has run on yet, when it was created. Null for a plugin marketplace that is not synchronized from a repository. format: date-time - `last_sync_read_sha: string` The commit the last synchronization attempt that reached the repository read, whether or not its content was then accepted (see `sync_status`); an attempt that ends `failed_auth` or `failed_transient` leaves it unchanged. Null until an attempt has first read the repository, and for a plugin marketplace that is not synchronized from a repository. - `name: string` Fixed for the plugin marketplace's lifetime. - `owner: BetaPluginOwnerOrganization or BetaPluginOwnerUser` The organization, or the member whose personal plugin marketplace it is. - `beta_plugin_owner_organization: object` - `type: "organization"` The Plugin lives in a plugin marketplace the organization owns. - `beta_plugin_owner_user: object` - `type: "user"` The Plugin lives in one member's personal plugin marketplace. - `user_id: string` The member's User ID. - `source: "directory" or "github" or "gitlab" or 2 more` Where the plugin marketplace's Plugins come from: `manual` when they are uploaded; `github`, `gitlab` or `public_git` when they are synchronized from the Git repository the owner connected, into which nothing can be uploaded; `directory` is Anthropic's own catalog, which this API does not list. A value this API does not yet name is returned as stored. - `"directory"` - `"github"` - `"gitlab"` - `"manual"` - `"public_git"` - `sync_status: "failed_auth" or "failed_content" or "failed_limits" or 3 more` Outcome of the plugin marketplace's most recent synchronization: one of `success`, `in_progress`, `failed_content`, `failed_transient`, `failed_auth`, `failed_limits`; a value this API does not yet name is returned as stored. Null until a synchronization is first attempted — so always for a `manual` plugin marketplace. - `"failed_auth"` - `"failed_content"` - `"failed_limits"` - `"failed_transient"` - `"in_progress"` - `"success"` - `next_page: string` Token to provide in as `page` in the subsequent request to retrieve the next page of data. #### Example ```bash ant beta:organization:plugin-marketplaces list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "marketplace_01HxQ3v9KpZ2mTn8RwLc4Ys7", "created_at": "2026-03-14T09:26:53.589793Z", "default_installation_preference": "available", "last_sync_ended_at": "2026-03-14T09:26:53.589793Z", "last_sync_read_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8", "name": "engineering-tools", "owner": { "type": "organization" }, "source": "github", "sync_status": "success", "type": "plugin_marketplace" } ], "next_page": "page_MjAyNi0wOS0xNlQxNDowNTowOVo" } ``` ### Get Plugin Marketplace `$ ant beta:organization:plugin-marketplaces retrieve` **GET** `/v1/organizations/plugin_marketplaces/{marketplace_id}` Retrieve a plugin marketplace by ID. **Accepted credentials:** an Admin API key with the `read:plugins` or `read:org_audit` scope, or a Compliance Access Key with the `read:compliance_org_data` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--marketplace-id: string` (path parameter) ID of the plugin marketplace (prefixed `marketplace_`). - `--organization-id: optional string` (query parameter) For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_plugin_marketplace: object` - `type: "plugin_marketplace"` Always `plugin_marketplace`. - `id: string` The plugin marketplace's ID, prefixed `marketplace_`. - `created_at: string` RFC 3339. format: date-time - `default_installation_preference: "auto_install" or "available" or "not_available" or "required"` Organization plugin marketplace: the organization-wide setting every Plugin in it with no setting of its own gets. Null for a member's personal plugin marketplace. One of `required`, `auto_install`, `available`, `not_available`; a value this API does not yet name is returned as stored. - `"auto_install"` - `"available"` - `"not_available"` - `"required"` - `last_sync_ended_at: string` RFC 3339. When the most recent synchronization attempt to finish did so, whatever its outcome; for a repository plugin marketplace no synchronization has run on yet, when it was created. Null for a plugin marketplace that is not synchronized from a repository. format: date-time - `last_sync_read_sha: string` The commit the last synchronization attempt that reached the repository read, whether or not its content was then accepted (see `sync_status`); an attempt that ends `failed_auth` or `failed_transient` leaves it unchanged. Null until an attempt has first read the repository, and for a plugin marketplace that is not synchronized from a repository. - `name: string` Fixed for the plugin marketplace's lifetime. - `owner: BetaPluginOwnerOrganization or BetaPluginOwnerUser` The organization, or the member whose personal plugin marketplace it is. - `beta_plugin_owner_organization: object` - `type: "organization"` The Plugin lives in a plugin marketplace the organization owns. - `beta_plugin_owner_user: object` - `type: "user"` The Plugin lives in one member's personal plugin marketplace. - `user_id: string` The member's User ID. - `source: "directory" or "github" or "gitlab" or 2 more` Where the plugin marketplace's Plugins come from: `manual` when they are uploaded; `github`, `gitlab` or `public_git` when they are synchronized from the Git repository the owner connected, into which nothing can be uploaded; `directory` is Anthropic's own catalog, which this API does not list. A value this API does not yet name is returned as stored. - `"directory"` - `"github"` - `"gitlab"` - `"manual"` - `"public_git"` - `sync_status: "failed_auth" or "failed_content" or "failed_limits" or 3 more` Outcome of the plugin marketplace's most recent synchronization: one of `success`, `in_progress`, `failed_content`, `failed_transient`, `failed_auth`, `failed_limits`; a value this API does not yet name is returned as stored. Null until a synchronization is first attempted — so always for a `manual` plugin marketplace. - `"failed_auth"` - `"failed_content"` - `"failed_limits"` - `"failed_transient"` - `"in_progress"` - `"success"` #### Example ```bash ant beta:organization:plugin-marketplaces retrieve \ --api-key my-anthropic-api-key \ --marketplace-id marketplace_id ``` ##### Response (200) ```json { "id": "marketplace_01HxQ3v9KpZ2mTn8RwLc4Ys7", "created_at": "2026-03-14T09:26:53.589793Z", "default_installation_preference": "available", "last_sync_ended_at": "2026-03-14T09:26:53.589793Z", "last_sync_read_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8", "name": "engineering-tools", "owner": { "type": "organization" }, "source": "github", "sync_status": "success", "type": "plugin_marketplace" } ``` ### Update Plugin Marketplace `$ ant beta:organization:plugin-marketplaces update` **POST** `/v1/organizations/plugin_marketplaces/{marketplace_id}` Set the default installation setting of one of the organization's own plugin marketplaces. Every Plugin in it without a setting of its own gets this default as its organization-wide setting, including Plugins added later. Pass it as `default_installation_preference`. A member's personal marketplace cannot be updated here (403). **Accepted credentials:** an Admin API key with the `write:plugins` scope. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--marketplace-id: string` (path parameter) ID of the plugin marketplace (prefixed `marketplace_`). - `--default-installation-preference: "auto_install" or "available" or "not_available" or "required"` The organization-wide installation setting every Plugin in the marketplace without one of its own gets: one of `required`, `auto_install`, `available`, `not_available`. Once set it can be changed but not removed. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_plugin_marketplace: object` - `type: "plugin_marketplace"` Always `plugin_marketplace`. - `id: string` The plugin marketplace's ID, prefixed `marketplace_`. - `created_at: string` RFC 3339. format: date-time - `default_installation_preference: "auto_install" or "available" or "not_available" or "required"` Organization plugin marketplace: the organization-wide setting every Plugin in it with no setting of its own gets. Null for a member's personal plugin marketplace. One of `required`, `auto_install`, `available`, `not_available`; a value this API does not yet name is returned as stored. - `"auto_install"` - `"available"` - `"not_available"` - `"required"` - `last_sync_ended_at: string` RFC 3339. When the most recent synchronization attempt to finish did so, whatever its outcome; for a repository plugin marketplace no synchronization has run on yet, when it was created. Null for a plugin marketplace that is not synchronized from a repository. format: date-time - `last_sync_read_sha: string` The commit the last synchronization attempt that reached the repository read, whether or not its content was then accepted (see `sync_status`); an attempt that ends `failed_auth` or `failed_transient` leaves it unchanged. Null until an attempt has first read the repository, and for a plugin marketplace that is not synchronized from a repository. - `name: string` Fixed for the plugin marketplace's lifetime. - `owner: BetaPluginOwnerOrganization or BetaPluginOwnerUser` The organization, or the member whose personal plugin marketplace it is. - `beta_plugin_owner_organization: object` - `type: "organization"` The Plugin lives in a plugin marketplace the organization owns. - `beta_plugin_owner_user: object` - `type: "user"` The Plugin lives in one member's personal plugin marketplace. - `user_id: string` The member's User ID. - `source: "directory" or "github" or "gitlab" or 2 more` Where the plugin marketplace's Plugins come from: `manual` when they are uploaded; `github`, `gitlab` or `public_git` when they are synchronized from the Git repository the owner connected, into which nothing can be uploaded; `directory` is Anthropic's own catalog, which this API does not list. A value this API does not yet name is returned as stored. - `"directory"` - `"github"` - `"gitlab"` - `"manual"` - `"public_git"` - `sync_status: "failed_auth" or "failed_content" or "failed_limits" or 3 more` Outcome of the plugin marketplace's most recent synchronization: one of `success`, `in_progress`, `failed_content`, `failed_transient`, `failed_auth`, `failed_limits`; a value this API does not yet name is returned as stored. Null until a synchronization is first attempted — so always for a `manual` plugin marketplace. - `"failed_auth"` - `"failed_content"` - `"failed_limits"` - `"failed_transient"` - `"in_progress"` - `"success"` #### Example ```bash ant beta:organization:plugin-marketplaces update \ --api-key my-anthropic-api-key \ --marketplace-id marketplace_id \ --default-installation-preference available ``` ##### Response (200) ```json { "id": "marketplace_01HxQ3v9KpZ2mTn8RwLc4Ys7", "created_at": "2026-03-14T09:26:53.589793Z", "default_installation_preference": "available", "last_sync_ended_at": "2026-03-14T09:26:53.589793Z", "last_sync_read_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8", "name": "engineering-tools", "owner": { "type": "organization" }, "source": "github", "sync_status": "success", "type": "plugin_marketplace" } ``` ### Validate Plugin Marketplace Repository `$ ant beta:organization:plugin-marketplaces validate-repository` **POST** `/v1/organizations/plugin_marketplaces/validate_repository` Check whether a plugin marketplace held in a public GitHub repository would synchronize into claude.ai, without connecting or storing it. To check a `.zip` of the marketplace directory instead, use Validate Plugin Marketplace Archive. The report says whether `marketplace.json` is well-formed, which plugins a synchronization would skip and why, and which plugins would synchronize only in part, with some files left out. A repository that is missing, private, or has no such branch or commit is reported, not refused: the response is a report with `valid: false`. Plugin sources outside the marketplace are fetched anonymously from GitHub, so a private one is reported as not found; a source on any other host is not fetched here, and the report notes that it will be checked when the marketplace actually synchronizes. Nothing is recorded on the Compliance API activity feed. For a worked example, see [Validate marketplace content](https://platform.claude.com/docs/en/manage-claude/plugins-api?sdk_languages=cli#validate-marketplace-content) in the Plugins API guide. **Accepted credentials:** an Admin API key with the `read:plugins` or `write:plugins` scope; `read:org_audit` and `read:compliance_org_data` do not grant it. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--repository-url: string` The `https://` URL of a public repository on github.com that holds the marketplace. A URL longer than 2,048 characters, on any other host or scheme, with a port other than 443 or 80, with credentials in it, or that does not name exactly `owner/repo` (a trailing `.git` or `/` is accepted) is a 400. A private or missing repository is reported in the response, not refused. minLength: 1 - `--ref: optional string` The branch to validate the tip of, or the full 40-character SHA of the commit to validate. When omitted, the branch a synchronization would read (usually the repository's default branch); if that is not the default branch, the report's `ref` says which branch was read. An empty string, a value longer than 255 characters, or one that contains `..` or a character other than ASCII letters, digits, `.`, `_`, `-`, `+`, and `/`, is a 400. Any other value that is not a 40-character SHA is read as a branch name; if the repository has no such branch, the response is a report with `valid: false`, not a 400. minLength: 1 - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_plugin_marketplace_validation_report: object` The outcome of validating plugin marketplace content: a report, not a stored object, so nothing in it can be retrieved afterwards. - `type: "plugin_marketplace_validation_report"` Always `plugin_marketplace_validation_report`. - `commit_sha: string` The full SHA of the commit that was validated: for a repository, the commit that was read; for an uploaded archive, the commit recorded in the archive's comment (as a Git host's download writes it; not verified), else null. - `manifest_error: string` Set when nothing could be validated: the repository or archive could not be read, or marketplace.json is missing, malformed or over a limit. Null otherwise. - `manifest_error_code: string` A stable identifier for `manifest_error`; null when that is. - `plugin_errors: array of BetaPluginMarketplaceValidationPluginError` One entry per plugin a synchronization would skip entirely, keyed by the plugin's name in marketplace.json. - `error: string` Why the plugin would be skipped by a synchronization. - `error_code: string` A stable identifier for the reason — the value to branch on. - `name: string` The plugin's name, as its entry in marketplace.json declares it. - `plugin_warnings: array of BetaPluginMarketplaceValidationPluginWarnings` One entry per plugin that would synchronize with some of its contents left out, keyed by the plugin's name in marketplace.json. - `name: string` The plugin's name, as its entry in marketplace.json declares it. - `warnings: array of BetaPluginMarketplaceValidationPluginWarning` The parts of the plugin a synchronization would leave out. - `error_code: string` A stable identifier for the kind of warning. - `message: string` What would be left out, and why. - `ref: string` For a repository, the branch that was read by name: the one requested, or else the branch a synchronization of this repository is set to read. Null when no branch is named or set and the repository's default branch was read, for a request by commit SHA, and for an uploaded archive. - `total_plugin_count: number` How many plugins marketplace.json declares; 0 when it could not be read. - `valid: boolean` True when marketplace.json is well-formed and no plugin would be skipped; warnings never make it false. #### Example ```bash ant beta:organization:plugin-marketplaces validate-repository \ --api-key my-anthropic-api-key \ --repository-url https://github.com/example-org/example-marketplace ``` ##### Response (200) ```json { "commit_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8", "manifest_error": "manifest_error", "manifest_error_code": "marketplace_sync_manifest_not_found", "plugin_errors": [ { "error": "error", "error_code": "marketplace_sync_plugin_missing_manifest", "name": "name" } ], "plugin_warnings": [ { "name": "name", "warnings": [ { "error_code": "marketplace_sync_zipball_symlink_dangling", "message": "message" } ] } ], "ref": "main", "total_plugin_count": 0, "type": "plugin_marketplace_validation_report", "valid": false } ``` ### Validate Plugin Marketplace Archive `$ ant beta:organization:plugin-marketplaces validate-archive` **POST** `/v1/organizations/plugin_marketplaces/validate_archive` Check whether a plugin marketplace, uploaded as a `.zip` of the marketplace directory, would synchronize into claude.ai, without connecting or storing it. To check a public GitHub repository instead, use Validate Plugin Marketplace Repository. The report says whether `marketplace.json` is well-formed, which plugins a synchronization would skip and why, and which plugins would synchronize only in part, with some files left out. An archive that cannot be read as a marketplace is reported, not refused: the response is a report with `valid: false`. Plugin sources outside the marketplace are fetched anonymously from GitHub, so a private one is reported as not found; a source on any other host is not fetched here, and the report notes that it will be checked when the marketplace actually synchronizes. Nothing is recorded on the Compliance API activity feed. For a worked example, see [Validate marketplace content](https://platform.claude.com/docs/en/manage-claude/plugins-api?sdk_languages=cli#validate-marketplace-content) in the Plugins API guide. **Accepted credentials:** an Admin API key with the `read:plugins` or `write:plugins` scope; `read:org_audit` and `read:compliance_org_data` do not grant it. Every request must include the beta header `anthropic-beta: ce-plugins-2026-09-01`. A request without it returns `404`, exactly as if the endpoint did not exist. The Plugins API is in beta and is available to Claude Enterprise organizations only. It is not available to Claude Platform (Claude Console) organizations, or to organizations with HIPAA readiness enabled. #### Parameters - `--archive: string` A .zip of the marketplace directory (its contents at the root, or wrapped in one folder as a Git host's download produces), sent as a file part with a filename; DEFLATE- or STORE-compressed, at most 32 MB. A part sent without a filename, a second archive part, or any other form field is a 400; a larger archive is a 413. format: binary - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `ce-plugins-2026-09-01` in this header. #### Returns - `beta_plugin_marketplace_validation_report: object` The outcome of validating plugin marketplace content: a report, not a stored object, so nothing in it can be retrieved afterwards. - `type: "plugin_marketplace_validation_report"` Always `plugin_marketplace_validation_report`. - `commit_sha: string` The full SHA of the commit that was validated: for a repository, the commit that was read; for an uploaded archive, the commit recorded in the archive's comment (as a Git host's download writes it; not verified), else null. - `manifest_error: string` Set when nothing could be validated: the repository or archive could not be read, or marketplace.json is missing, malformed or over a limit. Null otherwise. - `manifest_error_code: string` A stable identifier for `manifest_error`; null when that is. - `plugin_errors: array of BetaPluginMarketplaceValidationPluginError` One entry per plugin a synchronization would skip entirely, keyed by the plugin's name in marketplace.json. - `error: string` Why the plugin would be skipped by a synchronization. - `error_code: string` A stable identifier for the reason — the value to branch on. - `name: string` The plugin's name, as its entry in marketplace.json declares it. - `plugin_warnings: array of BetaPluginMarketplaceValidationPluginWarnings` One entry per plugin that would synchronize with some of its contents left out, keyed by the plugin's name in marketplace.json. - `name: string` The plugin's name, as its entry in marketplace.json declares it. - `warnings: array of BetaPluginMarketplaceValidationPluginWarning` The parts of the plugin a synchronization would leave out. - `error_code: string` A stable identifier for the kind of warning. - `message: string` What would be left out, and why. - `ref: string` For a repository, the branch that was read by name: the one requested, or else the branch a synchronization of this repository is set to read. Null when no branch is named or set and the repository's default branch was read, for a request by commit SHA, and for an uploaded archive. - `total_plugin_count: number` How many plugins marketplace.json declares; 0 when it could not be read. - `valid: boolean` True when marketplace.json is well-formed and no plugin would be skipped; warnings never make it false. #### Example ```bash ant beta:organization:plugin-marketplaces validate-archive \ --api-key my-anthropic-api-key \ --archive 'Example data' ``` ##### Response (200) ```json { "commit_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8", "manifest_error": "manifest_error", "manifest_error_code": "marketplace_sync_manifest_not_found", "plugin_errors": [ { "error": "error", "error_code": "marketplace_sync_plugin_missing_manifest", "name": "name" } ], "plugin_warnings": [ { "name": "name", "warnings": [ { "error_code": "marketplace_sync_zipball_symlink_dangling", "message": "message" } ] } ], "ref": "main", "total_plugin_count": 0, "type": "plugin_marketplace_validation_report", "valid": false } ``` ## Beta › Organization › Telemetry Destinations ### Create a Telemetry Destination `$ ant beta:organization:telemetry-destinations create` **POST** `/v1/organizations/telemetry_destinations` Register an OpenTelemetry destination for the organization. The destination starts in state `enabled`. An organization can have at most 10 destinations, including disabled ones. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#add-a-destination) to learn more about adding a destination. #### Parameters - `--endpoint-url: string` The base URL of your collector's OTLP/HTTP endpoint, for example `https://gateway.example.com`. The URL must use `https` and a hostname, not an IP address. The port, if given, must be 443. The URL must not contain a query string, a fragment, or a username and password. At most 2,048 characters. A path prefix, such as `/otlp`, is allowed. Don't include the per-signal path (`/v1/traces`), because the API appends it on delivery. If your collector takes traces on another path, also set `traces.endpoint_url`. minLength: 1, maxLength: 2048 - `--workspaces: BetaTelemetryDestinationWorkspacesAllParams or BetaTelemetryDestinationWorkspacesIncludeParams or BetaTelemetryDestinationWorkspacesExcludeParams` Which of the organization's workspaces the destination covers. - `--display-name: optional string` Human-readable name for the destination. Optional. 1 to 255 characters. - `--headers: optional map[string]` Request headers that the API sends with every delivery, typically your collector's authentication header (for example `authorization`). The API stores the values encrypted and never returns them. Reads show only `header_names`. At most 20 headers. Names are at most 128 characters. Two names can't differ only in case. Values are printable ASCII, at most 4,096 characters, and can't begin or end with a space. Names and values together are at most 16,384 bytes. Reserved names are rejected, for example `host`, `cookie`, `user-agent`, and names that start with `content-`, `proxy-`, `x-forwarded-`, or `anthropic-`. For this check, `_` in a name counts as `-`. - `--traces: optional object` The settings for the traces that the destination receives. If you leave it out, every setting takes its default. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `beta_telemetry_destination: object` An OpenTelemetry destination: an OTLP/HTTP endpoint, the request headers sent with every delivery to it, what the exported spans contain, and which workspaces it covers. A destination belongs to an organization. A workspace's spans go to every enabled destination that covers it. - `type: "telemetry_destination"` - `id: string` The unique ID of the destination (`tdst_...`). - `created_at: string` Time the destination was created. format: date-time - `delivery_health: object` The most recent delivery results for this destination. - `last_error: string` A message that describes the most recent failed delivery to the destination, or `null` if no delivery has failed yet. Examples are `temporary DNS failure`, `TLS failure`, `timeout`, `connection failure`, `invalid address`, `HTTP error (status 503)`, and `redirect (status 301)`. The message is `invalid address` both for a hostname that doesn't exist and for an address that isn't publicly routable. It never contains the endpoint's response body, a header value, a network address, or TLS details. `last_error` and `last_error_at` always change together. A later successful delivery doesn't clear them. If `last_success_at` is later than `last_error_at`, a delivery has succeeded since this failure. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#delivery-errors) to learn the likely cause of each error. - `last_error_at: string` Time of the failure that `last_error` describes. Changes together with `last_error`. Null until a delivery first fails. format: date-time - `last_success_at: string` Time of the most recent successful delivery to the destination, or `null` if no delivery has succeeded yet. format: date-time - `display_name: string` Human-readable name for the destination. Null when none was set. - `endpoint_url: string` The base URL of the destination's OTLP/HTTP endpoint, exactly as registered. The API appends the per-signal path, such as `/v1/traces`, on delivery, unless `traces.endpoint_url` is set. - `header_names: array of string` Names of the registered request headers. Header values are write-only and are never returned. - `state: BetaTelemetryDestinationStateEnabled or BetaTelemetryDestinationStateDisabled` Whether the destination receives deliveries. - `beta_telemetry_destination_state_enabled: object` The telemetry destination receives the spans of the workspaces that it covers. - `type: "enabled"` - `beta_telemetry_destination_state_disabled: object` The API doesn't deliver anything to the telemetry destination. Spans produced while it is disabled aren't delivered later. - `type: "disabled"` - `reason: BetaTelemetryDestinationDisabledReasonCaller or BetaTelemetryDestinationDisabledReasonSustainedFailure or BetaTelemetryDestinationDisabledReasonInvalidAddress or BetaTelemetryDestinationDisabledReasonRedirect` Whether a caller or the API disabled the destination and, when the API did, why. Read-only. - `beta_telemetry_destination_disabled_reason_caller: object` A caller disabled the destination with an update that set `state` to `disabled`. - `type: "caller"` - `beta_telemetry_destination_disabled_reason_sustained_failure: object` The API disabled the destination because deliveries to it failed, with no successful delivery in between, for longer than a threshold that Anthropic configures and that is not part of this contract. The reason is `invalid_address` instead when the most recent failed delivery failed with an invalid address. - `type: "sustained_failure"` - `beta_telemetry_destination_disabled_reason_invalid_address: object` The API disabled the destination because deliveries to it failed for longer than the same threshold as for `sustained_failure`, and the most recent failed delivery failed with an invalid address: the DNS answer says that the endpoint's hostname doesn't exist or doesn't have an address, or the address that the API would connect to isn't publicly routable or is reserved, for example a loopback, link-local, private-network, or cloud-metadata address. The API doesn't connect to such an address, and retries the delivery a bounded number of times as it does after a timeout. A timeout or a server failure of the DNS lookup is a temporary DNS failure instead, not an invalid address. - `type: "invalid_address"` - `beta_telemetry_destination_disabled_reason_redirect: object` The API disabled the destination because the endpoint answered a delivery with a 3xx status. Redirects are never followed, and one such answer disables the destination at once. - `type: "redirect"` - `traces: object` The destination's settings for the traces it receives. - `content_mode: "metadata_only" or "content"` What the exported spans contain. - `"metadata_only"` The spans contain identifiers, timing, status, token counts, and similar metadata. They don't contain prompt text, completion text, or tool inputs and outputs. - `"content"` The spans contain the same metadata as `metadata_only`, plus message and tool content. An organization with a data-handling restriction, such as under HIPAA, can't choose this mode. The API exports only metadata for such an organization, even to a destination that already has `content`. - `enabled: boolean` Whether the destination receives traces. A destination whose `enabled` is false keeps its other settings. - `endpoint_url: string` The full URL that the API posts traces to, exactly as registered, or `null` if the destination doesn't have one. When it is `null`, the API posts traces to `endpoint_url` with `/v1/traces` appended. - `max_content_bytes: number` The most bytes of content that one exported span can contain, or `null` if only the API's maximum applies. Content means model prompts and responses, and tool inputs and outputs. The API shortens longer content to this size before it delivers the span. A destination whose `content_mode` is `metadata_only` keeps this value. It applies once `content_mode` is `content`. format: int32 - `updated_at: string` Time of the last change to the destination's configuration or state. Changes to `delivery_health` don't change it. An update that sets a header value always changes it, even when the value is the same as before. Adding or removing a single workspace on the destination's list doesn't change it. An update that changes the list does. format: date-time - `workspaces: BetaTelemetryDestinationWorkspacesAll or BetaTelemetryDestinationWorkspacesInclude or BetaTelemetryDestinationWorkspacesExclude` Which of the organization's workspaces the destination covers. - `beta_telemetry_destination_workspaces_all: object` The destination covers every workspace of the organization, including the default workspace, archived workspaces, and workspaces created later. It doesn't have a list. - `type: "all"` - `beta_telemetry_destination_workspaces_include: object` The destination covers the workspaces on its list, and no others. - `type: "include"` - `beta_telemetry_destination_workspaces_exclude: object` The destination covers every workspace of the organization except the workspaces on its list. A workspace created later is covered until it is added to the list. - `type: "exclude"` #### Example ```bash ant beta:organization:telemetry-destinations create \ --api-key my-anthropic-api-key \ --endpoint-url x \ --workspaces '{type: all}' ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "delivery_health": { "last_error": "last_error", "last_error_at": "2019-12-27T18:11:19.117Z", "last_success_at": "2019-12-27T18:11:19.117Z" }, "display_name": "display_name", "endpoint_url": "endpoint_url", "header_names": [ "string" ], "state": { "type": "enabled" }, "traces": { "content_mode": "metadata_only", "enabled": true, "endpoint_url": "endpoint_url", "max_content_bytes": 0 }, "type": "telemetry_destination", "updated_at": "2019-12-27T18:11:19.117Z", "workspaces": { "type": "all" } } ``` ### List Telemetry Destinations `$ ant beta:organization:telemetry-destinations list` **GET** `/v1/organizations/telemetry_destinations` List the organization's destinations, newest first, optionally only those that cover given workspaces. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#set-up-api-tracing) to learn more about destinations. #### Parameters - `--limit: optional number` (query parameter) Number of destinations to return per page, between 1 and 1,000. Defaults to 20. format: int32 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. Leave it out to get the first page. - `--workspace-id: optional array of string` (query parameter) Return only the destinations that cover at least one of these workspaces (`wrkspc_...`). Send at most 100 IDs, as `workspace_ids[]`. A destination covers a workspace when its `workspaces.type` is `all`, when its `include` list has the workspace, or when its `exclude` list doesn't have it. Destinations in either state can match. An ID that isn't the ID of one of the organization's workspaces doesn't match any destination, not even one whose type is `all`. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `BetaListTelemetryDestinationsResponse: object` A page of the organization's telemetry destinations, newest first. - `data: array of BetaTelemetryDestination` Destinations on this page, newest first. - `type: "telemetry_destination"` - `id: string` The unique ID of the destination (`tdst_...`). - `created_at: string` Time the destination was created. format: date-time - `delivery_health: object` The most recent delivery results for this destination. - `last_error: string` A message that describes the most recent failed delivery to the destination, or `null` if no delivery has failed yet. Examples are `temporary DNS failure`, `TLS failure`, `timeout`, `connection failure`, `invalid address`, `HTTP error (status 503)`, and `redirect (status 301)`. The message is `invalid address` both for a hostname that doesn't exist and for an address that isn't publicly routable. It never contains the endpoint's response body, a header value, a network address, or TLS details. `last_error` and `last_error_at` always change together. A later successful delivery doesn't clear them. If `last_success_at` is later than `last_error_at`, a delivery has succeeded since this failure. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#delivery-errors) to learn the likely cause of each error. - `last_error_at: string` Time of the failure that `last_error` describes. Changes together with `last_error`. Null until a delivery first fails. format: date-time - `last_success_at: string` Time of the most recent successful delivery to the destination, or `null` if no delivery has succeeded yet. format: date-time - `display_name: string` Human-readable name for the destination. Null when none was set. - `endpoint_url: string` The base URL of the destination's OTLP/HTTP endpoint, exactly as registered. The API appends the per-signal path, such as `/v1/traces`, on delivery, unless `traces.endpoint_url` is set. - `header_names: array of string` Names of the registered request headers. Header values are write-only and are never returned. - `state: BetaTelemetryDestinationStateEnabled or BetaTelemetryDestinationStateDisabled` Whether the destination receives deliveries. - `beta_telemetry_destination_state_enabled: object` The telemetry destination receives the spans of the workspaces that it covers. - `type: "enabled"` - `beta_telemetry_destination_state_disabled: object` The API doesn't deliver anything to the telemetry destination. Spans produced while it is disabled aren't delivered later. - `type: "disabled"` - `reason: BetaTelemetryDestinationDisabledReasonCaller or BetaTelemetryDestinationDisabledReasonSustainedFailure or BetaTelemetryDestinationDisabledReasonInvalidAddress or BetaTelemetryDestinationDisabledReasonRedirect` Whether a caller or the API disabled the destination and, when the API did, why. Read-only. - `beta_telemetry_destination_disabled_reason_caller: object` A caller disabled the destination with an update that set `state` to `disabled`. - `type: "caller"` - `beta_telemetry_destination_disabled_reason_sustained_failure: object` The API disabled the destination because deliveries to it failed, with no successful delivery in between, for longer than a threshold that Anthropic configures and that is not part of this contract. The reason is `invalid_address` instead when the most recent failed delivery failed with an invalid address. - `type: "sustained_failure"` - `beta_telemetry_destination_disabled_reason_invalid_address: object` The API disabled the destination because deliveries to it failed for longer than the same threshold as for `sustained_failure`, and the most recent failed delivery failed with an invalid address: the DNS answer says that the endpoint's hostname doesn't exist or doesn't have an address, or the address that the API would connect to isn't publicly routable or is reserved, for example a loopback, link-local, private-network, or cloud-metadata address. The API doesn't connect to such an address, and retries the delivery a bounded number of times as it does after a timeout. A timeout or a server failure of the DNS lookup is a temporary DNS failure instead, not an invalid address. - `type: "invalid_address"` - `beta_telemetry_destination_disabled_reason_redirect: object` The API disabled the destination because the endpoint answered a delivery with a 3xx status. Redirects are never followed, and one such answer disables the destination at once. - `type: "redirect"` - `traces: object` The destination's settings for the traces it receives. - `content_mode: "metadata_only" or "content"` What the exported spans contain. - `"metadata_only"` The spans contain identifiers, timing, status, token counts, and similar metadata. They don't contain prompt text, completion text, or tool inputs and outputs. - `"content"` The spans contain the same metadata as `metadata_only`, plus message and tool content. An organization with a data-handling restriction, such as under HIPAA, can't choose this mode. The API exports only metadata for such an organization, even to a destination that already has `content`. - `enabled: boolean` Whether the destination receives traces. A destination whose `enabled` is false keeps its other settings. - `endpoint_url: string` The full URL that the API posts traces to, exactly as registered, or `null` if the destination doesn't have one. When it is `null`, the API posts traces to `endpoint_url` with `/v1/traces` appended. - `max_content_bytes: number` The most bytes of content that one exported span can contain, or `null` if only the API's maximum applies. Content means model prompts and responses, and tool inputs and outputs. The API shortens longer content to this size before it delivers the span. A destination whose `content_mode` is `metadata_only` keeps this value. It applies once `content_mode` is `content`. format: int32 - `updated_at: string` Time of the last change to the destination's configuration or state. Changes to `delivery_health` don't change it. An update that sets a header value always changes it, even when the value is the same as before. Adding or removing a single workspace on the destination's list doesn't change it. An update that changes the list does. format: date-time - `workspaces: BetaTelemetryDestinationWorkspacesAll or BetaTelemetryDestinationWorkspacesInclude or BetaTelemetryDestinationWorkspacesExclude` Which of the organization's workspaces the destination covers. - `beta_telemetry_destination_workspaces_all: object` The destination covers every workspace of the organization, including the default workspace, archived workspaces, and workspaces created later. It doesn't have a list. - `type: "all"` - `beta_telemetry_destination_workspaces_include: object` The destination covers the workspaces on its list, and no others. - `type: "include"` - `beta_telemetry_destination_workspaces_exclude: object` The destination covers every workspace of the organization except the workspaces on its list. A workspace created later is covered until it is added to the list. - `type: "exclude"` - `next_page: string` Cursor for the next page. Null on the last page. #### Example ```bash ant beta:organization:telemetry-destinations list \ --api-key my-anthropic-api-key ``` ##### Response (200) ```json { "data": [ { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "delivery_health": { "last_error": "last_error", "last_error_at": "2019-12-27T18:11:19.117Z", "last_success_at": "2019-12-27T18:11:19.117Z" }, "display_name": "display_name", "endpoint_url": "endpoint_url", "header_names": [ "string" ], "state": { "type": "enabled" }, "traces": { "content_mode": "metadata_only", "enabled": true, "endpoint_url": "endpoint_url", "max_content_bytes": 0 }, "type": "telemetry_destination", "updated_at": "2019-12-27T18:11:19.117Z", "workspaces": { "type": "all" } } ], "next_page": "next_page" } ``` ### Retrieve a Telemetry Destination `$ ant beta:organization:telemetry-destinations retrieve` **GET** `/v1/organizations/telemetry_destinations/{destination_id}` Read a destination's configuration, state, and most recent delivery results. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#delivery-and-health) to learn how the API delivers spans and when it disables a destination. #### Parameters - `--destination-id: string` (path parameter) ID of the destination (`tdst_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `beta_telemetry_destination: object` An OpenTelemetry destination: an OTLP/HTTP endpoint, the request headers sent with every delivery to it, what the exported spans contain, and which workspaces it covers. A destination belongs to an organization. A workspace's spans go to every enabled destination that covers it. - `type: "telemetry_destination"` - `id: string` The unique ID of the destination (`tdst_...`). - `created_at: string` Time the destination was created. format: date-time - `delivery_health: object` The most recent delivery results for this destination. - `last_error: string` A message that describes the most recent failed delivery to the destination, or `null` if no delivery has failed yet. Examples are `temporary DNS failure`, `TLS failure`, `timeout`, `connection failure`, `invalid address`, `HTTP error (status 503)`, and `redirect (status 301)`. The message is `invalid address` both for a hostname that doesn't exist and for an address that isn't publicly routable. It never contains the endpoint's response body, a header value, a network address, or TLS details. `last_error` and `last_error_at` always change together. A later successful delivery doesn't clear them. If `last_success_at` is later than `last_error_at`, a delivery has succeeded since this failure. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#delivery-errors) to learn the likely cause of each error. - `last_error_at: string` Time of the failure that `last_error` describes. Changes together with `last_error`. Null until a delivery first fails. format: date-time - `last_success_at: string` Time of the most recent successful delivery to the destination, or `null` if no delivery has succeeded yet. format: date-time - `display_name: string` Human-readable name for the destination. Null when none was set. - `endpoint_url: string` The base URL of the destination's OTLP/HTTP endpoint, exactly as registered. The API appends the per-signal path, such as `/v1/traces`, on delivery, unless `traces.endpoint_url` is set. - `header_names: array of string` Names of the registered request headers. Header values are write-only and are never returned. - `state: BetaTelemetryDestinationStateEnabled or BetaTelemetryDestinationStateDisabled` Whether the destination receives deliveries. - `beta_telemetry_destination_state_enabled: object` The telemetry destination receives the spans of the workspaces that it covers. - `type: "enabled"` - `beta_telemetry_destination_state_disabled: object` The API doesn't deliver anything to the telemetry destination. Spans produced while it is disabled aren't delivered later. - `type: "disabled"` - `reason: BetaTelemetryDestinationDisabledReasonCaller or BetaTelemetryDestinationDisabledReasonSustainedFailure or BetaTelemetryDestinationDisabledReasonInvalidAddress or BetaTelemetryDestinationDisabledReasonRedirect` Whether a caller or the API disabled the destination and, when the API did, why. Read-only. - `beta_telemetry_destination_disabled_reason_caller: object` A caller disabled the destination with an update that set `state` to `disabled`. - `type: "caller"` - `beta_telemetry_destination_disabled_reason_sustained_failure: object` The API disabled the destination because deliveries to it failed, with no successful delivery in between, for longer than a threshold that Anthropic configures and that is not part of this contract. The reason is `invalid_address` instead when the most recent failed delivery failed with an invalid address. - `type: "sustained_failure"` - `beta_telemetry_destination_disabled_reason_invalid_address: object` The API disabled the destination because deliveries to it failed for longer than the same threshold as for `sustained_failure`, and the most recent failed delivery failed with an invalid address: the DNS answer says that the endpoint's hostname doesn't exist or doesn't have an address, or the address that the API would connect to isn't publicly routable or is reserved, for example a loopback, link-local, private-network, or cloud-metadata address. The API doesn't connect to such an address, and retries the delivery a bounded number of times as it does after a timeout. A timeout or a server failure of the DNS lookup is a temporary DNS failure instead, not an invalid address. - `type: "invalid_address"` - `beta_telemetry_destination_disabled_reason_redirect: object` The API disabled the destination because the endpoint answered a delivery with a 3xx status. Redirects are never followed, and one such answer disables the destination at once. - `type: "redirect"` - `traces: object` The destination's settings for the traces it receives. - `content_mode: "metadata_only" or "content"` What the exported spans contain. - `"metadata_only"` The spans contain identifiers, timing, status, token counts, and similar metadata. They don't contain prompt text, completion text, or tool inputs and outputs. - `"content"` The spans contain the same metadata as `metadata_only`, plus message and tool content. An organization with a data-handling restriction, such as under HIPAA, can't choose this mode. The API exports only metadata for such an organization, even to a destination that already has `content`. - `enabled: boolean` Whether the destination receives traces. A destination whose `enabled` is false keeps its other settings. - `endpoint_url: string` The full URL that the API posts traces to, exactly as registered, or `null` if the destination doesn't have one. When it is `null`, the API posts traces to `endpoint_url` with `/v1/traces` appended. - `max_content_bytes: number` The most bytes of content that one exported span can contain, or `null` if only the API's maximum applies. Content means model prompts and responses, and tool inputs and outputs. The API shortens longer content to this size before it delivers the span. A destination whose `content_mode` is `metadata_only` keeps this value. It applies once `content_mode` is `content`. format: int32 - `updated_at: string` Time of the last change to the destination's configuration or state. Changes to `delivery_health` don't change it. An update that sets a header value always changes it, even when the value is the same as before. Adding or removing a single workspace on the destination's list doesn't change it. An update that changes the list does. format: date-time - `workspaces: BetaTelemetryDestinationWorkspacesAll or BetaTelemetryDestinationWorkspacesInclude or BetaTelemetryDestinationWorkspacesExclude` Which of the organization's workspaces the destination covers. - `beta_telemetry_destination_workspaces_all: object` The destination covers every workspace of the organization, including the default workspace, archived workspaces, and workspaces created later. It doesn't have a list. - `type: "all"` - `beta_telemetry_destination_workspaces_include: object` The destination covers the workspaces on its list, and no others. - `type: "include"` - `beta_telemetry_destination_workspaces_exclude: object` The destination covers every workspace of the organization except the workspaces on its list. A workspace created later is covered until it is added to the list. - `type: "exclude"` #### Example ```bash ant beta:organization:telemetry-destinations retrieve \ --api-key my-anthropic-api-key \ --destination-id destination_id ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "delivery_health": { "last_error": "last_error", "last_error_at": "2019-12-27T18:11:19.117Z", "last_success_at": "2019-12-27T18:11:19.117Z" }, "display_name": "display_name", "endpoint_url": "endpoint_url", "header_names": [ "string" ], "state": { "type": "enabled" }, "traces": { "content_mode": "metadata_only", "enabled": true, "endpoint_url": "endpoint_url", "max_content_bytes": 0 }, "type": "telemetry_destination", "updated_at": "2019-12-27T18:11:19.117Z", "workspaces": { "type": "all" } } ``` ### Update a Telemetry Destination `$ ant beta:organization:telemetry-destinations update` **POST** `/v1/organizations/telemetry_destinations/{destination_id}` Change a telemetry destination's settings, its state, or which workspaces it covers. Send at least one field. Omitted fields keep their stored values, except the registered headers, which a change of the endpoint's hostname or port removes. Only `display_name`, `traces`, `traces.endpoint_url`, `traces.content_mode`, `traces.max_content_bytes`, and individual `headers` values accept `null`. If another request changes the destination while the update runs, the API returns a 409 `conflict_error`. Read the destination again, then retry the update. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#delivery-and-health) to learn more about changing a destination. #### Parameters - `--destination-id: string` (path parameter) ID of the destination (`tdst_...`). - `--display-name: optional string` New human-readable name, 1 to 255 characters. Null clears it. - `--endpoint-url: optional string` The new base URL of the destination's OTLP/HTTP endpoint. The same rules as on create apply. A change of hostname or port first removes every registered header, so send the headers for the new endpoint in the same request. When the destination has a `traces.endpoint_url`, such a change must also set `traces.endpoint_url` to a URL with the new hostname and port, or to `null`. A change of the path alone keeps the headers. maxLength: 2048 - `--headers: optional map[string]` Headers to set or remove. The API merges them into the destination's headers by name. Names compare case-insensitively. A string value sets or replaces that header. A `null` value removes it. Headers that you omit don't change. The field itself can't be `null`. A request that sets a header value must also include `endpoint_url`. The current URL is accepted. The resulting set must stay within the same limits as on create. When the request sets a value, each stored value that it doesn't set counts as 4,096 bytes toward the 16,384-byte limit, because you can't read its real length. So to change one header of a destination that has four or more other headers, send the values of the others again in the same request. - `--state: optional BetaTelemetryDestinationStateEnabledParams or BetaTelemetryDestinationStateDisabledParams` Whether the destination receives deliveries after the update. The field can't be `null`. - `--traces: optional object` The traces settings to change. Omitted settings keep their stored values. `null` sets every traces setting to its create default. - `--workspaces: optional BetaTelemetryDestinationWorkspacesAllParams or BetaTelemetryDestinationWorkspacesIncludeParams or BetaTelemetryDestinationWorkspacesExcludeParams` The new workspace scope, in the same form as on create. The field can't be `null`. The API refuses an update that changes the type or sends `workspace_ids` while the destination's list has more than 750 workspaces. Remove workspaces one at a time until 750 or fewer remain, then send the update again. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `beta_telemetry_destination: object` An OpenTelemetry destination: an OTLP/HTTP endpoint, the request headers sent with every delivery to it, what the exported spans contain, and which workspaces it covers. A destination belongs to an organization. A workspace's spans go to every enabled destination that covers it. - `type: "telemetry_destination"` - `id: string` The unique ID of the destination (`tdst_...`). - `created_at: string` Time the destination was created. format: date-time - `delivery_health: object` The most recent delivery results for this destination. - `last_error: string` A message that describes the most recent failed delivery to the destination, or `null` if no delivery has failed yet. Examples are `temporary DNS failure`, `TLS failure`, `timeout`, `connection failure`, `invalid address`, `HTTP error (status 503)`, and `redirect (status 301)`. The message is `invalid address` both for a hostname that doesn't exist and for an address that isn't publicly routable. It never contains the endpoint's response body, a header value, a network address, or TLS details. `last_error` and `last_error_at` always change together. A later successful delivery doesn't clear them. If `last_success_at` is later than `last_error_at`, a delivery has succeeded since this failure. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#delivery-errors) to learn the likely cause of each error. - `last_error_at: string` Time of the failure that `last_error` describes. Changes together with `last_error`. Null until a delivery first fails. format: date-time - `last_success_at: string` Time of the most recent successful delivery to the destination, or `null` if no delivery has succeeded yet. format: date-time - `display_name: string` Human-readable name for the destination. Null when none was set. - `endpoint_url: string` The base URL of the destination's OTLP/HTTP endpoint, exactly as registered. The API appends the per-signal path, such as `/v1/traces`, on delivery, unless `traces.endpoint_url` is set. - `header_names: array of string` Names of the registered request headers. Header values are write-only and are never returned. - `state: BetaTelemetryDestinationStateEnabled or BetaTelemetryDestinationStateDisabled` Whether the destination receives deliveries. - `beta_telemetry_destination_state_enabled: object` The telemetry destination receives the spans of the workspaces that it covers. - `type: "enabled"` - `beta_telemetry_destination_state_disabled: object` The API doesn't deliver anything to the telemetry destination. Spans produced while it is disabled aren't delivered later. - `type: "disabled"` - `reason: BetaTelemetryDestinationDisabledReasonCaller or BetaTelemetryDestinationDisabledReasonSustainedFailure or BetaTelemetryDestinationDisabledReasonInvalidAddress or BetaTelemetryDestinationDisabledReasonRedirect` Whether a caller or the API disabled the destination and, when the API did, why. Read-only. - `beta_telemetry_destination_disabled_reason_caller: object` A caller disabled the destination with an update that set `state` to `disabled`. - `type: "caller"` - `beta_telemetry_destination_disabled_reason_sustained_failure: object` The API disabled the destination because deliveries to it failed, with no successful delivery in between, for longer than a threshold that Anthropic configures and that is not part of this contract. The reason is `invalid_address` instead when the most recent failed delivery failed with an invalid address. - `type: "sustained_failure"` - `beta_telemetry_destination_disabled_reason_invalid_address: object` The API disabled the destination because deliveries to it failed for longer than the same threshold as for `sustained_failure`, and the most recent failed delivery failed with an invalid address: the DNS answer says that the endpoint's hostname doesn't exist or doesn't have an address, or the address that the API would connect to isn't publicly routable or is reserved, for example a loopback, link-local, private-network, or cloud-metadata address. The API doesn't connect to such an address, and retries the delivery a bounded number of times as it does after a timeout. A timeout or a server failure of the DNS lookup is a temporary DNS failure instead, not an invalid address. - `type: "invalid_address"` - `beta_telemetry_destination_disabled_reason_redirect: object` The API disabled the destination because the endpoint answered a delivery with a 3xx status. Redirects are never followed, and one such answer disables the destination at once. - `type: "redirect"` - `traces: object` The destination's settings for the traces it receives. - `content_mode: "metadata_only" or "content"` What the exported spans contain. - `"metadata_only"` The spans contain identifiers, timing, status, token counts, and similar metadata. They don't contain prompt text, completion text, or tool inputs and outputs. - `"content"` The spans contain the same metadata as `metadata_only`, plus message and tool content. An organization with a data-handling restriction, such as under HIPAA, can't choose this mode. The API exports only metadata for such an organization, even to a destination that already has `content`. - `enabled: boolean` Whether the destination receives traces. A destination whose `enabled` is false keeps its other settings. - `endpoint_url: string` The full URL that the API posts traces to, exactly as registered, or `null` if the destination doesn't have one. When it is `null`, the API posts traces to `endpoint_url` with `/v1/traces` appended. - `max_content_bytes: number` The most bytes of content that one exported span can contain, or `null` if only the API's maximum applies. Content means model prompts and responses, and tool inputs and outputs. The API shortens longer content to this size before it delivers the span. A destination whose `content_mode` is `metadata_only` keeps this value. It applies once `content_mode` is `content`. format: int32 - `updated_at: string` Time of the last change to the destination's configuration or state. Changes to `delivery_health` don't change it. An update that sets a header value always changes it, even when the value is the same as before. Adding or removing a single workspace on the destination's list doesn't change it. An update that changes the list does. format: date-time - `workspaces: BetaTelemetryDestinationWorkspacesAll or BetaTelemetryDestinationWorkspacesInclude or BetaTelemetryDestinationWorkspacesExclude` Which of the organization's workspaces the destination covers. - `beta_telemetry_destination_workspaces_all: object` The destination covers every workspace of the organization, including the default workspace, archived workspaces, and workspaces created later. It doesn't have a list. - `type: "all"` - `beta_telemetry_destination_workspaces_include: object` The destination covers the workspaces on its list, and no others. - `type: "include"` - `beta_telemetry_destination_workspaces_exclude: object` The destination covers every workspace of the organization except the workspaces on its list. A workspace created later is covered until it is added to the list. - `type: "exclude"` #### Example ```bash ant beta:organization:telemetry-destinations update \ --api-key my-anthropic-api-key \ --destination-id destination_id ``` ##### Response (200) ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "delivery_health": { "last_error": "last_error", "last_error_at": "2019-12-27T18:11:19.117Z", "last_success_at": "2019-12-27T18:11:19.117Z" }, "display_name": "display_name", "endpoint_url": "endpoint_url", "header_names": [ "string" ], "state": { "type": "enabled" }, "traces": { "content_mode": "metadata_only", "enabled": true, "endpoint_url": "endpoint_url", "max_content_bytes": 0 }, "type": "telemetry_destination", "updated_at": "2019-12-27T18:11:19.117Z", "workspaces": { "type": "all" } } ``` ### Delete a Telemetry Destination `$ ant beta:organization:telemetry-destinations delete` **DELETE** `/v1/organizations/telemetry_destinations/{destination_id}` Delete a destination and its workspace list. The API stops sending spans to the destination. The spans of the workspaces it covered still go to the other destinations that cover them. A deleted destination can't be read, listed, or restored. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#delivery-and-health) to learn more about managing a destination. #### Parameters - `--destination-id: string` (path parameter) ID of the destination (`tdst_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `beta_deleted_telemetry_destination: object` Confirmation that a destination was deleted. - `type: "telemetry_destination_deleted"` - `id: string` ID of the deleted destination (`tdst_...`). #### Example ```bash ant beta:organization:telemetry-destinations delete \ --api-key my-anthropic-api-key \ --destination-id destination_id ``` ##### Response (200) ```json { "id": "id", "type": "telemetry_destination_deleted" } ``` ### Test a Telemetry Destination `$ ant beta:organization:telemetry-destinations test` **POST** `/v1/organizations/telemetry_destinations/{destination_id}/test` Send one test span, named `anthropic.test`, to the destination with its registered headers, once and without retries, and report the destination's answer. The response is 200 whether or not the destination answered with a 2xx status: its `result` has the type `success`, or the type `failure` and the reason in `error`. The destination's configuration, `state` and `delivery_health` do not change. A disabled destination can be tested too. Wait 10 seconds between tests of one destination; a request that comes sooner may be answered with status 429. #### Parameters - `--destination-id: string` (path parameter) ID of the destination to test (starts with `tdst_`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `beta_telemetry_destination_test_response: object` The result of one test span sent to a destination. - `type: "telemetry_destination_test"` - `result: BetaTelemetryDestinationTestSuccess or BetaTelemetryDestinationTestFailure` How the test went: `success` when the destination answered with a 2xx status, else `failure` with the reason. - `beta_telemetry_destination_test_success: object` The destination answered the test span with a 2xx status. - `type: "success"` - `beta_telemetry_destination_test_failure: object` The test span was not delivered. - `type: "failure"` - `error: string` A message that describes why the test span was not delivered, including the HTTP status code when the destination returned one. Examples: `HTTP error (status 403)`, `timeout`, `TLS failure`. It has the same form as the destination's `delivery_health.last_error` and never contains the destination's response body, any header value, a network address, or TLS details. #### Example ```bash ant beta:organization:telemetry-destinations test \ --api-key my-anthropic-api-key \ --destination-id destination_id ``` ##### Response (200) ```json { "result": { "type": "success" }, "type": "telemetry_destination_test" } ``` ## Beta › Organization › Telemetry Destinations › Workspaces ### List Telemetry Destination Workspaces `$ ant beta:organization:telemetry-destinations:workspaces list` **GET** `/v1/organizations/telemetry_destinations/{destination_id}/workspaces` List the workspaces on a destination's workspace list, newest entry first. A destination whose `workspaces.type` is `all` doesn't have a list, so its page is empty. The list includes archived workspaces. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#choose-workspaces-for-a-destination) to learn more about choosing the workspaces of a destination. #### Parameters - `--destination-id: string` (path parameter) ID of the destination (`tdst_...`). - `--limit: optional number` (query parameter) Number of entries to return per page, between 1 and 1,000. Defaults to 20. format: int32 - `--page: optional string` (query parameter) Opaque cursor from a previous response's `next_page`. Leave it out to get the first page. - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `BetaListTelemetryDestinationWorkspacesResponse: object` A page of a telemetry destination's workspace list, newest entry first. - `data: array of BetaTelemetryDestinationWorkspace` Entries on this page, newest first. - `type: "telemetry_destination_workspace"` - `created_at: string` Time the workspace was added to the list. format: date-time - `telemetry_destination_id: string` ID of the telemetry destination (`tdst_...`). - `workspace_id: string` ID of the workspace (`wrkspc_...`). - `next_page: string` Cursor for the next page. Null on the last page. #### Example ```bash ant beta:organization:telemetry-destinations:workspaces list \ --api-key my-anthropic-api-key \ --destination-id destination_id ``` ##### Response (200) ```json { "data": [ { "created_at": "2019-12-27T18:11:19.117Z", "telemetry_destination_id": "telemetry_destination_id", "type": "telemetry_destination_workspace", "workspace_id": "workspace_id" } ], "next_page": "next_page" } ``` ### Add a Telemetry Destination Workspace `$ ant beta:organization:telemetry-destinations:workspaces add` **POST** `/v1/organizations/telemetry_destinations/{destination_id}/workspaces/{workspace_id}` Add one workspace to a destination's workspace list. Under `include` the workspace's spans start going to the destination. Under `exclude` they stop. A list holds at most 1,000 workspaces. Adding a workspace that is already on the list changes nothing and returns the existing entry. An archived workspace that isn't on the list yet can't be added. A destination whose `workspaces.type` is `all` doesn't have a list, so the API returns 400. To change which workspaces such a destination covers, update its `workspaces`. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#choose-workspaces-for-a-destination) to learn more about choosing the workspaces of a destination. #### Parameters - `--destination-id: string` (path parameter) ID of the destination (`tdst_...`). - `--workspace-id: string` (path parameter) ID of the workspace to add (`wrkspc_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `beta_telemetry_destination_workspace: object` A workspace on a telemetry destination's workspace list. Under `include`, the destination covers the workspace. Under `exclude`, the destination covers every workspace except this one. The entry doesn't have an `id`. Its `telemetry_destination_id` and `workspace_id` together identify it. - `type: "telemetry_destination_workspace"` - `created_at: string` Time the workspace was added to the list. format: date-time - `telemetry_destination_id: string` ID of the telemetry destination (`tdst_...`). - `workspace_id: string` ID of the workspace (`wrkspc_...`). #### Example ```bash ant beta:organization:telemetry-destinations:workspaces add \ --api-key my-anthropic-api-key \ --destination-id destination_id \ --workspace-id workspace_id ``` ##### Response (200) ```json { "created_at": "2019-12-27T18:11:19.117Z", "telemetry_destination_id": "telemetry_destination_id", "type": "telemetry_destination_workspace", "workspace_id": "workspace_id" } ``` ### Remove a Telemetry Destination Workspace `$ ant beta:organization:telemetry-destinations:workspaces remove` **DELETE** `/v1/organizations/telemetry_destinations/{destination_id}/workspaces/{workspace_id}` Remove one workspace from a destination's workspace list. Under `include` the workspace's spans stop going to the destination. Under `exclude` they start. An archived workspace can be removed too. The API returns 404 when the workspace isn't on the list. A destination whose `workspaces.type` is `all` doesn't have a list, so the API returns 400. See the [OpenTelemetry export guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry?sdk_languages=cli#choose-workspaces-for-a-destination) to learn more about choosing the workspaces of a destination. #### Parameters - `--destination-id: string` (path parameter) ID of the destination (`tdst_...`). - `--workspace-id: string` (path parameter) ID of the workspace to remove (`wrkspc_...`). - `--beta: optional array of AnthropicBeta` (header parameter) This endpoint is in beta: requests must send `telemetry-destinations-2026-08-11` in this header. #### Returns - `beta_deleted_telemetry_destination_workspace: object` Confirmation that a workspace was removed from a destination's list. - `type: "telemetry_destination_workspace_deleted"` - `telemetry_destination_id: string` ID of the telemetry destination (`tdst_...`). - `workspace_id: string` ID of the workspace that was removed (`wrkspc_...`). #### Example ```bash ant beta:organization:telemetry-destinations:workspaces remove \ --api-key my-anthropic-api-key \ --destination-id destination_id \ --workspace-id workspace_id ``` ##### Response (200) ```json { "telemetry_destination_id": "telemetry_destination_id", "type": "telemetry_destination_workspace_deleted", "workspace_id": "workspace_id" } ```